Jambonz MCP

詹邦兹mcp

用于Jambonz文档智能和REST API控制的模型上下文协议（MCP）服务器。该软件包将Jambonz API参考公开为每个REST端点的一个MCP工具，并为架构、文档和操作指南提供本地文档查找。

免责声明：这是一个独立的社区套餐。它不是Jambonz的官方软件包，也不是由Jambonz团队开发、维护或支持的。

jambonz mcp与直接REST使用

该软件包为Jambonz提供了一个MCP接口。如果您将Jambonz连接到代理环境中，这将为您提供结构化的工具发现、端点级模式、权限门控和可重用的文档上下文。

• 直接REST：当你正在编写一个固定的应用程序集成，并且已经自己控制了HTTP客户端、身份验证生命周期、重试和验证时，情况会更好。
• 主控程序：当您希望代理动态发现工具、检查端点模式、使用文档作为上下文，并通过一致的工具界面执行Jambonz操作时，效果会更好。

主要特点

• 每个端点一个工具Jambonz REST API引用作为确定性工具公开，如 jambonz_alerts_list_alerts_by_account.
• 文档意识。公开用于端点发现的文档工具、资源和模式查找。
• 权限已关闭.强制执行 READ_ONLY, READ_WRITE，以及 ADMIN 在端点特定验证之前执行规则。
• 凭证安全默认值。返回机密或令牌的敏感端点会自动限制为 ADMIN.
• 运行时默认值.支持自动 AccountSid 注射时 JAMBONZ_ACCOUNT_SID 已配置。

需求

• Node.js 18或更新版本
• Codex、Claude Desktop、Cursor、Cline、VS Code或任何其他MCP客户端

入门

首先，在客户端上安装Jambonz MCP服务器。

标准配置 适用于大多数MCP客户端：

{
  "mcpServers": {
    "jambonz": {
      "command": "npx",
      "args": [
        "-y",
        "jambonz-mcp"
      ],
      "env": {
        "JAMBONZ_API_TOKEN": "your-token",
        "JAMBONZ_ACCOUNT_SID": "your-account-sid",
        "JAMBONZ_API_PERMISSION_LEVEL": "READ_ONLY"
      }
    }
  }
}

客户端设置

Codex

使用Codex CLI：

codex mcp add jambonz --env JAMBONZ_API_TOKEN=your-token --env JAMBONZ_ACCOUNT_SID=your-account-sid --env JAMBONZ_API_PERMISSION_LEVEL=READ_ONLY -- npx -y jambonz-mcp

或配置 ~/.codex/config.toml:

[mcp_servers.jambonz]
command = "npx"
args = ["-y", "jambonz-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.jambonz.env]
JAMBONZ_API_TOKEN = "your-token"
JAMBONZ_ACCOUNT_SID = "your-account-sid"
JAMBONZ_API_PERMISSION_LEVEL = "READ_ONLY"

Claude Desktop

遵循MCP安装 引导，使用上面的标准配置。

Cline

将服务器添加到 cline_mcp_settings.json:

{
  "mcpServers": {
    "jambonz": {
      "type": "stdio",
      "command": "npx",
      "timeout": 30,
      "args": [
        "-y",
        "jambonz-mcp"
      ],
      "env": {
        "JAMBONZ_API_TOKEN": "your-token",
        "JAMBONZ_ACCOUNT_SID": "your-account-sid",
        "JAMBONZ_API_PERMISSION_LEVEL": "READ_ONLY"
      }
    }
  }
}

Cursor

首选 Cursor Settings -> MCP -> Add new MCP Server 并使用：

• 命令： npx
• Args： -y jambonz-mcp

添加相同内容 JAMBONZ_* 标准配置中的环境变量。

VS Code

遵循MCP安装 引导，使用上面的标准配置。

它暴露了什么

文档工具

• jambonz_docs_search
• jambonz_docs_read
• jambonz_docs_schema

REST工具

• Jambonz API参考中每个REST端点一个MCP工具
• 确定性命名： jambonz__
• 示例：

- jambonz_alerts_list_alerts_by_account - jambonz_recent_calls_list_recent_calls - jambonz_users_create_user

资源和提示

• jambonz://docs/index
• jambonz://rest/catalog
• jambonz://rest/usage
• jambonz://runtime/defaults
• jambonz://doc/{path}
• jambonz://schema/{operationId}
• 提示： jambonz_usage_guide

配置

服务器是通过环境变量配置的。

权限模型

• READ_ONLY: GET
• READ_WRITE: GET, POST, PUT, PATCH
• ADMIN: GET, POST, PUT, PATCH, DELETE

附加规则：

• 返回机密、令牌、密码、webhook机密、API密钥或类似凭证材料的端点被强制 ADMIN 即使HTTP方法是 GET.

文档行为

该包可以在没有本地文档的情况下运行，但文档工具依赖于同步的文档目录。

如果你想要完整的文档界面(jambonz_docs_*, jambonz://doc/{path}, jambonz://schema/{operationId})，set JAMBONZ_DOCS_DIR 到Jambonz文档的本地同步副本。

代理运行时指南：

• jambonz://runtime/defaults 告诉代理哪个权限级别是活动的，以及是否为默认权限级别 AccountSid 已配置。
• 如果 JAMBONZ_ACCOUNT_SID 已设置，代理可以省略 pathParams.AccountSid 对于帐户范围的路由。
• 在对被阻止的方法进行端点特定参数验证之前，权限失败会返回。

发展

如果您使用的是源代码而不是已发布的包：

1. 安装依赖项：

- npm install

1. 同步本地Jambonz文档：

- npm run jambonz:sync

1. 重新生成REST目录：

- npm run rest:catalog:generate

1. 验证：

- npm run typecheck - npm test

命令

• npm run dev：从源使用stdio传输启动MCP服务器
• npm run build：构建已发布的ESM捆绑包
• npm run typecheck：运行TypeScript验证
• npm test：运行确定性单元测试
• npm run protocol:sync：刷新本地MCP协议文档 docs/protocol
• npm run jambonz:sync：在中刷新本地Jambonz文档 docs/jambonz
• npm run rest:catalog:generate：重新生成 src/rest/catalog.generated.ts
• npm run rest:catalog:check：验证生成的REST目录是最新的
• npm run inspect：针对本地源代码构建启动MCP检查器
• npm run inspect:help：显示MCP检查器CLI选项

发布

此存储库在匹配的Git标签上将包发布到npm v* 使用GitHub操作。

释放流量：

1. 确保 package.json 版本与预期版本匹配
2. 推一个标签，例如 v1.0.3
3. 配置存储库密钥 NPM_TOKEN

工作流安装依赖项，显式安装Linux Rollup本机二进制文件，运行 typecheck，运行 test，构建 dist/，并在启用出处的情况下发布。