{
  "markdown": "# charles-local-mcp\n\nLocal-only, profile-driven Charles Proxy automation for macOS. The same\napplication service is exposed through a JSON CLI and an MCP stdio server.\n\nVersion `0.1.3` supports Charles `4.6.8` on macOS. The public package contains\nonly generic `example.com` fixtures and no organization-specific hosts or paths.\n\n## Profile\n\n```toml\nschemaVersion = 1\n\n[profiles.demo]\nsourceHost = \"app.example.com\"\nsourcePath = \"/api*\" # optional Charles path pattern\ndestinationUrl = \"http://127.0.0.1:8080\"\nsslHosts = [\"app.example.com\"]\nverificationUrl = \"https://app.example.com/health\"\n```\n\nOmit `destinationUrl` for a proxy-only profile that disables Map Remote while\nretaining the exact SSL hosts and optional verification URL. When present,\n`destinationUrl` is restricted to loopback addresses.\n\nMap Remote destinations must resolve to a loopback host. `verificationUrl` is\noptional, must use HTTPS without embedded credentials, and must match\n`sourceHost`.\n\n## Commands\n\n```console\ncharles-local-mcp doctor --json\ncharles-local-mcp --profiles-file profiles.toml profiles validate --json\ncharles-local-mcp --profiles-file profiles.toml --evidence-root /absolute/path/exports session evidence --profile demo --xml-file session.xml --json\ncharles-local-mcp --profiles-file profiles.toml setup plan --profile demo --platform android --json\ncharles-local-mcp --profiles-file profiles.toml setup apply --token TOKEN --json\ncharles-local-mcp setup resume --token TOKEN --json\ncharles-local-mcp status --json\ncharles-local-mcp cleanup plan --json\ncharles-local-mcp cleanup apply --token TOKEN --json\ncharles-local-mcp serve\n```\n\nState defaults to `~/Library/Application Support/charles-local-mcp`. Tests and\nintegrators can isolate it with `CHARLES_LOCAL_MCP_HOME` or `--state-dir`.\nCLI stdout is JSON only; MCP stdout is protocol only. Diagnostics use stderr.\n\nMutation commands require macOS and Charles `4.6.8`. Setup and cleanup plans\nexpire after 15 minutes, are single-use, and are rejected if state changed.\nOnly one active session is allowed in a state directory.\n\n## Local XML session evidence\n\n`session evidence` reads only a selected local `.xml` file inside the\nconfigured `--evidence-root` and the selected immutable profile. If the option\nis omitted, the root defaults to `<state-dir>/evidence`; it is resolved only\nwhen evidence analysis is requested, so existing setup and inspection commands\ndo not require that directory. Relative traversal and absolute paths outside\nthe root are rejected without returning local paths. The evidence root, parent\ndirectories, and selected file must not be symbolic links.\n\nThe operation uses the selected profile's exact `sourceHost` only as an\ninternal filter. The bundle returns the profile name with `hostScope: \"exact\"`,\na fixed HTTP method enum, per-bundle opaque route references such as\n`route-001`, query parameter counts, numeric status/duration, and\nrequest/response sizes when those attributes exist. Repeated raw paths receive\nthe same opaque route reference within one bundle. Other hosts are excluded and\nreported only as a count.\n\nThe operation never returns raw hosts, paths, query names, query values,\nheaders, cookies, credentials, or bodies. Unknown request methods become the\nfixed value `OTHER`. It does not upload or persist the source session and does\nnot write an evidence ledger.\nFiles are limited to 10 MiB and 1,000 transactions; output is limited to 100\nrequests and 50 failures. DTD, DOCTYPE, and entity references are rejected.\nSome Charles exports include a DOCTYPE declaration; make a trusted local copy\nand remove the complete declaration before analysis. See\n[`docs/session-evidence.md`](docs/session-evidence.md) for the contract, safety\nboundary, limits, and stable error codes.\n\nThe real-device procedure is intentionally manual: see\n[`docs/manual-smoke.md`](docs/manual-smoke.md).\n\n## Install\n\nBuild from crates.io when a local Rust toolchain is available:\n\n```console\ncargo install charles-local-mcp --locked\n```\n\nFor a one-click MCP client installation on macOS, use the universal `.mcpb`\nasset from the matching GitHub Release. The native binary and bundle are not signed or notarized by Apple, so macOS may show a security warning when opening a downloaded asset. Verify `SHA256SUMS` from that release before installing. The bundle asks for a TOML profiles file and starts `charles-local-mcp serve`; profiles remain read-only to MCP tools.\nIt also asks for the XML evidence folder that is the only directory the\n`session_evidence` tool may read.\n\nRelease maintainers should follow [`docs/releasing.md`](docs/releasing.md).\n",
  "bytes": 4619,
  "sha": "d38dfd2fd19745ac81a446fea30f335b0e3e31624c4ef45cc52c24ce9126a6dd",
  "repo_slug": "eason0in/charles-local-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_eason0in_charles_local_mcp_ccac4dc7/readme"
}