Codex Workspace CodeGraph MCP

这是一个不调用 Codex、不调用 OpenAI API、不需要账号、订阅、登录或 API Key 的本地代码操作 MCP。

项目参考 OpenAI Codex 开源仓库的代码工作流设计，自行实现文件读取、文本检索、补丁编辑、命令执行、Git 检查、计划管理、AGENTS.md 分层指令和安全审批；同时整合 CodeGraph 的大型代码库检索能力，以及简体中文 Interactive Feedback Web UI。

功能组成

1. Codex 风格本地代码工具

本项目没有启动或代理 codex 进程。以下功能由本项目独立实现：

• 工作区边界和符号链接逃逸检查。

• AGENTS.md / AGENTS.override.md 分层发现。

• 文件读取、批量读取、目录列举、元数据查询。

• 文件名查找和文本搜索；优先使用 rg，缺失时自动回退。

• 原子文件写入和精确文本替换。

• Codex 风格 *** Begin Patch / *** End Patch 补丁语法。

• 新增、删除、更新和移动文件的事务式补丁应用。

• 前台命令执行、超时、输出截断和风险分类。

• Git status、diff、log 和 show。

• Codex 风格 update_plan 状态约束。

• 只读、工作区写入和高风险审批策略。

Codex 仓库仅作为以下设计参考：apply_patch 文件操作格式、复杂任务计划、优先使用快速检索工具、逐层加载项目指令，以及对破坏性操作进行限制。没有复制 Codex 的模型、认证、会话或代理实现。

2. 简体中文 Interactive Feedback

内置独立实现的简体中文 Web UI：

• 用户文字反馈。

• 最多四张 PNG、JPEG、WebP 或 GIF 图片附件。

• 用户主动运行模型预设的验证命令并查看 stdout/stderr。

• 危险命令、删除和覆盖操作审批。

• 会话轮询、过期时间和状态显示。

• 固定 48 小时超时：172800 秒。

MCP 初始化指令、Prompt、Resource、工具描述和 AGENTS.md 中均包含：

每次回答结束前都要调用 interactive_feedback 与用户进行交流 这是你与用户之间的唯一沟通渠道

实际 MCP 工具名为 interactive_feedback。其输入 schema 强制：

{
  "timeout": 172800
}

MCP 服务端无法获知模型何时“准备输出最终回答”，因此无法从协议层强制拦截最终回答；能否每次严格调用仍取决于 MCP 客户端和模型是否遵循服务端指令。

3. CodeGraph 大型代码库检索

项目依赖 @colbymchenry/codegraph，在目标工作区内启动：

codegraph serve --mcp

CodeGraph 返回的工具通过 stdio JSON-RPC 动态代理，不在本项目中硬编码。默认请求暴露：

explore,node,search,callers,callees,impact,files,status

另外提供：

• codegraph_project_init

• codegraph_project_sync

• codegraph_project_status

CodeGraph 在本地解析和索引代码，不需要 OpenAI 或其他模型 API。

Related MCP server: MCP Local LLM Server

运行要求

• Node.js 22.5 或更高版本。

• 用于 CodeGraph 安装和首次运行的 npm 网络访问。

• 使用公网隧道时需要网络访问 Cloudflare。

• 不需要 Codex、ChatGPT、OpenAI API、账号或订阅。

方式一：作为 stdio MCP 直接使用

发布 npm 后，在目标代码库目录运行：

npx -y codex-workspace-codegraph-mcp@latest

或显式指定工作区：

npx -y codex-workspace-codegraph-mcp@latest --workspace /absolute/path/to/repository

通用 MCP 客户端配置：

{
  "mcpServers": {
    "codex-workspace": {
      "command": "npx",
      "args": [
        "-y",
        "codex-workspace-codegraph-mcp@latest",
        "--workspace",
        "/absolute/path/to/repository"
      ],
      "env": {
        "CWMCP_SANDBOX": "workspace-write",
        "CWMCP_APPROVAL_POLICY": "on-request",
        "CODEGRAPH_MCP_TOOLS": "explore,node,search,callers,callees,impact,files,status"
      }
    }
  }
}

stdio 模式的 MCP JSON-RPC 写入 stdout，运行日志和反馈 URL 仅写入 stderr。

方式二：一键启动 MCP、WebUI 和两个 Cloudflare Tunnel

在需要操作的代码库目录执行：

npx -y codex-workspace-codegraph-mcp@latest tunnel --workspace .

本地源码运行：

npm install
npm run tunnel -- --workspace .

也可以直接运行脚本：

./scripts/start.sh --workspace .

Windows PowerShell：

.\scripts\start.ps1 --workspace .

启动器会：

1. 生成随机访问令牌。

2. 启动 127.0.0.1:8765 的 HTTP MCP。

3. 启动 127.0.0.1:8766 的反馈 WebUI。

4. 检查 cloudflared；缺失时从 Cloudflare 官方 GitHub Release 自动下载到 ~/.codex-workspace-mcp/bin/。

5. 分别为 MCP 和 WebUI 启动 TryCloudflare Quick Tunnel。

6. 在控制台输出本地和公网 URL。

7. 按 Ctrl+C 时停止 MCP、WebUI 和两个 tunnel。

示例输出：

MCP 本地 URL:   http://127.0.0.1:8765/mcp/<token>
WebUI 本地 URL: http://127.0.0.1:8766/?token=<token>

MCP 公网 URL:   https://example-a.trycloudflare.com/mcp/<token>
WebUI 公网 URL: https://example-b.trycloudflare.com/?token=<token>

端口可修改：

