Jitapi

🚀 JitAPI

面向大語言模型（LLMs）的即時API編排

JitAPI是一個MCP服務器，它使大語言模型（如Claude）能夠通過從OpenAPI規範中動態發現相關端點，與任何API進行交互。JitAPI無需將整個API規範加載到上下文中，而是使用語義搜索和依賴圖來僅查找每個任務所需的端點。

✨ 主要特性

• 語義搜索：使用自然語言查詢查找相關的API端點。
• 依賴圖：自動檢測端點依賴關係（例如，“POST /orders需要GET /products中的product_id”）。
• 大語言模型驅動的工作流規劃：使用GPT - 4o - mini從查詢中提取參數並規劃多步驟工作流。
• 通用執行：執行工作流，並在步驟之間自動傳遞參數。
• 多API支持：同時註冊和查詢多個API。
• MCP集成：通過模型上下文協議與Claude Code進行原生集成。

🚀 快速開始

📦 安裝指南

pip install jitapi

或者使用 uv：

uvx jitapi

⚠️ 重要提示

macOS用戶注意：如果使用pip時遇到“externally - managed - environment”錯誤，請使用虛擬環境：

python3 -m venv .venv
source .venv/bin/activate
pip install jitapi

或者使用uvx jitapi，它會自動處理此問題。

與Claude Desktop進行設置

1. 找到Claude Desktop配置文件：

2. 添加JitAPI MCP服務器配置：

{
  "mcpServers": {
    "jitapi": {
      "command": "uvx",
      "args": ["jitapi"],
      "env": {
        "OPENAI_API_KEY": "sk - proj - your - key - here"
      }
    }
  }
}

3. 重啟Claude Desktop。
4. 在MCP服務器列表（錘子圖標）中查找“jitapi”。

與Claude Code進行設置

選項A：項目級配置（推薦） 在項目目錄中創建一個.mcp.json文件：

{
  "mcpServers": {
    "jitapi": {
      "command": "uvx",
      "args": ["jitapi"],
      "env": {
        "OPENAI_API_KEY": "sk - proj - your - key - here"
      }
    }
  }
}

然後從該目錄啟動Claude Code。JitAPI將僅在該項目中可用。

選項B：全局配置 編輯~/.claude.json，使JitAPI在所有項目中可用：

{
  "mcpServers": {
    "jitapi": {
      "command": "uvx",
      "args": ["jitapi"],
      "env": {
        "OPENAI_API_KEY": "sk - proj - your - key - here"
      }
    }
  }
}

重啟Claude Code，並通過詢問“List available JitAPI tools”進行驗證。

替代方法：使用pip安裝的包 如果您是通過pip而不是uvx安裝的：

{
  "mcpServers": {
    "jitapi": {
      "command": "python",
      "args": ["-m", "jitapi"],
      "env": {
        "OPENAI_API_KEY": "sk - proj - your - key - here"
      }
    }
  }
}

替代方法：從源代碼（開發）

{
  "mcpServers": {
    "jitapi": {
      "command": "python",
      "args": ["-m", "jitapi"],
      "cwd": "/path/to/jitapi",
      "env": {
        "OPENAI_API_KEY": "sk - proj - your - key - here",
        "PYTHONPATH": "/path/to/jitapi/src"
      }
    }
  }
}

💻 使用示例

基礎用法

配置完成後，您可以使用自然語言與API進行交互：

用戶：“從https://petstore.swagger.io/v2/swagger.json註冊Petstore API”
Claude：[調用jitapi:register_api工具]
✓ 已註冊包含20個端點的Swagger Petstore

用戶：“查找一隻寵物並獲取其詳細信息”
Claude：[調用jitapi:get_workflow工具]
已規劃工作流：
1. GET /pet/findByStatus - 按狀態查找寵物
2. GET /pet/{petId} - 獲取寵物詳細信息
提取的參數：status="available"（來自上下文）

用戶：“執行該工作流”
Claude：[調用jitapi:set_api_auth，然後調用jitapi:execute_workflow]
步驟1：找到3只可用的寵物
步驟2：獲取寵物“Max”的詳細信息

🔧 技術細節

架構

