AppCrane

appcrane-mcp

专为 AppCrane 打造的独立 MCP 连接器——这是一个可自托管的部署平台，用于部署由 AI 构建的应用。

AppCrane 在 <instance>/api/mcp 提供 MCP 服务，并要求提供 X-API-Key。此软件包是一个轻量级的 stdio MCP 服务，它：

1. 无需任何配置，即可通过 tools/list 查看完整的 appcrane_* 工具目录——软件包内置了 catalog.json，因此注册表和沙盒（例如 Glama）可以在容器中启动它并离线查看工具。
2. 设置 APPCRANE_URL 和 APPCRANE_KEY 后，将真实的 tools/call 请求代理到你自己的 AppCrane 实例。

只要有 Node 20+，即可通过 npx appcrane-mcp 在任何地方运行。

**许可：**此连接器采用 MIT 许可证。它所连接的 AppCrane 平台属于另一个项目，采用 AGPL-3.0 许可证。安装此软件包不会一并安装该平台——此连接器是客户端，会连接到你自行托管的 AppCrane 实例。

连接方式

此处没有托管服务，也不需要 AppCrane 账号。整个流程完全由你自己掌控：

1. 在你控制的某处自托管 AppCrane（AGPL）。
2. 从该实例生成 API 密钥。
3. 你的 Agent 通过 stdio 在本地运行此连接器（npx -y appcrane-mcp）。
4. 连接器使用你的 X-API-Key 将每个 tools/call 请求转发到 ${APPCRANE_URL}/api/mcp。密钥保存在你自己的 MCP 客户端配置中，绝不会发送到你设置的实例 URL 以外的任何地方。

安装 / 运行

npx appcrane-mcp

即使没有设置环境变量，服务也会启动，并从内置目录响应 tools/list（共 57 个工具）。若要实际调用实例上的工具，请设置：

环境变量	必填	说明
APPCRANE_URL	调用时必填	实例基础 URL，例如 https://crane.example.com
APPCRANE_KEY	调用时必填	你的 AppCrane API 密钥（作为 X-API-Key 发送）
APPCRANE_GITHUB_TOKEN	可选	GitHub PAT（作为 X-Github-Token 发送），用于启用 github_* 直通工具

MCP 客户端配置

这是一个 stdio 命令服务（不是 HTTP 端点）。按如下方式将其添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "appcrane": {
      "command": "npx",
      "args": ["-y", "appcrane-mcp"],
      "env": {
        "APPCRANE_URL": "https://crane.example.com",
        "APPCRANE_KEY": "your_api_key",
        "APPCRANE_GITHUB_TOKEN": "ghp_optional_for_github_passthrough"
      }
    }
  }
}

Claude Code CLI：

claude mcp add appcrane \
  --env APPCRANE_URL=https://crane.example.com \
  --env APPCRANE_KEY=your_api_key \
  -- npx -y appcrane-mcp

工作原理

• tools/list
  • 如果已设置 APPCRANE_URL + APPCRANE_KEY → 连接到 ${APPCRANE_URL}/api/mcp（StreamableHTTP，使用 X-API-Key 标头；设置 GitHub token 时还会使用 X-Github-Token），获取实时且经过身份验证过滤的工具列表并返回。如果无法访问实例，则回退到内置目录。
  • 如果未配置 → 返回内置静态目录（catalog.json）。此路径无需环境变量，注册表的查看沙盒会使用此路径。
• tools/call → 需要 APPCRANE_URL + APPCRANE_KEY；将调用转发到后端并返回其结果。未配置时会返回明确的“未配置”错误。

Docker

docker build -t appcrane-mcp .

# Introspection only (no config) — starts and serves tools/list:
docker run -i --rm appcrane-mcp

# Full use:
docker run -i --rm \
  -e APPCRANE_URL=https://crane.example.com \
  -e APPCRANE_KEY=your_api_key \
  appcrane-mcp

开发

npm install
npm run build          # tsc -> dist/
npm run gen:catalog    # regenerate catalog.json from the AppCrane platform source
npm run check:catalog  # fail if catalog.json has drifted from that source
node scripts/test-list.mjs   # smoke test: spawn over stdio, assert tools/list

两个目录脚本都会从同级的 deployhub 检出目录导入平台自带的 getToolCatalog()；如果你的文件位于其他位置，请将 APPCRANE_SRC 设置为指向其 server/services/mcpTools.js。

发布

更新 package.json 中的 version，提交，然后推送匹配的标签：

git tag v1.7.1 && git push origin v1.7.1

.github/workflows/publish.yml 使用 npm Trusted Publishing 将其发布到 npm：无需 npm 令牌或一次性密码，且 npm 会附加来源证明（构建所依据的提交）。工作流会拒绝与 package.json 不匹配的标签，并在发布前将目录与平台当前的 main 分支进行核对，因此过时的 catalog.json 不会被发布。（它以前曾悄无声息地过时：落后平台 22 个工具，且宣传有 35 个，实际却有 57 个。）先在本地运行 npm run check:catalog，及时发现问题，不必等 CI 检查。

同一标签也会通过 OIDC 在官方 MCP Registry 中将此版本列为 io.github.gitayg/appcrane。请同时更新 server.json 中的 version 和 packages[0].version，以及 package.json：工作流会拒绝与这三处都不匹配的标签。（此前自动化尚未实现时，npm 已有新版本，列表却仍停留在 1.0.0。）

打包的 catalog.json 根据 AppCrane 平台中的实际工具定义（deployhub/server/services/mcpTools.js）生成，并采用与 AWS 对齐的工具命名（appcrane_set_secret、appcrane_get_secret、appcrane_cp 以及 stage 参数）。该文件会提交到代码库，因此发布的包是自包含的。

关于 AppCrane

AppCrane 是一个可自托管的平台，用于托管由 AI 构建和部署的应用。此连接器采用 MIT 许可，以最大限度地促进采用；平台本身采用 AGPL 许可。

• 此连接器（MIT）：https://github.com/gitayg/appcrane-mcp
• 平台（AGPL-3.0）：https://github.com/gitayg/appCrane
• 产品页面：https://glick.run/appcrane.html