coding-tools-mcp-js

一个面向个人多台 macOS 电脑使用的 TypeScript MCP 编码运行时。

项目采用全信任模式：工具可以访问当前用户有权限访问的任意路径，并可执行任意 shell 命令。它不提供 workspace 沙箱、命令审批或权限分级，只应运行在自己控制的电脑上。

Quick start

Run the local full-trust MCP runtime with one command:

npx coding-tools@latest

During local development in this repository:

pnpm build
node dist/cli.js

The CLI starts a background runtime bound to 127.0.0.1, stores runtime state under ~/.coding-tools, and prints the local MCP URL. The default command is idempotent: running it again reports the existing runtime instead of starting a duplicate.

The background runtime does not reserve a fixed local port. By default the operating system assigns an available loopback port at startup; the daemon records that actual port and the cloud tunnel forwards to it. The public device MCP URL is unaffected.

npx coding-tools@latest status
npx coding-tools@latest logs
npx coding-tools@latest restart
npx coding-tools@latest stop

The runtime only needs to run while an AI client is actually using this computer. When a client reports the computer as offline, coding-tools restart is the fix — it reuses the existing credentials, so the MCP URL never changes and no new enrollment is needed. Run from inside the managed runtime itself (for example through one of its own tools), restart hands off to a detached helper and returns before the replacement daemon exists, so it reports the restart as scheduled rather than done; confirm with coding-tools status and check logs if the replacement does not appear.

The runtime is intentionally full trust. Filesystem, repository, search, image, patch, and command tools accept absolute paths plus ~/ and $HOME/ paths, and can access anything available to the current operating-system user. There is no workspace root, mutable session working directory, or path sandbox.

当前能力

服务通过 Streamable HTTP 暴露 30 个工具：

• 文件与搜索：read_file、list_dir、list_files、search_text、apply_patch、view_image
• 命令：exec_command、write_stdin、read_output、kill_command；kill_session 作为旧客户端兼容别名保留
• Git：git_status、git_diff、git_log、git_show、git_blame
• Runtime：get_system_paths、check_exec_environment、server_info
• Codex MCP bridge：codex_mcp_list、codex_mcp_call、codex_mcp_release。它们按需启动本机 Codex app-server，并直接列出、调用已挂载 MCP；同一 direct interaction sequence 共用一个 synthetic turn，最后由 codex_mcp_release 统一结束。不会主动启动真实 Codex turn。未安装兼容 Codex 时，其余 coding-tools 工具仍可正常使用。
• Claude local bridge：claude_mcp_list、claude_mcp_call、claude_mcp_release。主 AI 只看到这 3 个入口，按需访问 Claude 原生 Browser Use（22 个工具）或 Computer Use（42 个工具）；执行层不启动 Claude 模型，也不要求 Claude 登录。
• 统一 Computer 路由：computer_control_call、computer_control_release。优先使用可用的本地 Computer backend；平台不支持的可选能力只返回 unavailable/unsupported，不影响核心 MCP 启动。computer_control_release 只释放 Computer 能力（Codex Computer Use native/session 收尾 + Claude Computer 会话与授权），不会结束同一 session 共享的 Codex direct turn，因此不会顺带拆掉正在使用的 Browser tab；结束整个 turn 仍用 codex_mcp_release。
• 配置 MCP 网关：mcp_list、mcp_call、mcp_release。从 coding-tools 配置目录的 mcp.json 按需连接其他 MCP，第一版支持 stdio 与 Streamable HTTP；某个可选 MCP 配错或连接失败不会影响 coding-tools 其他工具启动。

配置其他 MCP

默认配置文件为 ~/.coding-tools/mcp.json；设置 CODING_TOOLS_HOME 时使用该目录下的 mcp.json。格式沿用常见的 mcpServers：

{
  "mcpServers": {
    "local-demo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": {
        "TOKEN": "..."
      }
    },
    "remote-demo": {
      "type": "streamable-http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ..."
      }
    }
  }
}

type 可以省略：存在 command 时按 stdio，存在 url 时按 Streamable HTTP。mcp_list() 只读取配置，不会为了探测状态把所有服务启动起来；mcp_list(server="...") 才会按需连接并返回下游 tools。连接会在进程内复用，mcp_release(server="...") 关闭一个连接，不传 server 时关闭全部。已经打开的连接不会因为磁盘上的配置刚被修改而自动换配置，需要先 mcp_release 或重启 coding-tools。

