Heroku Code MCP

Heroku Code MCP

面向 Heroku Platform API 的精简 MCP 服务，采用 Code Mode 模式：search + execute + auth_status。

Heroku Code MCP 为 Agent 客户端提供了精简且节省 token 的 Heroku 操作控制界面。若希望在使用实时 API 工具的同时获得工作流指导、安全检查和 Heroku 产品背景信息，可将其与 Heroku Skills 搭配使用。

设计参考：

• Cloudflare Code Mode MCP
• Anthropic：构建有效的 Agent

快速开始

默认 MCP URL：http://127.0.0.1:3000/mcp

git clone https://github.com/dsouzaAnush/heroku-code-mcp.git
cd heroku-code-mcp
npm install
npm run build
npm test

从 Heroku CLI 初始化身份验证：

heroku auth:whoami
npm run seed:token

启动服务：

TOKEN_STORE_PATH=./data/tokens.integration.json \
TOKEN_ENCRYPTION_KEY_BASE64="<seed-output-key>" \
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

发布到 npm 之前，也可以从 GitHub 运行此软件包：

HOST=127.0.0.1 PORT=3333 \
TOKEN_STORE_PATH="$HOME/.heroku-code-mcp/tokens.json" \
TOKEN_ENCRYPTION_KEY_BASE64="<base64-32-byte-key>" \
WRITE_CONFIRMATION_SECRET="<random-secret>" \
npx -y github:dsouzaAnush/heroku-code-mcp

在 Agent 客户端中安装

Claude Code

安装配套插件，以使用技能并配置 MCP：

claude plugin marketplace add dsouzaAnush/heroku-plugin
claude plugin install heroku@heroku-plugin
claude plugin enable heroku@heroku-plugin

或者直接添加正在运行的 MCP 服务：

claude mcp add \
  --transport http \
  --scope local \
  heroku-code-mcp \
  http://127.0.0.1:3000/mcp \
  --header "x-user-id: default"

Claude Desktop

在支持时直接使用 HTTP 端点：

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

对于需要 stdio 服务的 Desktop 版本，可通过 mcp-remote 桥接：

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

使用以下命令构建 .mcpb 捆绑包：

npm run build:mcpb

Codex

Codex 使用 Heroku Plugin 提供技能和可选的 MCP 配置：

codex plugin marketplace add dsouzaAnush/heroku-plugin --ref main

在 Codex 的 Plugins 选项卡中启用 heroku-plugin@heroku-plugin，或添加：

[plugins."heroku-plugin@heroku-plugin"]
enabled = true

如果想通过插件使用实时 Heroku API 工具，请在 http://127.0.0.1:3333/mcp 上运行此 MCP 服务。

Cursor

git clone https://github.com/dsouzaAnush/heroku-plugin.git
cursor agent --plugin-dir heroku-plugin

将 MCP 服务添加到 ~/.cursor/mcp.json 或项目本地的 .cursor/mcp.json：

{
  "mcpServers": {
    "heroku-code-mcp": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3333/mcp",
      "headers": {
        "x-user-id": "default"
      }
    }
  }
}

其他 MCP 客户端

使用可流式传输的 HTTP：

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

或桥接到 stdio：

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

工作原理

工具	功能	用途
auth_status	报告调用方是否已通过 Heroku 身份验证	让 Agent 在调用 API 前能够清晰地选择后续流程
search	根据架构和文档上下文对 Heroku 操作进行排序	避免一开始就暴露几十个与端点一一对应的工具
execute	验证参数／请求体并调用所选的 Heroku 操作	提供单一且确定的执行路径

典型流程：

1. 调用 auth_status。
2. 使用自然语言意图调用 search。
3. 选择一个 operation_id。
4. 使用 path_params、query_params 和 body 调用 execute。
5. 对于写入操作，先运行 dry_run=true，然后使用返回的 confirm_write_token 和 ALLOW_WRITES=true 重试。

示例：

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

{
  "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 重试。敏感请求头和请求体字段会被脱敏。

主要环境变量：

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

完整示例：.env.example

基准测试

基准测试于 2026 年 2 月 22 日在同一台机器上进行，两个实现使用同一账户。

指标	heroku-code-mcp	官方 Heroku MCP	差异
工具数量	3	37	少 91.9%
工具列表载荷字节数	1,469	25,500	少 94.2%
工具列表近似 token 数	368	6,375	少 94.2%
平均连接耗时	14.8 ms	10,168.7 ms	快 687 倍
list_tools 平均耗时	4.3 ms	10.3 ms	快 2.4 倍
平均读取操作耗时	528.0 ms（execute GET /apps）	9,697.4 ms（list_apps）	快 18.4 倍

图表：

• 
• 

完整的方法说明和产物见 BENCHMARKS.md 和 benchmarks/results/。

开发与发布

在本地验证：

npm run build
npm test
npm run validate:server
npm run publish:dry-run

此仓库使用免费的 GitHub Actions：

• validate.yml 在 PR 和推送到 main 时运行构建、测试、server.json 验证和 npm pack 试运行。
• release.yml 在 v* 标签上运行，构建 .mcpb、更新发布版 server.json、创建或更新 GitHub Release，并通过 GitHub OIDC 发布到 MCP Registry。
• Dependabot 每周检查 npm 和 GitHub Actions 依赖项。

需要时手动发布：

npm publish --access public
mcp-publisher login github
mcp-publisher publish server.json

如需通过 CI 发布 npm，请为仓库 dsouzaAnush/heroku-code-mcp 和工作流 release.yml 配置 npm 可信发布，然后运行发布工作流并设置 publish_npm=true。

仓库结构

• src/schema/*：数据导入、操作规范化和缓存
• src/search/*：搜索索引和排序
• src/execute/*：验证和 Heroku API 执行
• src/auth/*：OAuth 和加密令牌存储
• tests/*：目录、搜索和执行测试
• benchmarks/results/*：基准测试产物
• server.json：MCP Registry 元数据

品牌与故障排除

此仓库在 assets 下包含官方 Heroku 字标和标志。请按照 Heroku 品牌指南使用。

常见问题修复：

• MCP Inspector 连接错误：确认 URL http://127.0.0.1:3000/mcp 和服务健康状态。
• AUTH_REQUIRED：添加令牌或完成 OAuth。
• 写入被阻止：确认 ALLOW_WRITES=true，并发送试运行确认令牌。
• 响应正文过大：缩小查询范围或降低输出上限。