2pay MCP Server

2Pay MCP服务器

用于2Checkout/Verifone2Pay.js支付API的模型上下文协议（MCP）服务器。该服务器使像Claude这样的人工智能助手能够通过自然语言与支付处理、订阅管理和订单操作进行交互。

目录

• 特性
• 先决条件
• 安装
• 配置
• 可用工具
• 资源和提示
• 使用示例
• 建筑
• 环境变量
• 安全
• 故障排除
• API 文档
• 贡献
• 许可证

特性

• 订单管理：使用2Pay.js令牌下订单，检索订单详细信息，搜索订单，处理退款
• 订阅管理：全生命周期管理，包括续订、升级、付款更新
• 客户管理：创建、更新和管理客户记录及其订阅
• 产品目录：查询和管理产品、定价配置和价格选项
• 促销：创建折扣、生成优惠券代码、管理促销活动

先决条件

• Node.js 18或更高版本
• 2结账/Verifone商户账户
• API凭证（商户代码和密钥）
• 生产：PCI DSS合规意识

安装

选项1:npm（推荐）

npm install -g @mcsacca/2pay-mcp-server

选项2：使用npx（无需安装）

您可以直接使用npx运行-请参阅 配置 在......下面

选项3：来源

git clone https://github.com/mcsacca/2pay-mcp-server.git
cd 2pay-mcp-server
npm install
npm run build

配置

克劳德桌面

添加到您的Claude Desktop配置文件中：

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

使用npx（推荐）

{
  "mcpServers": {
    "2pay": {
      "command": "npx",
      "args": ["-y", "@mcsacca/2pay-mcp-server"],
      "env": {
        "TWOCHECKOUT_MERCHANT_CODE": "your_merchant_code",
        "TWOCHECKOUT_SECRET_KEY": "your_secret_key",
        "TWOCHECKOUT_SANDBOX": "true"
      }
    }
  }
}

使用全局安装

{
  "mcpServers": {
    "2pay": {
      "command": "2pay-mcp-server",
      "env": {
        "TWOCHECKOUT_MERCHANT_CODE": "your_merchant_code",
        "TWOCHECKOUT_SECRET_KEY": "your_secret_key",
        "TWOCHECKOUT_SANDBOX": "true"
      }
    }
  }
}

使用本地构建

{
  "mcpServers": {
    "2pay": {
      "command": "node",
      "args": ["/path/to/2pay-mcp-server/dist/index.js"],
      "env": {
        "TWOCHECKOUT_MERCHANT_CODE": "your_merchant_code",
        "TWOCHECKOUT_SECRET_KEY": "your_secret_key",
        "TWOCHECKOUT_SANDBOX": "true"
      }
    }
  }
}

可用工具

订购工具（7）

订阅工具（22）

客户工具（6）

产品工具（7）

促销工具（7）

使用工具（5）

铅工具（5）

活动工具（8）

运输工具（3）

SKU工具（4）

账户工具（5）

SSO工具（4）

国际化工具（5）

资源和提示

资源

• 2pay://config -当前配置状态和API终结点
• 2pay://error-codes -常见错误代码及其含义

提示

• create-order -使用2Pay.js令牌创建订单的指导工作流程
• manage-subscription -订阅管理操作的指导性工作流程
• troubleshoot-payment -诊断并解决付款问题

使用示例

使用2Pay.js令牌下订单

{
  "token": "190f2d9c-0bbc-4ad0-a902-770adb8e7f90",
  "currency": "USD",
  "country": "US",
  "customerIP": "192.168.1.1",
  "items": [
    {
      "code": "PRODUCT_CODE",
      "quantity": 1
    }
  ],
  "billingDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "countryCode": "US"
  },
  "externalReference": "ORDER-12345"
}

订购动态产品

{
  "token": "your-2pay-token",
  "currency": "USD",
  "country": "US",
  "items": [
    {
      "name": "Custom Service",
      "quantity": 1,
      "price": 99.99,
      "isDynamic": true
    }
  ],
  "billingDetails": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "address1": "456 Oak Ave",
    "city": "Los Angeles",
    "zip": "90001",
    "countryCode": "US"
  }
}

搜索订单

