Heroku Code MCP

Herold代码MCP

用于Heroku平台API的令牌高效MCP服务器，使用代码模式模式： search + execute + auth_status.

设计参考：

• Cloudflare代码模式MCP
• Anthropic：构建有效代理（高级工具使用）

上下文比较

实际影响是，代理从一个小得多的工具模式开始，然后要求服务器进行即时端点发现。这使得用户意图、计划和响应质量能够及时获得预算，而不是将其花费在静态端点元数据上。

问题

Heroku的API表面很宽，每个工具的终结点MCP模型使代理在拥有足够的任务上下文之前在许多工具之间进行选择。这通常会增加工具选择的模糊性，提前消耗令牌，并使多步骤任务更加脆弱。问题不在于许多工具本身就很糟糕，而在于模型上下文稀缺，端点选择是一个代理规划问题，而不仅仅是一个传输问题。

方法

此服务器应用具有确定性输入的代码模式风格控制循环：

1. search 将自然语言意图映射到排名 operation_id 候选人。
2. execute 验证并执行所选的Heroku API操作。
3. auth_status 提供显式的身份验证状态，以便代理可以干净地分支。

服务器集中保存模式智能和安全策略。代理得到一个小的控制面和一个稳定的执行契约。

工具

Agent                           MCP Server
  │                                  │
  ├──search({query: "list apps"})──►│ rank operations from catalog/index
  │◄──[GET /apps, ...]───────────────│
  │                                  │
  ├──execute({operation_id: ...})───►│ validate + call Heroku API
  │◄──{status, headers, body}────────│

基准亮点

2026年2月22日，在同一台机器上捕获了基准，并对这两种实现进行了说明。下面的数字将此仓库的本地HTTP MCP端点与stdio上的官方Heroku MCP服务器进行了比较。

原始比较

对比图

这些是静态图表，因此标签在GitHub中保持可读性，而不需要巨大的自动缩放Mermaid面板。

Context reduction chart

Latency comparison chart

如何阅读这些结果

最强的胜利是上下文足迹。3工具接口大大降低了初始提示开销，并减少了模型的工具选择分支。第二个胜利是在此基准线束下的连接和读取路径延迟。在测量运行中，官方的Heroku MCP支付了更大的连接时间成本，其测量的读取操作比 execute GET /apps 在这台服务器上。

这并不意味着每个环境中的每个端点都将始终具有相同的乘数。这意味着在此设置中测量的默认体验有利于代码模式控制界面的上下文经济性和延迟。

基准方法

• 日期：2026年2月22日。
• 环境：相同的本地机器，相同的Heroku帐户，温暖的网络。
• 自定义服务器运行计数：10。
• 官方服务器运行计数：3。
• 上下文估计： ceil(list_tools_json_bytes / 4) 用于粗略的令牌近似。
• 读取比较配对：

- 自定义： execute GET /apps - 官方： list_apps

人工产品：

• benchmarks/results/context-footprint-2026-02-22.json
• benchmarks/results/custom-local-http-2026-02-22.json
• benchmarks/results/official-heroku-mcp-start-2026-02-22.json
• BENCHMARKS.md

开始使用

MCP网址： http://127.0.0.1:3000/mcp

cd heroku
npm install
npm run build
npm test

选项1:OAuth（推荐）

配置OAuth环境变量并使用 /oauth/start + /oauth/callback.

选项2：从Heroku CLI进行本地令牌种子设定

heroku auth:whoami
npm run seed:token

启动服务器：

TOKEN_STORE_PATH=./data/tokens.integration.json \
TOKEN_ENCRYPTION_KEY_BASE64='' \
PORT=3000 HOST=127.0.0.1 npm run dev

烟雾测试：

curl -sS http://127.0.0.1:3000/healthz
MCP_URL=http://127.0.0.1:3000/mcp USER_ID=default npm run smoke:mcp

添加到代理

可直接流式传输的HTTP

{
  "mcpServers": {
    "heroku-code-mcp": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "x-user-id": "default"
      }
    }
  }
}

指挥桥（如需要）

{
  "mcpServers": {
    "heroku-code-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3000/mcp"],
      "env": {
        "MCP_REMOTE_HEADERS": "{\"x-user-id\":\"default\"}"
      }
    }
  }
}

典型工作流程

1. 呼叫 auth_status.
2. 呼叫 search 意图。
3. 选一个 operation_id.
4. 呼叫 execute 随着 path_params, query_params，以及 body 根据需要。
5. 对于写入，请运行 dry_run=true 首先，然后重播 confirm_write_token 和 ALLOW_WRITES=true.

示例 search:

{
  "query": "list apps",
  "limit": 5
}

示例阅读 execute:

{
  "operation_id": "GET /apps"
}

示例写模拟运行：

{
  "operation_id": "PATCH /apps/{app_identity}",
  "path_params": {
    "app_identity": "my-app"
  },
  "body": {
    "maintenance": true
  },
  "dry_run": true
}

安全和护栏

• 突变(POST, PATCH, PUT, DELETE)默认情况下被阻止。
• 突变需要两者 ALLOW_WRITES=true 以及匹配 confirm_write_token.
• 敏感的页眉和正文字段已被编辑。
• 一次性重试(GET / HEAD)为瞬态故障启用。

性能设计

• 3-tool MCP表面最大限度地减少了前端工具上下文。
• 持久目录缓存(CATALOG_CACHE_PATH)避免冷启动后再次摄入。
• 后台刷新将摄取与请求路径分离。
• 条件获取(ETag/Last-Modified)降低刷新成本。
• 短读缓存(READ_CACHE_TTL_MS)改善了重复读取延迟。
• 输出界限(EXECUTE_MAX_BODY_BYTES, EXECUTE_BODY_PREVIEW_CHARS)防止过大的反应主导上下文。

配置

关键环境变量：

• ALLOW_WRITES
• REQUEST_TIMEOUT_MS
• MAX_RETRIES
• CATALOG_CACHE_PATH
• READ_CACHE_TTL_MS
• EXECUTE_MAX_BODY_BYTES
• EXECUTE_BODY_PREVIEW_CHARS

完整示例： .env.example

仓库的规划

• src/schema/*：摄取+操作规范化+缓存
• src/search/*：搜索索引+排名
• src/execute/*：验证+Heroku API执行
• src/auth/*：OAuth+加密令牌存储
• tests/*：编目/搜索/执行测试
• benchmarks/results/*：基准工件
• BENCHMARKS.md：基准方法细节
• REFERENCES.md：外部参考

故障排除

• MCP检查器连接错误：确认URL为 http://127.0.0.1:3000/mcp 服务器正在运行。
• AUTH_REQUIRED：种子令牌或完整的OAuth流。
• 写入受阻：设置 ALLOW_WRITES=true 并发送匹配 confirm_write_token.
• 响应体大：查询范围窄或输出上限低，以实现更严格的截断。