编程工具 MCPxyTom/coding-tools-mcp

Coding Tools MCP

让任何 AI 聊天应用或 agent，都能安全地上手你的代码仓库。

PyPI
npm
Python
compliance
release
License

Coding Tools MCP 是一个模型中立的编程运行时，通过
Model Context Protocol 对外提供服务：
文件读取与搜索、结构化多文件补丁、命令执行、交互式命令、git 操作——
一个服务器，任何 MCP 客户端都能驱动。Claude Desktop、Claude Code、Codex、
Cursor、Cline、VS Code、Windsurf、Gemini CLI，或你自己写的 agent，拿到的
都是默认目录中久经考验的 18 个工具：限定在单一工作区内，由权限模式层层把关。

观看演示

为什么用它

- 让聊天应用变成编程 agent。 Claude Desktop——或任何 MCP 聊天客户端——
用你已有的订阅直接获得真实的仓库访问能力，无需额外产品。
- 安全是产品本身，不是附加项。 每个服务器进程绑定一个工作区根目录；
绝对路径、.. 穿越、符号链接逃逸一律拒绝；权限模式对网络访问、shell
展开、内联脚本和破坏性命令逐项把关；Linux 上还有
Landlock 提供内核级文件系统隔离。
- 模型与厂商中立。 如实标注、感知权限模式的工具目录——没有 profile
切换，没有注解把戏。随意更换模型或客户端，运行时契约保持不变。
- 为上下文窗口精打细算。 工具结果按设计做摘要、分页与封顶；在确定性
dogfood 工作负载上，序列化结果字节数相比上一版本下降 37%，任务完成率不变。

快速开始

用你手头已有的工具链启动（服务器本体是 PyPI 上的 Python ≥ 3.11 包；
npm 包是一个轻量启动器，会通过 uv 或 pipx 拉起服务器）：

uvx coding-tools-mcp --stdio --workspace /path/to/repo   # Python 工具链
npx coding-tools-mcp --stdio --workspace /path/to/repo   # Node 工具链

接入 Claude Desktop、Claude Code、Codex、Cursor、VS Code、Windsurf、
Gemini CLI 或 Cline——各家的 JSON 配置完全相同（偏好 Node 的话把 uvx
换成 npx 即可）：

{
"mcpServers": {
"coding-tools": {
"command": "uvx",
"args": ["coding-tools-mcp", "--stdio", "--workspace", "/path/to/repo"]
}
}
}

然后对你的客户端说一句："跑一下测试，把第一个失败修了。"

想用 HTTP？去掉 --stdio，服务器就在
http://127.0.0.1:8765/mcp 上讲 Streamable HTTP。两代协议在两种 transport
上同时提供：完整支持 MCP 2026-07-28（对外声明的 capability 只有 tools），
同时继续支持握手时代的 2025-11-25 与 2025-06-18；两代都没有会话。
一行安装脚本、各客户端的完整接入指南和排障见
docs/quickstart.md 与
docs/mcp-client-config.md。

七个值得一试的玩法

1. 让 Claude Desktop 成为你的编程 agent。
上面那份配置就是全部——你已经在付费的聊天窗口，现在能读代码、打补丁、跑测试、看 diff。

2. 随时随地连回自己的电脑写代码。

CODING_TOOLS_MCP_AUTH_MODE=bearer ./integrations/tunnels/tunnel.sh cloudflared /path/to/repo

回环地址绑定 + 带认证的 HTTPS 隧道（cloudflared、ngrok 或 Microsoft Dev
Tunnel）。手机上打开 claude.ai，指向 https:///mcp，就能驱动家里的
工作站。ChatGPT 与 Grok 通过各自的连接器设置同样接入。内置 Bearer token 与
OAuth 2.1 + PKCE（含 RFC 7591 动态注册）。
→ docs/remote-mcp.md

3. 在一次性 Docker 沙箱里放心跑可疑代码。

docker build -t coding-tools-mcp-sandbox:local .
docker run --rm --init -it -p 8765:8765 -v "$PWD:/workspace" coding-tools-mcp-sandbox:local

容器化的服务器，工具链和缓存都预配好——放心把 agent 指向一个来路不明的
PR，用完即毁。→ docs/docker.md

4. 一个 MCP 调用，起一台云沙箱。内置的
Cloudflare Worker 控制面 把
start_coding_tools_sandbox 暴露为 MCP 工具：一次调用即派发 GitHub Actions
运行器，启动 Docker 沙箱并发布到带认证的 Cloudflare Tunnel 之后。
临时算力，无需自备服务器。

5. 用图形界面操作。

python -m pip install "coding-tools-mcp[desktop]"
coding-tools-mcp-desktop

按工作区管理配置、一键启停服务器与隧道、凭证设置带剪贴板助手、实时健康
检查。支持英文与简体中文。

