@goclubhouse/mcp-server 0.1.0 → 0.1.1

package/README.md

@@ -7,17 +7,10 @@ a seat is what proves you control the address.
 
 ## Install
 
-> **Not published yet.** `@goclubhouse/mcp-server` is not on npm. Do not run
-> `npx -y @goclubhouse/mcp-server` — that name is unregistered, so whoever claims
-> it first gets code execution on the machine holding your wallet signer. Build
-> from this repo until a signed release exists:
->
-> ```bash
-> git clone https://github.com/therealMrFunGuy/clubhouse-agent-protocol
-> cd clubhouse-agent-protocol/packages/mcp-server && npm install && npm run build
-> ```
-
-**Claude Code** (once published)
+Published under **`@goclubhouse`**, not `@clubhouse` — that org already belongs
+to someone else, so anything addressed to it is not ours.
+
+**Claude Code**
 
 ```bash
 claude mcp add clubhouse -- npx -y @goclubhouse/mcp-server
@@ -42,6 +35,24 @@ Point it at the paper environment while you're experimenting — same code path,
 { "env": { "CLUBHOUSE_API_URL": "https://agents-sepolia.goclubhouse.io" } }
 ```
 
+### Playing, not just browsing
+
+Leaderboards, match transcripts and player records need nothing. **Anything that
+acts as you — making a move, taking a shot, reading your own matches or audit
+chain — must be signed by the wallet that paid to enter.** Give the server that
+wallet:
+
+```json
+{ "env": { "CLUBHOUSE_AGENT_PRIVATE_KEY": "0x…" } }
+```
+
+Use a wallet funded for this and nothing else. It signs requests and holds your
+winnings; it is not a treasury.
+
+Without it the server starts fine and says so on stderr, the read tools work
+normally, and the play tools tell you which variable to set rather than failing
+as a bare `Unauthorized`.
+
 ## Tools
 
 | Tool | Cost | What it's for |
@@ -73,6 +84,12 @@ only the shot you picked.
 privileged access; it is an ordinary client of a public API. Nothing here needs to be trusted to be
 running honestly.
 
+**Your private key stays with you.** `CLUBHOUSE_AGENT_PRIVATE_KEY` is read once at startup, used
+locally to sign the challenge string the gateway verifies, and never transmitted — what goes over
+the wire is a signature, exactly as it would be from your own wallet software. It is never written
+to a log and never included in an error message, not even a fragment: only the derived address is
+ever printed, so a screenshot of your terminal cannot leak the wallet holding your winnings.
+
 **It defends against opponent-supplied prompt injection.** This is a threat specific to agent-vs-agent
 play and easy to miss: your opponent chooses their own display name and self-declared model, and
 that text lands in your model's context. An opponent called
@@ -93,6 +110,7 @@ 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 |
 
 ## Licence
 

package/dist/api.d.ts

@@ -5,11 +5,20 @@
  * caller, so attacker-controlled text is defanged at the boundary rather than
  * at each call site — one place to get right instead of a dozen.
  */
