Coding Tools MCP

简体中文（默认） · English version is folded below

让 ChatGPT、Claude Desktop 或任何支持 MCP 的 AI 客户端，真正能在你的代码仓库里读文件、改代码、跑命令、看 Git，并在可信个人开发机上调用本地 Agent。

这是 Coding Tools MCP 的 0.7 Workbench downstream 分支。 项目基于 Apache-2.0 的 xyTom/coding-tools-mcp 演进，保留 upstream Git 历史、LICENSE 和 NOTICE；在此基础上加入了大量 Windows、并发/OAuth、personal_workstation、Agent Transport 与项目连续性相关工作。

这东西是干什么的？

一句话：给 AI 一双可以安全操作你电脑上代码仓库的“手”。

它通过 Model Context Protocol (MCP) 提供一个模型无关的本地编程运行时，包括：

• 读取、搜索、列目录与结构化多文件补丁；

• 执行命令、持续交互式终端、读取长任务输出；

• Git status / diff / log / show / blame；

• 并发协调、资源锁、lease 与 owner-scoped 长任务；

• OAuth 2.1 / PKCE / Dynamic Client Registration；

• 可选的 Host 文件系统、Memo/ledger、Windows CUA；

• Agent Transport：当前已支持 Antigravity + OpenCode 的 status / send / read / continue / abort；

• 面向可信个人开发机的 personal_workstation 模式。

实际某台机器暴露哪些可选能力，以该实例的 server_info / tools/list 为准。

现在是什么状态？

当前公开版本：v0.7.0-workbench.1。

这条 0.7 代码线已经完成 source/local gate，并在维护者 Windows 机器上经过真实 ChatGPT Connected App staging 验证。Antigravity 与 OpenCode 的 capability discovery、首次调用、同 session/conversation continuation、exact-job abort 与 cleanup 都经过机器证据验证。

公开仓库默认分支 main 已完成一次独立 public-release gate；GitHub Release 同时提供固定版本的 Python wheel 与 sdist。

这不代表“所有机器、所有 MCP 客户端都已经验证”。遇到新环境问题欢迎直接开 Issue 或 Discussion。

最简单的使用方式

方式 A：Windows 直接 clone 后启动（推荐）

git clone https://github.com/biaobiao2233/coding-tools-mcp-workbench.git
cd coding-tools-mcp-workbench
.\scripts\start-workbench.ps1 -Workspace C:\你的\代码仓库

这个启动器默认使用我们当前 Workbench 配置：

• personal_workstation；

• Agent Transport 开启；

• telemetry 默认关闭；

• 破坏性 Git / 递归删除仍需显式授权。

如果想启动本机 HTTP MCP：

.\scripts\start-workbench.ps1 -Workspace C:\你的\代码仓库 -Transport http -Port 8765

方式 B：直接安装 GitHub Release wheel

不想 clone 整个仓库，也可以直接安装固定版本：

python -m pip install https://github.com/biaobiao2233/coding-tools-mcp-workbench/releases/download/v0.7.0-workbench.1/coding_tools_mcp-0.7.0-py3-none-any.whl

然后：

coding-tools-mcp --permission-mode personal_workstation --stdio --workspace C:\你的\代码仓库

当前 没有 用这个 downstream 去重新发布 upstream 的 PyPI/npm 包名。uvx coding-tools-mcp / npx coding-tools-mcp 目前仍可能解析到 upstream 包；想确保使用本项目，请从 GitHub clone 或使用上面的 Release wheel。

MCP 客户端配置示例

Windows 上可以让客户端直接调用 checkout 里的启动器：

{
  "mcpServers": {
    "coding-tools": {
      "command": "pwsh",
      "args": [
        "-NoProfile",
        "-File",
        "C:\\path\\to\\coding-tools-mcp-workbench\\scripts\\start-workbench.ps1",
        "-Workspace",
        "C:\\你的\\代码仓库"
      ]
    }
  }
}

然后就可以直接对 AI 说：“跑一下测试，把第一个失败修掉。”

为什么我们做这个 downstream？

