Recharge Storefront API MCP

充值店面API MCP服务器

全面的模型上下文协议（MCP）服务器，提供对Recharge Storefront API端点的完全访问。该服务器使AI助手和其他MCP客户端能够通过标准化的界面与充值订阅管理功能进行交互。

目录

• 概述
• 特性
• 安装
• 认证
• 配置
• 用法
• 可用工具
• 使用示例
• Unicode和国际支持
• 发展
• 测试
• 故障排除
• 安全
• 演出
• 贡献
• 许可证

概述

Recharge Storefront API MCP服务器弥补了人工智能助手与Recharge订阅管理平台之间的差距。它通过标准化的模型上下文协议为所有Recharge Storefront API端点提供了一个完整的、可生产的接口。

什么是充值？

Recharge是一个领先的订阅商务平台，为Shopify商店的定期计费提供支持。它为数千家商家处理订阅管理、计费周期、客户门户和定期订单处理。

什么是MCP？

模型上下文协议（MCP）是人工智能助手与外部服务和API交互的标准化方式。该服务器实现了MCP，使AI系统可以访问Recharge的功能。

主要优势

• API全面覆盖：所有88个Recharge Storefront API端点
• 智能身份验证：具有多客户支持的自动会话管理
• 生产就绪：错误处理、日志记录和监控
• 开发者友好：全面的文档、示例和调试工具
• 安全：内置安全保护和客户数据隔离
• 国际支持：为全球客户提供全面的Unicode支持

特性

完整的店面API覆盖范围

高级功能

• 自动会话管理：智能会话创建和缓存
• 多客户支持：在单个MCP连接中处理多个客户
• 灵活的身份验证：环境变量、每个工具的参数或显式标记
• 全面的错误处理：详细的错误消息和可操作的指导
• 调试模式：广泛的日志记录用于开发和故障排除
• 输入验证：所有工具参数的Zod模式验证
• 安全保护：防止意外的客户数据泄露
• Unicode支持：姓名和地址完全支持国际字符
• 业务规则验证：防止无效的订阅配置

会话缓存管理

• 自动会话缓存：缓存客户会话令牌以提高性能
• 环境切换支持：在dev/test/production之间切换时清除缓存的工具
• 自动清理：自动清除旧会话（4小时以上）以防止过期令牌
• 缓存统计：监视缓存会话和性能
• 手动吹扫：按需清除特定或所有缓存会话

安装

先决条件

• Node.js：18.0.0或更高版本
• Shopify商店：必须有安装了充值功能的Shopify商店
• 充值账户：活跃充值商户账户
• API访问：为会话创建重新充值管理员API令牌

快速开始

# Clone or download the project
# cd recharge-storefront-api-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Start the server
npm start

自动设置

# Make setup script executable (Linux/macOS)
chmod +x scripts/setup.sh

# Run the setup script
npm run setup

安装脚本将：

• 验证Node.js版本
• 安装依赖项
• 创建环境文件
• 验证配置
• 显示项目统计信息

验证

# Validate installation
npm run validate

# Check API coverage
npm run coverage

# Run comprehensive tests
npm run test

认证

了解充值身份验证

充值使用两步身份验证过程：

1. 管理员API令牌：使用Recharge对您的应用程序进行身份验证
2. 客户会话令牌：将操作范围限定在特定客户

Admin API Token + Customer ID → Customer Session Token → API Operations

获取您的API代币

1. 登录充值：访问您的商家门户
2. 导航到API令牌：转到应用程序和集成>API令牌
3. 创建管理员令牌：创建新 管理员API 令牌（不是Storefront API令牌）
4. 设置权限: 重要：默认情况下，充值令牌没有权限。您必须明确勾选所有必需的权限框（见下文）
5. 复制令牌：保存令牌（以您的商店前缀开头）

关键的：您必须使用 管理员API 代币。Storefront API令牌将不适用于会话创建。管理员令牌通常以您的商店前缀开头（例如。， mystore_)或 sk_.

所需令牌权限

您的管理员API令牌必须具有 读写权限 为了实现完整的功能。 默认情况下，充值不会授予这些权限 -创建令牌时必须明确选择每个权限：

所需权限：

