编程工具 MCP xyTom/coding-tools-mcp

Coding Tools MCP

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

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://<tunnel-host>/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。