单个 server 配置无效时，mcp_list() 会把它标为 invalid，其他配置仍可使用。Streamable HTTP 的 URL / headers 和 stdio 的 env 不会出现在 mcp_list() 返回里，避免把配置中的凭据带进模型上下文。第一版不实现第三方 MCP 的 OAuth 授权流程；需要鉴权的 HTTP MCP 先使用 URL 自带凭据或 headers。

Codex MCP bridge 与真实 Codex turn

codex_mcp_list / codex_mcp_call 是 Codex app-server 的直接 MCP bridge，不等同于运行一次完整的 Codex agent turn。codex_mcp_call 不会启动 Codex 模型；主 Agent 始终是调用 coding-tools 的 AI。

给 AI 的最简判断规则：需要的是 Codex 已挂载的本机工具能力，就用 codex_mcp_list / codex_mcp_call；只有用户明确要求“把任务交给 Codex 去做”时，才启动真实 Codex Agent。 不要因为某个本机能力来自 Codex，就默认执行 codex exec。

为了兼容依赖 Codex turn metadata 的本地 runtime，coding-tools 会在 codex_mcp_call 上自动附加非模型 direct turn context：session_id 使用当前 app-server thread id，并同时带上 thread_id / thread_source。同一个 coding-tools MCP transport session 中，一段连续的 codex_mcp_call 会跨 MCP server 复用同一个 synthetic turn_id，直到显式 codex_mcp_release 或 idle cleanup。这个 context 只提供运行时生命周期标识，不会执行 turn/start，也不会调用 Codex 模型。

Windows 上已验证官方 Codex Chrome Plugin 可以通过这条路径直接发现并读取当前 Chrome 标签页：调用方 AI 负责推理和编排，node_repl / Browser runtime / Chrome Plugin 只作为本机工具层参与。其他平台仍应以当前主机实际安装的 Codex 插件和后端能力为准。

对调用方 AI 来说，一个容易误判的点是：Chrome/Browser 不一定会以独立的 chrome / browser MCP server 出现在 codex_mcp_list 结果里。 在已经验证的 Codex Chrome Plugin 环境中，它通常是通过 node_repl 加载 Codex Browser runtime 后使用。因此“只看到 node_repl、没看到 chrome server”不能直接判定 Chrome 不可用。

Chrome 的最小 direct-call 流程是：先定位当前主机已安装的 openai-bundled/chrome/<version>/scripts/browser-client.mjs（版本必须动态发现，不要硬编码），然后通过 codex_mcp_call(server="node_repl", tool="js") 在 Node REPL 中 import 其中的 setupBrowserRuntime，执行 setupBrowserRuntime()，再 agent.browsers.get("chrome")。需要接管用户已打开的标签页时，先 chrome.user.openTabs()，按返回对象中的可见 title / URL / recency 选中确切对象，再把该对象传给 chrome.user.claimTab(...)；不要猜 tab id。

标签页策略是调用建议，不是 runtime 限制：有匹配的现有标签页时优先复用；当前工作标签能继续完成任务时尽量复用；对照、并行查看、登录流程或需要保留上下文时可以正常新开多个 tab。coding-tools 不通过 URL/标题启发式扫描并批量关闭用户标签页。

Computer Use 的路径更直接：如果 codex_mcp_list 中存在 computer-use server，就直接 codex_mcp_call 它的 MCP tools，不需要经过 node_repl。按其 tool schema 要求，每个 assistant turn 在对某个 App 进行交互前先调用一次 get_app_state，再由当前 AI 根据截图和 accessibility tree 决定后续 click / type_text / scroll / set_value 等动作。它与同一 direct interaction sequence 内的其他 Codex MCP 调用共享 synthetic turn；任务结束后统一执行 codex_mcp_release。

不同本机能力的直接调用路径并不完全相同：