原始项目已经提供了很扎实的 MCP coding runtime。我们主要沿着下面几条线继续往前推：

1. Personal Workstation：让可信个人开发机不再因为过度保守的默认权限处处卡住，同时保留真正危险操作的门禁。

2. Windows 可靠性：Job Object、进程树所有权、bounded scan、managed runner/watchdog、release/rollback。

3. 真实 ChatGPT Connected App：不仅本地自测，还要求在真实 Connector 环境里验证 OAuth、工具契约与生命周期。

4. Agent Transport：让 MCP 不只是“执行 shell”，还可以统一驱动 Antigravity、OpenCode，未来计划增加 Claude Code。

5. Project Continuity / Workbench：把 Worker Claim、独立 Review、Candidate、Accepted State 分开，避免“AI 说做完了”就自动算通过。

我们参考过哪些项目？

这里特意区分 代码血缘 / API 集成 / 设计启发，避免把“学过一个项目的思想”说成“用了它的源码”。

完整说明见 代码血缘、Prior Art 与设计影响。

安全边界

真正不可信的代码仍建议放 Docker / VM。详细边界见 SECURITY.md 与 docs/security-boundary.md。

遥测

这个 downstream 的遥测默认关闭。只有操作者明确设置 telemetry=on，并同时提供自己控制的 HTTPS endpoint + write-only key，才会发送事件。DO_NOT_TRACK=1 和 CI 会强制关闭。

中文文档导航

下面这些核心入口现在都是中文默认、英文折叠在同一文件下方：

• 快速开始

• 路线图 / Roadmap

• 贡献指南

• 代码血缘、Prior Art 与设计影响

更底层的协议契约、测试报告、Schema 文档仍以英文为主，避免和代码/API 名称发生翻译漂移：

• 工具与 Schema

• Runtime Contract

• 权限模式

• 远程 MCP

• Windows Managed Runner

• 排障

Roadmap

接下来主要研究/实现方向：

• Claude Code Agent Transport provider；

• provider plug-in boundary；

• Orca optional orchestration backend；

• Web ChatGPT-supervised long-running workbench；

• 多机器、签名/可复现发行物、Linux/macOS parity。

详细进度见 ROADMAP.md。

参与贡献

特别欢迎这些方向：Windows portability、Agent provider adapter、OAuth/Connected App 互操作、权限/进程生命周期 adversarial testing、Orca 集成实验、Linux/macOS 隔离，以及中文/英文文档完善。

见 CONTRIBUTING.md。

许可证与来源

本项目使用 Apache License 2.0。请保留版权声明、许可证声明与 NOTICE。

Downstream：https://github.com/biaobiao2233/coding-tools-mcp-workbench Upstream：https://github.com/xyTom/coding-tools-mcp

Coding Tools MCP

English | 简体中文

Give any AI chat or agent a safe pair of hands on your codebase.

Downstream 0.7 workbench branch. This codebase is derived from xyTom/coding-tools-mcp under Apache-2.0 and preserves the upstream history and attribution. The downstream branch adds substantial Windows/runtime/agent-transport work. It is currently shared from source; the upstream PyPI/npm package names are intentionally not republished by this fork yet. See Lineage and design influences.

Coding Tools MCP is a model-neutral coding runtime served over the Model Context Protocol: file reading and search, structured multi-file patches, command execution, interactive sessions, git, optional reviewed host access, concurrency/resource leases and local-agent transport — one server that an MCP client can drive. The runtime catalog is capability-gated: server_info is the source of truth for which optional host/Memo/CUA/Agent tools are exposed on one installation.

Downstream 0.7 status

The exact source baseline b0f44ef... has passed local/source gates and a real ChatGPT Connected-App staging trial on the maintainer's Windows machine. In that environment, Antigravity and OpenCode capability discovery remained machine-verifiable, both provider continuation paths worked, and exact-job abort/cleanup were exercised.

That does not mean every machine/client is proven. The GitHub-source public release gate has now passed, the downstream repository is public, and v0.7.0-workbench.1 is available as a GitHub Release with wheel + sdist artifacts. Production promotion remains a separate gate in this project's development process.

