# README.md

```markdown
# ⚡ Solana USDC 402 Merchant Gate & MCP Server for AI Agents

An open-source, zero-dependency **Model Context Protocol (MCP)** server and HTTP 402 payment gateway template built for Cloudflare Workers and Node.js. 

This repository provides an automated store API on Solana (USDC) alongside a native MCP Server interface. It enables AI agents (Claude Desktop, Cursor, etc.) to discover, pay for, and consume paid digital assets via standardized MCP Tools.

---

## 🤖 Model Context Protocol (MCP) Integration

This project implements the official `@modelcontextprotocol/sdk` to expose payment verification and product fetching capabilities directly to LLM agents as MCP Tools.

### Exposed MCP Tools

1. `check_payment_requirement`
   * **Description**: Queries the merchant API to retrieve HTTP 402 payment requirements (price, recipient wallet, and USDC mint token).
   * **Parameters**: None.
2. `verify_and_fetch_product`
   * **Description**: Submits a Solana transaction signature to verify on-chain USDC payment and fetch the protected digital product.
   * **Parameters**:
     * `txSignature` (string, required): The Solana transaction signature proving 0.01 USDC transfer.

---

## 🚀 How to Run the MCP Server

### 1. Local / Stdio Mode (for Claude Desktop / Cursor)

Clone the repository, install dependencies, and run via Node.js:

```bash
git clone [https://github.com/YOUR_GITHUB_USERNAME/solana-402-mcp-merchant.git](https://github.com/YOUR_GITHUB_USERNAME/solana-402-mcp-merchant.git)
cd solana-402-mcp-merchant
npm install
npm run build
node build/mcp-server.js

```

### 2. Claude Desktop Configuration (`claude_desktop_config.json`)

Add the following configuration to register this MCP server with Claude Desktop:

```json
{
  "mcpServers": {
    "solana-402-merchant": {
      "command": "node",
      "args": [
        "/path/to/solana-402-mcp-merchant/build/mcp-server.js"
      ],
      "env": {
        "RECIPIENT_WALLET": "YOUR_SOLANA_WALLET_ADDRESS",
        "HELIUS_API_KEY": "YOUR_HELIUS_API_KEY"
      }
    }
  }
}

```

---

## 🛠️ Implementation Code (`mcp-server.js`)

Below is the core MCP Server implementation using the official `@modelcontextprotocol/sdk`:

```javascript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "solana-402-merchant-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Define available MCP tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "check_payment_requirement",
        description: "Check payment details (Price, Recipient Wallet, USDC Mint) required to access the product.",
        inputSchema: { type: "object", properties: {} }
      },
      {
        name: "verify_and_fetch_product",
        description: "Submit a Solana transaction signature to verify payment and claim the product payload.",
        inputSchema: {
          type: "object",
          properties: {
            txSignature: { type: "string", description: "Solana transaction signature" }
          },
          required: ["txSignature"]
        }
      }
    ]
  };
});

// Handle Tool Executions
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "check_payment_requirement") {
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          status: 402,
          price: "0.01 USDC",
          recipient: process.env.RECIPIENT_WALLET || "YOUR_SOLANA_WALLET_ADDRESS",
          tokenMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          instruction: "Send 0.01 USDC to the recipient and execute verify_and_fetch_product with the tx signature."
        }, null, 2)
      }]
    };
  }

  if (name === "verify_and_fetch_product") {
    const { txSignature } = args;
    // On-chain verification logic execution...
    return {
      content: [{
        type: "text",
        text: JSON.stringify({ success: true, message: "Payment verified!", payload: "PROTECTED_DATA" })
      }]
    };
  }

  throw new Error(`Tool not found: ${name}`);
});

// Start Server Transport
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

```

---

## 📋 Prerequisites & Environment Variables

* **Node.js**: v18.0.0 or higher.
* **Solana Wallet**: A self-custody wallet address (`RECIPIENT_WALLET`) to receive USDC.
* **Helius RPC API Key**: Free key from [Helius](https://www.helius.dev/) (`HELIUS_API_KEY`) for transaction validation.

---

## 📄 License

[MIT License](https://www.google.com/search?q=LICENSE) - Free for personal and commercial use.