# MCP Pay Server

A standalone implementation of the Model Context Protocol (MCP) server with HTTP+SSE transport, including a basic pre-pay credit system.

## Features

- Exposes MCP tools, resources, and prompts
- Supports HTTP+SSE for bidirectional communication
- Implements a simple payment layer using USDC deposits on Base (or Base Sepolia)
- Built with Express, TypeScript, Viem, and Zod

## Setup

1.  **Install dependencies:**
    ```bash
    npm install
    ```

2.  **Configure Environment Variables:**
    Create a `.env` file in the root directory (`mcp-pay-server/.env`) with the following:

    ```dotenv
    # Required: Public address of the wallet the server will watch for USDC deposits
    SERVER_DEPOSIT_ADDRESS=0xYourServerWalletPublicAddress

    # Optional: RPC URL for Base or Base Sepolia (defaults provided)
    # BASE_RPC_URL=https://your-base-rpc-url

    # Optional: Port for the server (defaults to 3000)
    # PORT=3001
    ```

    *   `SERVER_DEPOSIT_ADDRESS`: The public `0x...` address the server should monitor for incoming USDC deposits.
    *   `BASE_RPC_URL`: The RPC endpoint for interacting with the Base blockchain (mainnet or Sepolia).
    *   `PORT`: The port the HTTP server will listen on.

## Usage

Start the server:

```bash
npm start
```

This will start the MCP server and begin watching for USDC deposits to the configured `SERVER_DEPOSIT_ADDRESS`.

## Payment System Overview

This server uses a pre-pay credit system verified via cryptographic signatures. Clients fetch the payment capabilities separately after connecting.

1.  **Connect:** Client connects to the server.
2.  **Fetch Capabilities:** Client calls the `payments/getCapabilities` method to receive:
    *   The URI of the resource providing deposit information (e.g., `mcp-pay://server/payment/info`).
    *   The name of the tool used for checking balances (e.g., `payments_getBalance`).
    *   A list of tools that require payment and their associated cost (as strings).
3.  **Deposit Info:** Clients read the deposit info resource (URI obtained from capabilities) to get the server's USDC deposit address.
4.  **Credit:** Clients send USDC (on the configured network) to the deposit address. The server monitors this address and credits the sender's account in its internal ledger.
5.  **Paid Tool Usage:** When a client calls a tool identified as paid in the capabilities:
    *   It *must* include `__payer` (its `0x...` address) and `__signature` (ECDSA signature of the canonical request) in the `params.arguments`.
    *   The server's central middleware verifies the signature and checks the payer's balance against the tool's cost *before* executing the tool logic.
    *   If verification succeeds, the tool executes. If the tool execution is successful, the cost is deducted from the payer's balance.
6.  **Balance Check:** Clients use the balance check tool (name obtained from capabilities) with their `payerAddress` as an argument. This tool does not require a signature.

## Available Endpoints

- `POST /mcp` - For client requests to the server (requires `mcp-session-id` header). Handles general MCP methods and `payments/getCapabilities`.
- `GET /mcp` - For SSE (Server-Sent Events) stream (requires `mcp-session-id` header).

## Payment Capabilities (Exposed via payments/getCapabilities)

- **Deposit Info Resource URI:** `mcp-pay://server/payment/info` (by default)
- **Balance Check Tool:** `payments_getBalance` (by default)
- **Paid Tools (Example):**
  - `greet`: 0.05 USDC (by default)
  - *(Others can be configured)*

## Available Tools

- `greet`: A simple greeting tool (Requires payment by default).
- `payments_getBalance`: Returns the credit balance for the calling wallet (Free).

## Available Resources

- `mcp-pay://server/payment/info`: Returns the server's deposit address.

## Development

Build the TypeScript code:

```bash
npm run build
```