• ✅ read_客户 -查看客户信息
• ✅ write_客户 -更新客户资料，创建会话
• ✅ read_订阅 -查看订阅详细信息
• ✅ write_订阅 -跳过、更新、取消、激活订阅
• ✅ read_orders -查看订单历史记录
• ✅ 写订单 -修改订单和费用
• ✅ read_产品 -浏览产品目录
• ✅ 读取地址 -查看客户地址
• ✅ 写地址 -创建、更新、删除地址
• ✅ 预付款方法 -查看付款信息
• ✅ write_payment_methods -更新账单信息
• ✅ read_discours -查看已申请的折扣
• ✅ write_discours -应用和删除折扣码

⚠️ 常见错误：许多用户最初只选择读取权限，认为不需要写入权限。然而，像“跳过订阅”或“更新客户”这样的操作需要写权限，即使它们看起来很简单。

常见权限问题：

问题：403个写操作错误（跳过、更新、取消订阅） 原因：令牌具有读取权限，但缺少写入权限 解决方案：更新令牌权限或创建具有完全写入权限的新令牌

问题：读取操作有效，但写入操作失败 原因：使用“只读”或有限权限创建的令牌 解决方案：确保令牌具有上面列出的所有权限

如何检查令牌权限：

1. 转到充值管理员→ 应用程序和集成→ API令牌
2. 查找您的管理员API令牌
3. 检查“权限”或“范围”部分
4. 确保启用了所有必需的权限
5. 如果缺少权限，请更新现有令牌或创建新令牌

身份验证方法

服务器支持三种灵活的身份验证方法：

方法1：客户电子邮件（推荐）

最简单的方法是提供客户的电子邮件地址：

{
  "name": "get_subscriptions",
  "arguments": {
    "customer_email": "customer@example.com"
  }
}

自动发生的事情：

1. 电子邮件查询→ 客户ID
2. 客户ID→ 会话令牌
3. 会话令牌→ 客户数据
4. 缓存会话以备将来调用

方法2：客户ID

如果您已经拥有客户ID：

{
  "name": "get_subscriptions",
  "arguments": {
    "customer_id": "123456"
  }
}

方法3：显式会话令牌

对于具有现有会话令牌的高级用例：

{
  "name": "get_subscriptions",
  "arguments": {
    "session_token": "existing_session_token"
  }
}

自动会话管理

服务器智能地管理客户会话：

会话创建流程

Customer Email/ID → Lookup → Session Creation → API Call → Cached Session Token

会话保持

客户会话令牌缓存在您的MCP连接中，并自动续订：

// First call - creates and caches session
{
  "name": "get_customer",
  "arguments": {"customer_email": "alice@example.com"}
}

// Subsequent calls - reuses cached session (fast!)
{
  "name": "get_subscriptions", 
  "arguments": {"customer_email": "alice@example.com"}
}

// Different customer - creates new cached session
{
  "name": "get_orders",
  "arguments": {"customer_email": "bob@example.com"}

自动会话续订

• 反应式续订：当API调用因过期而失败时，过期的会话令牌会自动续订
• 重试逻辑：由于令牌过期而导致的呼叫失败，将自动使用新会话重试

性能优势

• 快速：不重复创建会话
• 聪明的：电子邮件查找也已缓存
• 孤立的：每个客户都获得单独的会话令牌
• 自动：工作透明

多客户支持

无缝处理多个客户：

// Customer A operations
{"name": "get_customer", "arguments": {"customer_email": "alice@example.com"}}
{"name": "get_subscriptions", "arguments": {"customer_email": "alice@example.com"}}

// Customer B operations  
{"name": "get_customer", "arguments": {"customer_email": "bob@example.com"}}
{"name": "get_orders", "arguments": {"customer_email": "bob@example.com"}}

// Back to Customer A - reuses cached session
{"name": "get_addresses", "arguments": {"customer_email": "alice@example.com"}}

服务器包括内置的安全保护：

防止错误的客户数据

// Safe: Default session when no customer sessions exist
{"name": "get_subscriptions", "arguments": {}}  // Uses default session token

// Dangerous: Could expose wrong customer data
{"name": "get_customer", "arguments": {"customer_email": "alice@example.com"}}
{"name": "get_subscriptions", "arguments": {}}  // BLOCKED! Security error

// Safe: Always specify customer identification
{"name": "get_subscriptions", "arguments": {"customer_email": "alice@example.com"}}  // Safe

安全错误消息：

Security Error: Cannot use default session token when customer-specific sessions exist. 
Please specify 'customer_id', 'customer_email', or 'session_token' to ensure correct customer data access.

配置

MCP客户端配置

要将此服务器与MCP客户端一起使用，您需要配置客户端以连接到此服务器。以下是常见客户端的配置示例：

克劳德桌面版

编辑您的Claude Desktop配置文件：

位置:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "recharge-storefront-api": {
      "command": "node",
      "args": ["path/to/recharge-storefront-api-mcp/src/server.js"],
      "env": {
        "RECHARGE_STOREFRONT_DOMAIN": "your-shop.myshopify.com",
        "RECHARGE_ADMIN_TOKEN": "your_admin_token_here"
      }
    }
  }
}

