Just One API · MCP Server

把 Just One API 的 237+ 个数据接口（抖音 / 小红书 / 淘宝 / 亚马逊 / TikTok 等 30+ 平台）收敛为固定几个元工具的 MCP 服务。

核心特性：

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

设计细节见 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。

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（调用百炼编码，增量）：

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

---

运行

服务器

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：

{
  "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 提交到公开仓库。本项目直接同步该公开产物即可跟上后端，无需任何凭证：

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。