规格桥接器

Name: 规格桥接器
Author: TBosak

作者：TBosak5 星标更新：2025-07-19

安装使用来源：spider==github.com

项目介绍

<h1 align="center"> SpecBridge

</h1> 一个将OpenAPI规范转换为MCP工具的MCP服务器。扫描包含OpenAPI规范文件的文件夹，并自动生成相应的工具。无需配置文件，无需单独的服务器——只需将规范文件放入文件夹即可获得工具。

使用FastMCP构建，支持TypeScript。

✨ 特性

🎯 零配置：文件系统即接口——只需将OpenAPI规范文件放入文件夹
🔐 自动认证：简单的.env文件，使用{API_NAME}_API_KEY模式
🏷️ 命名空间隔离：多个API可以干净地共存（例如，petstore_getPet，github_getUser）
📝 全面支持OpenAPI：处理参数、请求体、认证和响应
🚀 多种传输方式：支持stdio和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"]
    }
  }
}

💻 CLI 使用

🚀 启动服务器

# 默认：stdio传输，当前目录
specbridge

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

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

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

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

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

🔑 认证模式

服务器通过环境变量自动检测认证，使用以下模式：

模式	认证类型	使用
`{API_NAME}_API_KEY`	🗝️ API密钥	`X-API-Key`头部
`{API_NAME}_TOKEN`	🎫 承载令牌	`Authorization: Bearer {token}`
`{API_NAME}_BEARER_TOKEN`	🎫 承载令牌	`Authorization: Bearer {token}`
`{API_NAME}_USERNAME` + `{API_NAME}_PASSWORD`	👤 基本认证	`Authorization: Basic {base64}`

{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: 示例API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /users/{id}:
    get:
      operationId: getUser
      summary: 根据ID获取用户
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 用户找到
  /users:
    post:
      operationId: createUser
      summary: 创建新用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
      responses:
        '201':
          description: 用户创建

这将创建名为：

example_getUser
example_createUser

🔧 故障排除

❌ 没有工具出现？

确认您的OpenAPI规范有效：
```
specbridge list --specs /path/to/specs
```
确保文件具有正确的扩展名（.json，.yaml，.yml）
检查服务器日志中的解析错误

⚠️ 注意：Specbridge在您使用绝对路径（不含空格）作为--specs参数和其他文件路径时效果最佳。相对路径或包含空格的路径可能在某些平台或某些MCP客户端上引起问题。

🔐 认证不起作用？

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

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

重启MCP服务器以重新加载规范
检查文件权限
如需，重启MCP客户端

🛠️ 开发

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

# 构建
npm run build

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

🤝 贡献

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