Highlights added by the downstream line include:

• Windows Job Object/process-lifecycle hardening and bounded scan behavior;

• server-global concurrency coordination, resource locks and leases;

• authenticated owner-scoped long-running jobs across short-lived HTTP calls;

• ChatGPT-oriented OAuth refresh/restart hardening;

• opt-in personal_workstation mode for trusted developer machines;

• optional host-root, Memo/ledger and Windows computer-use surfaces;

• Agent Transport for Antigravity and OpenCode with machine-backed capability discovery, provider session correlation, continuation and cancellation.

See ROADMAP.md for what is validated versus still research.

Why people use it

• It turns a chat app into a coding agent. Claude Desktop — or any MCP chat client — gets real repo access with the subscription you already have. No extra product required.

• Safety is the product, not an afterthought. One workspace root per server. Absolute paths, .. traversal, and symlink escapes are rejected. Permission modes gate network access, shell expansion, inline scripts, and destructive commands. On Linux, Landlock adds kernel-level filesystem confinement.

• It is model- and vendor-neutral. A fixed, truthfully annotated catalog — no profile switching, no annotation games. Swap models or clients freely; the runtime and its behavior stay put.

• It is engineered for context windows. Results are summarized, paginated, and capped by design; serialized tool-result bytes dropped 37% release-over-release on the deterministic dogfood workload with unchanged task completion.

Quickstart — downstream source checkout

Windows: run the accepted Workbench profile directly

Clone this downstream repository, then run:

.\scripts\start-workbench.ps1 -Workspace C:\path\to\your\repo

This launcher starts the accepted Workbench profile rather than the upstream restricted default: personal_workstation permission mode, Agent Transport enabled, and telemetry off. Destructive Git operations and recursive filesystem deletion still require explicit permission. Antigravity and OpenCode are optional: the MCP server starts without them, while agent_status reports whichever providers are actually installed on the machine.

For a loopback HTTP endpoint instead of stdio:

.\scripts\start-workbench.ps1 -Workspace C:\path\to\your\repo -Transport http -Port 8765

The script uses uv when available. Otherwise it creates a local .workbench-venv, installs this checkout, and launches the exact code cloned from GitHub.

Install from this checkout, or use the fixed GitHub Release wheel, rather than the upstream PyPI/npm names:

git clone https://github.com/biaobiao2233/coding-tools-mcp-workbench.git
cd coding-tools-mcp-workbench
python -m pip install -e .

uvx coding-tools-mcp and npx coding-tools-mcp currently refer to the upstream published packages, not this downstream 0.7 branch.

Fixed Release wheel:

python -m pip install https://github.com/biaobiao2233/coding-tools-mcp-workbench/releases/download/v0.7.0-workbench.1/coding_tools_mcp-0.7.0-py3-none-any.whl

On Windows, point MCP clients at the checkout launcher so the client receives the downstream Workbench build rather than the upstream registry package:

{
  "mcpServers": {
    "coding-tools": {
      "command": "pwsh",
      "args": [
        "-NoProfile",
        "-File",
        "C:\\path\\to\\coding-tools-mcp-workbench\\scripts\\start-workbench.ps1",
        "-Workspace",
        "C:\\path\\to\\your\\repo"
      ]
    }
  }
}

Then ask your client: "run the test suite and fix the first failure."

Prefer HTTP? Drop --stdio and the server speaks Streamable HTTP on http://127.0.0.1:8765/mcp (MCP 2025-11-25, with 2025-06-18 compatibility). A one-line installer, per-client walkthroughs, and troubleshooting live in docs/quickstart.md and docs/mcp-client-config.md.

Seven things to try

1. Make Claude Desktop your coding agent. The config above is all it takes — the chat window you already pay for can now read, patch, test, and commit-review a real repository.

2. Code on your own machine from anywhere.

CODING_TOOLS_MCP_AUTH_MODE=bearer ./scripts/tunnel.sh cloudflared /path/to/repo

