Recharge Storefront API MCP Server

使用说明内容（Markdown格式）

• 项目简介

  • 该仓库实现了一个基于 MCP（Model Context Protocol）的服务器端组件，提供对 Recharge Storefront API 的完整后端访问能力。它暴露工具集、支持资源访问和工具调用，方便将 Recharge 功能纳入对话式或基于大模型的应用中。

• 主要功能点

  • MCP 服务端核心：实现对 MCP 的 JSON-RPC 请求（如列出工具、调用工具）的响应，具备请求处理、错误处理、日志与健康监控等能力。
  • 完整工具集合：包含客户管理、订阅、地址、支付、产品、计划、订单、费用、折扣、集合、信用、礼品、元字段、认证、实用工具等多类别工具，覆盖 Recharge Storefront API 的大量端点。
  • 会话与多客户支持：内置会话缓存、按客户 ID/邮箱/会话令牌管理，支持多客户在同一 MCP 连接下并发操作。
  • 安全与健壮性：参数校验、输入/输出清洗、错误格式化、调试日志、兜底的错误处理与严格的依赖版本检查。
  • Unicode 与国际化：对姓名、地址等字段提供宽字符支持和校验，确保国际化场景下的数据稳定性。
  • 配置与调试：支持通过 .env 进行配置、提供 debug 模式，便于排错和性能调优。
  • 传输与兼容性：以标准的 stdio 传输进行 MCP 通信，兼容多种客户端实现。

• 安装步骤

  1. 安装 Node.js 18.0+ 环境。
  2. 克隆并进入项目目录。
  3. 安装依赖：npm install
  4. 拷贝并配置环境变量：cp .env.example .env，按需设置 RECHARGE_STOREFRONT_DOMAIN、RECHARGE_ADMIN_TOKEN、RECHARGE_SESSION_TOKEN、RECHARGE_API_URL 等。
  5. 启动服务器：npm start
  6. 如需本地验证，执行 npm run validate、npm run coverage、npm run test 等命令进行自检和测试。

• 服务器配置（MCP 客户端需要的最小信息） 说明：MCP 客户端需要配置服务器的启动命令及参数以建立连接。以下信息基于仓库提供的实现与 README 的常用用法推断，实际配置请使用客户端支持的路径与格式。

  • server name: Recharge Storefront API MCP Server
  • command: node
  • args: ["index.js"]（或 ["src/server.js"]，如客户端有特殊要求，可按实际路径指定）
  • 注释：该配置将通过 MCP 客户端启动该 Node.js 服务，使其以标准的 JSON-RPC 形式对外暴露工具和资源访问能力。启动时应确保环境变量 RECHARGE_STOREFRONT_DOMAIN、RECHARGE_ADMIN_TOKEN、RECHARGE_API_URL 等已正确设置，以便服务器能够连接 Recharge 的后端服务。

• 基本使用方法

  • 客户端连接后，首先通过 ListTools 获取服务器支持的工具列表与描述。
  • 选择具体工具（如 get_subscriptions、create_subscription 等），按工具输入模式（输入模式定义在各工具的 inputSchema）提供参数，发起 Tool 调用请求。
  • 如工具需要认证信息，系统会综合环境变量与调用时传入的参数优先级进行校验与 token 的获取/生成。
  • 服务器支持多客户场景，使用 customer_id/customer_email/session_token 等进行身份标识，以确保数据隔离与安全访问。
  • 在调试模式下（DEBUG=true），会打印详细日志，便于排错和优化。