┌─────────────────────────────────────────────────────────────────┐
│                    數據攝入管道                                 │
│                                                                 │
│  OpenAPI規範 → 解析器 → 圖構建器 → 嵌入器 → 存儲                │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    運行時管道                                   │
│                                                                 │
│  查詢 → 向量搜索 → 圖擴展 → 大語言模型重排序 →                  │
│  參數提取 → 工作流執行                                          │
└─────────────────────────────────────────────────────────────────┘

工作原理

1. 註冊API：解析OpenAPI規範，構建依賴圖，創建嵌入。
2. 查詢：用戶詢問“獲取東京的天氣”。
3. 搜索：查找語義相關的端點。
4. 擴展：添加所需的依賴項（地理編碼端點）。
5. 規劃：大語言模型提取“東京”作為城市參數，映射數據流。
6. 執行：運行工作流，將地理編碼的座標傳遞給天氣API。

📚 詳細文檔

MCP工具

配置

設置OpenAI API密鑰

JitAPI需要OpenAI API密鑰來進行嵌入和基於大語言模型的工作流規劃。您可以通過以下幾種方式設置：

選項1：在MCP配置中設置（推薦）

{
  "mcpServers": {
    "jitapi": {
      "command": "uvx",
      "args": ["jitapi"],
      "env": {
        "OPENAI_API_KEY": "sk - proj - your - key - here"
      }
    }
  }
}

選項2：環境變量

# 添加到~/.zshrc或~/.bashrc
export OPENAI_API_KEY="sk - proj - your - key - here"

選項3：.env文件 在以下位置之一創建一個.env文件（按順序檢查）：

1. 當前工作目錄
2. ~/.jitapi/.env
3. ~/.env

# ~/.jitapi/.env
OPENAI_API_KEY=sk - proj - your - key - here

環境變量

示例：天氣API工作流

用戶：“舊金山的天氣如何？”

JitAPI規劃工作流：
1. GET /geo/1.0/direct
   - 參數：q="舊金山"（來自用戶查詢）
   - 輸出映射：lat=$[0].lat, lon=$[0].lon

2. GET /data/2.5/weather
   - 參數：lat=step_1.lat, lon=step_1.lon
   - 返回：當前天氣數據

大語言模型從查詢中提取“舊金山”，並在步驟之間映射座標，無需硬編碼邏輯。

開發

# 克隆倉庫
git clone https://github.com/nk3750/jitapi.git
cd jitapi

# 安裝開發依賴
pip install -e ".[dev]"

# 運行測試
pytest

# 運行代碼檢查
ruff check src/

項目結構

jitapi/
├── src/jitapi/
│   ├── main.py          # 入口點
│   ├── ingestion/       # OpenAPI解析、圖構建、嵌入
│   ├── retrieval/       # 搜索、擴展、重排序
│   ├── execution/       # HTTP執行、工作流執行
│   ├── mcp/             # MCP服務器、工具、資源
│   └── stores/          # 數據持久化
├── tests/               # 單元測試
└── pyproject.toml

API參考

註冊API

# 通過MCP工具
{
  "tool": "register_api",
  "arguments": {
    "api_id": "weather",
    "spec_url": "https://example.com/openapi.yaml"
  }
}

獲取工作流

# 通過MCP工具
{
  "tool": "get_workflow",
  "arguments": {
    "query": "get the weather in Tokyo",
    "api_id": "weather"
  }
}

# 返回：
{
  "workflow_id": "abc123",
  "steps": [
    {
      "endpoint_id": "GET /geo/1.0/direct",
      "parameters": {
        "q": {"value": "Tokyo", "source": "user_query"}
      },
      "output_mapping": {
        "lat": "$[0].lat",
        "lon": "$[0].lon"
      }
    },
    ...
  ]
}

執行工作流

# 通過MCP工具
{
  "tool": "execute_workflow",
  "arguments": {
    "workflow_id": "abc123",
    "api_id": "weather"
  }
}

支持的認證方式

• API密鑰（請求頭）：X - API - Key，或自定義請求頭名稱。
• API密鑰（查詢參數）：?apikey=...，或自定義參數名稱。
• Bearer令牌：Authorization: Bearer ...

📄 許可證

本項目採用MIT許可證。

貢獻

歡迎貢獻代碼！請先閱讀貢獻指南。