{
  "markdown": "# Cartograph\n\nCartograph is task-shaped repo context for coding agents. It ships a CLI, an MCP server, user-scope install adapters for Claude Code and OpenClaw, and packaged agent assets for documentation-heavy workflows.\n\n- npm: [`@anthony-maio/cartograph`](https://www.npmjs.com/package/@anthony-maio/cartograph)\n- MCP Registry: [`io.github.anthony-maio/cartograph`](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.anthony-maio/cartograph)\n- Quickstart: [`cartograph.making-minds.ai`](https://cartograph.making-minds.ai)\n\nInstead of dumping an entire repository into context, Cartograph ranks the files that matter, maps dependencies, caches structured artifacts, and lets the next tool or agent pick up from those artifacts.\n\nThe primary workflow is:\n\n1. `analyze` to map the repo\n2. `packet` to prepare the work\n3. `context` to load the minimum files\n\n`wiki`, host installs, and benchmarks are secondary surfaces built around that core path.\n\n## Install\n\n```bash\nnpm install\nnpm run build\n```\n\nFor global use from npm:\n\n```bash\nnpm install -g @anthony-maio/cartograph\n```\n\nFor MCP host discovery via the official registry:\n\n- `io.github.anthony-maio/cartograph`\n- [Registry listing](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.anthony-maio/cartograph)\n\nFor Claude Code plugin install from this public repo:\n\n```text\n/plugin marketplace add anthony-maio/cartograph\n/plugin install cartograph@making-minds-tools\n```\n\nFor global use from a local checkout:\n\n```bash\nnpm install -g .\n```\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow and [SECURITY.md](./SECURITY.md) for vulnerability reporting.\n\n## Claude Code Plugin\n\nThis repo also acts as a Claude Code plugin marketplace. The `cartograph` plugin bundles:\n\n- a plugin-scoped Cartograph MCP server\n- slash commands: `/cartograph:analyze`, `/cartograph:context`, `/cartograph:wiki`\n- the `use-cartograph` and `repo-surveyor` skills\n- the documentation-agent bundle: `repo-scout`, `dependency-tracer`, `context-picker`, `api-surface-writer`, and `wiki-writer`\n\nInstall it with:\n\n```text\n/plugin marketplace add anthony-maio/cartograph\n/plugin install cartograph@making-minds-tools\n```\n\n## Primary Workflow\n\nIf you only remember one thing, remember this:\n\n```bash\ncartograph analyze <repo> --static\ncartograph packet <repo> --type <type> --task \"<task>\"\ncartograph context <repo> --task \"<task>\" --json\n```\n\n- `analyze` maps the repo and tells you what matters.\n- `packet` turns a concrete job into a reusable working artifact.\n- `context` gives the next agent the smallest useful file set.\n\n## Command Surface\n\n```bash\ncartograph analyze <repo> [options]\ncartograph packet <repo> --type <type> --task \"<task>\" [--changed <paths...>]\ncartograph context <repo> --task \"<task>\" [options]\ncartograph wiki <repo> [options]\ncartograph export <run-id> --to <path> [--artifact <name>]\ncartograph install <claude|openclaw|mcp>\ncartograph uninstall <claude|openclaw|mcp>\ncartograph doctor [target] [--json]\ncartograph mcp\n```\n\nLegacy compatibility still works:\n\n```bash\ncartograph <repo> --static\ncartograph <repo> -c \"trace auth flow\"\n```\n\n## CLI Usage\n\n```bash\n# Map the repo\ncartograph analyze ./my-project --static\n\n# Prepare a concrete job\ncartograph packet ./my-project --type bug-fix --task \"fix auth refresh bug\" --changed src/auth/service.ts tests/auth/service.test.ts\n\n# Load the minimum file set for that job\ncartograph context ./my-project --task \"add user authentication\" --json\n\n# Force embedded snippets when you really want them\ncartograph analyze ./my-project --static --json --include-contents\n\n# Full wiki output\ncartograph wiki ./my-project -p gemini -k $CARTOGRAPH_API_KEY -o wiki.md\n\n# Export a cached artifact to an explicit path\ncartograph export run-abc123 --to ./artifacts/wiki.md\n\n# Run the MCP server directly\ncartograph mcp\n```\n\nFor small repos, `analyze --static --json` now defaults to compact output instead of embedding top-file contents. That keeps tiny repos readable and lets direct file reads stay cheaper than a giant JSON blob. Use `--include-contents` when you explicitly want embedded snippets.\n\nThe default markdown output from `analyze --static` is human-first: it highlights what matters, surfaces dependency hubs, and recommends the next commands instead of dumping raw file contents immediately.\n\n### Providers\n\n- `gemini`\n- `openai`\n- `openrouter`\n- `ollama`\n\nSet the API key with `--key` or `CARTOGRAPH_API_KEY`. Ollama does not require a key.\n\n## Cache Model\n\nCartograph writes successful runs into the user cache by default:\n\n- Windows: `%USERPROFILE%\\\\.cartograph\\\\cache`\n- POSIX: `~/.cartograph/cache`\n\nEach run gets a manifest plus named artifacts, which keeps agent handoffs lightweight and makes `cartograph export` deterministic.\n\n## Host Installs\n\nCartograph uses an explicit hybrid install model. Installing the package does not modify Claude Code, OpenClaw, or MCP host configs automatically.\n\nInstead, install only the integration you want:\n\n```bash\ncartograph install claude\ncartograph install openclaw\ncartograph install mcp\n```\n\nWhat each target installs:\n\n- `claude`: user-scope skills plus the bundled documentation agents under `~/.claude`\n- `openclaw`: user-scope skill pack under `~/.openclaw`\n- `mcp`: a Cartograph MCP config snippet under `~/.cartograph/mcp`\n\nCheck status at any time:\n\n```bash\ncartograph doctor\ncartograph doctor --json\n```\n\n## Choose Your Surface\n\n- CLI: best default path when you want deterministic local analysis and explicit artifacts.\n- Claude Code plugin: best when you want plugin install, bundled skills, slash commands, and a plugin-scoped MCP server.\n- OpenClaw skills: best when you want the same Cartograph workflow inside an OpenClaw skill-first environment.\n- MCP Registry: best when your host already prefers tool wiring over shell commands.\n\n## MCP Server\n\nCartograph's MCP server exposes static repo analysis directly to hosts that prefer MCP over shell commands.\n\nTools:\n\n- `analyze_repo`: score files, map dependencies, and return compact analysis output or embedded top-file contents for a local repo or GitHub URL\n- `get_file_contents`: fetch full contents for specific files after analysis\n- `build_task_packet`: return a typed task packet with key files, dependency hubs, validation targets, risks, and task-specific details\n\nBug-fix packets are tuned to stay focused when you provide `--changed` or `changed_files`: they keep explicit change surfaces in view, prefer exact validation targets, and bias toward shared dependencies over peripheral utility scripts.\n\nIf you want Cartograph's packaged MCP snippet, run:\n\n```bash\ncartograph install mcp\n```\n\nThat writes a reusable config file that points at:\n\n```json\n{\n  \"mcpServers\": {\n    \"cartograph\": {\n      \"command\": \"cartograph\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n## MCP Registry\n\nCartograph is published in the official MCP Registry with the server name `io.github.anthony-maio/cartograph`.\n\n- [View the registry entry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.anthony-maio/cartograph)\n\nRepo-side metadata lives in:\n\n- [`package.json`](./package.json) via the `mcpName` field\n- [`server.json`](./server.json) for registry metadata\n\nThe current install artifact published to npm is:\n\n- `@anthony-maio/cartograph`\n\nFor repeatable registry releases, this repo also includes a GitHub Actions workflow at\n[`publish-mcp.yml`](./.github/workflows/publish-mcp.yml). It is set up for npm trusted publishing on\nGitHub Actions, then authenticates to the MCP Registry with GitHub OIDC and publishes `server.json`.\n\n## Packaged Agent Assets\n\nThe package currently ships:\n\n- two Claude skills: `use-cartograph` and `repo-surveyor`\n- five Claude documentation agents: `repo-scout`, `dependency-tracer`, `context-picker`, `api-surface-writer`, and `wiki-writer`\n- two OpenClaw skills: `use-cartograph` and `repo-surveyor`\n- bundled OpenProse templates inside both OpenClaw skills for repo-doc and task-context workflows\n\nSkill roles:\n\n- `use-cartograph`: tool-first path when the CLI or MCP server is available\n- `repo-surveyor`: manual fallback path when Cartograph is unavailable or needs verification\n\nBoth skills are designed to produce the same downstream contract:\n\n- key files\n- dependency hubs\n- minimal task context\n- doc-ready summary\n\nThese assets are meant to pass run IDs and artifact paths between steps instead of copying large prose into the main context.\n\nThe Claude plugin marketplace in this repo ships the same skills and agents, plus plugin-first slash commands and a bundled Cartograph MCP server.\n\n## Task Packet Benchmark\n\nThis repo includes a public benchmark pack for task packets under [`benchmarks/task-packets`](./benchmarks/task-packets).\n\nUse it to compare packet quality across large visible repos with a stable set of task prompts:\n\n```bash\nnpm run benchmark:task-packets -- --list\nnpm run benchmark:task-packets -- --case llama-cpp-bug-fix --dry-run\n```\n\nThe benchmark runner writes packet artifacts to `benchmarks/task-packets/output/`, which is gitignored.\n\nCurated scorecards and public artifact links are also published on the site:\n\n- [`cartograph.making-minds.ai/examples/benchmarks.html`](https://cartograph.making-minds.ai/examples/benchmarks.html)\n\n## Example Artifacts\n\nTracked examples live under [`docs/examples`](./docs/examples):\n\n- [`llama-cpp-task-packet.md`](./docs/examples/llama-cpp-task-packet.md)\n- [`llama-cpp-task-packet.json`](./docs/examples/llama-cpp-task-packet.json)\n- [`llama-cpp-deepwiki.md`](./docs/examples/llama-cpp-deepwiki.md)\n- [`task-packet-benchmark-scorecards.md`](./docs/examples/task-packet-benchmark-scorecards.md)\n\nThese are useful when you want to show what a focused bug-fix packet and a curated repo brief look like on a large public codebase.\n\n## Development\n\n```bash\nnpm install\nnpm test\nnpm run check\nnpm run build\nnpm run pack:smoke\n```\n\n## License\n\nMIT\n",
  "bytes": 9939,
  "sha": "1e18a1a76f858944cf7a98e64a72f8df7ab6cd9569f0465459e0274e8b80dd45",
  "repo_slug": "anthony-maio/cartograph",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_anthony_maio_cartograph_14723324/readme"
}