PYUSD支付管理服务器

PYUSD MCP Server

A Model Context Protocol (MCP) server for managing PYUSD invoices and payments on Sepolia testnet. This server enables AI assistants (like Claude) to interact with PYUSD blockchain transactions, manage product catalogs, and generate invoices.

🚀 Features

• Product Catalog Management: Browse items available for purchase
• Invoice Generation: Create invoices with buyer details and item information
• PYUSD Payments: Execute blockchain transactions on Sepolia testnet
• Wallet Operations: Check balances and send PYUSD directly
• Transaction Receipts: Track payment status and blockchain confirmations

📋 Prerequisites

• Node.js >= 18.0.0
• A wallet with PYUSD on Sepolia testnet
• Private key for the wallet

🔧 Installation

1. Install dependencies:

cd /app/mcp-server
yarn install

2. Configure environment variables:

cp .env.example .env

3. Edit .env and add your private key:

PRIVATE_KEY=your_private_key_here
SEPOLIA_RPC_URL=https://rpc.sepolia.org
PYUSD_CONTRACT_ADDRESS=0xCaC524BcA292aaade2DF8A05cC58F0a65B1B3bB9
PORT=3001

🎯 Usage

Running the Server

Start the MCP server:

yarn start

Or with auto-reload during development:

yarn dev

Configuring Claude Desktop

Add this to your Claude Desktop config file:

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

{
  "mcpServers": {
    "pyusd": {
      "command": "node",
      "args": ["/app/mcp-server/index.js"]
    }
  }
}

Then restart Claude Desktop.

🛠️ Available Tools

1. list_items

List all available items in the store catalog.

Example use in Claude:

"Show me the available items"

2. get_item

Get details of a specific item by ID.

Parameters:

• item_id (number): The ID of the item

Example:

"Tell me about item 1"

3. generate_invoice

Generate a new invoice for a purchase.

Parameters:

• buyer_name (string): Name of the buyer
• buyer_email (string): Email address
• buyer_wallet (string, optional): Buyer's wallet address
• item_id (number): ID of the item
• quantity (number, optional): Quantity (default: 1)
• recipient_wallet (string): Wallet to receive payment

Example:

"Create an invoice for Tanmay (tanmay@example.com) who wants to buy 1 Aikiko T-shirt. Send payment to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

4. pay_invoice

Process payment for an invoice using PYUSD.

Parameters:

• invoice_id (string): The invoice ID to pay

Example:

"Pay invoice INV-1234567890"

5. get_invoice

Retrieve invoice details including payment status.

Parameters:

• invoice_id (string): The invoice ID

Example:

"Show me invoice INV-1234567890"

6. list_invoices

List all invoices with optional status filter.

Parameters:

• status (string, optional): Filter by status (pending/paid/failed)

Example:

"Show all paid invoices"

7. send_pyusd

Send PYUSD directly from your wallet to another address.

Parameters:

• to_address (string): Recipient wallet address
• amount (number): Amount of PYUSD to send

Example:

"Send 10 PYUSD to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

8. check_balance

Check PYUSD balance of a wallet.

Parameters:

• address (string, optional): Wallet address (defaults to your wallet)

Example:

"What's my PYUSD balance?"

9. get_wallet_info

Get information about the configured wallet.

Example:

"Show my wallet info"

💡 Usage Examples

Complete Purchase Flow

1. Browse Items:

   "Show me what items are available"

2. Generate Invoice:

   "I want to buy an Aikiko T-shirt. My name is John Doe, email john@example.com, and send the payment to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

3. Pay Invoice:

   "Pay the invoice you just created"

4. Check Receipt:

   "Show me the transaction details"

Direct Transfer

"Send 5 PYUSD to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

🗄️ Database Structure

The server uses a JSON file (database.json) to store:

{
  "items": [
    {
      "id": 1,
      "name": "Aikiko T-shirt",
      "description": "Premium quality cotton t-shirt",
      "price": 12,
      "currency": "PYUSD",
      "stock": 50
    }
  ],
  "invoices": [
    {
      "id": "INV-1234567890",
      "buyer": {
        "name": "John Doe",
        "email": "john@example.com",
        "wallet": "0x..."
      },
      "item": {
        "id": 1,
        "name": "Aikiko T-shirt",
        "price": 12,
        "quantity": 1
      },
      "total": 12,
      "currency": "PYUSD",
      "recipient_wallet": "0x...",
      "status": "paid",
      "created_at": "2025-01-15T10:00:00.000Z",
      "payment": {
        "transaction_hash": "0x...",
        "block_number": 12345,
        "paid_at": "2025-01-15T10:05:00.000Z"
      }
    }
  ]
}

🔐 Security Notes

• Never commit your .env file with real private keys
• Use testnet only for development
• Keep your private key secure
• The server should only be run locally

🌐 Network Information

• Network: Sepolia Testnet
• PYUSD Contract: 0xCaC524BcA292aaade2DF8A05cC58F0a65B1B3bB9
• Decimals: 6
• RPC URL: https://rpc.sepolia.org

🐛 Troubleshooting

"PRIVATE_KEY not set in .env file"

Make sure you've created a .env file and added your private key.

Transaction fails

• Check if your wallet has enough PYUSD and ETH (for gas)
• Verify the recipient address is valid
• Ensure you're connected to Sepolia testnet

Server not responding

• Check if Node.js version >= 18
• Verify all dependencies are installed (yarn install)
• Check the console for error messages

📝 Development

To add new items to the catalog, edit database.json:

{
  "items": [
    {
      "id": 5,
      "name": "New Item",
      "description": "Description",
      "price": 10,
      "currency": "PYUSD",
      "stock": 100
    }
  ]
}

🤝 Contributing

This is a demo project for educational purposes. Feel free to extend it with:

• Database integration (MongoDB, PostgreSQL)
• User authentication
• Email notifications
• Frontend dashboard
• Multi-currency support

📄 License

MIT License