flickpay

v1.0.5

Published

4 months ago

FlickPay MCP Server - A Model Context Protocol server for FlickPay payment processing. Enables AI agents to interact with payment APIs for product listing, order creation, and refund processing.

0High
0Medium
0Low

jaysong123

mcp model-context-protocol flickpay payment ai agent jsonrpc api

FlickPay MCP Server

English | 中文

English

A Model Context Protocol (MCP) server for FlickPay payment processing. Enables AI agents to interact with payment APIs for product listing, order creation, and refund processing.

🌐 Web Interface: https://flickpay.aizelnetwork.com/

Installation and Usage / 安装和使用

Quick Start / 快速开始

# Run directly with npx (stdio mode for MCP clients)
# 使用 npx 直接运行（stdio 模式，适合 MCP 客户端）
npx flickpay

# Or install globally
# 或全局安装
npm install -g flickpay
flickpay

Command Line Options / 命令行选项

# Start in stdio mode (default, for MCP clients like Claude Desktop)
# 启动 stdio 模式（默认，适合 Claude Desktop 等 MCP 客户端）
flickpay
# or
flickpay stdio --api-key your-api-key

# Start HTTP server mode
# 启动 HTTP 服务器模式
flickpay start --port 8080 --api-key your-api-key

# Test the server
# 测试服务器
flickpay test --url http://localhost:3000 --api-key your-api-key

# Show help
# 显示帮助
flickpay --help

Usage

Command Line Options

# Start the MCP server
flickpay start [options]

Options:
  -p, --port <port>        Port to run the server on (default: 3000)
  -h, --host <host>        Host to bind the server to (default: localhost)
  --api-key <key>          Default API key for authentication
  --jwt-token <token>      Default JWT token for authentication
  --backend-api <url>      Backend API base URL (default: http://34.126.81.115:8090)

# Test the server
flickpay test --url http://localhost:3000 --api-key your-api-key

Environment Variables

FLICKPAY_API_KEY=your-api-key
FLICKPAY_API_BASE=http://34.126.81.115:8090

MCP Protocol Support

FlickPay implements the Model Context Protocol (MCP) specification, providing:

JSON-RPC 2.0 endpoint for AI agent integration
Standard MCP methods: initialize, tools/list, tools/call
Authentication: API Key support
Error handling: Business logic vs system error differentiation

Available Tools

| Tool | Description | Required Parameters | Optional Parameters | |------|-------------|-------------------|---------------------| | listProducts | Get available products for ordering | - | page, limit | | createOrder | Create new orders with product details | productId | customerEmail, customerName, orderType | | queryOrder | Query order status and details | orderNo | - | | refundOrder | Submit refund requests for orders | orderNo | - |

API Endpoints

POST / - JSON-RPC 2.0 endpoint for MCP requests
GET / - Server information and capabilities
GET /mcp.json - MCP capabilities file

Example Usage

Initialize Connection

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {"tools": {}},
    "clientInfo": {"name": "MyAI", "version": "1.0.0"}
  }
}

List Available Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Create an Order

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "createOrder",
    "arguments": {
      "productId": "77",
      "orderType": "once",
      "customerEmail": "[email protected]",
      "customerName": "John Doe"
    }
  }
}

Authentication

API Key (Header)

X-API-Key: your-api-key-here

Integration with AI Applications

FlickPay MCP Server is compatible with:

Claude Desktop - Add server endpoint to MCP configuration
VS Code with GitHub Copilot - Configure as MCP server
Custom AI applications - Use standard MCP client libraries

MCP Client Configuration (Claude Desktop) / MCP 客户端配置 (Claude Desktop)

Add the following to your Claude Desktop configuration file: 将以下内容添加到您的 Claude Desktop 配置文件中：

Configuration file location / 配置文件位置:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "flickpay": {
      "command": "npx",
      "args": ["flickpay"],
      "env": {
        "FLICKPAY_API_KEY": "your-api-key-here",
        "FLICKPAY_API_BASE": "http://34.126.81.115:8090"
      }
    }
  }
}

Note: The default command now runs in stdio mode, which is perfect for MCP clients like Claude Desktop. 注意: 默认命令现在运行在 stdio 模式下，非常适合 Claude Desktop 等 MCP 客户端。

Development

Programmatic Usage

import { createMCPServer } from 'flickpay'

const server = createMCPServer({
  port: 3000,
  host: 'localhost',
  apiKey: 'your-api-key',
  backendApiBase: 'http://your-backend.com'
})

await server.start()

Building from Source

git clone [email protected]:AizelNetwork/flickpay.git
cd flickpay
npm install
npm run build
npm start

Error Handling

FlickPay uses intelligent error handling:

Business Logic Errors (400/404): Returns friendly error messages without throwing exceptions
System Errors (500+): Throws exceptions for system-level issues
Authentication Errors: Clear messages for invalid credentials

Security

API keys and JWT tokens are never logged
HTTPS recommended for production
Input validation on all parameters
CORS support for web applications

