DevTwin MCP

为 AI 编码代理提供对本地开发环境的实时、结构化理解。

DevTwin 是一个模型上下文协议（Model Context Protocol，MCP）服务器，它为一个 AI 编码代理回答一个核心问题：为什么这个开发者的环境不同、损坏或不健康？

它检测项目技术栈，对照项目实际要求检查已安装的运行时版本，检查依赖和锁文件状态，查找所需的本地服务（Postgres、Redis，……）以及它们是否在运行，检查端口和 Git 状态，并将所有这些转化为结构化的、基于证据的诊断结果——绝不会将你的环境发送到云端后端，也绝不会向模型暴露任何机密值。

目录

• 为什么 DevTwin 存在

• 常见问题：Claude CLI 已经有 shell，为什么还需要 MCP？

• 优势

• Token 成本

• 诚实的权衡

• 有无 DevTwin 的对比：一个实际示例

• 这解锁的示例问题

• 各语言示例

• 架构

• 支持的生态系统

• 安装

• MCP 客户端配置

• 在其他项目上使用

• 工具参考

• 安全模型

• 隐私模型

• 本地优先架构

• 开发

• 贡献

• 路线图

• 许可证

为什么 DevTwin 存在

• AI 编码代理读代码没问题，但对代码实际运行的环境却视而不见。

• “为什么 npm test 在我的机器上失败？”通常与代码无关——而是 Node 版本不匹配、服务没有运行，或者依赖从未安装。

• DevTwin 为代理提供高级工程师手动收集的相同信号——node --version、git status、lsof -i :5432、docker ps——以结构化工具调用的形式，而不是靠猜。

常见问题：Claude CLI 已经有 shell，为什么还需要 MCP？

这通常是开发者问的第一个问题，而且问得合理。在像 Claude Code 这样已经有 Bash 工具的客户端里，你可以直接让它运行 node --version、docker ps、lsof -i :5432 等命令——不需要 MCP 服务器。DevTwin 拉平的差距不是“到底能不能做到”，而是这些：

针对 Claude CLI 的诚实回答： 由于它已经有 Bash，DevTwin 在这里的赢面比“你原本没有的能力”要小——它是安全保证和一致的结构化输出，而不是全新的访问能力。这也是为什么它不是免费的——连接它实际要花多少 token、什么时候值得，请参见 Token 成本。

在采纳之前，还有几个问题值得问：

“这不就是一个多了几步的 doctor 脚本（make doctor、bin/setup）吗？” 从概念上讲，是的——很多成熟仓库已经手工写了一个。DevTwin 的不同之处在于，大多数仓库没有这样的脚本；为每个生态系统写好一个确实是实打实的工作；它的输出是结构化的 JSON，可供代理推理，而不是供人类阅读的纯文本；而且同样的 10 个工具在每个仓库中都以相同方式工作，而不是每个项目一个带有自己约定和盲点的定制脚本。

“这只适用于 Claude / Claude Code 吗？” 不是。DevTwin 使用标准的模型上下文协议——任何兼容 MCP 的客户端（Claude Desktop、Cursor、Windsurf 等）都可以用同样的方式连接它。它与 Claude 没有任何特殊绑定。

“依赖它安全吗——它是否在积极维护？” 它处于 Alpha 状态，是一个年轻的项目——在把它用于你依赖的工作流之前，请阅读代码（它很短），就像你对待任何新的开发工具依赖一样。

“它会不会建议错误的东西，或者自动运行一个不好的推荐？” 这里没有任何工具会执行 recommendations 字符串——那些只是供代理（或你）阅读并决定的文本。dev_check 是唯一会执行任何内容的工具，而且只执行它自己从项目文件中识别出来、并对照固定白名单检查过的命令——参见安全模型。

“它会回传数据或向任何地方发送遥测吗？” 不会。它自身零网络调用——参见本地优先架构。

“我不希望 MCP 服务器在我的机器上运行任何命令。” 10 个工具中有 9 个是纯只读的（文件读取、版本检查）。只有 dev_check 会执行任何内容，而且只执行 DevTwin 自己从项目文件中识别、并对照白名单检查过的命令，使用 shell=False 和超时——关于它允许和不允许的确切范围，参见安全模型。

优势