• Chrome / Browser：codex_mcp_call(server="node_repl", tool="js", ...) → 在 JS 中初始化 Codex Browser runtime → 使用已安装的官方 Chrome Plugin/浏览器后端。
• Computer Use：如果 codex_mcp_list 能看到 computer-use server，直接调用 codex_mcp_call(server="computer-use", tool=...)；不需要经过 node_repl，也不需要真实 Codex turn。按照该 MCP 自己的工具约束，每个 assistant turn 在开始操作某个 App 前先调用一次 get_app_state。

两条路径的共同原则都是：当前 AI 负责思考，Codex app-server 只提供本机工具 transport/runtime；不会因为使用这些直接 MCP 能力而自动再跑一个 Codex 模型。 如果某个下游 MCP 自己另外调用模型或收费服务，则属于该 MCP 自身行为，不是这里的 Codex Agent turn。

当 AI 需要使用本机 Codex 自己拥有的能力时，推荐按下面的顺序处理：

1. 先检查当前主机实际安装/启用的 Codex 配置、插件和后端能力，不要假设 Windows、macOS、Linux/Ubuntu 完全一致。
2. 如果目标能力可以直接作为普通 MCP 调用，则优先使用 codex_mcp_call。这条路径会自动补齐 direct-call metadata，但不会启动 Codex 模型 turn。
3. 如果能力在已经有 direct-call metadata 的情况下仍无法直接调用，应把它视为当前主机能力或 bridge 适配问题，而不是自动启动另一个 Codex Agent。
4. 不要为了获得某个 Codex 插件能力而默认使用 exec_command 启动 codex exec。那会把任务委托给另一个 Codex Agent，并可能产生额外的模型调用/额度消耗。只有用户明确要求把任务交给 Codex 执行时才这样做。
5. 不要硬编码某个操作系统的 Codex 可执行文件路径；Windows、macOS、Linux/Ubuntu 的 Codex 能力和集成方式应按当前主机实际情况判断。

如果任务明确需要复用用户当前 Chrome 的标签页、登录态或扩展状态，且当前主机的 Codex Chrome Plugin 已安装、启用并能连接 Chrome，应优先让当前 AI 通过 codex_mcp_call → node_repl → Codex Browser runtime 使用该本地能力。只有在用户明确接受 Codex Agent 参与时才使用真实 Codex turn。

如果任务需要操作本机桌面 App，并且 codex_mcp_list 显示 computer-use 已挂载，则优先直接调用该 MCP。不要先启动 Codex Agent；先按 computer-use 工具 schema 获取 app state，再由当前 AI 决定并调用 click/type/scroll 等动作。整个 direct interaction sequence 结束后调用 codex_mcp_release，不要把 runtime 生命周期留给不存在的 Codex model turn 去收尾。

codex_mcp_release 结束当前 MCP transport session 持有的整个 direct synthetic turn，而不是释放某个特定 MCP server。release 后只对这个 turn 实际用过的能力执行对应收尾：如果使用过 node_repl，发送它的 turn_ended 生命周期事件；如果使用过 Computer Use，则执行现有 native/session cleanup。多个 transport session 仍然相互隔离；如果另一个 direct turn 正在使用 Computer Use，不会为了当前 turn 强停共享服务。旧调用形式中的 server 参数继续接受，但只作为兼容字段，不再限定 release 范围。release 会先等该 turn 里仍在执行的调用真正结束再收尾（不设人为上限，单次调用本身已受 MCP_BRIDGE_REQUEST_TIMEOUT_MS 约束），避免在操作进行中结束 turn。node_repl/turn_ended 这类生命周期通知不复用 120 秒业务超时，默认 5 秒（MCP_BRIDGE_NODE_REPL_TURN_ENDED_TIMEOUT_MS），超时只记日志，不会把 release 卡住。调用方取消请求（MCP notifications/cancelled）或会话断开时，该次调用会立刻向调用方返回，不再占用它的等待；但 Codex app-server 协议没有提供取消 mcpServer/tool/call 的方法，工具在 Codex 侧仍会执行到底，因此这个调用在 turn 的生命周期里仍然算在执行中，release 会等它真正结束或超时后才发 turn_ended。

