safe-workspace-mcp

一个极简、注重安全的 MCP 服务器，为恰好一个本地工作区提供结构化的读写访问，并内置本地 Git 检查点与回滚功能。

设计用于让聊天模型（例如支持 MCP 的 ChatGPT）安全地编辑一个项目文件夹中的文件——仅此而已。

Windows 便携版快速入门（无需 Python、Git、Node）

1. 从 Releases 下载 Windows 发行版 ZIP 并解压。

2. 准备一个工作区目录（服务器唯一允许操作的文件夹）。

3. 获取一个 OpenAI Secure MCP Tunnel ID（在此创建）和一个 Runtime API Key（在此创建）。

4. 在解压后的文件夹中运行：

.\Start-SafeWorkspaceMCP.ps1 -Workspace "D:\ChatGPT_Workspace\demo" -TunnelId "tunnel_..."

5. 出现提示时输入 Runtime API Key（输入被隐藏，且绝不存储）。

6. 保持终端打开；Ctrl+C 可停止所有内容。

7. 从 ChatGPT 开发者模式连接现有隧道——这一步需要在你的账户侧自行完成。

启动器会在首次运行时下载官方 OpenAI 隧道客户端（固定为 v0.0.11，并经过 SHA-256 校验），并将其缓存在 %LOCALAPPDATA%\SafeWorkspaceMCP\ 下。无需管理员权限，不修改 PATH/注册表。完整详情请参阅 ZIP 内的 README-PORTABLE.md\。

准确的表述：无需安装 Python/Git/Node 即可进行便携式本地部署；启动器会自动引导经过测试的 OpenAI 隧道客户端。 这并非“零配置”——你需要自行准备工作区、隧道 ID、运行时密钥以及 ChatGPT 账户侧的设置。

Related MCP server: git-mcp-server

它是什么

• 一个进程 = 一个配置 = 一个固定的工作区（启动时选定，运行时不可变）

• 结构化的文本文件 CRUD，支持原子多文件事务

• 乐观并发：对现有文件的每次修改都必须提供其当前的 sha256

• 托管的本地 Git 历史（通过 Dulwich，绝不使用 git.exe）：变更前/后检查点、差异、历史、恢复

• stdio MCP 服务器，共 9 个工具

非目标（明确不存在）

没有 shell、没有终端、没有子进程、没有代码执行、没有编译器/测试运行器/包管理器、没有任意的 HTTP 或网络工具、没有远程 Git、没有工作区切换、没有二进制/图像编辑、没有操作系统沙箱承诺。

如果某项能力未在下面列出，则此服务器不具备该能力。

架构

ChatGPT / any MCP client
        │
OpenAI Secure MCP Tunnel (account-side, outbound-only)
        │
tunnel-client.exe            <- external deployment layer (official OpenAI binary,
        │                       pinned + SHA-256 verified by the launcher)
        │ MCP over stdio (child process)
        ▼
Safe Workspace MCP           <- this project (9 tools, no network, no exec)
        │
   fixed single workspace
        │
   ┌────┴─────────────┐
   │                   │
structured file CRUD   managed local Git checkpoints

• Web 搜索 / URL 抓取由聊天宿主本身完成；按设计，此服务器没有网络能力。

• 隧道客户端是外部部署组件，不属于此服务器：服务器进程本身从不打开套接字，启动器的唯一网络活动是下载固定版本且经校验和验证的官方隧道客户端。

九个工具

apply_changes 操作都会先进行校验（路径、哈希、策略、计划冲突）；如果任何一项失败，则什么都不应用。执行中途失败时，所有内容都会回滚。

安装

两种受支持的路径：

• 最终用户（Windows）：下载便携版发行 ZIP——无需 Python/Git/Node（见上方快速入门）。

• 开发者 / Linux：使用 Python 3.12+ 的源码检出：

git clone https://github.com/Xs-trek/safe-workspace-mcp.git
cd safe-workspace-mcp
py -3.12 -m venv .venv
.venv\Scripts\pip install -e .

运行时依赖：mcp==2.0.0（官方 SDK）、dulwich==1.2.6、Python 标准库。没有其他依赖。便携版发行版的最终用户前提条件仅为：Windows 10/11、PowerShell、用于隧道的互联网、一个工作区文件夹、隧道 ID + Runtime API Key，以及你自己的 ChatGPT 账户设置。

配置

TOML 文件，启动时加载一次，之后不可改变。没有任何工具（也没有任何代码路径）能在运行时更改配置、工作区根目录或任何限制。

[workspace]
root = "D:/ChatGPT_Workspace/demo"
max_file_bytes = 2097152        # largest file the server will write/track
max_read_bytes = 1048576        # largest read returned / searched per file
max_transaction_bytes = 10485760
max_search_results = 200
excluded = ["node_modules", "build", "dist", ".venv"]  # plus built-ins

[paths]
reject_reparse_points = true    # symlinks/junctions/mounts: always recommended
reject_hardlinks = true
require_same_filesystem = true

[write]
allow_create_file = true
allow_modify_file = true
allow_delete_file = true
allow_move = true
allow_create_directory = true
allow_delete_empty_directory = true
require_expected_hash = true

[git]
mode = "managed"                # only mode in v0.1.0
author_name = "Safe Workspace MCP"
author_email = "safe-workspace-mcp@local"

[search]
include_hidden = false

[server]
transport = "stdio"             # only transport in v0.1.0

参见 examples/ 了解最小 / 现有源码 / 大型源码变体。

托管工作区

在首次启动使用空目录或普通源码目录（无 .git）时，服务器：

