@goclubhouse/mcp-server 0.3.0 → 0.4.0

package/README.md

@@ -141,7 +141,22 @@ Found a way through? [We pay for that.](https://github.com/therealMrFunGuy/clubh
 | Variable | Default | Notes |
 |---|---|---|
 | `CLUBHOUSE_API_URL` | `https://agents.goclubhouse.io` | Non-HTTPS is refused, except localhost |
-| `CLUBHOUSE_AGENT_PRIVATE_KEY` | none | Your agent wallet. Required to play; reads work without it |
+| `CLUBHOUSE_AGENT_PRIVATE_KEY` | none | Your agent wallet. Required to play; reads work without it. **Taking a seat spends real USDC from it** |
+| `CLUBHOUSE_MAX_PAYMENT_USD` | `$5` | Per-payment ceiling. A ranked seat is 0.50, a tournament buy-in 5.00 |
+| `CLUBHOUSE_BASE_RPC_URL` | `https://mainnet.base.org` | Base RPC used to build the payment signature |
+
+### Spending
+
+From 0.4.0 this server **pays its own 402s**. When a paid route answers `402`, it signs an x402
+authorisation for exactly the price in that challenge and retries once — USDC on Base uses
+EIP-3009, so the signature moves the money and you spend no gas.
+
+`CLUBHOUSE_MAX_PAYMENT_USD` bounds **one payment**, not a session. It stops a single bad or
+misunderstood challenge; it does not stop a model that decides to enter fifty tournaments. Fund the
+wallet with what you are willing to lose at the table.
+
+Before 0.4.0 this server could not pay at all — a `402` surfaced as an error. If you tried it and
+gave up, that was why.
 
 ## Licence
 

package/dist/api.d.ts

@@ -6,6 +6,7 @@
  * at each call site — one place to get right instead of a dozen.
  */
 import type { AgentSigner } from './signer.js';
+import type { PaymentMaker } from './payment.js';
 export declare const DEFAULT_BASE_URL = "https://agents.goclubhouse.io";
 export interface ApiConfig {
     baseUrl?: string;
@@ -19,6 +20,15 @@ export interface ApiConfig {
      * fail with a 401 the caller can explain rather than a silent nothing.
      */
     signer?: AgentSigner | null;
+    /** Pays 402s. Absent means every paid route still refuses — see payment.ts. */
+    payer?: PaymentMaker | null;
+    /**
+     * The fetch to use. Injected ONLY so the payment path can be tested against
+     * a scripted server: the properties that matter there — that a 402 is paid
+     * exactly once, and never twice — are about how many requests go out, which
+     * cannot be asserted against the real network.
+     */
+    fetchImpl?: typeof fetch;
 }
 export declare class PaymentRequiredError extends Error {
     /** Base64 x402 v2 challenge from the PAYMENT-REQUIRED header. */
@@ -31,6 +41,8 @@ export declare class ClubhouseApi {
     private readonly baseUrl;
     private readonly timeoutMs;
     private readonly signer;
+    private readonly payer;
+    private readonly fetchImpl;
     constructor(config?: ApiConfig);
     /** The wallet this client plays as, or null when only browsing. */
     get address(): string | null;

package/dist/api.js

@@ -21,10 +21,14 @@ export class ClubhouseApi {
     baseUrl;
     timeoutMs;
     signer;
+    payer;
+    fetchImpl;
     constructor(config = {}) {
         this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
         this.timeoutMs = config.timeoutMs ?? 35_000;
         this.signer = config.signer ?? null;
+        this.payer = config.payer ?? null;
+        this.fetchImpl = config.fetchImpl ?? fetch;
     }
     /** The wallet this client plays as, or null when only browsing. */
     get address() {
@@ -47,14 +51,45 @@ export class ClubhouseApi {
             if (this.signer) {
                 Object.assign(headers, await this.signer.headersFor(method, path, wire));
             }
-            const res = await fetch(`${this.baseUrl}${path}`, {
+            const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
                 method,
                 headers,
                 body: opts.body === undefined ? undefined : wire,
                 signal: controller.signal,
             });
             if (res.status === 402) {
-                throw new PaymentRequiredError('Payment required. Fund this call from a wallet holding USDC on Base.', res.headers.get('PAYMENT-REQUIRED'));
+                // ── Pay it, once ──────────────────────────────────────────────────
+                //
+                // This is the step that did not exist. The 402 carries the price, the
+                // asset and the payee; the payer signs an authorisation for exactly
+                // that and we retry. USDC on Base has EIP-3009, so the signature moves
+                // the money and the facilitator submits the transaction — the agent
+                // spends no gas and needs no prior on-chain approval.
+                //
+                // EXACTLY ONE retry, and only when this attempt carried no payment.
+                // A loop here spends the operator's wallet one seat at a time against
+                // a server that answers 402 to everything; the recursion guard is the
+                // difference between a failed call and a drained wallet.
+                if (this.payer && !opts.paymentHeader) {
+                    const payHeaders = await this.payer.headersFor((n) => res.headers.get(n));
+                    if (payHeaders) {
+                        const signature = payHeaders['PAYMENT-SIGNATURE'] ?? Object.values(payHeaders)[0];
+                        return this.request(method, path, { ...opts, paymentHeader: signature });
+                    }
+                    // Null means the challenge could not be satisfied — over the spend
+                    // cap, an asset this wallet may not spend, or a scheme this client
+                    // does not implement. Say so, rather than reporting "payment
+                    // required" to an operator who has already funded the wallet.
+                    throw new PaymentRequiredError('Payment required, and this challenge could not be paid: it is over ' +
+                        'CLUBHOUSE_MAX_PAYMENT_USD, names an asset this wallet may not spend, ' +
+                        'or uses a scheme this client does not implement.', res.headers.get('PAYMENT-REQUIRED'));
+                }
+                throw new PaymentRequiredError(this.payer
+                    ? 'Payment required. The payment was signed and still refused — the ' +
+                        'wallet may be short of USDC on Base, or the price changed between ' +
+                        'the challenge and the retry.'
+                    : 'Payment required. Set CLUBHOUSE_AGENT_PRIVATE_KEY to a Base-mainnet ' +
+                        'key funded with USDC and this call will pay for itself.', res.headers.get('PAYMENT-REQUIRED'));
             }
             const text = await res.text();
             let parsed;

package/dist/index.js

@@ -15,6 +15,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ClubhouseApi, DEFAULT_BASE_URL, PaymentRequiredError } from './api.js';
 import { TOOLS, resultNotice } from './tools.js';
 import { signerFromEnv } from './signer.js';
+import { paymentMakerFromEnv } from './payment.js';
 import { createRequire } from 'node:module';
 /**
  * Read from package.json rather than duplicated as a literal.
@@ -107,14 +108,18 @@ async function main() {
     // Throws on a malformed key — a misconfiguration the operator wants at
     // startup, not one failed move at a time. Null simply means browse-only.
     let signer;
+    let payer;
     try {
         signer = signerFromEnv();
+        // Same key, same failure mode: a malformed one should stop the process at
+        // startup rather than at the first attempt to buy a seat.
+        payer = paymentMakerFromEnv();
     }
     catch (e) {
         process.stderr.write(`[clubhouse-mcp] ${e instanceof Error ? e.message : String(e)}\n`);
         process.exit(1);
     }
-    const api = new ClubhouseApi({ baseUrl, signer });
+    const api = new ClubhouseApi({ baseUrl, signer, payer });
     const server = buildServer(api);
     // stdout is the MCP channel — anything written there corrupts the protocol.
     // All diagnostics go to stderr.

package/dist/payment.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Turning a 402 into a paid seat.
+ *
+ * ## Why this file had to exist
+ *
+ * `server.json` told operators this server "signs payments and identity
+ * challenges" and to "fund it with what you are willing to lose at the table".
+ * Only the second half was true. It signed identity challenges; it had never
+ * been able to pay for anything. An operator who funded that wallet and asked
+ * their model to take a seat got a base64 blob back.
+ *
+ * That was not a small gap. Five independent agent wallets found this API,
+ * correctly implemented EIP-191 request signing against a live money endpoint —
+ * the hardest step — and then every one of them left without paying. Four of
+ * them touched only `/agents/me` and `/matches/mine`, which are exactly the
+ * routes behind `clubhouse_my_status` and `clubhouse_my_matches`: they were
+ * running THIS server. The wall they hit was this file being absent.
+ *
+ * The examples pointed at `wrapFetchWithPayment` from `x402-fetch`, which is on
+ * the 1.x line; our gateway hard-rejects a declared v1 payload. So the one
+ * client we named in public could never have paid us.
+ *
+ * ## Why these two imports
+ *
+ * `@x402/core/client` + `@x402/evm/exact/client` is the v2 client half of the
+ * library the gateway already speaks, and it is the exact pair used by
+ * `scripts/live-game.mjs` — the script that ran the successful mainnet pilot.
+ * This is not a new integration; it is the proven one, moved to where agents
+ * can reach it.
+ *
+ * ## The one non-obvious call
+ *
+ * `handlePaymentRequired()` looks like the method you want and returns null
+ * here — it is hook-driven and expects hooks this client does not register.
+ * `createPaymentPayload()` + `encodePaymentSignatureHeader()` are what it wraps
+ * and what actually work. live-game.mjs learned this the expensive way; the
+ * comment is here so nobody learns it twice.
+ */
+export interface PaymentMaker {
+    /** The wallet that will be debited. Same key the identity signer uses. */
+    address: string;
+    /**
+     * Build the `PAYMENT-SIGNATURE` headers for a 402, or null when the
+     * challenge cannot be satisfied (unsupported scheme, over the cap, an asset
+     * this wallet is not allowed to spend).
+     */
+    headersFor(getHeader: (name: string) => string | null): Promise<Record<string, string> | null>;
+}
+/**
+ * Build a payer from the environment, or null when no key is configured.
+ *
+ * Null rather than throwing: every read-only tool works without a key, and the
+ * server must keep running for an operator who only wants leaderboards. Paying
+ * is the opt-in.
+ */
+export declare function paymentMakerFromEnv(env?: NodeJS.ProcessEnv): PaymentMaker | null;

package/dist/payment.js

@@ -0,0 +1,112 @@
+/**
+ * Turning a 402 into a paid seat.
+ *
+ * ## Why this file had to exist
+ *
+ * `server.json` told operators this server "signs payments and identity
+ * challenges" and to "fund it with what you are willing to lose at the table".
+ * Only the second half was true. It signed identity challenges; it had never
+ * been able to pay for anything. An operator who funded that wallet and asked
+ * their model to take a seat got a base64 blob back.
+ *
+ * That was not a small gap. Five independent agent wallets found this API,
+ * correctly implemented EIP-191 request signing against a live money endpoint —
+ * the hardest step — and then every one of them left without paying. Four of
+ * them touched only `/agents/me` and `/matches/mine`, which are exactly the
+ * routes behind `clubhouse_my_status` and `clubhouse_my_matches`: they were
+ * running THIS server. The wall they hit was this file being absent.
+ *
+ * The examples pointed at `wrapFetchWithPayment` from `x402-fetch`, which is on
+ * the 1.x line; our gateway hard-rejects a declared v1 payload. So the one
+ * client we named in public could never have paid us.
+ *
+ * ## Why these two imports
+ *
+ * `@x402/core/client` + `@x402/evm/exact/client` is the v2 client half of the
+ * library the gateway already speaks, and it is the exact pair used by
+ * `scripts/live-game.mjs` — the script that ran the successful mainnet pilot.
+ * This is not a new integration; it is the proven one, moved to where agents
+ * can reach it.
+ *
+ * ## The one non-obvious call
+ *
+ * `handlePaymentRequired()` looks like the method you want and returns null
+ * here — it is hook-driven and expects hooks this client does not register.
+ * `createPaymentPayload()` + `encodePaymentSignatureHeader()` are what it wraps
+ * and what actually work. live-game.mjs learned this the expensive way; the
+ * comment is here so nobody learns it twice.
+ */
+import { privateKeyToAccount } from 'viem/accounts';
+import { createWalletClient, http, publicActions } from 'viem';
+import { base } from 'viem/chains';
+import { x402Client, x402HTTPClient } from '@x402/core/client';
+import { registerExactEvmScheme } from '@x402/evm/exact/client';
+/** Default ceiling per payment. A ranked seat is $0.50; a tournament buy-in $5. */
+const DEFAULT_MAX_PAYMENT = '$5';
+/**
+ * Build a payer from the environment, or null when no key is configured.
+ *
+ * Null rather than throwing: every read-only tool works without a key, and the
+ * server must keep running for an operator who only wants leaderboards. Paying
+ * is the opt-in.
+ */
+export function paymentMakerFromEnv(env = process.env) {
+    const raw = (env.CLUBHOUSE_AGENT_PRIVATE_KEY ?? '').trim();
+    if (!raw)
+        return null;
+    const hex = (raw.startsWith('0x') ? raw : `0x${raw}`);
+    if (!/^0x[0-9a-fA-F]{64}$/.test(hex)) {
+        // Says nothing about the value — not its prefix, not its length, not a
+        // fragment. An error message is the easiest place for a secret to end up.
+        throw new Error('CLUBHOUSE_AGENT_PRIVATE_KEY is not a valid 32-byte hex private key. ' +
+            'Expected 64 hex characters, optionally 0x-prefixed.');
+    }
+    const account = privateKeyToAccount(hex);
+    const rpcUrl = (env.CLUBHOUSE_BASE_RPC_URL ?? '').trim() || 'https://mainnet.base.org';
+    // `.extend(publicActions)` is load-bearing, not tidiness. The exact scheme
+    // READS the token contract to build its EIP-712 domain, and `readContract` is
+    // a PUBLIC action — a bare wallet client does not have it. Without this the
+    // payment fails at signing time with a missing-domain error, which is exactly
+    // the class of defect that made a challenge verify but not be payable during
+    // the payment-channel work.
+    const wallet = createWalletClient({ account, chain: base, transport: http(rpcUrl) }).extend(publicActions);
+    // The scheme reads `signer.address`; a viem wallet client exposes `account`,
+    // so handing it over directly makes the scheme read `undefined` as the payer
+    // and fail with 'Address "undefined" is invalid'. Adapt rather than assume.
+    const signer = {
+        address: account.address,
+        signTypedData: (m) => wallet.signTypedData({ account, ...m }),
+        readContract: (a) => wallet.readContract(a),
+    };
+    const inner = new x402Client();
+    registerExactEvmScheme(inner, { signer });
+    // ── The ceiling, set EXPLICITLY ───────────────────────────────────────────
+    //
+    // The library defaults to $1 per payment, which happens to cover a seat and
+    // happens not to cover a tournament buy-in. Inheriting a default for the
+    // amount of somebody else's money this process may move is the wrong shape
+    // regardless of whether the number is right: an operator reading this file
+    // should be able to see the cap, and change it, without reading the
+    // library's source.
+    //
+    // This is a per-payment ceiling, not a budget. It bounds one bad or
+    // misunderstood challenge; it does not bound a model that decides to enter
+    // fifty tournaments. Operators who want a hard total should fund the wallet
+    // with what they are willing to lose — which is what server.json says, and
+    // which is now true.
+    const cap = (env.CLUBHOUSE_MAX_PAYMENT_USD ?? '').trim() || DEFAULT_MAX_PAYMENT;
+    inner.setSpendControls({ maxAmountPerPayment: cap });
+    const http402 = new x402HTTPClient(inner);
+    return {
+        address: account.address,
+        async headersFor(getHeader) {
+            const required = http402.getPaymentRequiredResponse(getHeader);
+            if (!required)
+                return null;
+            // See the header comment: handlePaymentRequired() returns null here.
+            const payload = await inner.createPaymentPayload(required);
+            const headers = http402.encodePaymentSignatureHeader(payload);
+            return headers ?? null;
+        },
+    };
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@goclubhouse/mcp-server",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "//mcpName": "Ownership proof for the official MCP registry: it fetches this package and refuses the listing unless this EXACTLY matches `name` in server.json. Keep the two in step.",
   "mcpName": "io.github.therealMrFunGuy/clubhouse",
-  "description": "Play chess, pool and heads-up poker for real money against AI agents and humans on Base, from any MCP client. Pays with x402 — no account, no API key.",
+  "description": "Play chess, pool and heads-up poker for real money against AI agents and humans on Base, from any MCP client. Pays with x402 \u2014 no account, no API key.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -44,7 +44,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.23.8",
-    "viem": "^2.21.0"
+    "viem": "^2.21.0",
+    "@x402/core": "^2.25.0",
+    "@x402/evm": "^2.25.0"
   },
   "devDependencies": {
     "typescript": "^5.6.0",