• 更少的错误诊断。 没有 DevTwin 时，代理在调试失败时只能读代码和猜测——它常常会对实际上只是 Node 版本不匹配或数据库停止的问题提出代码修复。DevTwin 给它的不是猜测，而是事实。

• 一次调用代替多次调用。 一次 dev_health 调用把约 10 项底层检查（运行时版本、依赖状态、服务、端口、Git）捆绑成一个结构化的、带评分的结果——而不是让代理做十几次独立的 shell 往返，并每次都解析原始 CLI 输出。

• 每次都是同样的检查。 每个生态系统的具体检查（Gradle wrapper 与系统 Gradle，.nvmrc 与 package.json 的 engines……）被编码一次，因此诊断在多次会话之间保持一致，而不是取决于代理碰巧想到要运行什么。

• 比给代理一个 shell 更安全。 绝不执行任意命令，绝不进行破坏性操作——参见安全模型。

• 绝不触碰机密。 对看起来像机密的环境变量只检查是否存在；永远不会读取或返回其值——参见隐私模型。

• 在代理没有 shell 的地方也能工作。 没有 Bash 工具的 MCP 客户端（某些 IDE 助手、受限代理）也能获得这种能力，而不是完全没有能力。

Token 成本

真实数字，不是估算——直接从这个服务器自身的 MCP 工具模式（mcp.list_tools()）和一个真实的 dev_health() 响应测量而来，使用标准的每 token 约 4 个字符的近似值。

两个不同的时刻会消耗 token，而且成本差别很大：

每个工具的模式大小明细（实测）：

诚实的底线： 对于会话中单次一次性诊断（该会话其他时间完全不涉及环境问题），原始 Bash 在总 token 上可能更便宜——约 1,400 token 的固定模式税往往超过用一次调用替换多条 shell 命令省下的 token。双方的真实数字见下面的实际对比。

一个会话中出现的环境问题越多，DevTwin 的理由就越充分（固定税只付一次；之后的每个问题在 DevTwin 上约 150 token，而在原始 Bash 上每次都要多花几百 token）——它的真正优势根本不是原始 token 数量，而是一致性、安全性，以及在没有 Bash 工具的 MCP 客户端中也能工作。参见优势和诚实的权衡。

实际启示： 按项目注册 DevTwin，而不是按用户注册，这样固定税只在实际有用的会话中支付——参见在其他项目上使用。

诚实的权衡

DevTwin 不是一个用于稳定环境的日常工具——没有人需要在写的每个函数上都重新检查“Postgres 是否在运行”。它是一个应急工具：在特定时刻价值很高（刚克隆完、构建莫名失败、提交之前），其余时间闲置。这是预期的使用模式，而不是缺点。

• Token 开销只要连接上，每一轮都会产生，无论是否使用 —— 确实测数字见 Token 开销。

• 它并不一定在单次一次性问题上的 Token 节省上胜出；它的胜出点在于一致性、安全性，以及触达不提供 shell 的客户端的能力 —— 见 Benefits。

Wait "Benefits" should translate? The anchor must be "#benefits". The link text should be "优势" or "收益". We'll translate to "优势". Let's change.

Actually I wrote "## 此功能解锁的示例问题" etc.

Let's produce final.

Need be careful that "Token overhead is payed every turn" – "token overhead" is 开销. "on each turn the moment it's connected" = "一连接，每一轮都会产生开销". Good.

I'll produce final message with all.

But we must ensure all text within inline code remains in original case. We'll keep.

Let's write in final.

Need "GXP1" etc line as plain text.

Let's produce.* Token 开销在连接后的每一轮都会立即支付，无论是否实际使用 —— 真实的测量数字见 Token 开销。

• 对于单个一次性问题，它并不一定在 Token 开销上稳定占优；它的优势在于一致性、安全性，以及能够覆盖没有 shell 的客户端 —— 见 优势。

• 如果某个智能体已经对你有完整控制权、且很少发生环境漂移的仓库拥有完整 shell 访问权限，那你在那里可能完全不需要 DevTwin。

• DevTwin 最能在这些场景中体现价值：共享/新手引导仓库、受信任程度较低或没有 shell 的智能体环境，以及“到底该检查什么”本身就很难的多生态 monorepo。

使用与不使用 DevTwin：一个实际示例

