@phqb/mcp-server/README.md

PHQB MCP Payment Server - AI-powered payment processing for Claude and other AI assistants

# PHQB MCP Server

🤖 **AI-powered payment processing for Claude and other AI assistants**

PHQB MCP Server is a Model Context Protocol (MCP) compatible server that enables AI assistants like Claude to create payments, manage orders, process refunds, and analyze payment data through natural language conversations.

## ✨ Features

### 🎯 16 Professional Payment Tools

#### 💳 Payment Creation (3 tools)
- **create_wechat_payment** - WeChat Pay specific QR codes
- **create_alipay_payment** - Alipay specific QR codes
- **create_auto_payment** - Smart aggregated payment with one QR code for WeChat + Alipay

#### 📋 Order Management (4 tools)
- **get_order_details** - Detailed order information
- **search_orders** - Advanced order search with filters
- **get_recent_orders** - Recent order history (up to 100 orders)
- **cancel_order** - Cancel unpaid orders

#### 💰 Refund Management (3 tools)
- **create_refund** - Create full or partial refunds
- **get_refund_status** - Track refund processing status
- **get_refund_history** - Refund history and statistics

#### 📊 Analytics & Insights (3 tools)
- **get_payment_stats** - Payment statistics with trends
- **get_revenue_summary** - Comprehensive revenue analysis
- **get_top_products** - Best-selling products/services ranking

#### 👥 Customer Management (2 tools)
- **get_customer_info** - Customer payment history and profile
- **get_customer_stats** - Customer behavior analytics

### 🔒 Security & Permissions

- **API Key Authentication** - Secure access with PHQB API keys
- **Fine-grained Permissions** - Tool access based on API key permissions
- **Rate Limiting** - Plan-based usage limits (Free/Pro/Advanced)
- **Usage Logging** - Complete audit trail of AI tool usage

## 🚀 Quick Start

### 1. Installation

```bash
npm install -g @phqb/mcp-server
```

### 2. Get Your API Key

1. Visit [PHQB Dashboard](https://www.phqb.com/dashboard?tab=apikey)
2. Create a new API Key with MCP permissions
3. Copy your API Key

### 3. Configure Claude Desktop

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "phqb-payment": {
      "command": "npx",
      "args": ["@phqb/mcp-server"],
      "env": {
        "PHQB_API_KEY": "your-api-key-here",
        "PHQB_API_URL": "https://www.phqb.com"
      }
    }
  }
}
```

### 4. Restart Claude Desktop

Restart Claude Desktop to load the PHQB payment tools.

### 5. Start Using AI Payments!

Try these example prompts in Claude:

```
"Create a payment link for $99 for my AI programming course"

"Show me today's payment statistics"

"Check the status of order PHQB_123456789"

"Create a refund for order PHQB_123456789 due to customer request"
```

## 🛠️ CLI Usage

### Test Connection
```bash
phqb-mcp test --api-key "your-api-key"
```

### List Available Tools
```bash
phqb-mcp tools --api-key "your-api-key"
```

### Start Server Manually
```bash
phqb-mcp start --api-key "your-api-key"
```

## 📋 Plan Limitations

| Feature | Free | Pro | Advanced |
|---------|------|-----|----------|
| **API Keys** | 2 | 10 | Unlimited |
| **MCP Tools** | 2 tools | 8 tools | 16 tools |
| **Daily Calls** | 50 | 500 | Unlimited |
| **Payment Creation** | ✅ | ✅ | ✅ |
| **Order Management** | ❌ | ✅ | ✅ |
| **Refund Processing** | ❌ | ❌ | ✅ |
| **Analytics** | ❌ | Basic | Advanced |
| **Customer Management** | ❌ | ❌ | ✅ |

## 🎯 Use Cases

### 💼 Business Automation
- **AI Sales Assistant**: "Create payment links for new customers"
- **Customer Service**: "Process refunds and check order status"
- **Financial Reporting**: "Generate monthly revenue reports"

### 🛒 E-commerce Integration
- **Product Sales**: "Create payment for premium course $199"
- **Subscription Management**: "Check customer payment history"
- **Inventory Tracking**: "Show top-selling products this month"

### 📊 Data Analysis
- **Revenue Insights**: "Analyze payment trends over last 90 days"
- **Customer Behavior**: "Find high-value customers for marketing"
- **Performance Metrics**: "Calculate conversion rates and success metrics"

## 🔧 Advanced Configuration

### Environment Variables

```bash
export PHQB_API_KEY="your-api-key"
export PHQB_API_URL="https://www.phqb.com"  # Optional
```

### Custom Base URL (for development)

```json
{
  "mcpServers": {
    "phqb-payment": {
      "command": "npx",
      "args": ["@phqb/mcp-server"],
      "env": {
        "PHQB_API_KEY": "your-api-key",
        "PHQB_API_URL": "http://localhost:3000"
      }
    }
  }
}
```

## 🐛 Troubleshooting

### Common Issues

**"Invalid API Key" Error**
- Verify your API key is correct
- Check API key permissions include MCP tools
- Ensure API key is active and not expired

**"Permission Denied" Error**
- Your API key lacks required permissions
- Upgrade your PHQB plan for more tools
- Edit API key permissions in dashboard

**"Rate Limit Exceeded" Error**
- You've exceeded your plan's daily/hourly limits
- Upgrade to Pro or Advanced plan
- Wait for rate limit reset

### Getting Help

- 📖 [Documentation](https://www.phqb.com/docs/mcp)
- 💬 [Support](https://www.phqb.com/support)
- 🐛 [Report Issues](https://github.com/nzleo/phqb/issues)

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

---

**Made with ❤️ by the PHQB Team**

🌐 [Website](https://www.phqb.com) • 📚 [Docs](https://www.phqb.com/docs) • 🐦 [Twitter](https://twitter.com/phqb_com)