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.mdLicense
见 LICENSE。
