Controlapi Openapi To MCP

🚀 ControlAPI-MCP

ControlAPI-MCP 是一个 MCP 服务器，它能将任何 OpenAPI/REST API 转换为 MCP 工具，支持动态服务器切换和变量替换。

🚀 快速开始

📦 安装指南

一键安装

可直接在编辑器中点击安装，无需任何配置！

• Linux / macOS：
  • 📥 在 VS Code 中安装
  • 📥 在 VS Code Insiders 中安装

💡 安装后：AI 助手会引导你连接到 API 服务器。当被询问时，只需提供 OpenAPI URL，或使用 set_server_config 工具连接到你的 API。

自动下载快速启动

零安装，自动下载并运行最新版本：

1. 下载自动运行脚本：

curl -O https://raw.githubusercontent.com/fellowabhi/ControlAPI-openapi-to-mcp/main/auto-run.sh
chmod +x auto-run.sh

2. 在你的 MCP 配置中使用：

{
  "servers": {
    "controlapi-mcp": {
      "type": "stdio",
      "command": "/path/to/auto-run.sh"
    }
  }
}

注意：你可以选择在环境变量中设置 OPENAPI_URL、BASE_URL 和 SERVER_NICKNAME，或者使用 set_server_config 工具进行动态配置。

也可以从 releases 下载或自行构建：

export OPENAPI_URL='http://your-api.com/openapi.json'
export BASE_URL='http://your-api.com'  # 可选
./dist/controlapi-mcp

开发环境设置

pip install -e .

构建二进制文件

./build.sh

会在 dist/controlapi-mcp 生成一个独立的可执行文件（16MB）。

MCP 配置

使用二进制文件

{
  "servers": {
    "controlapi-mcp": {
      "type": "stdio",
      "command": "/path/to/openapi-mcp-adapter/dist/controlapi-mcp",
      "env": {
        "OPENAPI_URL": "http://localhost:8000/openapi.json",
        "BASE_URL": "http://localhost:8000",
        "DEBUG_PORT": "45133"
      }
    }
  }
}

使用 Python（开发环境）

{
  "servers": {
    "controlapi-mcp": {
      "type": "stdio",
      "command": "/path/to/project/.venv/bin/python",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/project",
      "env": {
        "OPENAPI_URL": "http://localhost:8000/openapi.json",
        "REFRESH_INTERVAL": "300",
        "PYTHONPATH": "/path/to/project",
        "BASE_URL": "http://localhost:8000",
        "DEBUG_PORT": "45133"
      }
    }
  }
}

可选参数：OPENAPI_URL、BASE_URL、SERVER_NICKNAME、DEBUG_PORT（默认值：45133）

💡 无需配置：你可以在不设置环境变量的情况下启动，然后使用 set_server_config 工具动态配置服务器。AI 助手会引导你完成设置。 🔍 调试界面：可在 http://localhost:45133（或自定义的 DEBUG_PORT）访问基于浏览器的请求/响应监视器。URL 可在 get_server_info 的响应中获取。

✨ 主要特性

跨平台支持

• Linux (x86_64) - 完全支持
• macOS (Intel & Apple Silicon) - 完全支持
• Windows - 使用 Python 或 WSL

动态服务器切换

• 在运行时连接到任何 OpenAPI 服务器
• 在多个 API（开发、测试、生产环境）之间切换
• 跟踪服务器上下文并记录历史
• 自动重新加载模式

可用工具

• set_server_config - 连接到 OpenAPI 服务器（如果未配置，先使用此工具）
• get_server_info - 检查当前服务器和连接状态
• get_server_history - 查看最近的服务器切换记录
• health_check - 测试服务器连接性
• list_endpoints - 列出所有 API 端点
• search_schema - 按关键字搜索端点
• execute_request - 进行 HTTP 请求并支持变量替换
• set_variable - 存储变量（如认证令牌）
• get_variables - 查看所有存储的变量
• reload_schema - 重新加载当前服务器的模式

💻 使用示例

变量替换

在请求头、请求体或路径中使用 {{variable_name}}：

{
  "headers": {
    "Authorization": "{{token}}"
  }
}

示例工作流

1. 首次使用：使用 set_server_config 并提供 openapi_url
2. 执行 execute_request 到 /auth/login 获取令牌
3. 使用 set_variable 存储令牌，如 key="token" value="Bearer xyz..."
4. 执行 execute_request 并在请求头中使用 Authorization: {{token}}
5. 切换服务器：使用 set_server_config 在不同环境中进行测试