使用说明

SpecBridge

An MCP server that turns OpenAPI specifications into MCP tools. Scan a folder for OpenAPI spec files and automatically generate corresponding tools. No configuration files, no separate servers - just drop specs in a folder and get tools.

建于 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规范文件放入您的规范文件夹：

# Example: Download the Petstore spec
curl -o ~/mcp-apis/petstore.json https://petstore3.swagger.io/api/v3/openapi.json

4.️⃣ 配置身份验证（可选）

创建一个 .env specs文件夹中的文件：

# ~/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使用情况

🚀 启动服务器

# Default: stdio transport, current directory
specbridge

# Custom specs folder
specbridge --specs ~/my-api-specs

# HTTP transport mode
specbridge --transport httpStream --port 8080

📋 列出加载的规格和工具

# List all loaded specifications and their tools
specbridge list

# List specs from custom folder
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

🏷️ 工具命名

工具将使用此模式自动命名：

带操作ID: {api_name}_{operationId}
无操作ID: {api_name}_{method}_{path_segments}

示例：

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

📁 文件结构

your-project/
├── api-specs/           # Your OpenAPI specs folder
│   ├── .env            # Authentication credentials
│   ├── petstore.json   # OpenAPI spec files
│   ├── github.yaml     # 
│   └── custom-api.yml  # 
└── mcp-config.json     # MCP client configuration

📄 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

🔧 故障排除

❌ 没有工具出现？

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

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

🔐 身份验证不起作用？

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

🔄 规格更改后工具不更新？

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

🛠️ 发展

# Clone and install
git clone https://github.com/TBosak/specbridge.git
cd specbridge
npm install

# Build
npm run build

# Test locally
npm run dev -- --specs ./examples

🤝 贡献

欢迎投稿！请随时提交问题和拉取请求。