iamyounglee/remote-workspace-mcp

远程工作区 MCP

CI
Latest Release
License: MIT
Go

remote-workspace-mcpd 是部署在远端机器上的 MCP 服务。它通过 Streamable HTTP 向编码 Agent 提供「像操作本地工作区一样」的远程文件读写、代码搜索、受控命令执行、文件传输与目录增量同步能力，并使用静态 Bearer Token 鉴权、Workspace / 路径白名单与可选 Bubblewrap 沙箱（Linux）约束访问范围。

目录

- 文档
- 特性
- 推荐使用场景
- 环境要求
- 安装
- 快速开始
- 配置
- 安全
- 支持的运行平台
- 贡献与许可

以 MIT 许可证开源，模块路径 github.com/iamyounglee/remote-workspace-mcp，守护进程（二进制）名为 remote-workspace-mcpd。欢迎参与贡献，见 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md。

文档

- 配置参考 — 完整 YAML 示例与逐项说明（server / auth / workspace / paths / files / bash / logging）
- MCP 工具与接口 — 工具参数、接口生命周期、文件/目录传输、增量同步、健康检查
- Bubblewrap 沙箱原理 — namespace 隔离、启用方式与能力边界
- 安全边界与运维建议

特性

- MCP Streamable HTTP：POST /mcp，无状态、无需会话。
- 静态 Bearer Token 鉴权：首次启动自动生成、持久化、可热轮换。
- Workspace 与路径白名单：相对 / 绝对路径控制，独立只读 / 可写名单，解析符号链接防越权。
- MCP 工具：read、write、edit、apply_patch、grep、glob、list、bash。
- 文件 / 目录传输：单文件 PUT/GET /files，目录 tar / tar.gz PUT/GET /directories。
- 增量同步：基于 manifest 与 SHA-256 的差异同步 POST /sync/plan、PUT /sync/apply。
- 受控命令执行：bash 工具可开关（enabled），命令统一经 bash -c 执行（支持完整 Shell 语法），并可选 Bubblewrap 沙箱（bash.sandbox.mode: none|bubblewrap）做文件系统与网络隔离。
- 资源限制与健康检查：文件大小、超时、并发限制；GET /healthz、GET /readyz。
- 工具调用审计：logging.audit_enabled 开启后，每次工具调用与文件 / 目录 / 同步传输都会写入审计记录，含操作类型、目标、结果、耗时、客户端 IP 与失败原因，命令内容统一截断至 512 字节。
- 客户端 IP 归因：审计记录客户端 IP，并通过 server.trusted_proxies 在反向代理场景下安全采信 X-Forwarded-For。
- 可选 TLS 加密传输：配置 server.tls.cert_file / key_file 后仅以 TLS 监听，支持证书定时热加载，无需重启进程。

推荐使用场景

remote-workspace-mcp 把「文件读写 / 搜索 / 命令执行 / 传输 / 同步」收敛成一个受控的远端 MCP 服务，适合任何需要让编码 Agent 安全操作远端机器的场景。典型用法：

1. 接入 DeepSeek++ 浏览器插件做远端开发：把服务部署在开发机或云主机上，在浏览器里的 DeepSeek++ 插件中配置 streamableHttp 类型的 MCP 指向该服务，即可让网页版对话模型直接读写远端仓库、运行构建与测试，把「网页模型」变成一台可操作真实远端工作区的开发代理。
2. 网络受限的内网机器开发：内网机器无法直连公网 IDE 插件或云端 Agent 时，在内网机上部署本服务，Agent 通过内网可达的 HTTP 地址操作内网代码与命令，避免把整个内网暴露给外部，也无需在受限机上安装完整 IDE。
3. CI / 构建农场中的一次性远程构建与调试：将服务临时部署到构建节点，让 Agent 在失败现场直接登录查看日志、复现、打补丁并重新触发构建，缩短「本地改 → 提交 → 等 CI」的循环；任务结束即可销毁实例。
4. 多 Agent 协作的共享远端工作区：多个编码 Agent（或同一 Agent 的多次会话）共享同一远端 Workspace，通过统一的路径白名单、Token 鉴权与增量同步保持一致，避免每个人都维护一份本地副本带来的状态漂移。
5. 临时云开发机 / 沙箱预览：为每次需求或 PR 拉起一台临时云机器并部署本服务，Agent 在其中完成开发验证；配合 Bubblewrap 沙箱（bash.sandbox.mode: bubblewrap）隔离文件系统与网络，验证完成后整机回收，环境零残留。
所有场景都建议结合网络 ACL / 防火墙将服务端口限制在可信来源，并对生产环境启用 Bubblewrap 沙箱与最小权限运行用户。详见 安全边界与运维建议。