6. 保持一个活着的交互式命令。exec_command 在真实 PTY 下启动 REPL 或
调试器；write_stdin 跨轮次喂输入；read_output 分页读取长输出；
kill_command 干净收尾。长时进程是一等公民，配有命令看门狗与有界缓冲。

7. 给自研 agent 装上生产级的"手"。用 Anthropic SDK 或任何框架搭 agent
循环？别再手写文件和执行工具——对着这个服务器讲 MCP，整个安全边界直接
继承。→ docs/embedding.md

工具目录

注册表包含 19 个如实标注的工具。默认的 safe 与 trusted 模式对外声明
18 个；dangerous 还会声明 request_permissions，也只有该模式下这个工具
才能授予权限。apply_patch 与 apply_changes 都是文件修改原语：分阶段、
基线校验、跨文件原子提交并支持回滚。

| 分组 | 工具 |
| --- | --- |
| 文件与搜索 | read_file · list_dir · list_files · search_text · apply_patch · apply_changes · view_image |
| 执行 | exec_command · write_stdin · read_output · kill_command · request_permissions（仅 dangerous） |
| Git | git_status · git_diff · git_log · git_show · git_blame |
| 运行时 | server_info · check_exec_environment |

仓库根部的 AGENTS.md/CLAUDE.md 会自动载入，并随 initialize 的
instructions 下发；不握手的客户端则通过 server/discover 拿到同一份内容。
工具的 content 是给 agent 看的精炼文本，structuredContent 则是完整稳定的
机器结果。Schema 与结果封装：
docs/tools-and-schemas.md ·
docs/runtime-contract-v0.3.md

安全边界

| 模式 | 适用场景 | 放行范围 |
| --- | --- | --- |
| safe（默认） | 日常 agent 工作 | 文件工具与常规命令；疑似联网命令、shell 展开、内联脚本、破坏性命令均需显式授权 |
| trusted | 本地开发 | 放开网络、shell 展开与内联脚本；保留敏感值过滤与破坏性命令检查 |
| dangerous | 仅限隔离容器/虚拟机 | 关闭 exec_command 权限门；工作区路径边界依然生效 |

递归列举与搜索默认排除 .git、node_modules、构建产物、虚拟环境和常见
缓存。命令在工作区限定的 cwd 下运行，环境经过清洗，带超时与输出上限。
支持 Landlock 的 Linux 主机获得内核级文件系统隔离；其他平台会收到明确
警告——这仍不是完整的操作系统级沙箱，真正不可信的工作请用 Docker 镜像或
虚拟机。详见：
SECURITY.md · docs/security-boundary.md ·
docs/permission-modes.md

遥测

服务器会发送匿名使用遥测（每工具的成功率/延迟计数与版本/平台维度——
绝不包含路径、参数、命令或文件内容），用于确定修复优先级。设置
CODING_TOOLS_MCP_TELEMETRY=off 或 DO_NOT_TRACK=1 可关闭；CI 环境自动
关闭。CODING_TOOLS_MCP_TELEMETRY=debug 会把每个事件打印到 stderr 而不
发送。完整事件清单与承诺见 docs/telemetry.md。

证据、Dogfood 与 SWE-bench

每个版本都经由 tag 触发的流水线发布：合规套件、真实工作负载基准和
SWE-bench 评测与 registry 发布运行在同一个 commit 上——PyPI 与 npm 均走
trusted publishing，npm 带 provenance。Dogfood 效率指标可复现
（make dogfood-smoke），报告存于 reports/。本仓库不宣称任何模型生成的
SWE-bench 榜单成绩——docs/swe-bench.md 写明了测了什么、
没测什么。更多：COMPLIANCE.md ·
BENCHMARK.md · docs/dogfood.md

文档

| | |
| --- | --- |
| 文档导航 | 按主题浏览文档 |
| 上手 | 快速开始 · 客户端配置 · 排障 |
| 远程与沙箱 | Remote MCP · Docker 沙箱 · 云沙箱 Worker |
| 工具与契约 | 工具与 Schema · 运行时契约 · 迁移到 0.3 · 权限模式 |
| 命令执行 | Exec 配方 · Exec 排障 |
| 集成 | 嵌入指南 · npm 启动器 |
| 安全与质量 | 安全策略 · 安全边界 · CI 与测试 · 已知限制 · 竞品分析 |

开发

python -m pip install -e ".[dev]"
make ci        # lint、类型检查、测试、协议/集成套件与各项门禁

完整门禁矩阵见 docs/ci-and-tests.md。

许可证

本项目基于 Apache License 2.0 发布。

如果你使用了本项目的代码、文档、实质性实现细节或衍生成果，请保留版权
声明、许可证声明与 NOTICE 文件，并清晰注明出处。

Project: Coding Tools MCP
Author: Coding Tools MCP Contributors
Source: https://github.com/xyTom/coding-tools-mcp

引用元数据见 CITATION.cff。