{
  "markdown": "# cartograph-mcp\n\n[![CI](https://github.com/benteigland11/cartograph-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/benteigland11/cartograph-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/cartograph-mcp?cacheSeconds=60)](https://pypi.org/project/cartograph-mcp/)\n\nmcp-name: io.github.benteigland11/cartograph\n\nTired of vibe coding the same solutions **over and over**?\nTime to stop spending money on **redundant tokens** and start spending it on **innovative solutions**.\n\nThis MCP server is for [Cartograph](https://github.com/benteigland11/Cartograph) that exposes the daily widget workflow for agents without mirroring the entire CLI. It targets the MCP 2.0 SDK contract and returns the standard `ListToolsResult` envelope from `tools/list`. On installation of the MCP the CLI will be installed automatically. Once you have it, Search, inspect, install, create, validate, check in, custom rules, and configure Cartograph defaults through a compact agent-facing surface, then fall back to the CLI for the full administrative and recovery surface.\n\nIt is highly recommended to use the [plugins](https://github.com/benteigland11/cartograph-plugins) for the skills that go with this MCP. It will give your agent what it needs to explain a lot of the configuration and give you a very powerful workflow tool.\n\n## Why this exists\n\nI personally have spent hours and hours working on solutions I'm proud of, only to hit a wall trying to get the same one done. The reality was prompting was never good enough, I needed a way to know my llama.cpp server client integration was going to be the same everytime I used it. I also needed to know that when I found an improvement, that improvement would stick.\n\nIf you are sick and tired of wasting money and time on redoing things you've done before, like a **mouse on a wheel** then get your agents to start using Cartograph.\n\nThe Cartograph CLI is the source of truth, but agents do better when the common path is small and explicit.\n\nThis MCP keeps the top-level tool surface focused on daily driving:\n\n- finding reusable widgets\n- inspecting and installing them\n- managing installed widget copies\n- creating new widgets\n- validating and checking them back in\n- adjusting the core Cartograph defaults that affect normal workflow\n\nEverything else stays in the CLI. That keeps the MCP easier to teach, easier to test, and less likely to drift into a second full interface.\n\n## Quick start\n\n```bash\npip install cartograph-mcp\n```\n\nClaude Desktop example:\n\n```json\n{\n  \"mcpServers\": {\n    \"cartograph\": {\n      \"command\": \"cartograph-mcp\"\n    }\n  }\n}\n```\n\nThe package depends on `cartograph-cli` and shells out to it as the source of truth for the full command surface.\n\nCommon CLI setup commands:\n\n```bash\n# Claude Code\nclaude mcp add cartograph --scope user -- cartograph-mcp\n\n# Codex\ncodex mcp add cartograph -- cartograph-mcp\n\n# Gemini CLI\ngemini mcp add cartograph cartograph-mcp\n\n# Cursor\ncursor --add-mcp '{\"name\":\"cartograph\",\"command\":\"cartograph-mcp\"}'\n```\n\nClaude Code expects an explicit scope flag such as `--scope user`.\n\n## Tool surface\n\nThe MCP intentionally exposes a small workflow-oriented surface:\n\n- `registry_widget`\n  Actions: `search`, `inspect`, `install`, `rate`\n- `installed_widget`\n  Actions: `upgrade`, `uninstall`\n- `widget_status`\n- `create_widget`\n- `validate_widget`\n- `checkin_widget`\n- `cartograph_config`\n- `cartograph_rules`\n\nThese are not a 1:1 mirror of the CLI. They are grouped around agent intent:\n\n- registry-facing work\n- installed-widget mutation\n- project health/status\n- widget authoring\n- workflow configuration\n- custom validation rules\n\n## Example workflow\n\n```text\n1. Search the registry before writing logic.\n2. Inspect the widget you want to reuse.\n3. Install it into the project.\n4. If no existing widget fits, create one.\n5. Validate it with the full dry-run pipeline.\n6. Check it in with a reason once it is ready.\n```\n\nIn Cartograph terms:\n\n- `registry_widget` handles discovery and install\n- `installed_widget` handles already-installed widget paths like `cg/backend_retry_python`\n- `validate_widget` is the dry run for `checkin_widget`\n- `cartograph_config` manages the defaults that change how your day-to-day loop behaves\n- `cartograph_rules` manages custom rules that run during validate and checkin\n\n## Philosophy\n\nThis MCP is deliberately not the whole CLI.\n\nThe common path belongs in MCP. The official full surface belongs in `cartograph`.\n\nFor uncommon, administrative, or recovery operations, use:\n\n```bash\ncartograph --help\ncartograph <command> --help\n```\n\nThat includes things like rollback/delete, cloud operations, auth, setup, rules, doctor, export/import, and other non-daily commands.\n\n## Configuration\n\n`cartograph_config` exposes the workflow defaults that matter most to agents:\n\n- `auto-publish`\n- `visibility`\n- `governance`\n- `cloud`\n- `show-unavailable`\n- `publish-registry`\n\nReading and writing config is done through the CLI's `--json` path so MCP can consume it safely.\n\n## Testing\n\nThis package is tested in two layers:\n\n- command-contract tests that mock the CLI runner and assert the exact commands the MCP builds\n- isolated integration tests that run the real Cartograph CLI in a temporary environment\n\nThe integration suite isolates:\n\n- `HOME`\n- `XDG_CONFIG_HOME`\n- `XDG_DATA_HOME`\n- `XDG_CACHE_HOME`\n- `WIDGET_LIBRARY_PATH`\n- project working directory\n\nThat means validate/checkin/install flows are exercised without touching the real widget library or user config on the machine running tests.\n\n\n## Development\n\n```bash\npip install -e .\npytest -q\n```\n\nThe repo includes:\n\n- `ci.yml` for normal test/build validation on pushes and pull requests\n- `pypi-publish.yml` for automated release publishing after a successful version-bump CI run\n\nFor the full product story and complete CLI surface, see [Cartograph](https://github.com/benteigland11/Cartograph).\n",
  "bytes": 5918,
  "sha": "8e5747e1ac890585c0df5384e025e1cd2d844164ba16649216613dec42001d90",
  "repo_slug": "benteigland11/cartograph-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_benteigland11_cartograph_2ffcff91/readme"
}