官方 Browser runtime 的正常收尾依赖 turn-end 生命周期。direct bridge 不会生成真实 Codex rollout，因此 codex_mcp_release / idle cleanup 会在该 direct turn 使用过 node_repl 时补发 node_repl/turn_ended。Browser runtime 再按自己的规则处理临时 agent-created tab 和 claimed user tab；coding-tools 不自己猜哪些网页属于 AI。idle cleanup 只是兜底，正常流程仍应显式 release。Computer Use 会占用 native capture/cursor，所以它的兜底窗口是 60 秒（MCP_BRIDGE_COMPUTER_USE_IDLE_CLEANUP_MS）；这一步只收尾 Computer Use，如果同一个 turn 还用过别的 server，turn 会继续存活，不会中途拆掉 Browser 已 claim 的 tab。其余 direct turn 的兜底窗口默认 15 分钟（MCP_BRIDGE_DIRECT_TURN_IDLE_CLEANUP_MS）。node_repl/turn_ended 失败时会写入 runtime 日志，不会静默吞掉。

Codex MCP bridge 的单次请求默认超时为 120 秒，可通过 MCP_BRIDGE_REQUEST_TIMEOUT_MS 覆盖。

Windows 默认通过 PATH 中的全局 codex 命令启动 Codex app-server，以保留用户已有的命令 wrapper、代理和环境配置。若显式设置 CODEX_APP_SERVER_PATH，Windows 下应指向可直接执行的原生 codex.exe；macOS/Linux 可继续指向可直接执行的 Codex 路径。

MCP transport session 共享同一个进程级命令运行时，因此后续工具调用即使落到新的 HTTP session，仍然可以继续读取和写入先前启动的命令。新调用使用 command_id；旧版 session_id 仍作为兼容别名接受。exec_command 默认保持原有 pipe 模式；只有显式传入 terminal: true 时才启用真实 PTY/TTY，并继续复用同一套 command_id、write_stdin、read_output 和 kill_command 生命周期。PTY 的合并终端输出写入 stdout，stderr 保持为空。

环境要求

• macOS
• Node.js 22 或更高版本，建议使用当前 LTS 或 Node 24
• pnpm 10.33.0；项目通过 packageManager 字段固定 pnpm 版本
• Git
• ripgrep（rg），供 search_text 使用

推荐安装方式：

corepack enable
brew install ripgrep
pnpm install --frozen-lockfile

每台电脑的配置

复制配置模板：

cp .env.example .env

然后根据该电脑修改 .env。最重要的变量如下：

| 变量 | 说明 | |---|---| | HOST | 监听地址，默认 127.0.0.1 | | PORT | HTTP 端口，默认 3456 | | MCP_AUTH_MODE | auto、none、bearer、oauth 或 bearer+oauth | | MCP_AUTH_TOKEN | 静态 Bearer token | | MCP_OAUTH_PASSWORD | OAuth 授权页面密码 | | MCP_ISSUER_URL | OAuth 对外 issuer URL；使用隧道时填写隧道地址 |

auto 会根据已配置的凭据自动选择：

• 两种凭据都没有：仅 loopback 下使用 none
• 只有 MCP_AUTH_TOKEN：bearer
• 只有 MCP_OAUTH_PASSWORD：oauth
• 两种都有：bearer+oauth

当 HOST 不是 loopback 时，服务拒绝以 none 模式启动。

运行

开发运行：

pnpm dev

pnpm dev 不是 watch 模式。修改源码后，现有进程不会自动重启；需要手动重启才能加载新代码。

构建后运行：

pnpm build
pnpm start

健康检查：

curl http://127.0.0.1:3456/health

验证

pnpm typecheck
pnpm test
pnpm build

测试覆盖补丁事务、命令会话、Git、流式文件读取、ripgrep 搜索、OAuth、Streamable HTTP session 生命周期，以及多个 MCP transport session 共享同一个进程级命令运行时的行为。

多台电脑复用

普通使用不需要 clone 仓库。每台 Mac 直接运行 npx coding-tools@latest，云端模式下从 dashboard 为那台电脑生成一次 enrollment command。设备身份、daemon 状态和固定运行时副本都保存在各自的 ~/.coding-tools 下；不同电脑不共享绝对路径或本机凭据。

.env.example、.oauth-state.json 和 ecosystem.config.cjs 只服务于仓库内开发/独立本地 OAuth 调试，不是 npm 用户的安装流程。

运行时约定

