WorkspaceGuard MCP

WorkspaceGuard MCP 是一个本地、跨平台的 MCP 服务器，允许 ChatGPT 或 MCP 客户端在指定工作区上操作。该项目在研究 FileMCP 后全新构建，保留了有用的安全原则，并精简了首个版本中尚不需要的部分。

用途是什么？

• 列出、按文件或按行读取、按文件名搜索和按内容搜索。

• 以原子方式写入文件，支持 dry_run 和 expected_sha256 以避免覆盖更新的更改。

• “删除”通过移入 .workspaceguard/trash 实现，可手动恢复。

• 读取 Git status、log 和 diff，无需启用 shell。

• 可选地通过 program + args 运行终端命令，不通过 shell 拼接字符串，且仅允许 allowlist 中的可执行文件。

• 通过 stdio 或带 token 的 127.0.0.1 上的 MCP Streamable HTTP 使用。

• 记录 audit JSONL，不保存文件内容或完整命令参数。

Related MCP server: Kastor

主要改进

该应用具有 Electron 桌面界面，用于选择工作区、选择模式、选择命令 allowlist、启动/停止服务器、在应用内直接测试 MCP 以及连接 Secure MCP Tunnel。沿用 FileMCP 的方向，应用每次会话生成新的 loopback token，将服务器保持在 127.0.0.1，管理 tunnel-client 的生命周期，并使用操作系统加密机制（macOS 上可用时使用 Keychain）保存 Runtime API key。tunnel-client 二进制文件仍由用户从 OpenAI 下载；项目不打包该二进制文件。本地运行时和 Tunnel 不调用 Codex 或 OpenAI 模型/API：通过 developer-mode 应用配合 ChatGPT Web 使用，因此不消耗 Codex 配额。对话仍受当前 ChatGPT 套餐限制的约束。

要求

• Node.js 20 或更高版本（已在 Node.js 24 上测试）。

• 使用 git_* 工具时需要 Git。

• 对于 ChatGPT：需要一个支持自定义 MCP 应用的工作区、一个 Secure MCP Tunnel 以及具有相应 tunnel 权限的 runtime API key。参见 OpenAI Secure MCP Tunnel。

分步运行

第 1 步 — 安装依赖

cd "/Users/danhpham/Documents/ChatGPT/MCP"
npm install

不要将 API key 放入 .env 或提交到 Git。

第 2 步 — 检查整个项目

npm run verify

此命令运行 typecheck、单元/集成测试、生产构建以及通过 MCP stdio 进行的语义冒烟测试。

第 3 步 — 运行桌面界面（最简单的方式）

npm run desktop

在 WorkspaceGuard 窗口中：

1. 点击**选择文件夹…**并选择一个测试工作区。

2. 首次使用时保持只读。

3. 点击启动 MCP。当状态变为运行中时，HTTP 服务器已在 127.0.0.1:<端口> 上就绪。

4. 完成后点击停止。关闭应用也会同时停止服务器和 Tunnel。

界面不显示或保存 HTTP token；token 在每次启动时由主进程重新生成。

在界面内直接测试完整 MCP

服务器显示运行中后，点击运行 MCP 测试。这是 Electron 主进程中的真实 MCP 客户端，不是通过界面的假测试。

• 对于只读，应用测试 MCP HTTP 握手、工具发现、workspace_info 和 list_files。

• 对于读写，应用额外测试 write_file → read_file → trash_path。您必须勾选确认，因为随机命名的测试文件将被移入 .workspaceguard/trash。

• 对于运行命令，在 allowlist 中保持勾选 node，以便应用额外使用 node --version 测试 run_command。

为后两种模式选择一个单独的测试目录。每一步的结果会立即显示在界面的测试部分中。

第 4 步 — 通过终端构建核心（可选）

npm run build

生产入口点是：

/Users/danhpham/Documents/ChatGPT/MCP/dist/index.js

第 5 步 — 通过终端选择工作区和模式（可选）

建议先使用一个小型测试目录：

mkdir -p /tmp/workspaceguard-demo
printf 'Xin chào MCP\n' > /tmp/workspaceguard-demo/hello.txt

三种模式：

• read-only：只有文件读取和 Git 读取工具。这是默认模式。

• workspace-write：增加 write_file 和 trash_path。

• command：增加写入权限和 run_command。

注意：服务器在三种模式下仍会将内部审计写入 .workspaceguard/audit.jsonl。“只读”描述的是公开工具，而非服务器进程自身的文件系统沙箱。

第 6A 步 — 通过 stdio 运行（推荐）

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode read-only

终端将等待 MCP 客户端通过 stdin 发送请求。这是正确行为，不是卡死。

