Codex Workspace Codegraph

这是一个不调用 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。

运行要求

• 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 批准高风险操作，直接拒绝。

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

环境变量

变量	默认值	说明
CWMCP_WORKSPACE	当前目录	允许访问的工作区根目录
CWMCP_TRANSPORT	stdio	stdio 或 http
CWMCP_HOST	127.0.0.1	MCP HTTP 监听地址
CWMCP_MCP_PORT	8765	MCP HTTP 端口
CWMCP_WEB_HOST	127.0.0.1	WebUI 监听地址
CWMCP_WEB_PORT	8766	WebUI 端口
CWMCP_ACCESS_TOKEN	随机值	HTTP MCP 和 WebUI 访问令牌
CWMCP_ALLOWED_ORIGINS	空	额外允许的浏览器 Origin，逗号分隔；默认仅接受同源和本机 Origin
CWMCP_SANDBOX	workspace-write	沙箱模式
CWMCP_APPROVAL_POLICY	on-request	审批策略
CWMCP_COMMAND_TIMEOUT_MS	120000	普通命令超时
CWMCP_MAX_OUTPUT_BYTES	1048576	stdout/stderr 输出上限
CWMCP_MAX_READ_BYTES	2097152	单文件读取上限
CWMCP_DISABLE_CODEGRAPH	0	设为 1 禁用 CodeGraph
CWMCP_CODEGRAPH_COMMAND	codegraph	CodeGraph 可执行文件
CODEGRAPH_MCP_TOOLS	完整列表	CodeGraph MCP 工具列表
CWMCP_CLOUDFLARED	自动查找	cloudflared 可执行文件
CWMCP_TUNNEL_VERBOSE	0	设为 1 输出子进程详细日志

本地开发和验证

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。