License

MIT License - see LICENSE file for details

Default Configuration

When you run npx flickpay, the server starts with:

Host: localhost
Port: 3000
Backend API: http://34.126.81.115:8090
Web Interface: https://flickpay.aizelnetwork.com/

Support

Issues: https://github.com/AizelNetwork/flickpay/issues
Documentation: https://github.com/AizelNetwork/flickpay
Web Interface: https://flickpay.aizelnetwork.com/

中文

FlickPay 支付处理的模型上下文协议 (MCP) 服务器。使 AI 代理能够与支付 API 交互，进行产品列表、订单创建和退款处理。

🌐 Web 界面: https://flickpay.aizelnetwork.com/

快速开始

使用 npx（推荐）

# 使用默认设置启动服务器 (localhost:3000)
npx flickpay

# 使用自定义配置启动
npx flickpay start --port 8080 --host 0.0.0.0 --api-key your-api-key

# 测试连接
npx flickpay test --url http://localhost:3000 --api-key your-api-key

安装

npm install -g flickpay
flickpay start

使用方法

命令行选项

# 启动 MCP 服务器
flickpay start [选项]

选项:
  -p, --port <port>        服务器运行端口 (默认: 3000)
  -h, --host <host>        服务器绑定主机 (默认: localhost)
  --api-key <key>          默认 API 密钥用于认证
  --backend-api <url>      后端 API 基础 URL (默认: http://34.126.81.115:8090)

# 测试服务器
flickpay test --url http://localhost:3000 --api-key your-api-key

环境变量

FLICKPAY_API_KEY=your-api-key
FLICKPAY_API_BASE=http://34.126.81.115:8090

MCP 协议支持

FlickPay 实现了模型上下文协议 (MCP) 规范，提供：

JSON-RPC 2.0 端点用于 AI 代理集成
标准 MCP 方法: initialize, tools/list, tools/call
认证: API 密钥支持
错误处理: 业务逻辑与系统错误区分

可用工具

| 工具 | 描述 | 必需参数 | 可选参数 | |------|------|----------|----------| | listProducts | 获取可订购产品列表 | - | page, limit | | createOrder | 基于产品详情创建新订单 | productId | customerEmail, customerName, orderType | | queryOrder | 查询订单状态和详情 | orderNo | - | | refundOrder | 提交订单退款请求 | orderNo | - |

API 端点

POST / - MCP 请求的 JSON-RPC 2.0 端点
GET / - 服务器信息和功能
GET /mcp.json - MCP 功能文件

调用逻辑

1. 初始化连接

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {"tools": {}},
    "clientInfo": {"name": "MyAI", "version": "1.0.0"}
  }
}

2. 列出可用工具

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

3. 创建订单

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "createOrder",
    "arguments": {
      "productId": "77",
      "orderType": "once",
      "customerEmail": "[email protected]",
      "customerName": "张三"
    }
  }
}

4. 查询订单

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "queryOrder",
    "arguments": {
      "orderNo": "FP1757316824649l9f8y"
    }
  }
}

认证

API 密钥（请求头）

X-API-Key: your-api-key-here

与 AI 应用程序集成

FlickPay MCP 服务器兼容：

Claude Desktop - 将服务器端点添加到 MCP 配置
VS Code with GitHub Copilot - 配置为 MCP 服务器
自定义 AI 应用程序 - 使用标准 MCP 客户端库

Claude Desktop 配置

添加到您的 MCP 设置：

{
  "mcpServers": {
    "flickpay": {
      "command": "npx",
      "args": ["flickpay"],
      "env": {
        "FLICKPAY_API_KEY": "your-api-key"
      }
    }
  }
}

默认配置

当您运行 npx flickpay 时，服务器使用以下默认配置启动：

主机: localhost
端口: 3000
后端 API: http://34.126.81.115:8090
Web 界面: https://flickpay.aizelnetwork.com/

开发

编程使用

import { createMCPServer } from 'flickpay'

const server = createMCPServer({
  port: 3000,
  host: 'localhost',
  apiKey: 'your-api-key',
  backendApiBase: 'http://your-backend.com'
})

await server.start()

从源码构建

git clone [email protected]:AizelNetwork/flickpay.git
cd flickpay
npm install
npm run build
npm start

错误处理

FlickPay 使用智能错误处理：

业务逻辑错误 (400/404): 返回友好的错误消息而不抛出异常
系统错误 (500+): 对系统级问题抛出异常
认证错误: 对无效凭据提供清晰消息

安全性

API 密钥和 JWT 令牌永不记录
生产环境建议使用 HTTPS
所有参数输入验证
支持 CORS 用于 Web 应用程序

许可证

MIT 许可证 - 详见 LICENSE 文件

支持

问题: https://github.com/AizelNetwork/flickpay/issues
文档: https://github.com/AizelNetwork/flickpay
Web 界面: https://flickpay.aizelnetwork.com/