# 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 服务运行在服务器上。

---

## 🏗️ 架构示意

```text
+---------------------+           +--------------------------+           +-----------------------+
|    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. 快速开始与环境安装

### 克隆项目与安装依赖
```bash
git clone https://github.com/doghelWang/mcp-http-api-gateway.git
cd mcp-http-api-gateway

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

`requirements.txt` 内容：
```text
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` 环境变量：

```json
{
  "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 文本即可：
```text
http://192.168.1.105:8000
```

---

## 🛠️ 4. 自定义扩展 API Tools

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

```python
@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.