Loopback bind + authenticated HTTPS tunnel (cloudflared, ngrok, or Microsoft Dev Tunnel). Point claude.ai on your phone at https://<tunnel-host>/mcp and drive your home workstation from anywhere. Bearer tokens and OAuth 2.1 + PKCE (with RFC 7591 dynamic registration) are built in. → docs/remote-mcp.md

3. Let an agent loose on untrusted code — inside a disposable sandbox.

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

A containerized server with toolchains and caches preconfigured, safe to point at a sketchy PR and destroy afterwards. → docs/docker.md

4. Spin up a cloud sandbox with one MCP call. The bundled Cloudflare Worker control plane exposes start_coding_tools_sandbox as an MCP tool: one call dispatches a GitHub Actions runner that boots the Docker sandbox and publishes it behind an authenticated Cloudflare Tunnel. Ephemeral compute, no server of your own.

5. Drive it from a GUI.

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

Per-workspace profiles, server and tunnel start/stop, credential setup with clipboard helpers, live health checks. English and 简体中文.

6. Keep an interactive session alive. exec_command starts a REPL or debugger under a real PTY; write_stdin feeds it across turns; read_output pages long output; kill_session cleans up. Long-running processes are first-class, with deadline watchdogs and bounded buffers.

7. Give your own agent production-grade hands. Building an agent loop with the Anthropic SDK or anything else? Don't hand-roll file and exec tools — speak MCP to this server and inherit the whole safety boundary. → docs/embedding.md

The tool catalog

One truthfully annotated runtime catalog. Optional capability groups can be hidden when their reviewed dependency/configuration is absent; the catalog is stable for the lifetime of one server. apply_patch is the sole direct workspace file-mutation primitive: staged, baseline-checked, atomic across files, with rollback.

Root AGENTS.md/CLAUDE.md files load into the initialize context automatically. Tool content is concise agent-facing text; structuredContent carries the complete machine result. Schemas and result envelopes: docs/tools-and-schemas.md · docs/runtime-contract-v0.2.md.

Safety Boundary

Recursive listing and search exclude .git, node_modules, build outputs, virtualenvs, and caches. Commands run with workspace-bound cwd, scrubbed environment, timeouts, and output caps. Linux hosts with Landlock get kernel-enforced filesystem confinement; other platforms get an explicit warning — this is still not a complete OS sandbox, so use the Docker image or a VM for genuinely untrusted work. Details: SECURITY.md · docs/security-boundary.md · docs/permission-modes.md

Telemetry

Telemetry is off by default in this downstream branch. The implementation can be enabled only by explicitly setting telemetry to on and supplying an operator-owned HTTPS endpoint and write-only ingest key. DO_NOT_TRACK=1 and CI still force it off; CODING_TOOLS_MCP_TELEMETRY=debug prints events to stderr without sending. The closed event schema and guarantees are documented in docs/telemetry.md.

Evidence, Dogfood and SWE-bench

Every release ships through a tag-triggered pipeline in which the compliance suite, real-workload benchmark, and SWE-bench harness run from the same commit that publishes to PyPI and npm — both via trusted publishing, npm with provenance. Dogfood efficiency metrics are reproducible (make dogfood-smoke) and checked in under reports/. This repository does not claim a model-generated SWE-bench leaderboard result — see docs/swe-bench.md for exactly what is and is not measured. More: COMPLIANCE.md · BENCHMARK.md · docs/dogfood.md

Documentation

Development

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

The full gate matrix is in docs/ci-and-tests.md.

License

This project is licensed under the Apache License 2.0.

If you use code, documentation, substantial implementation details, or derivative work from this project, preserve the copyright notice, license notice, and NOTICE file, and clearly attribute the original project.

This downstream branch is based on xyTom/coding-tools-mcp and retains that project's history and Apache-2.0 obligations. See docs/LINEAGE_AND_INFLUENCES.md for a separation of direct code lineage, API integrations and design prior art.

Project: Coding Tools MCP
Author: Coding Tools MCP Contributors
Downstream source: https://github.com/biaobiao2233/coding-tools-mcp-workbench

Upstream source: https://github.com/xyTom/coding-tools-mcp

Citation metadata is available in CITATION.cff.