Cartograph

cartograph-mcp

mcp-name: io.github.benteigland11/cartograph

厌倦了一遍又一遍地用氛围编程写出相同的解决方案？ 是时候停止为重复的 token花钱，开始把钱花在创新的解决方案上了。

此 MCP 服务适用于 Cartograph，它为 Agent 提供日常组件工作流，同时不会镜像整个 CLI。它面向 MCP 2.0 SDK 契约，并从 tools/list 返回标准的 ListToolsResult 信封。安装 MCP 时会自动安装 CLI。安装后，你可以通过简洁、面向 Agent 的界面搜索、检查、安装、创建、验证、签入组件，管理自定义规则并配置 Cartograph 默认设置；然后在需要完整的管理和恢复功能时，切换到 CLI。

强烈建议使用与此 MCP 配套的技能插件。它能为你的 Agent 提供解释大量配置所需的信息，并为你带来强大的工作流工具。

为什么要做这个项目

我曾花费大量时间和精力开发自己引以为豪的解决方案，最后却发现无法再次复现同样的结果。事实是，提示词始终不够好；我需要一种方法，确保每次使用时，llama.cpp 服务端的客户端集成都能保持一致。我还需要确保找到改进方案后，这些改进能够保留下来。

如果你厌倦了像仓鼠转轮一样，浪费金钱和时间重做以前做过的事情，那就让你的 Agent 开始使用 Cartograph 吧。

Cartograph CLI 是事实来源，但对于 Agent 来说，常见操作路径越简洁、越明确，效果越好。

此 MCP 服务将顶层工具界面聚焦于日常工作：

• 查找可复用的组件
• 检查和安装组件
• 管理已安装的组件副本
• 创建新组件
• 验证组件并将其签入
• 调整会影响常规工作流的核心 Cartograph 默认设置

其他所有操作都保留在 CLI 中。这样能让 MCP 更易于讲解和测试，也不容易逐渐演变成另一个完整的界面。

快速开始

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 的一对一镜像，而是围绕 Agent 的使用意图分组：

• 面向注册表的操作
• 已安装组件的修改
• 项目健康状况／状态
• 组件创作
• 工作流配置
• 自定义验证规则

工作流示例

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 提供对 Agent 最重要的工作流默认设置：

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

配置的读取和写入通过 CLI 的 --json 路径完成，以便 MCP 安全地读取配置。

测试

此软件包通过以下两层测试：

• 命令契约测试：模拟 CLI 运行器，并断言 MCP 构建的确切命令
• 隔离的集成测试：在临时环境中运行真实的 Cartograph CLI

集成测试套件会隔离：

• HOME
• XDG_CONFIG_HOME
• XDG_DATA_HOME
• XDG_CACHE_HOME
• WIDGET_LIBRARY_PATH
• 项目工作目录

这意味着 validate/checkin/install 流程会在测试期间运行，而不会触碰运行测试的机器上的真实 widget 库或用户配置。

开发

pip install -e .
pytest -q

仓库包含：

• ci.yml，用于在推送和拉取请求时进行常规测试/构建验证
• pypi-publish.yml，用于在版本升级 CI 运行成功后自动发布版本

如需了解完整的产品介绍和 CLI 功能，请参阅 Cartograph。