如果您在使用Claude Desktop时遇到JSON-RPC或超时问题，尝试以下替代配置：

{
  "mcpServers": {
    "recharge-storefront-api": {
      "command": "node",
      "args": ["index.js"],
      "cwd": "path/to/recharge-storefront-api-mcp",
      "env": {
        "RECHARGE_STOREFRONT_DOMAIN": "your-shop.myshopify.com",
        "RECHARGE_ADMIN_TOKEN": "your_admin_token_here"
      }
    }
  }
}

光标IDE

1. 安装MCP扩展 （如果可用）或手动配置
2. 添加到光标设置 (Ctrl/Cmd + ,):

{
  "mcp.servers": {
    "recharge-storefront-api": {
      "command": "node",
      "args": ["src/server.js"],
      "cwd": "path/to/recharge-storefront-api-mcp",
      "env": {
        "RECHARGE_STOREFRONT_DOMAIN": "your-shop.myshopify.com",
        "RECHARGE_ADMIN_TOKEN": "your_admin_token_here"
      }
    }
  }
}

1. 如果您在Cursor中遇到MCP协议问题，您有两个选择：

选项A：创建包装脚本 在项目根目录中(run-server.js):

#!/usr/bin/env node
import('./src/server.js').catch(console.error);

然后使用此配置：

{
  "mcp.servers": {
    "recharge-storefront-api": {
      "command": "node",
      "args": ["run-server.js"],
      "cwd": "path/to/recharge-storefront-api-mcp",
      "env": {
        "RECHARGE_STOREFRONT_DOMAIN": "your-shop.myshopify.com",
        "RECHARGE_ADMIN_TOKEN": "your_admin_token_here"
      }
    }
  }
}

选项B：使用.env文件 使用更简单的配置（如果包装器脚本不起作用）：

{
  "mcp.servers": {
    "recharge-storefront-api": {
      "command": "node",
      "args": ["src/server.js"],
      "cwd": "path/to/recharge-storefront-api-mcp"
    }
  }
}

*注意：这取决于您的 .env 项目目录中包含所需环境变量的文件。*

GPT-5和OpenAI客户端

对于GPT-5和其他基于OpenAI的MCP客户端：

{
  "mcpServers": [
    {
      "name": "recharge-storefront-api",
      "command": "node",
      "args": ["index.js"],
      "cwd": "path/to/recharge-storefront-api-mcp",
      "env": {
        "RECHARGE_STOREFRONT_DOMAIN": "your-shop.myshopify.com",
        "RECHARGE_ADMIN_TOKEN": "your_admin_token_here"
      }
    }
  ]
}

如果遇到协议问题，尝试使用主入口点：

{
  "mcpServers": [
    {
      "name": "recharge-storefront-api",
      "command": "node",
      "args": ["src/server.js"],
      "cwd": "path/to/recharge-storefront-api-mcp"
    }
  ]
}

VSCode与GitHub Copilot