1. 扫描目录（仅跟踪常规文本文件），

2. 在 <root>/.git 处初始化托管仓库，

3. 创建 initial snapshot 检查点。

如果工作区已包含 .git，启动将失败并返回 EXISTING_GIT_REPOSITORY_NOT_SUPPORTED。采用现有仓库、工作树、子模块和远程仓库不在 v0.1.0 范围内。

可编辑 ⇒ 可恢复：MCP 可以修改或删除的每个常规文件都被托管仓库跟踪，因此始终可以从检查点恢复。被排除的目录（node_modules、构建产物、virtualenvs 等）对所有工具不可见——不可读、不可写、不可搜索、不会被检查点记录。

运行

.venv\Scripts\safe-workspace-mcp path\to\config.toml

服务器通过 stdio 进行 MCP 通信，并将日志输出到 stderr。如果工作区根目录不存在或不安全，它会拒绝启动。

多个项目

一个进程只服务一个工作区。使用多个配置运行多个进程：

safe-workspace-mcp project-a.toml
safe-workspace-mcp project-b.toml

导入现有源码

将 workspace.root 指向没有 .git 的现有源码目录。初始快照会将当前状态提交为基线；此后该目录即进入托管状态。大型生成目录应添加到 excluded。

便携版使用场景（Windows）

• 在新电脑上首次运行：解压 ZIP，创建/选择一个工作区，运行启动器，提供隧道凭据。启动器会自动下载并验证固定版本的隧道客户端。

• 第二次运行：使用相同的启动器；缓存的隧道客户端将被复用——无需重新下载、无需重新安装。

• 切换项目：同一发行版，不同的 -Workspace 路径。每个 MCP 进程仍然只服务一个固定工作区（不支持运行时切换）。

• 离线安装（高级）：自行预下载官方 tunnel-client-<version>-windows-<arch>.zip，对照官方 SHA256SUMS.txt 进行验证，并将 -TunnelClientPath 指向解压后的官方 tunnel-client.exe。这是高级操作者覆盖方式：它会跳过启动器固定的 SHA-256 保证（但仍会检查文件是否存在和 --version）。正常使用中不需要。

使用 MCP Inspector 进行测试

npx @modelcontextprotocol/inspector .venv\Scripts\safe-workspace-mcp -- args/config.toml

（或者使用 MCP SDK CLI 中的 mcp dev。）请验证 tools/list 正好显示九个工具，只读注解正确，并先在一个一次性工作区上执行 读取 → 搜索 → apply_changes → git_diff/git_history/git_restore 的操作流程。

连接 ChatGPT Desktop / ChatGPT Web

ChatGPT 通过 OpenAI 的 Secure MCP Tunnel（开发者模式 / 连接器）访问本地 MCP 服务器。本项目仅是 stdio 服务器外加一个由操作者运行的启动器——它不包含隧道传输、OAuth 或凭据存储，也从不读取或写入 ChatGPT/Codex 的配置。

建议流程：

1. 使用一次性工作区通过完整的本地测试套件（见上文）。

2. 在 OpenAI Platform 中创建一个 Secure MCP Tunnel，并使用该隧道 ID 运行便携式启动器（或自行运行 tunnel-client run）。

3. 在 ChatGPT 中，在启动器终端运行期间，将现有隧道作为开发者/应用连接器连接。

4. 先使用专门的测试工作区，然后将配置切换到你的真实项目。

始终在 ChatGPT 的界面中手动进行配置。

安全概览

• 工作区限制 — 仅允许工作区相对路径；路径穿越、绝对/驱动器/UNC 路径、保留设备名、ADS 冒号、尾随点/空格名称均被拒绝；包含性检查基于文件系统（realpath），绝不是字符串前缀匹配。

• 链接 — 现有路径的任一组件中存在重解析点（符号链接、junction、挂载点、未知标签）⇒ 拒绝。硬链接的常规文件（st_nlink > 1）⇒ 拒绝。

• 内部隔离 — 通过所有文件工具都无法访问 .git；它只能由托管的 Git 存储触碰。

• 原子写入 — 临时同目录文件 → fsync → 校验 → os.replace；写入失败绝不会截断原始文件。

• 乐观并发 — 过期的 expected_sha256 ⇒ HASH_MISMATCH，用户更新的文件绝不会被覆盖。

• 不执行 / 无网络 — 生产代码不包含任何 subprocess/socket 使用（测试通过 AST 强制检查，扫描每个模块的导入和调用）；dulwich 的无条件钩子执行路径在导入时即被消除，并使用植入的钩子文件进行回归测试；托管仓库永远不会获得钩子、过滤器或远程仓库。

• 资源限制 — 文件/读取/事务字节数及搜索结果数量有上限；达到上限时以关闭状态失败。

• 提示注入 — 未解决，但已遏制：被误导的模型只能在一个文件夹内执行结构化、带检查点的文件编辑，而你始终可以回滚。

完整分析和残余风险请参阅 SECURITY.md 和 THREAT_MODEL.md。

已知限制（v0.1.0）

• 仅支持文本（UTF-8）文件；拒绝二进制文件。

• Windows 是主要安全目标；Linux 也受支持并通过 CI 测试。

• 除哈希检查外，没有并发多客户端协调（请只运行一个写入者）。

• 检查点历史会无限增长（v0.1.0 中没有 gc）。

• 恢复是文件级别的；被排除的目录不会被恢复操作触碰。

安全报告

请打开私有安全公告（GitHub 的 “Report a vulnerability”），而不是公开 issue。

许可证

Apache-2.0 — 参见 LICENSE。