# Just One API · MCP Server

把 [Just One API](https://justoneapi.com) 的 **237+ 个数据接口**（抖音 / 小红书 / 淘宝 / 亚马逊 / TikTok 等 30+ 平台）收敛为**固定几个元工具**的 [MCP](https://modelcontextprotocol.io) 服务。

核心特性：

- **工具数量不随接口增长而爆炸**——无论后端多少接口，对外只暴露固定的 4 个核心工具 + 2 个维护工具。
- **自然语言智能选接口**——基于阿里云百炼 `text-embedding-v4`（2048 维）的跨语言语义检索，中文随口提问即可命中英文接口描述。
- **SDK / 后端更新时，MCP 代码零改动**——接口知识全部来自数据产物（`catalog.json` + `embeddings.json`），增删改接口只需重建数据，并支持热加载（无需重启）。

设计细节见 [`docs/mcp-server-design.md`](docs/mcp-server-design.md)。

---

## 工作原理

后端 OpenAPI 是唯一真源，派生出 MCP 的接口目录与向量索引：

```
后端 OpenAPI → normalized.json → catalog.json + embeddings.json（向量）
                                      ↓
LLM 按「搜索 → 取参数 → 调用」编排，动态使用全部 237+ 接口：
   search_endpoints → get_endpoint_schema → call_endpoint
```

### 暴露的工具

| 工具 | 作用 |
|------|------|
| `search_endpoints` | 用自然语言发现接口（语义检索，返回候选 endpoint_id） |
| `get_endpoint_schema` | 查看某接口的完整参数契约 |
| `call_endpoint` | 传参执行接口，返回数据（大结果截断 + 翻页提示） |
| `list_platforms` | 列出所有平台及接口数量 |
| `check_updates` | [维护·只读] 对比上游，列出将新增/移除/变更的接口 |
| `rebuild_catalog` | [维护·管理员] 同步上游并重建目录与向量索引 |

---

## 安装

需要 Python ≥ 3.10。

```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt          # 运行时依赖：mcp / httpx / pydantic
```

## 配置

### 服务器侧（环境变量）

| 变量 | 必需 | 说明 |
|------|------|------|
| `MCP_TRANSPORT` | 是 | 固定为 `http` |
| `MCP_HOST` / `MCP_PORT` | 否 | 监听地址，默认 `0.0.0.0:8000` |
| `MCP_ADMIN_TOKEN` | 否 | 仅当你要通过 MCP 工具远程调用 `rebuild_catalog` 时才需要；日常取数不必配置 |

### 客户端（Cursor `mcp.json` 的 headers）

| Header | 必需 | 说明 |
|--------|------|------|
| `Authorization` | 是 | `Bearer <你的 justone token>`，调用业务接口时扣你的 justone 余额 |
| `X-DashScope-Key` | 是 | 你的百炼 key，`search_endpoints` 语义检索时使用 |
| `X-Admin-Token` | **否** | **仅**在你要通过 MCP 调用 `rebuild_catalog` 重建目录时才需要，且须与服务器 `MCP_ADMIN_TOKEN` 一致；日常搜索/取数完全不需要 |

## 生成数据产物

首次运行前需生成 `catalog.json` + `embeddings.json`（调用百炼编码，增量）：

```bash
python -m tools.mcp_catalog            # 生成目录 + 向量
python -m tools.mcp_catalog --no-embed # 只生成目录，跳过向量编码
```

---

## 运行

### 服务器

```bash
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8000 python -m justoneapi.mcp.server
```

如需通过 MCP 工具远程调用 `rebuild_catalog`，服务器额外设置 `MCP_ADMIN_TOKEN=<随机强串>`。

### 客户端（Cursor `mcp.json`）

日常取数只需两个 header：

```jsonc
{
  "mcpServers": {
    "justoneapi": {
      "url": "http://<服务器IP或域名>:8000/mcp",
      "headers": {
        "Authorization": "Bearer <你的 justone token>",
        "X-DashScope-Key": "<你的百炼 key>"
      }
    }
  }
}
```

仅当需要通过 MCP 调用 `rebuild_catalog` 时，才额外加上 `"X-Admin-Token": "<与服务器 MCP_ADMIN_TOKEN 一致>"`。

> 生产环境建议在前面挂 HTTPS（Nginx/Caddy 反代 + TLS），避免请求头中的 token 明文传输。

---

## 接口更新

后端 OpenAPI 是唯一真源，justone 官方 CI 每日把归一化后的 `public-api.normalized.json` 提交到公开仓库。本项目直接同步该公开产物即可跟上后端，**无需任何凭证**：

```bash
python -m scripts.sync_mcp            # 拉上游 → 有变更才重建（含接口 diff）
python -m scripts.sync_mcp --dry-run  # 只看差异，不写不重建
python -m scripts.sync_mcp --force    # 即使无变更也重建
```

也可在客户端按需调用维护工具：先 `check_updates` 看差异，确认后再 `rebuild_catalog`（需配置 `MCP_ADMIN_TOKEN` 并在 headers 带 `X-Admin-Token`）。重建为原子替换、增量编码，运行中的 server 通过 mtime 自动热加载，**无需重启**。

---

## 项目结构

```
just-one/
├── justoneapi/
│   ├── _transport.py          # 稳定调用出口 Transport.get(path, params)
│   ├── _exceptions.py
│   ├── _response.py
│   ├── _version.py
│   ├── log.py
│   ├── mcp/
│   │   ├── server.py          # FastMCP 入口，注册 6 个工具
│   │   ├── search.py          # 语义检索
│   │   ├── executor.py        # 参数校验 + 多租户 token + 调用
│   │   ├── catalog.py         # 内存目录 + mtime 热加载
│   │   ├── embedding.py       # 百炼 text-embedding-v4 封装
│   │   └── config.py          # 环境变量与平台别名
│   └── mcp_data/              # 运行时产物（生成）
│       ├── catalog.json
│       ├── embeddings.json
│       └── embeddings.meta.json
├── openapi/
│   └── public-api.normalized.json   # 接口目录唯一数据来源（由上游同步）
├── scripts/
│   └── sync_mcp.py            # 同步上游 + 重建（无需凭证）
├── tools/
│   └── mcp_catalog.py         # 由 normalized.json 生成 catalog + 向量
├── docs/
│   └── mcp-server-design.md
├── requirements.txt
├── pyproject.toml
└── README.md
```

## License

见 [LICENSE](LICENSE)。