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许可证。

贡献

欢迎贡献代码！请先阅读贡献指南。