第 6B 步 — 启用写入权限

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode workspace-write

trash_path 默认 dry_run=true。仅当调用方发送 dry_run=false 时，路径才会被移入回收站。

第 6C 步 — 允许自行运行终端命令

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode command \
  --allow-command git,node,npm,npx

工具输入示例：

{
  "program": "npm",
  "args": ["test"],
  "cwd": "",
  "timeout_seconds": 120
}

run_command 不使用 shell，但不是操作系统沙箱。node、npm、Python 或任何被允许的可执行文件仍然可以读写工作区之外的内容、使用网络并以当前账户的权限运行其他进程。仅在可信的工作区和工作流中使用 command 模式。

第 7 步 — 通过 Secure MCP Tunnel 界面连接 ChatGPT

在 OpenAI Platform 上，创建一个 Secure MCP Tunnel 和具有使用 tunnel 权限的 runtime API key。下载适合操作系统的 tunnel-client。不要将 Runtime API key 发送给 Codex，也不要将其写入 .env、源代码或 Git。

在应用中，MCP 已显示运行中后：

1. 粘贴格式为 tunnel_... 的 Tunnel ID。

2. 粘贴 Runtime API key。下次可以留空以使用已加密保存的 key。

3. 如果二进制文件已在 PATH 中，则输入 tunnel-client，或点击**选择文件…**选择已下载的二进制文件。

4. 保持默认 profile，点击连接 Tunnel，等待“已为 ChatGPT 就绪”的通知。

5. 绿色提示“已为 ChatGPT 就绪”确认本地部分已连接。点击打开 ChatGPT Web；此应用不会打开或调用 Codex。

6. 如果只想断开 ChatGPT，点击断开 Tunnel；点击停止可同时停止 Tunnel 和 MCP 服务器。

应用执行相当于 tunnel-client init --sample sample_mcp_remote_no_auth → doctor --explain → run 的流程，MCP 端点为 http://127.0.0.1:<端口>/mcp，本地健康检查端点，token 头通过环境变量传递。Tunnel profile 位于应用自身的数据中，不在工作区内。

在 ChatGPT Web 中，按照工作区策略启用 Developer Mode/自定义 MCP 应用，创建新应用，选择 Tunnel 连接，选择刚创建的 tunnel，运行 Scan Tools，然后在启用写入工具之前先尝试 workspace_info、list_files 和 read_file。如果看不到 Tunnel 选项，请检查工作区是否已获得使用 Tunnel 的读取权限。

第 8 步 — HTTP loopback（可选）

export WORKSPACE_MCP_TOKEN="$(openssl rand -hex 32)"

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport http \
  --mode read-only \
  --port 7331

健康检查：

curl --fail http://127.0.0.1:7331/healthz

MCP 请求必须发送以下头：

X-Workspace-MCP-Token: <WORKSPACE_MCP_TOKEN>

HTTP 服务器仅绑定 127.0.0.1，检查 Host、Origin、token、基本 framing 和 body 大小限制。如果没有特定的 HTTP 需求，请使用 stdio。

可用工具

始终可用

• workspace_info

• list_files

• read_file

• read_file_range

• search_filenames

• search_content

• git_status

• git_log

• git_diff

workspace-write 或 command 模式

• write_file

• trash_path

仅 command 模式

• run_command

恢复已回收的文件

工具返回 trashPath。通过本地命令恢复，例如：

mv "/tmp/workspaceguard-demo/.workspaceguard/trash/<id>/remove-me.txt" \
  "/tmp/workspaceguard-demo/remove-me.txt"

WorkspaceGuard 在此版本中不会自动清理回收站，以避免意外删除数据。

结构

src/
├── config.ts                 # CLI/env và mode
├── security/path-policy.ts   # containment + sensitive-path policy
├── services/files.ts         # file/search/write/trash
├── services/git.ts           # Git read-only
├── services/process.ts       # process limits + tree cleanup
├── tools.ts                  # MCP schemas, annotations, audit
├── server.ts                 # stdio + HTTP loopback
├── desktop/                  # Electron main/preload + renderer an toàn
└── index.ts                  # CLI entry
tests/                        # unit, integration, MCP semantic smoke
docs/                         # phân tích source và lộ trình

补充文档

• 原始 FileMCP 项目分析

• 项目构建步骤和路线图

• 安全模型

许可证和参考来源

项目使用 Apache License 2.0。FileMCP 也使用 Apache-2.0；参见 NOTICE 了解参考设计来源。不包含 tunnel-client 二进制文件；运维人员从 OpenAI 官方来源下载相应版本。