| name | devspace-mcp-setup |
| description | 当需要安装、配置、暴露、连接或验证 @waishnav/devspace MCP server，让 ChatGPT 或其他 MCP client 通过 Cloudflare/公网 HTTPS 调用本机 workspace 工具时使用。 |
DevSpace MCP Setup
适用场景
使用本 skill 帮用户把 @waishnav/devspace 从零安装到可验证状态。目标不是只让服务启动，而是证明 MCP client 能通过真实协议完成 tools/list、open_workspace 和 read。
典型触发：
- 用户要把 ChatGPT 连接到本机项目目录。
- 用户要用 Cloudflare tunnel 或自有域名暴露 DevSpace MCP。
- 用户说 DevSpace App 显示异常，需要判断 UI 问题还是协议问题。
- 用户要做只读 smoke test，避免先开放写文件或 shell。
- 用户要检查 DevSpace 安全边界，例如
allowedRoots、owner password、bash 风险。
安全边界
DevSpace 可能暴露 write、edit 和 bash。把它当成 shell-capable 本机入口处理。
必须遵守：
- 不要打印、粘贴、提交
~/.devspace/auth.json 里的 owner password。
allowedRoots 只允许必要项目目录。- 先跑只读验证，再考虑
write、edit、bash。
- 长期公网 endpoint 使用自有域名、HTTPS 和额外访问控制。
- 不把随机
trycloudflare.com 临时 URL 当长期入口。
- 证据以 MCP 协议调用结果和 DevSpace server log 为准，ChatGPT UI app chip 只能作辅助参考。
安装流程
- 安装 CLI。
npm install -g @waishnav/devspace
npm install -g cloudflared
- 初始化 DevSpace。
devspace init
devspace doctor
- 检查配置。
devspace config get
确认：
allowedRoots 指向要开放给 MCP client 的项目目录。publicBaseUrl 是公网 HTTPS base URL，不包含 /mcp。
- 本地启动并检查。
devspace serve
curl http://127.0.0.1:7676/healthz
- 暴露公网入口。
Cloudflare 转发流程
DevSpace 的本地服务默认监听 http://127.0.0.1:7676。Cloudflare 只负责把一个公网 HTTPS hostname 转发到这个本地地址。这里有两条路径：
- quick tunnel：最快拿到临时公网地址，适合首次 smoke test。
- named tunnel + 自有域名：适合长期使用，推荐用于 ChatGPT 或其他 MCP client 的固定配置。
路径 A：quick tunnel 临时公网地址
临时验证可用 quick tunnel。它会生成一个随机 trycloudflare.com 地址：
cloudflared tunnel --url http://127.0.0.1:7676
拿到地址后，把 DevSpace 的 public base URL 设置为该地址，不包含 /mcp：
devspace config set publicBaseUrl https://example.trycloudflare.com
MCP client 使用的最终 endpoint 是：
https://example.trycloudflare.com/mcp
quick tunnel 的缺点是 URL 会变，适合临时验证，不适合长期写进 ChatGPT App 或团队配置。
路径 B：named tunnel + 自有域名
长期方案用 Cloudflare 账号下的 named tunnel，把自己的子域名转发到本机 DevSpace。
先登录 Cloudflare：
cloudflared tunnel login
创建 tunnel：
cloudflared tunnel create devspace
把子域名路由到 tunnel：
cloudflared tunnel route dns devspace devspace.example.com
创建 ~/.cloudflared/config.yml，把公网 hostname 指向本机 DevSpace：
tunnel: devspace
credentials-file: /Users/you/.cloudflared/<tunnel-id>.json
ingress:
- hostname: devspace.example.com
service: http://127.0.0.1:7676
- service: http_status:404
启动 tunnel：
cloudflared tunnel run devspace
设置 DevSpace public base URL：
devspace config set publicBaseUrl https://devspace.example.com
MCP client 使用：
https://devspace.example.com/mcp
如果用户已有自己的域名，优先走 named tunnel。配置成功后再考虑加 Cloudflare Access 或其他访问控制，尤其是在 DevSpace 暴露 bash 时。
验证流程
优先做协议层验证，不要只看网页 UI。
- 准备 marker 文件。
mkdir -p adhoc_jobs/devspace_mcp_smoke
printf 'Marker: DEVSPACE_MCP_SMOKE_%s\n' "$(date +%Y%m%d%H%M%S)" > adhoc_jobs/devspace_mcp_smoke/task_input.md
- 使用内置脚本跑 MCP smoke。
node ~/.codex/skills/devspace-mcp-setup/scripts/devspace_mcp_smoke.mjs \
--url https://devspace.example.com/mcp \
--workspace /absolute/path/to/project \
--path adhoc_jobs/devspace_mcp_smoke/task_input.md \
--expect DEVSPACE_MCP_SMOKE
默认从 ~/.devspace/auth.json 读取 ownerToken。也可以用环境变量：
DEVSPACE_OWNER_TOKEN='...' node ~/.codex/skills/devspace-mcp-setup/scripts/devspace_mcp_smoke.mjs ...
- 检查输出。
成功输出应包含：
{
"ok": true,
"tools": ["open_workspace", "read", "..."],
"markerSeen": true
}
- 检查 DevSpace 日志。
tail -n 40 ~/.devspace/logs/launchd.out.log
应看到：
tool_call open_workspace ... success:true
tool_call read ... success:true
判断结果
- 本地
/healthz 成功：只证明本地服务活着。
- 公网
/healthz 成功：证明 tunnel/DNS/HTTPS 到本地通。
- OAuth 成功：证明授权链路通。
tools/list 成功：证明 MCP capability 暴露成功。open_workspace/read 成功并读到 marker：证明工具真实执行。- server log 出现
tool_call：证明调用经过 DevSpace server。
只有最后三项成立，才算 MCP 调通。
常见问题
ChatGPT UI 显示点击以重试
先不要下结论。检查 tool call card 和 DevSpace server log。UI chip 可能滞后或显示异常，协议调用结果和 server log 更可靠。
401 Unauthorized
通常是 OAuth token 缺失、过期、resource 不匹配，或 owner password 没通过授权。重新跑 OAuth flow 或直接用 smoke 脚本验证。
allowedRoots 拒绝 workspace
把 workspace 放进 ~/.devspace/config.json 的 allowedRoots，再重启 DevSpace。
只想给 ChatGPT 读文件
DevSpace 默认会暴露更多工具。更保守的做法是额外部署只读 adapter，或在网络/身份层限制可访问 client。
完成标准
汇报完成时必须说明：
- DevSpace endpoint。
devspace config get 的非敏感摘要。tools/list 返回的工具名。open_workspace 返回的 workspaceId。read 读取到的 marker 或目标文件摘要。- DevSpace server log 中对应的
tool_call 证据。
不要把 owner password、access token 或完整私密日志写进最终回复。