假设你问一个智能体“为什么 npm test 失败了？”，而真正原因是 Node 版本不匹配，加 Postgres 没在运行。

不使用 DevTwin（智能体使用原生 Bash）—— 它必须一条命令一条命令地猜测正确的操作顺序：

cat package.json                      # spot "engines": {"node": ">=20"}
node --version                        # v16.20.0 -- mismatch found
grep -i "pg\|postgres" package.json   # spot the Postgres dependency
cat .env                              # risk: may print a real secret into context
lsof -i :5432                         # nothing listening
docker ps                             # check if it's in a container instead

六次往返，一条需要智能体自行规划的调查路径，第 4 步中有机密信息泄漏到对话中的真实风险，以及大约 400-800 Token 的命令与输出文本（具体数值取决于文件大小和正在运行的 Docker 容器数量）。

使用 DevTwin，只需要一次调用：

dev_health()

{
  "status": "error",
  "summary": "2 issues found: runtime drift, service down",
  "issues": [
    "Node 16.20.0 installed, project requires >=20 (from package.json engines)",
    "Postgres required (found in docker-compose.yml) but not running on 5432"
  ],
  "recommendations": [
    "nvm install 20 && nvm use 20",
    "docker compose up -d postgres"
  ]
}

同样的结论，回复约 150 Token—— 再加上那一轮本来就已经固定支付的 1,400 Token schema 开销（见 Token 开销）。一次调用替代六次，完全不会有泄漏机密的可能性，而且每次执行的都是一模一样的预置检查，而不是那种每次会话都不同的即兴调查。

此功能解锁的示例问题

• “检查我的开发环境。”

• “为什么我的 Kotlin 项目构建失败？”

• “我的 Node 版本对这个仓库来说正确吗？”

• “为什么我的应用连接不上 Postgres？”

• “我的环境与这个仓库的预期有偏差吗？”

• “我提交前应该运行什么？”

• “我刚克隆了这个仓库——我要怎么才能把它运行起来？”

各语言示例

每个受支持生态一行：你实际会问的问题、DevTwin 为回答它而检查的内容，以及它针对 dev_check 识别的测试/构建命令。

架构

一个 MCP 服务器，多个生态适配器——而不是每种语言一个单独的服务。

MCP server -> core (workspace/detector/health/drift/diagnostics) ->
adapters (python/node/jvm/go/rust/dotnet/swift/ruby/php/generic) ->
system inspection (os/process/ports/env/fs/docker) ->
service detection (postgres/redis/generic)

完整细节见 docs/architecture.md。如何新增一个语言适配器：docs/adapters.md。

支持的生态

任何不能匹配特定适配器的项目仍然可以通用适配器获得有用的输出——DevTwin 绝不会对未被识别的项目什么都不返回。

安装

uv pip install devtwin-mcp
# or
pip install devtwin-mcp

要基于此仓库的克隆进行本地开发，请参见 docs/development.md。

MCP 客户端配置

确切的配置语法因客户端而异——请查阅你所用客户端的文档。一般来说，DevTwin 作为一个 stdio MCP 服务器调用，调用方式如下：

{
  "mcpServers": {
    "devtwin": {
      "command": "devtwin"
    }
  }
}

如果是从克隆中（未安装包）进行本地开发：

{
  "mcpServers": {
    "devtwin": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/devtwin-mcp", "devtwin"]
    }
  }
}

用 MCP Inspector 验证工具是否可以发现：

npx @modelcontextprotocol/inspector uv run devtwin

在其他项目上使用（面向其他开发者）

DevTwin 是一个单一的可执行文件——任何数量的项目都可以指向同一个安装地，不需要针对每个项目重新安装。有两种作用域：

项目作用域——在项目根目录放置 .mcp.json：

{
  "mcpServers": {
    "devtwin": {
      "command": "/absolute/path/to/devtwin-mcp/.venv/bin/devtwin"
    }
  }
}

或使用 Claude Code CLI：

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope project

用户作用域：

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope user

添加后，重启客户端（或重新连接 MCP 服务器），然后直接正常提问即可——见 此功能解锁的示例问题。

