JustOneAPI MCP Server
使用说明（Markdown 格式）
-
项目简介
- 该仓库实现一个 MCP 服务器，用于将 JustOneAPI 的端点通过 MCP 协议暴露给 MCP 客户端（如 Claude/Cursor 等），以标准化的方式提供工具调用和数据访问，并返回 upstream 的原始 JSON 数据，保证数据保真。
-
主要功能点
- 将 JustOneAPI 的端点暴露为 MCP 工具（例如 unified_search_v1 和 kuaishou_search_video_v2）。
- 处理认证、重试、超时、错误归一化等网络行为，确保稳定性。
- 返回 upstream 的原始 JSON，未进行字段解析或重构，保持数据原样。
- 通过标准 MCP 传输层（此实现使用 StdioServerTransport，支持通过命令行、管道等方式对接 MCP 主机）。
- 提供统一的错误处理与可观测性（调试日志可通过 JUSTONEAPI_DEBUG 打开）。
-
安装步骤
- 确保环境中已安装 Node.js（支持 TypeScript 构建与运行）。
- clone 该仓库并安装依赖：
- npm install
- 构建项目（若需要生成可执行输出）：
- npm run build
- 在运行前，务必设置环境变量 JUSTONEAPI_TOKEN（你的 JustOneAPI 访问令牌）。
- 直接使用 npm 运行（开发模式）：
- npx justoneapi-mcp
- 全局安装后运行（若全局安装）：
- npm install -g justoneapi-mcp
- justoneapi-mcp
- 运行时日志默认输出到标准错误，方便与 MCP HOST 集成时不冲突。
-
服务器配置（MCP 客户端所需信息，示例为可直接配置的 JSON 配置片段，不需要代码）
- 服务器名称：justoneapi
- 启动命令及参数示例（支持 Claude Desktop、Cursor 等 MCP 主机的通用配置方式）： { "name": "justoneapi", "command": "npx", "args": ["-y", "justoneapi-mcp"], "env": { "JUSTONEAPI_TOKEN": "your_actual_token_here" // 其他可选参数示例（如超时、调试等），仅在需要时配置 // "JUSTONEAPI_TIMEOUT_MS": "30000", // "JUSTONEAPI_DEBUG": "true" } }
- 说明
- 该配置仅用于 MCP 客户端在本地或服务器上启动并连接到 MCP 服务。MCP 客户端需要的是服务器的启动命令及参数，确保环境变量 JUSTONEAPI_TOKEN 设置正确即可正常工作。
- 服务器默认通过标准输入/输出（stdio）进行 MCP 通信，若你的环境需要其它传输方式（如 SSE、WebSocket），请按 MCP 主机的支持选项进行配置对接。
-
基本使用方法
- 启动后，MCP 主机（如 Claude Desktop）将自动发现并连接工具：
- 你可以请求列出可用工具，通常会看到 unified_search_v1、kuaishou_search_video_v2 等。
- 使用示例（对话式交互）
- 调用 unified_search_v1：跨平台进行关键词搜索，返回 upstream 的原始 JSON。
- 调用 kuaishou_search_video_v2：按关键词检索 Kuaishou 视频，返回 upstream 的原始 JSON。
- 错误处理
- 服务会将错误统一映射为 MCP 错误码，并提供可读的错误信息，便于定位 token、配额、网络等问题。
- 日志与调试
- 如需调试输出，在环境变量中设置 JUSTONEAPI_DEBUG=true，服务器会将调试日志输出到标准错误。
- 启动后，MCP 主机（如 Claude Desktop）将自动发现并连接工具：