{
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "customerEmail": "customer@example.com",
  "status": "COMPLETE",
  "page": 1,
  "limit": 50
}

搜索订阅

{
  "customerEmail": "customer@example.com",
  "status": "Active",
  "recurringEnabled": true,
  "page": 1,
  "limit": 10
}

更新订阅付款方式

{
  "subscriptionReference": "SUB123456789",
  "eesToken": "new-2pay-token-from-frontend",
  "holderName": "John Doe"
}

创建促销

{
  "name": "Summer Sale 2024",
  "description": "20% off all products",
  "startDate": "2024-06-01",
  "endDate": "2024-08-31",
  "discountType": "PERCENT",
  "discountValue": 20,
  "couponType": "SINGLE",
  "couponCode": "SUMMER20",
  "productCodes": ["PROD1", "PROD2"],
  "maximumOrders": 1000,
  "applyRecurring": false
}

报告计量计费的使用情况

{
  "subscriptionReference": "SUB123456789",
  "optionCode": "API_CALLS",
  "units": 1500,
  "usageStart": "2024-01-01",
  "usageEnd": "2024-01-31",
  "description": "January API usage"
}

暂停订阅

{
  "subscriptionReference": "SUB123456789",
  "pauseDays": 30
}

导入订阅（迁移）

{
  "customerEmail": "customer@example.com",
  "productCode": "PREMIUM_PLAN",
  "startDate": "2024-01-01",
  "expirationDate": "2025-01-01",
  "recurringEnabled": true,
  "quantity": 1,
  "externalCustomerReference": "LEGACY-CUST-123"
}

设置下一个续订价格

{
  "subscriptionReference": "SUB123456789",
  "price": 19.99,
  "currency": "USD"
}

建筑

src/
├── index.ts              # MCP server entry point & tool handlers
├── auth/
│   └── authentication.ts # REST header & JSON-RPC session auth
├── tools/
│   ├── orders.ts         # Order management tools
│   ├── subscriptions.ts  # Subscription management tools
│   ├── customers.ts      # Customer management tools
│   ├── products.ts       # Product catalog tools
│   ├── promotions.ts     # Promotion management tools
│   ├── usage.ts          # Usage/metered billing tools
│   ├── leads.ts          # Lead management tools
│   ├── campaigns.ts      # Cross-sell/upsell campaigns
│   ├── shipping.ts       # Shipping management tools
│   ├── sku.ts            # SKU code management
│   ├── account.ts        # Account info tools
│   ├── sso.ts            # Single sign-on tools
│   └── i18n.ts           # Internationalization tools
├── types/
│   └── 2checkout.ts      # TypeScript type definitions
└── utils/
    └── api-client.ts     # REST & JSON-RPC API client

认证

服务器支持两种身份验证方法：

1. REST API：用途 X-Avangate-Authentication 带有HMAC-SHA256哈希的标头
2. JSON-RPC API：用途 login 获取会话ID的方法（缓存30分钟）

默认情况下，这两种方法都使用SHA-256（MD5已弃用）。

环境变量

安全

重要安全注意事项

• 永远不要暴露密钥 在客户端代码或日志中
• 使用环境变量 对于凭据，切勿对其进行硬编码
• 令牌在30分钟后过期 -为每笔交易生成新的代币
• EES_TOKEN_PAYMENT没有测试模式 -令牌必须由有效的卡数据生成
• PCI DSS合规性 -在处理付款数据时，请注意您的合规要求

最佳实践

1. 始终使用HTTPS端点
2. 实施适当的错误处理
3. 记录交易参考，而不是付款详细信息
4. 在开发过程中使用沙盒模式
5. 定期旋转API键

故障排除

常见错误

调试模式

对于开发，请检查配置资源：

Use the 2pay://config resource to verify your setup

会话问题

如果遇到与会话相关的错误，客户端会自动处理会话刷新。如果问题仍然存在，请重新启动MCP服务器。

API 文档

• 2Pay.js集成指南
• JSON-RPC API 6.0参考
• REST API 6.0参考
• API身份验证
• 错误代码

贡献

欢迎投稿！请随时提交拉取请求。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

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

______________________________________________________________________

与 模型上下文协议 SDK。