Cartograph

cartograph-mcp

mcp-name: io.github.benteigland11/cartograph

同じ解決策を何度も何度もバイブコーディングすることにうんざりしていませんか？ 無駄なトークンにお金を使うのをやめて、革新的な解決策に使い始めるときです。

この MCP サーバーは Cartograph 用です。CLI 全体をそのまま再現するのではなく、エージェント向けに日常的なウィジェットのワークフローを提供します。MCP 2.0 SDK の仕様に準拠し、tools/list から標準の ListToolsResult エンベロープを返します。MCP をインストールすると、CLI も自動的にインストールされます。インストール後は、コンパクトなエージェント向けインターフェイスから、Cartograph の検索、調査、インストール、作成、検証、チェックイン、カスタムルール、デフォルト設定を行い、管理や復旧に必要なすべての機能は CLI に切り替えて利用できます。

この MCP と連携するスキルには、プラグインの使用を強くおすすめします。プラグインを使うと、エージェントが多くの設定について説明するために必要な情報を得られ、非常に強力なワークフローツールとして活用できます。

これが作られた理由

私は、自分でも誇りに思う解決策を作るのに何時間も費やしてきました。しかし、同じものをもう一度作ろうとすると、行き詰まってしまうことがありました。実際のところ、プロンプトだけでは十分ではありませんでした。llama.cpp サーバーのクライアント統合が、使うたびに同じように動作することを確認する方法が必要でした。また、改善点を見つけたとき、その改善が確実に反映されることも知りたかったのです。

以前にやったことをやり直すためにお金と時間を無駄にするのに、回し車の上のネズミのようにうんざりしているなら、エージェントに Cartograph を使わせましょう。

Cartograph CLI が信頼できる唯一の情報源ですが、一般的な作業経路が小さく明確になっているほうが、エージェントはよりうまく動作します。

この MCP は、日常的に使うトップレベルのツールを次の用途に絞っています。

• 再利用可能なウィジェットを探す
• ウィジェットを調査してインストールする
• インストール済みウィジェットのコピーを管理する
• 新しいウィジェットを作成する
• ウィジェットを検証してチェックインする
• 通常のワークフローに影響する Cartograph の基本設定を調整する

それ以外はすべて CLI に残します。これにより、MCP は教えやすく、テストしやすくなり、2つ目の完全なインターフェイスへと肥大化しにくくなります。

クイックスタート

pip install cartograph-mcp

Claude Desktop の例：

{
  "mcpServers": {
    "cartograph": {
      "command": "cartograph-mcp"
    }
  }
}

このパッケージは cartograph-cli に依存しており、完全なコマンド一式の信頼できる唯一の情報源として、シェルから呼び出します。

一般的な CLI のセットアップコマンド：

# Claude Code
claude mcp add cartograph --scope user -- cartograph-mcp

# Codex
codex mcp add cartograph -- cartograph-mcp

# Gemini CLI
gemini mcp add cartograph cartograph-mcp

# Cursor
cursor --add-mcp '{"name":"cartograph","command":"cartograph-mcp"}'

Claude Code では、--scope user のような明示的なスコープフラグが必要です。

ツールの範囲

この MCP が公開するのは、ワークフローを重視した小規模なインターフェイスです。

• registry_widget アクション：search、inspect、install、rate
• installed_widget アクション：upgrade、uninstall
• widget_status
• create_widget
• validate_widget
• checkin_widget
• cartograph_config
• cartograph_rules

これらは CLI をそのまま1対1で再現したものではありません。エージェントの目的に合わせてグループ化されています。

• レジストリ関連の作業
• インストール済みウィジェットの変更
• プロジェクトの健全性とステータス
• ウィジェットの作成
• ワークフローの設定
• カスタム検証ルール

ワークフローの例

1. Search the registry before writing logic.
2. Inspect the widget you want to reuse.
3. Install it into the project.
4. If no existing widget fits, create one.
5. Validate it with the full dry-run pipeline.
6. Check it in with a reason once it is ready.

Cartograph では、次のように使います。

• registry_widget は検索とインストールを担当します
• installed_widget は、cg/backend_retry_python のようなインストール済みウィジェットのパスを扱います
• validate_widget は checkin_widget のドライランです
• cartograph_config は、日々の作業ループの動作を変えるデフォルト設定を管理します
• cartograph_rules は、検証とチェックインの際に実行されるカスタムルールを管理します

方針

この MCP は、意図的に CLI 全体をカバーしていません。

一般的な操作は MCP で行います。公式の全機能は cartograph が提供します。

頻度の低い管理操作や復旧操作には、次を使用してください。

cartograph --help
cartograph <command> --help

これには、ロールバック／削除、クラウド操作、認証、セットアップ、ルール、doctor、エクスポート／インポート、その他の日常的ではないコマンドなどが含まれます。

設定

cartograph_config は、エージェントにとって特に重要なワークフローのデフォルト設定を公開します。

• auto-publish
• visibility
• governance
• cloud
• show-unavailable
• publish-registry

設定の読み取りと書き込みには、MCP が安全に利用できるよう、CLI の --json 経由の方法を使用します。

テスト

このパッケージは、次の 2 つの層でテストされています。

• CLI ランナーをモックし、MCP が組み立てる正確なコマンドを検証するコマンド契約テスト
• 一時的な環境で実際の Cartograph CLI を実行する、分離された統合テスト

統合テストでは、次の項目を分離します。

• HOME
• XDG_CONFIG_HOME
• XDG_DATA_HOME
• XDG_CACHE_HOME
• WIDGET_LIBRARY_PATH
• プロジェクトの作業ディレクトリ

これにより、テストの実行マシン上の実際のウィジェットライブラリやユーザー設定に触れることなく、validate／checkin／install の各フローを検証できます。

開発

pip install -e .
pytest -q

リポジトリには、次のものが含まれています。

• プッシュおよびプルリクエスト時に通常のテスト／ビルド検証を行う ci.yml
• バージョン更新の CI 実行が成功した後に、リリースを自動公開する pypi-publish.yml

製品の全体像と CLI の全機能については、Cartograph をご覧ください。