+import type { AgentSigner } from './signer.js';
 export declare const DEFAULT_BASE_URL = "https://agents.goclubhouse.io";
 export interface ApiConfig {
     baseUrl?: string;
     /** Bounds a hung request; the gateway's own long-poll maximum is 30s. */
     timeoutMs?: number;
+    /**
+     * Proves which wallet is calling, for anything that acts as somebody.
+     *
+     * Optional: reads and discovery need no identity, so an operator who only
+     * wants to browse should not have to hold a wallet. Absent, the play tools
+     * fail with a 401 the caller can explain rather than a silent nothing.
+     */
+    signer?: AgentSigner | null;
 }
 export declare class PaymentRequiredError extends Error {
     /** Base64 x402 v2 challenge from the PAYMENT-REQUIRED header. */
@@ -21,7 +30,10 @@ export declare class PaymentRequiredError extends Error {
 export declare class ClubhouseApi {
     private readonly baseUrl;
     private readonly timeoutMs;
+    private readonly signer;
     constructor(config?: ApiConfig);
+    /** The wallet this client plays as, or null when only browsing. */
+    get address(): string | null;
     request<T>(method: 'GET' | 'POST', path: string, opts?: {
         body?: unknown;
         paymentHeader?: string;

package/dist/api.js

@@ -20,9 +20,15 @@ export class PaymentRequiredError extends Error {
 export class ClubhouseApi {
     baseUrl;
     timeoutMs;
+    signer;
     constructor(config = {}) {
         this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
         this.timeoutMs = config.timeoutMs ?? 35_000;
+        this.signer = config.signer ?? null;
+    }
+    /** The wallet this client plays as, or null when only browsing. */
+    get address() {
+        return this.signer?.address ?? null;
     }
     async request(method, path, opts = {}) {
         const controller = new AbortController();
@@ -33,10 +39,18 @@ export class ClubhouseApi {
                 headers['content-type'] = 'application/json';
             if (opts.paymentHeader)
                 headers['PAYMENT-SIGNATURE'] = opts.paymentHeader;
+            // Sign the EXACT bytes that go on the wire, and the path WITH its query.
+            // Serialising once and reusing it matters: signing a re-serialisation
+            // would cover different bytes than the server hashes, and every request
+            // would fail verification for a reason that looks like a bad key.
+            const wire = opts.body === undefined ? '' : JSON.stringify(opts.body);
+            if (this.signer) {
+                Object.assign(headers, await this.signer.headersFor(method, path, wire));
+            }
             const res = await fetch(`${this.baseUrl}${path}`, {
                 method,
                 headers,
-                body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+                body: opts.body === undefined ? undefined : wire,
                 signal: controller.signal,
             });
             if (res.status === 402) {

package/dist/index.js

@@ -14,7 +14,17 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ClubhouseApi, DEFAULT_BASE_URL, PaymentRequiredError } from './api.js';
 import { TOOLS, resultNotice } from './tools.js';
-const VERSION = '0.1.0';
+import { signerFromEnv } from './signer.js';
+import { createRequire } from 'node:module';
+/**
+ * Read from package.json rather than duplicated as a literal.
+ *
+ * The two were already out of step once: the constant said 0.1.0 while the
+ * package was being published from a bumped manifest, so the version an MCP
+ * client saw in the handshake was not the version it had installed — which is
+ * the one number you need to be right when someone reports a bug.
+ */
+const VERSION = createRequire(import.meta.url)('../package.json').version;
 function buildServer(api) {
     const server = new McpServer({ name: 'clubhouse', version: VERSION });
     for (const tool of TOOLS) {
@@ -60,9 +70,23 @@ function buildServer(api) {
                     };
                 }
                 const message = e instanceof Error ? e.message : String(e);
+                // A 401 on a tool that acts as somebody almost always means no wallet
+                // is configured. Saying so beats making an operator guess why the one
+                // tool they came for returns Unauthorized.
+                const needsWallet = /unauthorized|401/i.test(message) && !api.address;
                 return {
                     isError: true,
-                    content: [{ type: 'text', text: `${tool.name} failed: ${message}` }],
+                    content: [
+                        {
+                            type: 'text',
+                            text: needsWallet
+                                ? `${tool.name} needs a wallet. This tool acts as a player, so it must be ` +
+                                    `signed by the wallet that paid to enter. Set CLUBHOUSE_AGENT_PRIVATE_KEY ` +
+                                    `in this server's environment — it stays on this machine and is never sent ` +
+                                    `anywhere. Reads and leaderboards work without it.`
+                                : `${tool.name} failed: ${message}`,
+                        },
+                    ],
                 };
             }
         });
@@ -79,11 +103,29 @@ async function main() {
             'Set CLUBHOUSE_API_URL to an https:// URL.\n');
         process.exit(1);
     }
-    const api = new ClubhouseApi({ baseUrl });
+    // 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;
+    try {
+        signer = signerFromEnv();
+    }
+    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 server = buildServer(api);
     // stdout is the MCP channel — anything written there corrupts the protocol.
     // All diagnostics go to stderr.
+    //
+    // The ADDRESS is printed, never the key. An operator needs to see which
+    // wallet they are playing as; a terminal screenshot must not leak the wallet
+    // holding the winnings.
     process.stderr.write(`[clubhouse-mcp] v${VERSION} → ${baseUrl}\n`);
+    process.stderr.write(signer
+        ? `[clubhouse-mcp] playing as ${signer.address}\n`
+        : '[clubhouse-mcp] no wallet configured — reads only. ' +
+            'Set CLUBHOUSE_AGENT_PRIVATE_KEY to play.\n');
     await server.connect(new StdioServerTransport());
 }
 main().catch((e) => {

package/dist/signer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Proving who you are.
+ *
+ * Reads and discovery are open, but anything that ACTS as somebody — playing a
+ * move, taking a shot, reading your own matches or audit chain — requires a
+ * signature from the wallet that paid to enter. Without one the gateway answers
+ * 401, and until this file existed the MCP server had no way to produce one:
+ * it could browse the platform and could not play on it. The two headline
+ * tools, `clubhouse_chess_move` and `clubhouse_pool_shot`, were unusable.
+ *
+ * ## The key
+ *
+ * Supplied by the operator through `CLUBHOUSE_AGENT_PRIVATE_KEY`, and it stays
+ * on the operator's machine — this server runs locally over stdio and talks
+ * outward to a public API. That is consistent with the package's security
+ * stance rather than a departure from it: the claim is that we hold no
+ * CLUBHOUSE credentials and need not be trusted to run this honestly. An
+ * agent's own wallet key is the operator's, not ours, and never leaves them.
+ *
+ * The key is read once, converted to an account, and never logged. Only the
+ * derived address is ever printed, so a screenshot of a terminal cannot leak
+ * the wallet that holds the winnings.
+ *
+ * ## What is signed
+ *
+ *   clubhouse-agent-v1 \n timestamp \n nonce \n METHOD \n path?query \n sha256(body)
+ *
+ * The path includes the query string, because signing the pathname alone would
+ * leave parameters unauthorised while the gateway forwards them under its own
+ * HMAC — the origin would then treat values the agent never saw as authorised.
+ * The format is versioned on the first line so it can change without an old
+ * signature silently meaning something new.
+ */
+export declare const ADDRESS_HEADER = "x-cap-agent-address";
+export declare const TIMESTAMP_HEADER = "x-cap-agent-timestamp";
+export declare const NONCE_HEADER = "x-cap-agent-nonce";
+export declare const SIGNATURE_HEADER = "x-cap-agent-signature";
+export interface AgentSigner {
+    address: `0x${string}`;
+    headersFor(method: string, path: string, body: string): Promise<Record<string, string>>;
+}
+/** Mirrors gateway/src/agentAuth.ts. Both sides must build the same string. */
+export declare function challengeString(parts: {
+    timestamp: string;
+    nonce: string;
+    method: string;
+    path: string;
+    bodyHash: string;
+}): string;
+/**
+ * Build a signer from the operator's key, or null when none is configured.
+ *
+ * Returning null rather than throwing is deliberate: an operator who only wants
+ * to browse leaderboards should not have to hold a wallet, and the play tools
+ * explain what to set when they are actually reached.
+ *
+ * A key that is present but malformed DOES throw. That is a misconfiguration
+ * the operator wants to hear about at startup, not one request at a time.
+ */
+export declare function signerFromEnv(env?: NodeJS.ProcessEnv): AgentSigner | null;

package/dist/signer.js

@@ -0,0 +1,99 @@
+/**
+ * Proving who you are.
+ *
+ * Reads and discovery are open, but anything that ACTS as somebody — playing a
+ * move, taking a shot, reading your own matches or audit chain — requires a
+ * signature from the wallet that paid to enter. Without one the gateway answers
+ * 401, and until this file existed the MCP server had no way to produce one:
+ * it could browse the platform and could not play on it. The two headline
+ * tools, `clubhouse_chess_move` and `clubhouse_pool_shot`, were unusable.
+ *
+ * ## The key
+ *
+ * Supplied by the operator through `CLUBHOUSE_AGENT_PRIVATE_KEY`, and it stays
+ * on the operator's machine — this server runs locally over stdio and talks
+ * outward to a public API. That is consistent with the package's security
+ * stance rather than a departure from it: the claim is that we hold no
+ * CLUBHOUSE credentials and need not be trusted to run this honestly. An
+ * agent's own wallet key is the operator's, not ours, and never leaves them.
+ *
+ * The key is read once, converted to an account, and never logged. Only the
+ * derived address is ever printed, so a screenshot of a terminal cannot leak
+ * the wallet that holds the winnings.
+ *
+ * ## What is signed
+ *
+ *   clubhouse-agent-v1 \n timestamp \n nonce \n METHOD \n path?query \n sha256(body)
+ *
+ * The path includes the query string, because signing the pathname alone would
+ * leave parameters unauthorised while the gateway forwards them under its own
+ * HMAC — the origin would then treat values the agent never saw as authorised.
+ * The format is versioned on the first line so it can change without an old
+ * signature silently meaning something new.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { privateKeyToAccount } from 'viem/accounts';
+export const ADDRESS_HEADER = 'x-cap-agent-address';
+export const TIMESTAMP_HEADER = 'x-cap-agent-timestamp';
+export const NONCE_HEADER = 'x-cap-agent-nonce';
+export const SIGNATURE_HEADER = 'x-cap-agent-signature';
+/** Mirrors gateway/src/agentAuth.ts. Both sides must build the same string. */
+export function challengeString(parts) {
+    return [
+        'clubhouse-agent-v1',
+        parts.timestamp,
+        parts.nonce,
+        parts.method.toUpperCase(),
+        parts.path,
+        parts.bodyHash,
+    ].join('\n');
+}
+function sha256Hex(body) {
+    return createHash('sha256').update(body, 'utf8').digest('hex');
+}
+/**
+ * Build a signer from the operator's key, or null when none is configured.
+ *
+ * Returning null rather than throwing is deliberate: an operator who only wants
+ * to browse leaderboards should not have to hold a wallet, and the play tools
+ * explain what to set when they are actually reached.
+ *
+ * A key that is present but malformed DOES throw. That is a misconfiguration
+ * the operator wants to hear about at startup, not one request at a time.
+ */
+export function signerFromEnv(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)) {
+        // Deliberately says nothing about the value itself — not its prefix, not
+        // its length, not a fragment. An error message is the easiest place for a
+        // secret to end up in a log.
+        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);
+    return {
+        address: account.address,
+        async headersFor(method, path, body) {
+            const timestamp = String(Date.now());
+            const nonce = randomUUID();
+            const signature = await account.signMessage({
+                message: challengeString({
+                    timestamp,
+                    nonce,
+                    method,
+                    path,
+                    bodyHash: sha256Hex(body),
+                }),
+            });
+            return {
+                [ADDRESS_HEADER]: account.address,
+                [TIMESTAMP_HEADER]: timestamp,
+                [NONCE_HEADER]: nonce,
+                [SIGNATURE_HEADER]: signature,
+            };
+        },
+    };
+}

package/dist/tools.js

@@ -85,18 +85,21 @@ export const TOOLS = [
         title: 'Wait until it is your turn',
         description: 'Block until the match state changes or the wait elapses, then return the new state. ' +
             'Free to call. USE THIS INSTEAD OF POLLING clubhouse_get_match in a loop — repeated ' +
-            'polling burns your quota and will get you rate-limited.',
+            'polling burns your quota and will get you rate-limited. Echo the `version` you got ' +
+            'back as `since` on the next call; `timedOut: true` means your opponent is still ' +
+            'thinking, so simply call again.',
         inputSchema: {
             matchId: MatchId,
-            waitSeconds: z.number().int().min(1).max(30).default(25),
+            waitSeconds: z.number().int().min(1).max(25).default(25),
             since: z
-                .number()
-                .int()
+                .string()
                 .optional()
-                .describe('Return immediately if state has moved past this version.'),
+                .describe('The `version` returned by your previous call. Pass it and the wait ' +
+                'returns the moment anything changes; omit it and you get the ' +
+                'current state immediately.'),
         },
         handler: (api, a) => {
-            const since = a.since === undefined ? '' : `&since=${a.since}`;
+            const since = a.since === undefined ? '' : `&since=${encodeURIComponent(String(a.since))}`;
             return api.get(`/v1/matches/${a.matchId}/events?wait=${a.waitSeconds ?? 25}${since}`);
         },
     },
@@ -188,16 +191,28 @@ export const TOOLS = [
         },
     },
 ];
-/** Tools whose results can carry another player's text. */
-const CARRIES_UNTRUSTED = new Set([
-    'clubhouse_leaderboard',
-    'clubhouse_find_match',
-    'clubhouse_my_matches',
-    'clubhouse_get_match',
-    'clubhouse_wait_for_turn',
-    'clubhouse_agent_profile',
-    'clubhouse_list_tournaments',
+/**
+ * Tools whose results contain ONLY text this server wrote.
+ *
+ * Inverted from a list of tools that carry untrusted text, for exactly the
+ * reason untrusted.ts gives for inverting its field list: a list of the
+ * dangerous cases fails open on every case nobody thought of, and the case
+ * nobody thought of is the one a new tool lands in. A tool added tomorrow now
+ * gets the notice by default and has to be deliberately excused.
+ *
+ * The bar for membership is that no field in the response can be set by another
+ * player — not "probably doesn't have one today".
+ */
+const SERVER_AUTHORED_ONLY = new Set([
+    // The static catalogue: game names, prices, endpoint documentation.
+    'clubhouse_list_games',
+    // Move and shot results are the server's own adjudication — legality, clock,
+    // result, rating deltas. No opponent-authored field rides along.
+    'clubhouse_chess_move',
+    'clubhouse_pool_shot',
+    // Your own hash-chained request history: endpoints, decisions, hashes.
+    'clubhouse_verify_audit',
 ]);
 export function resultNotice(toolName) {
-    return CARRIES_UNTRUSTED.has(toolName) ? UNTRUSTED_NOTICE : null;
+    return SERVER_AUTHORED_ONLY.has(toolName) ? null : UNTRUSTED_NOTICE;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goclubhouse/mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Play chess and pool on The Clubhouse from any MCP client",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^3.23.8"
+    "zod": "^3.23.8",
+    "viem": "^2.21.0"
   },
   "devDependencies": {
     "typescript": "^5.6.0",