Specbridge

🚀 SpecBridge

SpecBridge 是一个 MCP 服务器，它可以将 OpenAPI 规范转换为 MCP 工具。你只需扫描一个包含 OpenAPI 规范文件的文件夹，就能自动生成相应的工具。无需配置文件，也无需单独的服务器，只需将规范文件放入文件夹即可。

本项目基于适用于 TypeScript 的 FastMCP 构建。

✨ 主要特性

• 🎯 零配置：文件系统即接口，只需将 OpenAPI 规范文件放入文件夹。
• 🔐 自动认证：通过简单的 .env 文件，使用 {API_NAME}_API_KEY 模式。
• 🏷️ 命名空间隔离：多个 API 可以清晰共存（例如，petstore_getPet、github_getUser）。
• 📝 全面支持 OpenAPI：处理参数、请求体、认证和响应。
• 🚀 多传输方式：支持标准输入输出和 HTTP 流。
• 🔍 内置调试功能：使用列表命令查看已加载的规范和工具。

🚀 快速开始

1️⃣ 安装（可选）

npm install -g specbridge

2️⃣ 创建规范文件夹

mkdir ~/mcp-apis

3️⃣ 添加 OpenAPI 规范

将任何 .json、.yaml 或 .yml 格式的 OpenAPI 规范文件放入你的规范文件夹：

# 示例：下载 Petstore 规范
curl -o ~/mcp-apis/petstore.json https://petstore3.swagger.io/api/v3/openapi.json

4️⃣ 配置认证（可选）

在你的规范文件夹中创建一个 .env 文件：

# ~/mcp-apis/.env
PETSTORE_API_KEY=your_api_key_here
GITHUB_TOKEN=ghp_your_github_token
OPENAI_API_KEY=sk-your_openai_key

5️⃣ 添加到 MCP 客户端配置

对于 Claude Desktop 或 Cursor，将其添加到你的 MCP 配置中：

如果已安装在你的机器上：

{
  "mcpServers": {
    "specbridge": {
      "command": "specbridge",
      "args": ["--specs", "/path/to/your/specs/folder"]
    }
  }
}

否则：

{
  "mcpServers": {
    "specbridge": {
      "command": "npx",
      "args": ["-y", "specbridge", "--specs", "/absolute/path/to/your/specs"]
    }
  }
}

💻 使用示例

基础用法

🚀 启动服务器

# 默认：标准输入输出传输，当前目录
specbridge

# 自定义规范文件夹
specbridge --specs ~/my-api-specs

# HTTP 传输模式
specbridge --transport httpStream --port 8080

📋 列出已加载的规范和工具

# 列出所有已加载的规范及其工具
specbridge list

# 列出自定义文件夹中的规范
specbridge list --specs ~/my-api-specs

🔑 认证模式

服务器会根据以下模式自动从环境变量中检测认证信息：

{API_NAME} 是从你的 OpenAPI 规范文件名中派生出来的：

• petstore.json → PETSTORE_API_KEY
• github-api.yaml → GITHUB_TOKEN
• my_custom_api.yml → MYCUSTOMAPI_API_KEY

🏷️ 工具命名

工具会根据以下模式自动命名：

• 有 operationId 时：{api_name}_{operationId}
• 无 operationId 时：{api_name}_{method}_{path_segments}

示例：

• petstore_getPetById（来自 operationId）
• github_get_user_repos（从 GET /user/repos 生成）

📁 文件结构

your-project/
├── api-specs/           # 你的 OpenAPI 规范文件夹
│   ├── .env            # 认证凭证
│   ├── petstore.json   # OpenAPI 规范文件
│   ├── github.yaml     # 
│   └── custom-api.yml  # 
└── mcp-config.json     # MCP 客户端配置

📄 示例 OpenAPI 规范

以下是一个创建两个工具的最小示例：

# ~/mcp-apis/example.yaml
openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /users/{id}:
    get:
      operationId: getUser
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
  /users:
    post:
      operationId: createUser
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
      responses:
        '201':
          description: User created

这将创建名为以下的工具：

• example_getUser
• example_createUser

🔧 故障排除

❌ 工具未显示？

1. 检查你的 OpenAPI 规范是否有效：

   specbridge list --specs /path/to/specs
   

2. 确保文件具有正确的扩展名（.json、.yaml、.yml）
3. 检查服务器日志中是否有解析错误

⚠️ 重要提示

在使用 --specs 参数和其他文件路径时，请使用绝对路径（无空格）。相对路径或包含空格的路径可能会在某些平台或某些 MCP 客户端上导致问题。

🔐 认证失败？

1. 验证你的 .env 文件是否位于规范目录中
2. 检查命名模式是否与你的规范文件名匹配
3. 使用列表命令验证认证配置：

   specbridge list
   

🔄 规范更改后工具未更新？

1. 重启 MCP 服务器以重新加载规范
2. 检查文件权限
3. 必要时重启 MCP 客户端

🛠️ 开发

# 克隆并安装
git clone https://github.com/TBosak/specbridge.git
cd specbridge
npm install

# 构建
npm run build

# 本地测试
npm run dev -- --specs ./examples

🤝 贡献

欢迎贡献代码！请随时提交问题和拉取请求。