• 文件系统、搜索、图片、补丁和 Git 仓库参数接受绝对路径、~/... 和 $HOME/...。
• get_system_paths 返回当前设备的 Home、Desktop、Documents、Downloads、临时目录和卷挂载目录。
• exec_command.cwd 可省略；省略时命令在当前系统用户主目录执行。该位置不可由 MCP session 修改。
• exec_command.terminal 默认是 false，因此升级不会改变历史命令行为；交互式 CLI、REPL 或 debugger 需要 TTY 时可显式设为 true。PTY 依赖是 optional dependency，若当前安装/平台不可用会返回 PTY_UNAVAILABLE，并可去掉 terminal 继续使用 pipe 模式。
• apply_patch 会在进程级补丁锁内验证所有文件和上下文，再原子提交整个变更集；失败时回滚。末尾换行、空 context line、BOM/CRLF 和并发修改都由回归测试覆盖。
• 长时间运行的命令会返回 command_id，随后使用 write_stdin、read_output 或 kill_command。为兼容现有客户端，结果同时返回同值 session_id，write_stdin / read_output 也继续接受它，kill_session 继续可用。
• stdout/stderr 每个流保留 512 KiB：前 64 KiB 固定保留，后 448 KiB 作为滚动 tail；超大输出中被淘汰的中间区间通过 evicted_gap_bytes 明确报告。
• MCP transport session 只隔离协议 transport 生命周期；命令属于进程级 CodingRuntime，因此 ChatGPT 在后续 HTTP session 中仍可以继续 read_output / write_stdin 先前启动的命令。

明确不做

当前不实现：

• workspace 沙箱和权限审批
• request_permissions
• stdio transport 和直接进程内 transport
• Docker 和桌面 GUI
• 独立 output_ref / verbosity 机制
• 插件系统和远程 sandbox

这些取舍适用于个人受控环境，不代表通用生产部署的安全默认值。

Cloud enrollment

The Cloudflare Worker can create a short-lived enrollment command:

npx coding-tools@latest --enroll <one-time-token> --cloud-url https://app.example.com

The CLI exchanges the token for a device identity, stores the device credential in ~/.coding-tools/device.json with mode 0600, starts the local full-trust runtime, and maintains an outbound WebSocket to the device Durable Object. It never opens an inbound public port.

If the local daemon or device configuration needs to be restored, open the existing computer in the dashboard and generate a one-time restart command. Running that command rotates the device's local credentials, preserves its Device ID and public MCP URL, and starts the daemon again instead of creating a duplicate computer.

Cloud Worker development:

pnpm cloud:migrate:local
pnpm cloud:dev
pnpm cloud:typecheck
pnpm cloud:doctor

pnpm cloud:doctor checks the Worker, DNS, TLS, Worker route, OAuth discovery/PKCE/refresh support, D1, Durable Object, device tunnel, legacy MCP credential, and an MCP initialize request for the enrolled device.

Before deployment, configure the D1 database ID and Cloudflare domain values in apps/worker/wrangler.jsonc. Device MCP URLs use https://<public-id>.<zone>/mcp; the CLI automatically migrates older https://<public-id>.mcp.<zone>/mcp device files. ChatGPT connectors work either way: Mixed/OAuth against <APP_ORIGIN>/mcp/<public-id>, or No Auth against <APP_ORIGIN>/mcp/<public-id>/<no-auth-token> — both URLs are shown on the device page. The No Auth URL carries its own device-scoped token, rewritten by the Worker into the same static-Bearer check as the legacy header credential. Clients that can send custom headers should keep the token in the header instead of the URL.

The cloud dashboard uses the shared session from auth.acckm.com. The Worker binds the verified auth-hub user ID to the local D1 user row. Each computer still has one owner, one public MCP URL, one local runtime, and one outbound device tunnel, but the owner can share that same computer with additional verified Auth Hub accounts by email. Shared accounts see the same MCP URL and authorize their own OAuth grants; they can use the computer but cannot re-enroll, rotate credentials, share it onward, or delete it. Pending email shares expire after 30 days and are claimed automatically when that verified email signs in. The dashboard and API share app.acckm.com; workers.dev is disabled. See docs/cloudflare-github-deployment.md for deployment details.