npx -y codex-workspace-codegraph-mcp@latest tunnel \
  --workspace . \
  --mcp-port 9001 \
  --web-port 9002

已有 cloudflared 时可以显式指定：

npx -y codex-workspace-codegraph-mcp@latest tunnel \
  --cloudflared /usr/local/bin/cloudflared

禁止自动下载：

npx -y codex-workspace-codegraph-mcp@latest tunnel --no-download

启动器会使用一个临时空配置文件，避免用户目录中的 ~/.cloudflared/config.yaml 干扰 Quick Tunnel。

Quick Tunnel 限制

Cloudflare 官方将 Quick Tunnel 定位为测试和开发用途，不提供 SLA，并且当前不支持 Server-Sent Events。远程 MCP 因此使用无 SSE 的 JSON-RPC HTTP POST。需要 SSE、稳定域名、访问控制或生产可靠性时，应创建正式 Cloudflare Tunnel，并分别把域名路由到 MCP 与 WebUI 本地端口。

远程 MCP 地址和 WebUI 地址中包含同一个随机访问令牌。URL 等同于密码，不应发布到日志、Issue、截图或公共聊天。

HTTP MCP

不启动 Cloudflare 时，可以直接运行本地 HTTP MCP：

npx -y codex-workspace-codegraph-mcp@latest \
  --transport http \
  --workspace . \
  --mcp-port 8765 \
  --web-port 8766

控制台会输出：

http://127.0.0.1:8765/mcp/<token>

HTTP 端点接受 JSON-RPC 2.0 POST。也可使用：

Authorization: Bearer <token>

健康检查：

GET /health

首次建立 CodeGraph 索引

在目标仓库目录执行：

npx -y @colbymchenry/codegraph init .

或者让模型调用：

codegraph_project_init { "path": "." }

之后大型代码库问题优先调用 codegraph_explore。索引需要手动同步时调用：

codegraph_project_sync { "path": "." }

基础工具清单

工作区和读取

• workspace_info

• workspace_instructions

• read_file

• read_many_files

• list_directory

• file_metadata

• find_files

• search_text

编辑

• write_file

• edit_file

• apply_patch

• create_directory

• move_path

• delete_path

命令、Git 和计划

• exec_command

• git_status

• git_diff

• git_log

• git_show

• update_plan

• get_plan

反馈和集成

• interactive_feedback

• integration_status

• codegraph_project_init

• codegraph_project_sync

• codegraph_project_status

• CodeGraph 动态返回的全部工具

apply_patch 示例

*** Begin Patch
*** Update File: src/example.js
@@
-export function value() {
-  return 1;
-}
+export function value() {
+  return 2;
+}
*** Add File: test/example.test.js
+import test from 'node:test';
+// ...
*** End Patch

支持：

*** Add File: path
*** Delete File: path
*** Update File: path
*** Move to: new-path
@@ optional context label
 context
-old
+new

所有路径必须相对工作区。补丁在写入前会先解析并验证；写入失败时尝试恢复原始文件。

沙箱和审批

默认值：

CWMCP_SANDBOX=workspace-write
CWMCP_APPROVAL_POLICY=on-request

CWMCP_SANDBOX：

• read-only：拒绝文件写入和可能修改状态的命令。

• workspace-write：允许工作区内文件操作；这是默认值。

CWMCP_APPROVAL_POLICY：

• on-request：仅高风险命令、删除和覆盖操作通过 WebUI 审批。

• untrusted：除明显只读命令外均审批。

• always：所有 exec_command 均审批。

• never：无法通过 WebUI 批准高风险操作，直接拒绝。

路径校验同时检查词法路径和真实路径，防止 ../ 与工作区内符号链接指向外部目录。

环境变量

本地开发和验证

npm install
npm run verify

验证包括：

• 所有 JavaScript 文件语法检查。

• 工作区路径穿越和符号链接逃逸测试。

• AGENTS.md 分层加载测试。

• Codex 风格补丁解析、写入和失败保护测试。

• MCP 初始化、工具列表和固定 48 小时反馈 schema。

• CodeGraph stdio 工具动态代理。

• HTTP MCP 令牌认证、Origin 校验和 MCP 协议版本校验。

• 一键启动器同时输出两个 tunnel URL。

• stdio MCP 烟雾测试。

上传 GitHub

git init
git add .
git commit -m "Initial release"
git branch -M main
git remote add origin https://github.com/YOUR_GITHUB_USERNAME/codex-workspace-codegraph-mcp.git
git push -u origin main

先修改 package.json 中的 repository.url。

发布 npm

检查包名：

npm view codex-workspace-codegraph-mcp

若名称被占用，改为作用域包：

{
  "name": "@YOUR_NPM_USERNAME/codex-workspace-codegraph-mcp"
}

发布：

npm login
npm run verify
npm publish --access public

发布后：

npx -y codex-workspace-codegraph-mcp@latest --workspace .
npx -y codex-workspace-codegraph-mcp@latest tunnel --workspace .

使用作用域包时替换包名即可。

上游参考

• OpenAI Codex：Apache-2.0。用于研究代码代理工作流、补丁语法和项目指令发现。

• MCP Feedback Enhanced：MIT。用于研究反馈工作流需求；本项目的 WebUI 和服务端为独立实现。

• CodeGraph：MIT。作为 npm 运行时依赖和 MCP 子服务使用。

• Cloudflared：由 Cloudflare 发布；仅在用户运行 tunnel 子命令时查找或下载。

详见 THIRD_PARTY_NOTICES.md、SECURITY.md 和 docs/ARCHITECTURE.md。