SpecBridge MCP

SpecBridge MCP 是一个**“克隆即用”的 MCP 入门项目**，旨在为 AI 智能体提供 OpenAPI/Huma 合约智能。它将 OpenAPI/Huma 规范转换为确定性的端点元数据、模式、验证事实、引用的 DTO 以及 TypeScript 声明，智能体可以在修改前端或客户端代码之前使用这些信息。

本项目旨在以仓库为先，而非发布 npm 包：克隆它，根据您的私有或公共规范调整后端注册表，并将本地 MCP 服务器注册到您的智能体宿主中。该实现通过避免下游文件变更、使用中立的公共演示后端、支持多个注入后端以及将推断出的辅助信息视为尽力而为而非保证，保持了核心的非主观性。

状态：实验性。该工具界面对于本地自动化很有用，但该仓库旨在由每个团队自行拥有和调整。

简史

SpecBridge MCP 最初是 SesameLab 的一个内部个人工具，旨在改善后端 API 合约的开发周期。在实践中，通过 MCP 为 AI 智能体提供结构化的 OpenAPI/Huma 合约数据，比直接让它们阅读 API 文档页面减少了幻觉。

它提供了什么

• 可配置的后端注册表，支持一个或多个 OpenAPI/Huma 兼容规范

• 使用真实公共 OpenAPI URL 的零配置演示后端

• 支持 JSON/YAML 的规范加载和刷新

• 端点列表和过滤

• 包含确定性事实的端点合约包：

  • 操作元数据

  • 参数

  • 请求和响应模式

  • 引用的组件模式

  • 端点作用域的 TypeScript DTO 声明

  • 验证事实，如 required、nullable、enum、format、数组、映射和组合

• 从组件模式生成 TypeScript DTO 声明

• 尽力而为的建议辅助工具，明确作为确定性规范事实的次要补充

非目标

• 将此项目发布到 npm 以实现 v1

• 提供通用的可安装 CLI 抽象

• 变更下游前端/客户端仓库

• 成为特定于框架的客户端或 SDK 生成器

• 远程托管规范或存储团队 API 数据

要求

• Node.js 18+

• pnpm 10+

安装

git clone <your-fork-or-copy-url> specbridge-mcp
cd specbridge-mcp
pnpm install
pnpm build

配置后端

SpecBridge 附带了指向公共演示 API 的 openapi.backends.json，因此工具可以立即工作。

要使用您自己的 API，请编辑 openapi.backends.json 或将 OPENAPI_BACKENDS_FILE 指向另一个 JSON 文件。

[
  {
    "id": "public-demo",
    "name": "Public Demo API",
    "specUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "description": "Public OpenAPI demo backend",
    "domainHints": ["/pet", "/store", "/user"]
  },
  {
    "id": "local-service",
    "name": "Local Service API",
    "specUrl": "http://localhost:8080/openapi.json",
    "fallbackSpecUrls": ["http://localhost:8080/openapi.yaml"],
    "description": "Your local service contract"
  }
]

配置优先级

对于工具调用，首先会尝试该调用的显式 specUrl 覆盖。

后端注册表源按以下顺序合并，后面的源通过 id 覆盖前面的源：

1. 内置公共演示后端

2. 仓库本地的 openapi.backends.json（如果存在）

3. OPENAPI_BACKENDS_FILE（如果已设置）

4. OPENAPI_BACKENDS（如果已设置）

DEFAULT_BACKEND_ID 选择默认后端。如果未设置，SpecBridge 使用 swagger-petstore。

环境变量

• MCP_TRANSPORT: stdio 或 http

• MCP_HTTP_HOST: HTTP 绑定主机

• MCP_HTTP_PORT: HTTP 端口

• MCP_HTTP_PATH: MCP 端点路径，例如 /mcp

• MCP_HTTP_STATELESS: 设置为 true 以启用无状态 HTTP 模式

• DEFAULT_BACKEND_ID: 默认后端 ID

• OPENAPI_BACKENDS: 后端配置的 JSON 数组

• OPENAPI_BACKENDS_FILE: 后端配置 JSON 文件的路径

• OPENAPI_FETCH_TIMEOUT_MS: 规范加载的获取超时时间

• OPENAPI_CACHE_TTL_MS: 内存中规范缓存的 TTL

• OPENAPI_ENABLE_SWAGGER_UI_SCRIPT_EXTRACTION: 选择从静态 Swagger UI 脚本中提取严格的 JSON 对象；获取的 JavaScript 永远不会被执行

运行

stdio 模式

pnpm mcp
# or
./mcp-server.sh

HTTP 模式

pnpm mcp:http

无状态 HTTP 模式：

pnpm mcp:http:stateless

MCP 宿主设置

基于命令的 stdio 配置

{
  "mcpServers": {
    "specbridge-mcp": {
      "command": "/absolute/path/to/specbridge-mcp/mcp-server.sh"
    }
  }
}

Codex config.toml 示例

[mcp_servers.specbridge-mcp]
args = ["/absolute/path/to/specbridge-mcp/mcp-server.sh"]
command = "bash"

HTTP URL

启动服务器：

./mcp-server.sh --transport http --host 127.0.0.1 --port 3000 --path /mcp

然后将您的宿主连接到：

• http://127.0.0.1:3000/mcp

如果您的宿主在会话状态方面遇到问题，请使用 --stateless 重试。

工具

推荐流程：

1. list_backends

2. load_openapi_spec

3. list_api_endpoints

4. get_endpoint_contract

5. generate_typescript_dto

list_backends

列出已配置的后端目标、默认后端 ID 和可选的域提示。

load_openapi_spec

为后端加载或刷新 OpenAPI/Huma 兼容规范。支持直接的 specUrl 覆盖。

list_api_endpoints

列出已加载规范中的端点，支持可选的标签、方法、路径子字符串和限制过滤器。

get_endpoint_contract

返回确定性的端点合约包：操作元数据、参数、请求体、响应、引用的模式、端点作用域的 TypeScript DTO 声明、验证事实以及尽力而为的提示。

generate_typescript_dto

从组件模式名称生成 TypeScript DTO 声明，并包含引用的嵌套 DTO 类型。

propose_new_endpoint

返回与当前规范中发现的模式一致的尽力而为的端点和 DTO 建议。请将其视为智能体辅助工具，而非确定性保证。

开发

pnpm install
pnpm check
pnpm build
pnpm test

有用的脚本：

• pnpm check: Biome 检查

• pnpm format: 应用 Biome 格式化

• pnpm lint: 仅 Biome lint

• pnpm build: 清理 TypeScript 构建

• pnpm test: 构建并运行所有测试

• pnpm test:e2e: 构建并运行 MCP 冒烟测试

克隆即用指南

SpecBridge 旨在以仓库为先。保持核心精简，在本地调整后端配置，并让下游智能体决定如何编辑您的客户端代码。如果您的团队需要自定义身份验证、内部命名规则或额外的合约事实，请在您的克隆版本中添加它们，而不是与全局包抽象作斗争。