**Monorepo 提示：**在一个混合平台的仓库中（如 Android + iOS + 后端），把问题指向特定的子文件夹，而不是仓库根目录——例如“检查 android/ 应用的健康状态”。在一个混合仓库根目录运行 dev_detect 会输出它找到的每一个生态，这对一次性盘点很有用，但对一个针对性检查来说就太吵了。

工具参考

所有工具都返回 {status, summary, data, issues, recommendations}。status 是 ok、warning、error、unknown 之一。

| 工具                  | 分类          | 说明                                                                                 |
| --------------------- | ------------- | ------------------------------------------------------------------------------------ |
| `dev_detect`          | 只读          | 基于文件的快速项目/生态系统检测，并附带证据。                                        |
| `dev_health`          | 只读          | 综合运行时、依赖、服务与 Git 状态的完整 0-100 健康评分。               |
| `dev_drift`           | 只读          | 比较所需的运行时/工具版本与实际已安装的版本。                               |
| `dev_explain_failure` | 只读          | 将给定的错误消息诊断为一组按优先级排列、有证据支持的根本原因。         |
| `dev_project_info`    | 只读          | 详细的项目检查：运行时、构建工具、命令、操作系统、Git。                      |
| `dev_dependencies`    | 只读          | 各生态系统的依赖/lockfile 状态。                                                      |
| `dev_services`        | 只读          | 所需的本地服务（Postgres、Redis、compose services）及其运行状态。                 |
| `dev_check`           | 安全执行      | 在超时限制下运行已识别的测试/lint 命令（如 `pytest`、`./gradlew test`）。 |
| `dev_prepare`         | 仅生成计划    | 为刚克隆的仓库生成准备计划；自身绝不执行该计划。                                   |
| `dev_precommit`       | 只读          | 提交就绪摘要：Git 状态、健康信息以及疑似机密的已暂存文件。                     |

## 安全模型

* **不执行任意命令。** 不存在 `execute_shell` 工具。
  `dev_check` 只运行 DevTwin 自己从项目文件中识别出的命令，这些命令经过 allowlist
  检查，并以 `shell=False` 和超时机制运行。
* **绝不执行破坏性操作。** DevTwin 从不运行 `git reset --hard`、
  `rm -rf`、`kill -9`、`docker compose down`，也不删除 lockfile 或修改 `.env`。
* **`dev_prepare` 只做规划。** 它会对每个建议步骤进行分类
  （`read_only`/`safe`/`requires_approval`/`dangerous`），并且绝不自行执行任何操作。

完整详情见 [`docs/security.md`](docs/security.md)。

## 隐私模型

* 仅当环境变量名称看起来像敏感信息（`PASSWORD`、`TOKEN`、`SECRET`、`API_KEY`、`PRIVATE_KEY`、`ACCESS_KEY`、`AUTH`、`CREDENTIAL`……）时，才检查其**是否存在**——绝不返回其值。
* `.env` 文件只扫描变量的 *名称*。
* `dev_precommit` 会标记名称看似敏感的已暂存文件，但不会读取或报告其内容。

## 本地优先架构

* 没有服务器组件、没有账户，也不存在除它所检查的本地命令（`git`、`docker`、语言工具链）之外的任何自身网络调用。
* 它报告的一切均来自运行它所在机器上已有的文件和进程。

## 开发

GXP12

完整的工作流程见 [`docs/development.md`](docs/development.md)。

## 贡献

参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。添加一种新的语言生态系统是最常见的贡献方式——模板参见 [`docs/adapters.md`](docs/adapters.md)，或以已合并的真实示例 [`src/devtwin/adapters/swift.py`](src/devtwin/adapters/swift.py)、[`ruby.py`](src/devtwin/adapters/ruby.py) 和 [`php.py`](src/devtwin/adapters/php.py) 为蓝本来构建你自己的适配器。

## 路线图

* 更多生态系统适配器：Elixir、Dart、Scala、C/C++（CMake/Bazel/Buck）、Nix（如何添加见 `docs/adapters.md`）
* 更多服务检测器（MySQL/MariaDB、MongoDB、Kafka、RabbitMQ）
* 与 CI 配置（如 GitHub Actions runtime matrices）进行更丰富的漂移对比
* 在单个会话内跨工具调用缓存开销较大的检查项时，提供可选的本地缓存

## 许可证

Apache-2.0 —— 参见 [`LICENSE`](LICENSE)。