环境要求

- Go 1.26+。
- 建议以普通非特权系统用户运行。
- bash：启用 bash 工具时需要（命令经 bash -c 执行，需系统存在 bash）。
- Bubblewrap（可选）：仅当 bash.sandbox.mode: bubblewrap 时需要。
- 暂不提供 Docker 部署文件；构建后二进制可直接运行，无需 Go 运行时。

安装

方式一：go install

通过 go install 安装最新版（需本地已安装 Go 1.26+）：

go install github.com/iamyounglee/remote-workspace-mcp/cmd/remote-workspace-mcpd@latest

方式二：从 Release 下载

从 GitHub Releases 下载对应平台压缩包（含 remote-workspace-mcpd 二进制与 config.example.yaml，并提供 checksums.txt 校验），解压即可使用：

以 Linux x64 为例
curl -fsSL -O https://github.com/iamyounglee/remote-workspace-mcp/releases/latest/download/remote-workspace-mcpd__linux_amd64.tar.gz
tar -xzf remote-workspace-mcpd__linux_amd64.tar.gz
./remote-workspace-mcpd --help

方式三：源码构建

从源码构建（推荐用仓库 Makefile）：

make build   # CGO_ENABLED=0 go build -o remote-workspace-mcpd ./cmd/remote-workspace-mcpd
make test    # go test -race ./...
make lint    # golangci-lint run ./...

快速开始

复制示例配置并改名为运行时配置
cp config.example.yaml config.yaml
编辑配置，至少设置 workspace.root 指向你的项目目录
校验配置是否合法
./remote-workspace-mcpd validate-config --config ./config.yaml
启动服务，守护进程开始监听 MCP 端口
不带任何参数等价于 serve --config config.yaml，配置相对当前工作目录解析
./remote-workspace-mcpd serve        --config ./config.yaml
查看当前 Bearer Token，首次启动会自动生成并持久化
./remote-workspace-mcpd token show   --config ./config.yaml
轮转 Token，生成、持久化并立即激活新 Token，旧 Token 失效
./remote-workspace-mcpd token rotate --config ./config.yaml

在 Agent 侧配置 MCP（token show 获取的 Token 建议放入平台 Secret，不要提交代码）：

{
"mcpServers": {
"remote-workspace-mcp": {
"type": "streamableHttp",
"url": "http://:/mcp",
"headers": { "Authorization": "Bearer " }
}
}
}

配置

完整 YAML 示例与逐项说明见 docs/configuration.md，亦可参考仓库内的 config.example.yaml。安全相关配置建议见 安全边界与运维建议。

安全

remote-workspace-mcpd 通过静态 Bearer Token 鉴权；Token 为服务级权限、以明文经 HTTP 传输，因此应结合网络 ACL / 防火墙将服务端口限制在可信来源内。

生产环境建议：

- Linux 平台启用 Bubblewrap 沙箱（bash.sandbox.mode: bubblewrap、bash.sandbox.require: true）约束命令执行的文件系统与网络视图；
- 默认关闭网络访问（bash.sandbox.allow_network: false）；allow_network 仅当 mode: bubblewrap 且在 Linux 上运行时才生效，非 Linux 或 mode: none 下无论该值如何命令都按宿主机网络执行，无法隔离网络；
- 使用专用非特权系统用户运行，并按最小权限配置 Workspace 与路径白名单。

更完整的安全边界与运维建议见 安全边界与运维建议。

支持的运行平台

remote-workspace-mcpd 是纯 Go 实现，可交叉编译到任意 Go 支持的平台。生产部署唯一完整支持 Linux x64——Bubblewrap 沙箱仅 Linux 可用，提供文件系统与网络隔离。

macOS / Windows 可运行服务与 bash 工具，但只能使用 bash.sandbox.mode: none，无沙箱隔离：

- macOS：系统自带 /bin/bash，bash 工具开箱可用。
- Windows：需安装 Git Bash 或 WSL，并把 bash（如 C:\Program Files\Git\bin\bash.exe）加入 PATH；此外路径白名单需使用 Windows 盘符绝对路径、文件权限语义与 Linux 不同。
跨平台构建与测试见 CI（ubuntu / macOS / windows）。完整说明见 安全边界与运维建议。

贡献与许可

- 贡献指南：CONTRIBUTING.md
- 行为准则：CODE_OF_CONDUCT.md
- 许可证：MIT