Coding Tools

Coding Tools MCP

英文 | 简体中文

为任何 AI 聊天应用或 Agent 提供安全操作代码库的能力。

Coding Tools MCP 是一个与模型无关的编码运行时，通过 Model Context Protocol 提供服务：文件读取与 搜索、结构化的多文件补丁、命令执行、交互式会话以及 git——一个 MCP 服务，任何 MCP 客户端都能驱动。Claude Desktop、 Claude Code、Codex、Cursor、Cline、VS Code、Windsurf、Gemini CLI，或你自行构建的 Agent，都能使用默认目录中的 18 个经过实战检验的工具；这些工具仅限于一个工作区，并受权限模式管控。

为什么大家会使用它

• 它能将聊天应用变成编码 Agent。 Claude Desktop——或任何 MCP 聊天客户端——都能借助你已有的订阅真正访问代码库。 无需额外产品。
• 安全性是产品的核心，而非事后补充。 每个服务只有一个工作区根目录。绝对路径、.. 遍历和符号链接逃逸都会被拒绝。 权限模式会限制网络访问、Shell 展开、内联脚本和 破坏性命令。在 Linux 上，Landlock 还会增加 内核级文件系统隔离。
• 它与模型和供应商无关。 工具目录如实标注并感知模式——无需切换配置，也无需玩标注把戏。你可以自由更换模型或客户端， 运行时契约始终不变。
• 它专为上下文窗口而设计。 结果会经过摘要、分页处理，并受到大小限制；在确定性的内部实测工作负载中，每次发布的序列化工具结果字节数减少了 37%，而任务完成情况保持不变。

快速开始

使用你现有的工具链运行（服务端要求 Python ≥ 3.11，可从 PyPI 安装；npm 包是一个轻量启动器，会通过 uv 或 pipx 启动服务端）：

uvx coding-tools-mcp --stdio --workspace /path/to/repo   # Python toolchain
npx coding-tools-mcp --stdio --workspace /path/to/repo   # Node toolchain

将其接入 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。两种协议时期都支持这两种传输方式：完整支持 MCP 2026-07-28，且仅公布 tools 这一项能力；同时支持握手时期的 2025-11-25，并兼容 2025-06-18。两者都不使用会话。单行安装器、各客户端的操作指南和故障排查内容见 docs/quickstart.md 和 docs/mcp-client-config.md。

七件值得尝试的事

1. 将 Claude Desktop 变成你的编码 Agent。 只需使用上面的配置——你已经付费使用的聊天窗口现在可以读取、修改、测试真实代码仓库，并审查提交。

2. 随时随地在自己的机器上编写代码。

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

绑定到 Loopback + 通过经过身份验证的 HTTPS 隧道（cloudflared、ngrok 或 Microsoft Dev Tunnel）连接。在手机上的 claude.ai 中，将 https://<tunnel-host>/mcp 设为连接目标，即可随时随地操控家中的工作站。 ChatGPT 和 Grok 也可以通过各自的连接器设置以相同方式连接。 内置 Bearer 令牌和 OAuth 2.1 + PKCE（采用 RFC 7591 动态注册）。→ docs/remote-mcp.md

3. 在一次性沙箱中，让 Agent 处理不受信任的代码。

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

容器化的服务已预配置工具链和缓存，可安全地用于有风险的 PR，之后可将其销毁。→ docs/docker.md

4. 通过一次 MCP 调用启动云端沙箱。 随附的 Cloudflare Worker 控制平面将 start_coding_tools_sandbox 作为 MCP 工具提供：一次调用即可派发 GitHub Actions runner，启动 Docker 沙箱，并通过经过身份验证的 Cloudflare Tunnel 发布。 使用临时计算资源，无需自备服务。

5. 通过 GUI 操控。

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 包含完整的机器结果。架构和结果封装格式：docs/tools-and-schemas.md · docs/runtime-contract-v0.3.md。

安全边界

模式	适用场景	允许的操作
safe（默认）	日常 Agent 工作	文件工具和经过审核的命令；看起来会访问网络的命令、Shell 扩展、内联脚本和破坏性命令均需要明确许可
trusted	本地开发	允许访问网络、使用 Shell 扩展和内联脚本；保留机密过滤和破坏性命令检查
dangerous	仅限隔离的容器/VM	禁用 exec_command 权限门控；仍受工作区路径边界限制

递归列出和搜索时会排除 .git、node_modules、构建输出、 虚拟环境和缓存。命令在工作区范围内的 cwd 中运行，环境经过清理， 并设有超时和输出上限。使用 Landlock 的 Linux 主机会获得 由内核强制执行的文件系统隔离；其他平台会显示明确警告——这并非 完整的 OS 沙箱，因此对于真正不受信任的工作，请使用 Docker 镜像或 VM。详情： 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

每次发布都会通过由标签触发的流水线完成，合规 测试套件、真实工作负载基准测试和 SWE-bench 测试框架均从同一提交运行， 并通过可信发布发布到 PyPI 和 npm——两者均使用可信发布，npm 还带有 来源证明。Dogfood 效率指标可复现（make dogfood-smoke）， 并已提交至 reports/。本仓库不声称拥有由模型生成的 SWE-bench 排行榜结果——请参阅 docs/swe-bench.md，了解具体测量了哪些内容以及未测量哪些内容。更多信息：COMPLIANCE.md · BENCHMARK.md · docs/dogfood.md

文档

文档索引	按主题浏览文档
开始使用	快速入门 · 客户端配置 · 故障排查
远程与沙箱	远程 MCP · Docker 沙箱 · 云端沙箱工作进程
工具与契约	工具和架构 · 运行时契约 · 迁移到 0.3 · 权限模式
执行	Exec 配方 · Exec 故障排查
集成	嵌入 · npm 启动器
安全与质量	安全政策 · 安全边界 · CI 和测试 · 限制 · 竞品分析

开发

python -m pip install -e ".[dev]"
make ci        # lint, typecheck, tests, protocol/integration suites, gates

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

许可证

本项目根据 Apache License 2.0 授权。

如果你使用本项目的代码、文档、实质性实现细节或衍生作品， 请保留版权声明、许可证 声明和 NOTICE 文件，并明确注明原项目。

项目：Coding Tools MCP
作者：Coding Tools MCP Contributors
源码：https://github.com/xyTom/coding-tools-mcp

引用元数据见 CITATION.cff。