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

🤝 貢獻

歡迎貢獻代碼！請隨時提交問題和拉取請求。