MCP HTTP API Gateway (Python 版)

将只有 裸 IP 地址（无域名、无需 Token / 或可选 Token 验证） 的 REST HTTP API 服务器，轻松包装并暴露为标准的 MCP Server (Model Context Protocol)。

支持在 Cursor、Antigravity IDE、Claude Desktop、Trae 等 AI 开发工具中作为 Tool 调用。

---

🌟 核心特性

• 🚀 零域名依赖：原生支持直接连接 http://123.45.67.89:8000 格式的纯 IP 与自定义端口服务器。
• 🔓 免 Token 鉴权：针对无 Auth 验证的私有/测试服务器开箱即用，同时也支持可选的 Bearer Token 参数。
• 🔄 动态 IP 在线切换：
  • 对话框修改：直接在 AI 聊天框里对 AI 说：“更新服务器 IP 为 192.168.1.108:8000”，AI 自动调用内置工具完成热更新！
  • 本地文件热重载：修改同级目录下的 target_ip.txt 文件，网关在下一次请求时自动无感加载最新 IP。
• ⚡ 双模式运行：
  • Stdio 模式（推荐）：运行在本地电脑，本地 IDE 进程直连，无需在公网开放任何 MCP 端口与 SSL 证书。
  • SSE 模式：作为独立 HTTP/SSE 服务运行在服务器上。

---

🏗️ 架构示意

+---------------------+           +--------------------------+           +-----------------------+
|    AI 客户端 / IDE   |  Stdio /  |   Python MCP Gateway     |  HTTP REST| 目标纯 IP REST 服务器  |
| (Cursor/Claude/etc) |   SSE     |  (mcp_gateway.py)        |  (无Token) | (http://123.45.67.89) |
|                     | --------> |                          | --------> |                       |
|  tool: "get_user"   | <-------- |  JSON-RPC ↔ REST 协议转换 | <-------- | GET /api/v1/users/100 |
+---------------------+           +--------------------------+           +-----------------------+

---

📦 1. 快速开始与环境安装

克隆项目与安装依赖

git clone https://github.com/doghelWang/mcp-http-api-gateway.git
cd mcp-http-api-gateway

# 安装 Python 依赖包
pip install -r requirements.txt

requirements.txt 内容：

fastmcp>=0.1.0
requests>=2.31.0
uvicorn>=0.30.0

---

⚙️ 2. IDE 接入配置指南 (mcp.json)

在您使用的 AI 编辑器（Cursor / Antigravity IDE / Claude Desktop / Trae）的 MCP 配置文件中加入以下节点：

推荐：模式 A（本地 Stdio 模式）

将目标服务器 IP 填入 TARGET_API_BASE 环境变量：

{
  "mcpServers": {
    "ip-api-gateway": {
      "command": "python3",
      "args": [
        "/绝对路径/到/mcp_http_api_gateway/mcp_gateway.py"
      ],
      "env": {
        "TARGET_API_BASE": "http://123.45.67.89:8000"
      }
    }
  }
}

💡 配置文件存放路径提示：

• Antigravity IDE: ~/Library/Application Support/Antigravity IDE/User/mcp.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• VS Code / Trae: ~/Library/Application Support/Code/User/mcp.json 或 mcp.json

---

🔄 3. 动态 IP 变更应对机制（无需重配 IDE）

当您的目标 API 服务器 IP 发生变化时，完全不需要重新修改 IDE 的配置文件！可以任选以下两种方式之一：

方式 1：直接在 AI 对话框中动态修改（最智能）

直接在聊天框中告诉 AI 助手：

“今天的目标服务器 IP 变为了 192.168.1.105:8000，请更新一下。”

AI 助手会自动调用网关内置的 set_target_ip 工具完成保存，后续所有的 API 调用将即刻发往新 IP。

方式 2：修改本地 target_ip.txt 文件

在 mcp_gateway.py 同级目录下新建或修改 target_ip.txt 文件，写入一行最新 IP 文本即可：

http://192.168.1.105:8000

---

🛠️ 4. 自定义扩展 API Tools

根据您已有 HTTP API 的实际接口，在 mcp_gateway.py 中使用 @mcp.tool() 装饰器即可快速增加新工具：

@mcp.tool()
def get_user_info(user_id: str) -> str:
    """通过用户 ID 查询目标 IP 服务器的用户详细信息"""
    return _call_remote_api(f"/api/v1/users/{user_id}", method="GET")

@mcp.tool()
def create_order(item_name: str, quantity: int) -> str:
    """在目标 IP 服务器上提交并创建新订单"""
    payload = {"item_name": item_name, "quantity": quantity}
    return _call_remote_api("/api/v1/orders", method="POST", data=payload)

---

📄 开源协议

MIT License.