1. 安装MCP扩展 用于VSCode（如果可用）
2. 添加到VSCode设置.json (Ctrl/Cmd + Shift + P → “首选项：打开设置（JSON）”）：

{
  "mcp.servers": [
    {
      "name": "recharge-storefront-api",
      "command": "node",
      "args": ["src/server.js"],
      "cwd": "path/to/recharge-storefront-api-mcp",
      "env": {
        "RECHARGE_STOREFRONT_DOMAIN": "your-shop.myshopify.com",
        "RECHARGE_ADMIN_TOKEN": "your_admin_token_here"
      }
    }
  ]
}

1. 备选方案：工作区配置 (.vscode/settings.json 在您的项目中）：

{
  "mcp.servers": [
    {
      "name": "recharge-storefront-api",
      "command": "node",
      "args": ["../recharge-storefront-api-mcp/src/server.js"],
      "cwd": "../recharge-storefront-api-mcp"
    }
  ]
}

克劳德代码（Anthropic的集成开发环境）

1. 打开克劳德代码设置
2. 导航到MCP服务器部分
3. 添加新的服务器配置:

{
  "name": "Recharge Storefront API",
  "command": "node",
  "args": ["src/server.js"],
  "cwd": "path/to/recharge-storefront-api-mcp",
  "env": {
    "RECHARGE_STOREFRONT_DOMAIN": "your-shop.myshopify.com",
    "RECHARGE_ADMIN_TOKEN": "your_admin_token_here"
  }
}

通用MCP客户端配置

对于任何兼容MCP的客户端：

• 命令: node src/server.js
• 工作目录：此项目的路径
• 环境变量：在客户端配置或.env文件中设置
• 协议：stdio（标准输入/输出）

解决MCP客户端问题

常见问题：不同MCP客户端（Claude Desktop、Cursor、GPT-5等）之间的JSON-RPC或超时错误

根本原因：不同的MCP客户端实现的协议略有不同，导致与JSON-RPC传输层的兼容性问题。

解决方案 （按顺序尝试）：

1. 使用主入口点 (index.js 而不是 src/server.js):

   "args": ["index.js"]

1. 创建包装脚本 (run-server.js):

   #!/usr/bin/env node
   import('./src/server.js').catch(console.error);

然后使用： "args": ["run-server.js"]

1. 使用直接stdio执行:

   # Test the server directly
   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node src/server.js

1. 启用调试模式 查看详细的协议通信：

   "env": {
     "DEBUG": "true",
     "RECHARGE_STOREFRONT_DOMAIN": "your-shop.myshopify.com",
     "RECHARGE_ADMIN_TOKEN": "your_admin_token_here"
   }

1. 验证服务器启动 独立地：

   cd path/to/recharge-storefront-api-mcp
   npm start
   # Should show: [INFO] Server ready - listening for MCP requests

为什么会这样MCP规范仍在发展中，不同的AI平台在JSON-RPC处理、超时机制和传输层上略有不同。

最佳实践：从最简单的配置开始(node src/server.js)并且仅在需要时才增加复杂性。

常规配置提示

1. 使用绝对路径 跨不同环境的可靠性
2. 环境变量 可以在客户端配置或.env文件中设置
3. 测试连接 使用客户端的MCP测试功能进行设置后
4. 启用调试模式 通过添加 "DEBUG": "true" 用于故障排除的env变量

环境变量

创建 .env 项目根目录中的文件：

# Required: Your Shopify domain
RECHARGE_STOREFRONT_DOMAIN=your-shop.myshopify.com

# Required: Admin API token for session creation
RECHARGE_ADMIN_TOKEN=your_admin_api_token_here

# Optional: Recharge API URL (defaults to production)
RECHARGE_API_URL=https://api.rechargeapps.com

# Optional: Default customer session token (if you have one)
RECHARGE_SESSION_TOKEN=

# Optional: Server configuration
MCP_SERVER_NAME=recharge-storefront-api-mcp
MCP_SERVER_VERSION=1.0.0

# Optional: Enable debug logging
DEBUG=true

配置选项

\*除非在每次工具调用中提供，否则需要

重要提示：API URL行为

• 默认：使用生产API(https://api.rechargeapps.com)何时 RECHARGE_API_URL 未设置
• 自定义网址：仅在明确指定且有效的情况下使用替代URL
• 无退路：如果自定义URL无效，服务器将无法启动（防止无意的生产更改）
• 安全：所有URL都必须使用HTTPS协议

根据工具配置

在单个工具调用中覆盖环境变量：

{
  "name": "get_subscriptions",
  "arguments": {
    "store_url": "different-shop.myshopify.com",
    "admin_token": "different_admin_api_token",
    "customer_email": "customer@example.com"
  }
}

配置验证

# Validate configuration
npm run validate

# Test environment setup
npm run test:api-keys

# Check project health
npm run health

用法

启动服务器

# Production mode
npm start

# Development mode with file watching
npm run dev

# Development with debug logging
npm run dev:debug

# Debug mode (production)
DEBUG=true npm start

可用工具

客户管理（10个工具）

订阅管理（14个工具）

地址管理（9个工具）

付款方式（3种工具）

产品目录（3个工具）

计划管理（2个工具）

订单历史记录（2个工具）

收费管理（8个工具）

一次性产品（5个工具）

捆绑包管理（7个工具）

身份验证（8个工具）

实用工具（4个工具）

收藏（3个工具）

学分（3个工具）

礼品（2个工具）

元字段（3个工具）

使用示例

1.基本客户操作

客户查找

// Find customer by email
{
  "name": "get_customer_by_email",
  "arguments": {
    "email": "customer@example.com"
  }
}

// Get customer details with automatic session creation
{
  "name": "get_customer",
  "arguments": {
    "customer_email": "customer@example.com"
  }
}

// Update customer information with Unicode support
{
  "name": "update_customer",
  "arguments": {
    "customer_email": "customer@example.com",
    "first_name": "José",
    "last_name": "García",
    "phone": "+34-123-456-789"
  }
}

2.客户服务工作流程

// 1. Look up customer
{
  "name": "get_customer",
  "arguments": {"customer_email": "customer@example.com"}
}

// 2. Check their subscriptions
{
  "name": "get_subscriptions",
  "arguments": {"customer_email": "customer@example.com"}
}

// 3. View recent orders
{
  "name": "get_orders",
  "arguments": {"customer_email": "customer@example.com"}
}

3.订阅管理工作流程

// 1. Get subscription details
{
  "name": "get_subscription",
  "arguments": {
    "customer_email": "customer@example.com",
    "subscription_id": "sub_123"
  }
}

// 2. Skip next delivery
{
  "name": "skip_subscription",
  "arguments": {
    "customer_email": "customer@example.com",
    "subscription_id": "sub_123",
    "date": "2024-02-15"
  }
}

// 3. Add one-time product to next delivery
{
  "name": "create_onetime",
  "arguments": {
    "customer_email": "customer@example.com",
    "variant_id": 789012,
    "quantity": 1,
    "next_charge_scheduled_at": "2024-02-15"
  }
}

4.先进的多客户操作

// Customer A operations
{"name": "get_subscriptions", "arguments": {"customer_email": "alice@example.com"}}

// Customer B operations  
{"name": "get_orders", "arguments": {"customer_email": "bob@example.com"}}

// Back to Customer A (reuses cached session)
{"name": "get_addresses", "arguments": {"customer_email": "alice@example.com"}}

5.会话缓存管理

// Clear all cached sessions (recommended when switching environments)
{
  "name": "purge_session_cache",
  "arguments": {
    "all": true,
    "reason": "switching from dev to production"
  }
}

// Clear only sessions older than 2 hours
{
  "name": "purge_session_cache",
  "arguments": {
    "all": false,
    "older_than_minutes": 120,
    "reason": "cleanup old sessions"
  }
}

// Check cache statistics
{
  "name": "get_session_cache_stats",
  "arguments": {}
}

5.错误处理和故障排除

// This will fail with helpful error message
{
  "name": "get_subscription", 
  "arguments": {
    "subscription_id": "invalid_id"
  }
}

// Error response:
{
  "content": [
    {
      "type": "text",
      "text": "API Error (404): Subscription not found\n\nTip: Verify the resource ID exists and you have access to it."
    }
  ],
  "isError": true
}

Unicode和国际支持

完全支持Unicode

该服务器为国际客户提供全面的Unicode支持：

客户名称

• Unicode标准化：NFC标准化，实现一致存储
• 国际人物：支持所有语言的字母、标记和数字
• 字符验证：在允许正确Unicode的同时防止控制字符
• 长度限制：名称最多255个字符

国际地址

• 地址字段：街道地址、城市、省份完全支持Unicode
• 邮政编码：针对美国、加拿大、英国格式的国家特定验证
• 电话号码：国际E.164格式支持
• 字符编码：正确处理国际字符和变音符号（运输提供商不支持表情符号和特殊符号）

验证功能

• NFC标准化：典型分解和组合
• 控制字符删除：删除有问题的字符
• 空白归一化：一致的间距处理
• 长度验证：每种字段类型的适当限制
• 运输兼容性：限制可能导致运输标签和支付处理器问题的字符

例子

// International customer update
{
  "name": "update_customer",
  "arguments": {
    "customer_email": "müller@example.de",
    "first_name": "François",
    "last_name": "Müller",
    "phone": "+49-30-12345678"
  }
}

// International address creation
{
  "name": "create_address",
  "arguments": {
    "customer_email": "tanaka@example.jp",
    "first_name": "Tanaka",
    "last_name": "Taro", 
    "address1": "1-2-3 Jinnan, Shibuya-ku",
    "city": "Tokyo",
    "province": "Tokyo",
    "zip": "150-0041",
    "country": "Japan",
    "phone": "+81-3-1234-5678"
  }
}

// Note: While Unicode letters are supported (José, Müller, etc.), 
// emojis and mathematical symbols are not supported by shipping providers

发展

开发设置

# Install dependencies
npm install

# Setup environment
npm run setup

# Start development server
npm run dev

开发命令

# Development with file watching
npm run dev

# Development with debug logging
npm run dev:debug

# Validate code and configuration
npm run validate

# Check API coverage
npm run coverage

# View project statistics
npm run health

代码质量

# Lint code
npm run lint

# Validate syntax
npm run validate

# Test API key logic
npm run test:api-keys

# Health check
npm run health

添加新工具

1. 创建工具文件: src/tools/new-feature-tools.js
2. 遵循模式：使用现有工具作为模板
3. 添加到索引：出口自 src/tools/index.js
4. 添加客户端方法：实施 src/recharge-client.js
5. 彻底测试：使用 npm run validate

调试

启用调试模式以进行详细日志记录：

DEBUG=true npm start

调试输出包括：

• API请求/响应详细信息
• 身份验证流跟踪
• 会话创建和缓存
• 错误堆栈跟踪
• 性能指标

测试

可用测试命令

# Run all tests
npm run test

# Run comprehensive test suite
npm run test:full

# Validate API key logic
npm run test:api-keys

# Check syntax and configuration
npm run validate

# View API coverage
npm run coverage

测试类别

1.语法和配置测试

• Node.js版本验证
• Package.json完整性
• 环境文件验证
• 源文件语法检查

2.API集成测试

• 身份验证流验证
• 会话管理测试
• 错误处理验证
• Unicode支持验证

3.业务逻辑测试

• 订阅频率验证
• 变量存在检查
• 地址格式验证
• 客户数据处理

4.安全测试

• 令牌处理验证
• 客户数据隔离
• 输入净化
• 错误消息安全

运行特定测试

# Test environment setup
npm run test:api-keys

# Validate all configurations
npm run validate

# Check project health
npm run health

# Test MCP protocol startup
npm run mcp:test

故障排除

常见问题

身份验证错误

问题: Customer not found

# Solution: Check customer ID and merchant token
# Ensure customer exists in Recharge system
# Verify merchant token has Storefront API permissions

问题: Invalid merchant token

# Solution: Verify token type and permissions
# Use Admin API token (not Storefront API)
# Check token hasn't expired or been revoked

问题: 403 Forbidden 写操作（跳过、更新、取消）

# Solution: Check token permissions
# Your Admin API token needs WRITE permissions, not just read
# Go to Recharge admin → API tokens → Check permissions
# Ensure token has: write_subscriptions, write_customers, write_orders
# Create new token with full permissions if needed

问题：读取操作有效，但写入操作失败，403

# This is a classic token permissions issue
# Your token has read permissions but missing write permissions
# Solution: Update token permissions to include ALL write scopes:
# - write_customers
# - write_subscriptions  
# - write_orders
# - write_addresses
# - write_payment_methods
# - write_discounts

配置问题

问题: No store URL available

# Solution: Set environment variable or provide in tool calls
export RECHARGE_STOREFRONT_DOMAIN=your-shop.myshopify.com

问题: Domain must end with .myshopify.com

# Solution: Use correct Shopify domain format
# Correct: shop.myshopify.com
# Incorrect: shop.com

问题: Invalid RECHARGE_API_URL specified

# Solution: Fix or remove the custom API URL
# The server will NOT fall back to production to prevent unintentional changes

# Option 1: Fix the URL format (must be HTTPS)
# IMPORTANT: Only specify this for non-production environments
# If invalid URL is specified, server will fail to start (no fallback to production)
# This prevents unintentional production changes when intending to use staging/test
# Production: https://api.rechargeapps.com (default - don't specify)
# Staging: https://api.stage.rechargeapps.com
# Sandbox: https://api.sandbox.rechargeapps.com
#RECHARGE_API_URL=https://api.stage.rechargeapps.com

# Option 2: Remove the setting to use production
# Comment out or delete the RECHARGE_API_URL line in .env

# Option 3: Use a valid staging/test URL
# Staging: https://api.stage.rechargeapps.com
# Sandbox: https://api.sandbox.rechargeapps.com

Unicode和字符问题

问题: Invalid characters in name/address

# Solution: Use proper Unicode characters
# Allowed: Letters, numbers, spaces, punctuation
# Avoid: Control characters, special symbols
# Use international formats for phone numbers

问题: Postal code format invalid

# Solution: Use country-specific formats
# US: 12345 or 12345-6789
# Canada: A1A 1A1 or A1A1A1
# UK: SW1A 1AA or M1 1AA

订阅问题

问题: Invalid subscription frequency

# Solution: Use valid frequency ranges
# Daily: 1-90 days
# Weekly: 1-52 weeks  
# Monthly: 1-12 months
# Maximum total: 365 days

问题: Variant not found or not subscription-enabled

# Solution: Validate variant exists and is configured
# Use get_products to find valid variants
# Ensure product is enabled for subscriptions
# Check storefront_purchase_options setting

重定向问题

问题: Too many redirects 或 API returned redirect

# Common causes and solutions:

# 1. Incorrect store URL format
# Use: your-shop.myshopify.com
# Not: your-shop.com or https://your-shop.myshopify.com

# 2. Invalid authentication tokens
# Verify your tokens are correct and have proper permissions

# 3. API endpoint issues
# Enable debug mode to see redirect details:
DEBUG=true npm start

# 4. Check if store has Recharge installed
# Verify Recharge is properly installed on the Shopify store

# 5. Token type mismatch  
# Ensure you're using Admin API tokens, not Storefront API tokens
# Storefront API tokens may cause OAuth redirects

# 6. Domain validation issues
# Ensure domain follows exact format: shop-name.myshopify.com
# No trailing slashes, no protocol prefix, lowercase

会话问题

问题: Cross-environment token contamination

# Solution: Purge session cache when switching environments
# Use the purge_session_cache tool to clear cached tokens
# This prevents dev tokens from being used in production

问题: Too many cached sessions affecting performance

# Solution: Clean up old sessions periodically
# Use purge_session_cache with older_than_minutes parameter
# Or check get_session_cache_stats to monitor cache size

问题: Customer session token expired

# Solution: Customer session tokens are automatically recreated
# Provide customer_id or customer_email in next call

问题: Security Error: Cannot use default customer session token

# Solution: Always specify customer identification
# Add customer_email or customer_id to tool calls

问题: Session creation returned invalid token

# Solution: Check admin token permissions and format
# Ensure admin token has customer session creation permissions
# Verify token is not expired or revoked

调试模式

启用全面调试：

DEBUG=true npm start

调试信息包括：

• 身份验证流程详细信息
• API请求/响应日志记录
• 客户会话令牌创建和缓存
• 错误堆栈跟踪
• 性能指标
• Unicode规范化详细信息

获取帮助

1. 检查文件：查看此自述文件
2. 启用调试模式：使用 DEBUG=true 用于详细记录
3. 验证安装程序：运行 npm run validate
4. 测试API密钥：运行 npm run test:api-keys
5. 检查覆盖范围：运行 npm run coverage
6. 运行完整测试：运行 npm run test:full

安全

安全最佳实践

API代币安全

• 从不提交代币 到版本控制
• 使用环境变量 敏感数据
• 定期旋转令牌 （推荐：每90天一次）
• 使用所需的最小权限

客户数据保护

• 始终指定客户身份 在工具调用中
• 验证客户访问权限 手术前
• 使用会话令牌 用于客户范围的操作
• 监控异常访问模式

网络安全

• 使用HTTPS 用于所有API通信（由axios自动处理）
• 实施适当的防火墙规则
• 监控API使用情况 异常
• 请注意API充值费率限制

Unicode安全

• 规范Unicode输入 防止编码攻击
• 验证字符集 防止注射
• 消毒控制特征 根据用户输入
• 使用正确的编码 国际数据

安全特性

内置保护

• 客户数据隔离：每个客户都获得单独的会话令牌
• 错误客户预防：阻止不明确的工具调用
• 输入验证：对所有输入进行Zod模式验证
• 错误清理：从日志和错误消息中删除敏感数据
• 会话令牌缓存：安全的内存会话管理
• 自动会话续订：透明地重新创建过期会话
• 参数清理：已从API请求中删除敏感参数
• 会话缓存隔离：环境专题会议管理
• 万国码规范化：防止基于编码的攻击
• API URL验证：自定义URL必须使用HTTPS，不能回退到生产环境
• 快速配置失败：启动时捕获到无效设置

报告安全问题

对于安全问题，请遵循负责任的披露做法，并直接联系项目维护人员。

演出

性能特点

会话管理

• 智能高速缓存：缓存客户会话以避免重复的API调用
• 自动续订：已过期的会话以透明方式续订
• 环境隔离：切换环境时可以清除会话缓存
• 多客户支持：高效处理多个客户会话

请求优化

• 连接池：具有优化连接处理的Axios实例
• 请求超时：30秒超时可防止挂起请求
• 错误恢复：自动重试过期的会话令牌

内存管理

• 高效缓存：具有自动清理功能的内存会话缓存
• Unicode标准化：优化了Unicode处理
• 垃圾回收：适当清理过期会话

监控

• 调试日志：启用时提供全面的性能指标
• 请求跟踪：监视API调用模式和响应时间
• 错误跟踪：跟踪错误率和类型

性能提示

1. 重复使用客户会话：使用相同的客户电子邮件/ID进行相关操作
2. 启用缓存：让服务器自动缓存客户会话
3. 批量操作：同一客户的集团相关业务
4. 切换环境时进行清除：使用 purge_session_cache 在开发/测试/生产之间切换时
5. 监控调试输出：使用 DEBUG=true 识别性能瓶颈

贡献

欢迎投稿！贡献时：

• 遵循现有模式：使用既定的代码结构和命名约定
• 添加适当的验证：对所有新工具参数使用Zod模式
• 彻底测试：运行 npm run test:full 提交更改之前
• 更新文档：保持README与任何更改保持同步
• 正确处理错误：使用现有的错误处理模式
• 支持Unicode：确保新功能中的国际字符支持
• 添加业务验证：包括适当的业务规则验证

开发指南

1. 代码质量：遵循现有模式并使用正确的Types/JSDoc
2. 测试：添加新功能的测试
3. 文档：更新README和内联文档
4. 安全：遵循安全最佳实践
5. 演出：考虑变更对绩效的影响
6. Unicode支持：确保妥善处理国际字符

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

支持

资源

• 文档：此自述文件和全面的内联代码文档
• 例子：本自述文件中的完整使用示例
• 调试模式：用于故障排除的详细日志记录
• 测试套件：全面的测试工具

获取帮助

• 调试模式：启用 DEBUG=true 用于故障排除
• 验证：运行 npm run validate 检查设置
• 覆盖：运行 npm run coverage 查看API覆盖范围
• 完整测试：运行 npm run test:full 用于全面测试

项目统计

• 59工具：完成补给店面API覆盖范围
• 11分类：全面的订阅管理
• 生产就绪：错误处理、日志记录和监控
• 安全：内置会话令牌隔离的客户数据保护
• 国际的：为全球客户提供全面的Unicode支持
• 证据充分的：综合指南和示例
• 经过彻底测试：具有多个验证层的综合测试套件

______________________________________________________________________

*为Recharge和MCP社区精心打造*

最后更新时间： 2026年1月26日