mcp-dev-agent

通过 Streamable HTTP 运行的 MCP（Model Context Protocol） 服务器，为 AI 代理——由 Microsoft Copilot Studio 代理消费——提供与 Claude Code 代理在此 VM 中相同的开发能力：执行命令、编辑/移动/列出文件，以及使用 node、npm、gh、git 等。由代理决定运行哪些命令。

文档

• docs/RECOMENDACAO.md — 生产环境前的架构建议和后续步骤。

• docs/DEPLOY-CLOUDFLARE.md — 通过 Cloudflare Tunnel 暴露（公共 HTTPS，无需开放端口）。

• docs/CREDENCIAIS.local.md — 机密，不纳入版本控制（.gitignore）：生产环境中的 URL、令牌和隧道数据（mcp.criaelo.com）。

Related MCP server: SkyDeckAI Code

架构

Copilot Studio (nuvem)
        │  HTTPS + Bearer token
        ▼
[ Reverse proxy / túnel com TLS ]   ← obrigatório: Copilot Studio exige HTTPS público
        │
        ▼
mcp-dev-agent  (Express + Streamable HTTP, porta 3000)
        │  child_process / fs
        ▼
  VM de desenvolvimento  (node, npm, gh, git, arquivos das aplicações)

• 传输方式： Streamable HTTP（单一端点 POST/GET/DELETE /mcp），这是 Copilot Studio 消费 MCP 的方式。

• 认证（两种方式，/mcp 均接受）：

  • 静态 Bearer 令牌，通过 Authorization 请求头（MCP_AUTH_TOKEN 变量）——供 Copilot Studio 使用。

  • OAuth 2.1，遵循 MCP 授权规范（Dynamic Client Registration、authorization code + PKCE、refresh token）——ChatGPT 要求。端点：/.well-known/oauth-authorization-server、/.well-known/oauth-protected-resource/mcp、/authorize、/token、/register、/revoke。审批时需要输入 OAUTH_APPROVAL_PASSWORD 密码（回退：MCP_AUTH_TOKEN）。客户端和令牌存储在 data/oauth-state.json 中（不纳入版本控制，chmod 600）；实现在 src/oauth.ts 中。

• 文件范围： 无路径限制——代理可操作 VM 中的任何路径（项目决策）。解析 ~ 和相对路径。

暴露的工具

run_command 单独就能覆盖所有操作；文件工具的存在是因为它们对代理来说比拼装 shell 命令更可靠、更易读。

运行

npm install
npm run build

# gere um token forte e exporte antes de iniciar
export MCP_AUTH_TOKEN=$(openssl rand -hex 32)
export PORT=3000
# producao: URL publica HTTPS (issuer OAuth) e senha da tela de aprovacao
export PUBLIC_URL=https://seu-host
export OAUTH_APPROVAL_PASSWORD=uma-senha-forte
npm start

带热重载的开发模式：npm run dev（同样需要 MCP_AUTH_TOKEN）。

健康检查（无需认证）：GET /health → { "status": "ok", "tools": [...] }。

快速测试握手

curl -X POST http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}'

响应头 Mcp-Session-Id 必须在后续调用（tools/list、tools/call）中重新发送。

使用 HTTPS 暴露（Copilot Studio 必需）

Copilot Studio（云端）只能访问公共 HTTPS 端点。请将服务器置于 TLS 之后。选项：

• 反向代理（nginx/Caddy），使用证书，转发到 http://127.0.0.1:3000。

• 隧道 快速暴露：cloudflared、ngrok，如果 VM 是 Azure 的，也可以使用 Azure Application Gateway / Front Door。

当前面有代理时，请让 MCP 服务器监听 127.0.0.1，以免暴露裸 HTTP 端口。

连接到 Copilot Studio

Copilot Studio 通过指向 Streamable HTTP 端点的 tool/custom connector 来消费 MCP：

1. 在 Copilot Studio 中，打开你的代理 → Tools → Add a tool → New tool → Model Context Protocol。 （或者，Power Apps → Custom connectors 并导入下面的规范。）

2. Server URL： 指向 /mcp 的公共 HTTPS URL（例如：https://seu-host/mcp）。

3. 身份验证： 类型为 API Key / 请求头，使用 Authorization 头，值为 Bearer <seu MCP_AUTH_TOKEN>。将令牌保存在 connector 的密钥库/环境变量中，切勿放在提示词中。

4. 保存并发布 connector；将 tool 添加到代理。

5. 这 8 个工具会出现在代理中，代理将自行决定何时调用 run_command、edit_file 等。

注意：Copilot Studio 对 MCP 的支持发展很快。如果 UI 在你的区域/许可证下不提供原生 MCP，请创建一个 custom connector，使用描述 /mcp 端点（Streamable HTTP）和 Authorization 头的 OpenAPI 规范。

连接到 ChatGPT

ChatGPT 要求 OAuth（不接受静态 Bearer 令牌），并且需要 developer mode（Plus/Pro）或 Business/Enterprise 套餐：

1. Settings → Connectors → Create（在 Settings → Connectors → Advanced 中启用 developer mode）。

2. MCP Server URL： https://seu-host/mcp — Authentication： OAuth。

3. ChatGPT 通过 /.well-known/* 发现端点，自行注册（DCR）并打开审批页面：输入 OAUTH_APPROVAL_PASSWORD。

4. 完成——访问令牌有效期为 2 小时，并通过刷新令牌自动续期（30 天，带轮换）。

要撤销 ChatGPT 的访问权限：删除 data/oauth-state.json 并重启服务（或使用 /revoke）。

安全——生产环境前请阅读

此服务器会在 VM 上执行任意命令。后果：

• 将 MCP_AUTH_TOKEN 视为 VM 的 root 访问凭据。定期轮换。

• 使用专用的低权限用户运行进程，不要以 root 身份运行。

• 每个项目最好使用可丢弃/隔离的 VM；不要指向包含其他系统敏感数据的机器。

• 始终位于 TLS 之后；切勿在互联网上暴露裸 HTTP 端口。

• 如果需要可追溯性，请考虑对收到的命令进行审计日志记录。