Supadata MCP 服务器

使用说明（Markdown 格式）

• 项目简介

  • 本仓库实现了一个符合 MCP（Model Context Protocol）标准的服务器端，核心职责是向 LLM 客户端提供上下文信息和能力，包括工具注册/执行、资源管理以及提示模板的渲染等。实现中通过 Supadata API 提供具体的工具能力，如转录、网页抓取、地图发现和网站爬虫等。

• 主要功能点

  • 注册并暴露工具：supadata_transcript、supadata_check_transcript_status、supadata_scrape、supadata_map、supadata_crawl、supadata_check_crawl_status 等工具。
  • 工具执行：通过 MCP 的 CallTool 请求调用工具，返回结构化内容供 LLM 使用。
  • 支持多种传输：通过 STDIO（本地命令行/脚本集成）和 Web HTTP 实现与客户端的通信（Worker 版本）。
  • 与 Supadata API 的安全访问：通过 API Key 进行鉴权，支持 GET/POST 请求组合。

• 安装步骤

  • 安装运行环境（Node.js 18+，默认浏览器/Node 环境下的 fetch 支持）。
  • 安装依赖：在项目根目录执行 npm install。
  • 构建与运行（两种场景可选）：
    • 本地开发/测试（STDIO 直连）：先构建再用 STDIO 启动 MCP 服务。
    • 服务器/云环境（HTTP/Web 传输）：通过 worker 模式暴露 HTTP 服务并对外接入。
  • 环境变量配置：
    • 需要 SUPADATA_API_KEY（Supadata 的 API Key）或通过其他运行时注入的方式提供 API Key。

• 服务器配置（供 MCP 客户端参考的示例信息） 说明：MCP 客户端需要知道如何启动并连接到该 MCP 服务器。下面给出一个示意性的配置信息，该信息用于客户端在开发或文档中理解如何连接该 MCP 服务。实际使用中，请以你的部署方式为准。

  配置信息示例（用于 MCP 客户端配置，不在服务器端执行）： { "serverName": "supadata", "command": "node", "args": ["dist/index.js"] }

  注释：

  • serverName：在 MCP 客户端注册的服务名称，需与服务器实际暴露的名称保持一致（此处为 “supadata”）。
  • command：启动 MCP 服务器的命令。若服务器已打包为 dist/index.js，则通常使用 node。
  • args：启动命令的参数。此处演示 dist/index.js，表示通过打包后的入口启动服务器。具体部署环境请按实际输出路径与启动方式调整。客户端不需要直接执行此命令，只用于说明服务器启动信息。

• 基本使用方法

  • 在 MCP 客户端注册 MCP 服务器后，可以查询可用工具、调用工具并获取返回内容。
  • 典型工作流包括：
    • 请求工具列表以了解可用能力；
    • 调用 supadata_transcript 获取视频/文件转录（可选语言、是否返回文本等参数）；
    • 调用 supadata_scrape / supadata_map / supadata_crawl 获取网页内容、URL 列表或爬虫任务；
    • 使用 supadata_check_transcript_status、supadata_check_crawl_status 等状态查询工具的异步结果。
  • 结果通常以 JSON-RPC 的内容结构返回，LLM 可以将内容渲染为文本、markdown 或其他格式，供后续对话使用。

• 运行与测试

  • 运行环境就绪后，通过 MCP 客户端连接服务器，按文档中工具的定义进行调用。
  • 服务器端实现包含对 Supadata API 的封装调用、错误处理和重试逻辑（如需要可在后续扩展）。

• 备注

  • 本实现包含两个入口：一个使用 STDIO（本地直接交互），一个使用 Web 标准传输（HTTP/WebSocket 形式，适用于云端部署）。
  • API Key 的安全性请在实际部署时通过安全的方式管理（环境变量、密钥管理系统等）。