Shared-account erasure is coordinated by Auth Hub through a private Worker Service Binding. Deleting a shared user's Auth Hub account revokes that user's grants and removes only that user's device access. Deleting the owner account still deletes that owner's computers, revokes every shared user's grants for those computers, disconnects and purges their Durable Object state, removes pending OAuth consent records, and then hard-deletes the Coding Tools user row so device, enrollment, credential, and sharing rows cascade away. Muster can also revoke only the OAuth grant associated with one of its dynamic client registrations before deleting its local access/refresh tokens.

Platform compatibility

The core MCP runtime is supported on macOS, Linux (including Ubuntu), and Windows. Platform-specific integrations are optional capabilities and are never startup dependencies:

| Capability | macOS | Ubuntu / Linux | Windows | | --- | --- | --- | --- | | Files, commands, patches, Git, process/session tools | Yes | Yes | Yes | | HTTP MCP + Cloud tunnel | Yes | Yes | Yes | | Codex MCP bridge | Yes, when Codex is installed | Yes, when Codex is installed | Yes, when Codex is installed | | Claude Browser local adapter | Supported when Claude Code + compatible Chrome extension are available | Supported when Claude Code + compatible Chrome/Chromium extension are available | Best-effort when the compatible local components are available | | Claude Computer local adapter | Yes | Unsupported; reported as unavailable | Unsupported; reported as unavailable |

Unsupported optional capabilities return an unavailable/unsupported status or a structured MCP tool error. They do not prevent the main runtime from starting.

For a service manager such as systemd, run the foreground process directly:

coding-tools daemon

Do not supervise coding-tools restart: that is a one-shot management command which starts a detached runtime and must not be placed in a KeepAlive/restart loop.

Claude 原生 Browser / Computer Use 本地复用

Claude Browser Use can be prepared where the compatible Claude Code + Chrome extension are installed. Claude Computer Use currently remains macOS-only. Missing or unsupported optional capabilities are reported and skipped instead of preventing the main MCP runtime from starting. On macOS, both can be used as 无 Claude 模型、无 Claude 登录的本地执行层，同时保持官方 /Applications/Claude.app 和 Web Store Claude 扩展不变。先准备隔离副本：

coding-tools claude-local doctor
coding-tools claude-local prepare

推荐让 AI 只连接正常的 coding-tools 主 MCP，然后使用：

claude_mcp_list(server="browser" | "computer")
claude_mcp_call(server="browser" | "computer", tool=..., arguments=...)
claude_mcp_release(server="browser" | "computer")

因此调用方不需要把 Claude 的 22 + 42 个原生工具全部常驻进 tool list，也不需要分别配置两个额外 MCP。主 bridge 同一能力在同一时间只允许一个 MCP transport session 持有；不同会话不会静默共享 Browser tab group 或 Computer app grants。完成后显式 release，另有 5 分钟 idle cleanup 兜底。

Browser 路径尽量复用 Anthropic 原程序：

任意 AI
  -> coding-tools / claude_mcp_*
  -> Claude Code 自带 --claude-in-chrome-mcp
  -> coding-tools localBridge relay (127.0.0.1:8765)
  -> 隔离 patched Claude in Chrome
  -> Claude 原生 Browser executor

Computer 路径同样复用 Claude Desktop 原 dispatcher/native modules：

任意 AI
  -> coding-tools / claude_mcp_*
  -> 隔离 Claude Local Tools.app
  -> Claude 原 Computer Use session binder/dispatcher
  -> @ant/computer-use-mcp + native modules
  -> macOS Accessibility / ScreenCapture / AX

补丁只应用到 ~/.coding-tools/claude-local 下的隔离副本，并对 Claude Desktop / Claude in Chrome 版本和关键文件指纹/语义锚点做精确匹配；版本不匹配时直接拒绝 patch。Browser 默认只允许 localhost，普通站点需要显式加入 allowlist；Computer App 授权继续经过本地确认，macOS TCC、Claude 原有 per-app tier/policy/secure-input 等执行检查不会被移除。

Browser 的语义 find 是少数额外需要模型的工具，可选接到 Anthropic Messages 兼容 API；其余已验证的核心 Browser 工具可以完全本地执行。完整 patch 点、离线验证结果、版本升级流程和安全边界见 docs/claude-local.md。