@powforge/captcha-mcp 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# @powforge/captcha-mcp
+
+**Charge AI agents per-call without accounts.** PoW solve = free tier. Lightning payment = paid tier.
+
+OpenAI's Sora API does not let you charge per call. Anthropic's billing does not pass through to your tools. If you ship an MCP server today and an autonomous agent finds it, you eat the bill.
+
+This is the gate. Three tools over stdio. Stdlib only.
+
+## Quickstart
+
+```bash
+npx -y @powforge/captcha-mcp
+```
+
+That is it. No install, no config, no API key. The server starts on stdio and waits for an MCP client.
+
+To wire it into Claude Code, Cursor, or any MCP-compatible host, add to your config:
+
+```json
+{
+  "mcpServers": {
+    "powforge-captcha": {
+      "command": "npx",
+      "args": ["-y", "@powforge/captcha-mcp"]
+    }
+  }
+}
+```
+
+Or run `npx @powforge/captcha-mcp --install` to print the config block.
+
+## What it does
+
+Wraps the PowForge pow-captcha service ([captcha.powforge.dev](https://captcha.powforge.dev)) as three MCP tools:
+
+| Tool        | Purpose                                                                 |
+|-------------|-------------------------------------------------------------------------|
+| `challenge` | Request a fresh proof-of-work puzzle. Returns `{id, salt, difficulty, signature}`. |
+| `verify`    | Submit a solved nonce. Returns a 5-minute HMAC-signed access token.     |
+| `status`    | Server health, lifetime stats, L402 endpoint metadata.                  |
+
+The free tier costs the agent ~5-10 seconds of CPU time (SHA-256, default 14 leading zero bits). The paid tier costs 3 sats over Lightning via L402 (RFC 7235 + bolt11 invoice in `WWW-Authenticate`).
+
+## Why this and not OAuth, API keys, or Stripe
+
+| Approach          | Per-call cost | Account required | Agent-friendly |
+|-------------------|---------------|------------------|-----------------|
+| API keys          | $0            | yes              | no              |
+| OAuth             | $0            | yes              | no              |
+| Stripe metering   | high overhead | yes              | no              |
+| **PoW + L402**    | seconds or 3 sats | **no**       | **yes**         |
+
+Agents do not have email addresses. They do not click confirmation links. They do not enter credit cards. PoW + Lightning is the only auth primitive that works for fully autonomous callers.
+
+## Configuration
+
+Set `CAPTCHA_URL` to point at a different captcha backend. Default is `http://localhost:3077` so you can run the full stack locally for development. Production deployments point it at `https://captcha.powforge.dev`.
+
+```bash
+CAPTCHA_URL=https://captcha.powforge.dev npx @powforge/captcha-mcp
+```
+
+## Local development
+
+Clone the [captcha widget repo](https://www.npmjs.com/package/@powforge/captcha) or run the public service. The MCP server only needs HTTP access to the captcha endpoints listed under `status`.
+
+```bash
+git clone https://github.com/zekebuilds-lab/captcha-mcp
+cd captcha-mcp
+node src/server.js
+```
+
+It prints `ready` to stderr and waits for JSON-RPC on stdin.
+
+Smoke-test the protocol manually:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}' | node src/server.js
+```
+
+You should see a JSON response with `serverInfo: { name: "@powforge/captcha-mcp", version: "0.1.0" }`.
+
+## Token verification from your own backend
+
+When an agent submits a token to your service, verify it without trusting the agent:
+
+```bash
+curl -X POST https://captcha.powforge.dev/api/token/verify \
+  -H "Content-Type: application/json" \
+  -d '{"token":"<token-from-verify-tool>"}'
+```
+
+Returns `{valid: true, method, issued_at, expires_at}` or `{valid: false, reason}`.
+
+## Related packages
+
+- [`@powforge/captcha`](https://www.npmjs.com/package/@powforge/captcha) — the browser widget for the same service.
+- [`@powforge/mcp-l402-gate`](https://www.npmjs.com/package/@powforge/mcp-l402-gate) — Express middleware to gate any MCP server with L402 + Depth-of-Identity scoring.
+- [`@powforge/mcp-identity`](https://www.npmjs.com/package/@powforge/mcp-identity) — agent reputation oracle. Pair with this gate for first-call abuse protection.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@powforge/captcha-mcp",
+  "version": "0.1.0",
+  "description": "MCP server that turns PowForge pow-captcha into agent auth. Charge AI agents per-call without accounts: PoW solve = free tier, Lightning payment = paid tier. Three tools: challenge, verify, status. Stdio transport, stdlib only — no MCP SDK dependency.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agent-auth",
+    "captcha",
+    "proof-of-work",
+    "lightning",
+    "l402",
+    "rate-limiting",
+    "anti-bot",
+    "powforge"
+  ],
+  "main": "src/index.js",
+  "bin": {
+    "captcha-mcp": "src/server.js"
+  },
+  "scripts": {
+    "test": "node --test tests/server.test.js",
+    "start": "node src/server.js"
+  },
+  "license": "MIT",
+  "author": "PowForge",
+  "homepage": "https://powforge.dev/captcha",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zekebuilds-lab/captcha-mcp"
+  },
+  "bugs": {
+    "url": "https://powforge.dev"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.js

@@ -0,0 +1,242 @@
+/**
+ * @powforge/captcha-mcp — MCP server module
+ *
+ * Wraps the PowForge pow-captcha HTTP service as three MCP tools:
+ *   - challenge() → request a fresh PoW challenge
+ *   - verify({salt, nonce, signature, id, algo, difficulty}) → verify a solution, return token
+ *   - status() → server health + current config
+ *
+ * Free tier: solve the PoW (SHA-256, ~14 leading zero bits, ~5-10s in browser JS).
+ * Paid tier: skip the PoW via L402 Lightning payment (3 sats, RFC 7235 + LN).
+ *
+ * Tools are exported as plain async functions so they can be tested without
+ * spinning up the stdio transport.
+ */
+
+'use strict';
+
+const DEFAULT_CAPTCHA_URL = 'http://localhost:3077';
+
+/**
+ * Resolve the base URL of the pow-captcha HTTP service. Override via
+ * CAPTCHA_URL env var. Defaults to the canonical local-dev port (3077).
+ * In production, point this at https://captcha.powforge.dev.
+ */
+function captchaUrl() {
+  const raw = process.env.CAPTCHA_URL || DEFAULT_CAPTCHA_URL;
+  return raw.replace(/\/+$/, '');
+}
+
+/**
+ * Tool: challenge
+ *
+ * Input shape: {} (no arguments)
+ *
+ * Output shape:
+ *   {
+ *     id: string,            // unique challenge id (signed by server)
+ *     salt: string,          // hex salt for the PoW
+ *     difficulty: number,    // leading zero bits required (e.g. 14)
+ *     algo: 'sha256',        // hash algorithm
+ *     signature: string,     // server-issued HMAC binding the challenge to the id
+ *     instructions: string   // how to solve and return the nonce
+ *   }
+ *
+ * Output shape on error:
+ *   { error: string, hint?: string }
+ */
+async function challenge(_input, opts = {}) {
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (!fetchImpl) {
+    return { error: 'fetch_unavailable', hint: 'Node 18+ required, or pass fetchImpl in opts.' };
+  }
+  try {
+    const r = await fetchImpl(`${captchaUrl()}/api/challenge`, { method: 'GET' });
+    if (!r.ok) return { error: 'challenge_http_error', status: r.status };
+    const ch = await r.json();
+    return {
+      id: ch.id,
+      salt: ch.salt,
+      difficulty: ch.difficulty,
+      algo: ch.algo || 'sha256',
+      signature: ch.signature,
+      instructions:
+        'Find a nonce string such that ' +
+        'SHA-256(salt + nonce) has at least `difficulty` leading zero bits. ' +
+        'Then call the verify tool with {salt, nonce, id, signature, algo, difficulty}. ' +
+        'Returns a 5-min HMAC token your server can accept as proof-of-human or proof-of-agent. ' +
+        'Or skip the PoW by paying the L402 invoice at POST ' + captchaUrl() + '/l402/skip.',
+    };
+  } catch (e) {
+    return { error: 'challenge_request_failed', hint: e.message };
+  }
+}
+
+/**
+ * Tool: verify
+ *
+ * Input shape:
+ *   {
+ *     salt: string,
+ *     nonce: string,         // string-encoded nonce that solves the PoW
+ *     id: string,            // challenge id from the challenge tool
+ *     signature: string,     // signature from the challenge tool
+ *     algo?: 'sha256',
+ *     difficulty?: number    // defaults to challenge difficulty
+ *   }
+ *
+ * Output shape on success:
+ *   { valid: true, token: string, method: 'pow' | 'sha256', expires_in_sec: 300 }
+ *
+ * Output shape on failure:
+ *   { valid: false, reason: string }
+ */
+async function verify(input, opts = {}) {
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (!fetchImpl) {
+    return { error: 'fetch_unavailable', hint: 'Node 18+ required, or pass fetchImpl in opts.' };
+  }
+  if (!input || typeof input !== 'object') return { error: 'input_required' };
+  const { salt, nonce, id, signature, algo, difficulty } = input;
+  if (!salt || typeof salt !== 'string') return { error: 'salt_required' };
+  if (typeof nonce === 'undefined' || nonce === null) return { error: 'nonce_required' };
+  if (!id || typeof id !== 'string') return { error: 'id_required' };
+  if (!signature || typeof signature !== 'string') return { error: 'signature_required' };
+
+  const body = {
+    salt,
+    nonce: String(nonce),
+    id,
+    signature,
+    algo: algo || 'sha256',
+    difficulty: typeof difficulty === 'number' ? difficulty : undefined,
+  };
+
+  try {
+    const r = await fetchImpl(`${captchaUrl()}/api/verify`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    const result = await r.json();
+    if (result.valid) {
+      return {
+        valid: true,
+        token: result.token,
+        method: result.method || 'pow',
+        expires_in_sec: 300,
+        verify_endpoint: `${captchaUrl()}/api/token/verify`,
+        hint: 'POST {token} to verify_endpoint to confirm validity from your own backend.',
+      };
+    }
+    return { valid: false, reason: result.reason || 'verification_failed' };
+  } catch (e) {
+    return { error: 'verify_request_failed', hint: e.message };
+  }
+}
+
+/**
+ * Tool: status
+ *
+ * Input shape: {} (no arguments)
+ *
+ * Output shape:
+ *   {
+ *     ok: true,
+ *     captcha_url: string,
+ *     stats: { pow_solves: number, ln_skips: number, challenges_issued: number },
+ *     l402: { scope: string, price_sats: number, endpoint: string }
+ *   }
+ *
+ * Output shape on failure:
+ *   { ok: false, error: string }
+ */
+async function status(_input, opts = {}) {
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (!fetchImpl) {
+    return { ok: false, error: 'fetch_unavailable', hint: 'Node 18+ required, or pass fetchImpl in opts.' };
+  }
+  const url = captchaUrl();
+  try {
+    const [statsR, l402R] = await Promise.all([
+      fetchImpl(`${url}/api/stats`).then((r) => (r.ok ? r.json() : null)).catch(() => null),
+      fetchImpl(`${url}/l402/info`).then((r) => (r.ok ? r.json() : null)).catch(() => null),
+    ]);
+    if (!statsR) return { ok: false, error: 'captcha_unreachable', captcha_url: url };
+
+    const ep = (l402R && l402R.endpoints && l402R.endpoints[0]) || null;
+    return {
+      ok: true,
+      captcha_url: url,
+      stats: statsR,
+      l402: ep
+        ? {
+            scope: ep.scope,
+            price_sats: ep.price_sats,
+            endpoint: `${url}${ep.path}`,
+            note: 'POST with no auth to receive a 402 + macaroon + bolt11 invoice. Pay, then re-POST with Authorization: L402 <macaroon>:<preimage_hex>.',
+          }
+        : null,
+    };
+  } catch (e) {
+    return { ok: false, error: 'status_request_failed', hint: e.message, captcha_url: url };
+  }
+}
+
+/**
+ * Tool registry for the MCP server. Each entry is { name, description,
+ * inputSchema, handler } so the stdio server can advertise them via
+ * tools/list and route tools/call.
+ */
+const TOOLS = [
+  {
+    name: 'challenge',
+    description:
+      'Request a fresh PoW challenge from the PowForge captcha service. Returns {id, salt, difficulty, signature, instructions}. The agent must find a nonce such that SHA-256(salt + nonce) has at least `difficulty` leading zero bits, then call the verify tool. Free tier — no payment required.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+    handler: challenge,
+  },
+  {
+    name: 'verify',
+    description:
+      'Verify a PoW solution. Input: {salt, nonce, id, signature, algo?, difficulty?} from a prior challenge call plus the nonce the agent computed. Returns a 5-minute HMAC-signed token on success, or {valid: false, reason} on failure. Tokens can be re-verified server-side via POST /api/token/verify.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        salt: { type: 'string', description: 'Hex salt from the challenge response' },
+        nonce: { type: 'string', description: 'Nonce string the agent computed' },
+        id: { type: 'string', description: 'Challenge id from the challenge response' },
+        signature: { type: 'string', description: 'HMAC signature from the challenge response' },
+        algo: { type: 'string', description: "Hash algorithm. Default: 'sha256'" },
+        difficulty: { type: 'number', description: 'Leading zero bits required. Default: matches challenge.' },
+      },
+      required: ['salt', 'nonce', 'id', 'signature'],
+      additionalProperties: false,
+    },
+    handler: verify,
+  },
+  {
+    name: 'status',
+    description:
+      'Return PowForge captcha server health, lifetime stats (pow_solves, ln_skips, challenges_issued), and L402 endpoint metadata (scope, price_sats, paid endpoint URL). Use this to discover the Lightning skip price before paying, or as a liveness check.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+    handler: status,
+  },
+];
+
+module.exports = {
+  TOOLS,
+  challenge,
+  verify,
+  status,
+  captchaUrl,
+  DEFAULT_CAPTCHA_URL,
+};

package/src/server.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * @powforge/captcha-mcp — MCP stdio server entrypoint.
+ *
+ * This is the npx-installable binary. Implements the Model Context Protocol
+ * over stdio using line-delimited JSON-RPC 2.0. No SDK dependency — Node 18+
+ * stdlib only.
+ *
+ * Designed to be referenced from a Claude Code / Cursor / Continue MCP config:
+ *
+ *     {
+ *       "mcpServers": {
+ *         "powforge-captcha": {
+ *           "command": "npx",
+ *           "args": ["-y", "@powforge/captcha-mcp"]
+ *         }
+ *       }
+ *     }
+ *
+ * Optional environment variables:
+ *   CAPTCHA_URL   override the captcha base URL (default: http://localhost:3077)
+ *
+ * Why stdlib only:
+ *   - Smaller install footprint (`npx -y` is faster).
+ *   - No transitive deps to audit.
+ *   - The MCP protocol is simple line-delimited JSON-RPC 2.0; the SDK is
+ *     ~200 lines of glue we can replicate in <100 lines here.
+ */
+
+'use strict';
+
+const { TOOLS } = require('./index.js');
+
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_INFO = {
+  name: '@powforge/captcha-mcp',
+  version: '0.1.0',
+};
+
+// --install: print a ready-to-paste MCP config block. We don't write to the
+// user's config — config paths vary across editors and that's their decision.
+if (process.argv.includes('--install') || process.argv.includes('-i')) {
+  const block = {
+    mcpServers: {
+      'powforge-captcha': {
+        command: 'npx',
+        args: ['-y', '@powforge/captcha-mcp'],
+      },
+    },
+  };
+  // eslint-disable-next-line no-console
+  console.log('Add this block to your MCP config (e.g. ~/.config/Claude/claude_desktop_config.json):\n');
+  // eslint-disable-next-line no-console
+  console.log(JSON.stringify(block, null, 2));
+  // eslint-disable-next-line no-console
+  console.log('\nThen restart your MCP client. The three tools (challenge, verify, status) will appear automatically.');
+  process.exit(0);
+}
+
+// --version: print version and exit. Useful for CI smoke tests.
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+  // eslint-disable-next-line no-console
+  console.log(SERVER_INFO.version);
+  process.exit(0);
+}
+
+/**
+ * Send a JSON-RPC response on stdout. Stdout MUST stay strictly JSON-RPC —
+ * any stray writes to stdout will corrupt the framing. Diagnostics go to
+ * stderr.
+ */
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + '\n');
+}
+
+function makeError(id, code, message, data) {
+  const err = { code, message };
+  if (data !== undefined) err.data = data;
+  return { jsonrpc: '2.0', id, error: err };
+}
+
+function makeResult(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+/**
+ * Handle one incoming JSON-RPC request and return a response (or null for
+ * notifications). Methods implemented:
+ *   - initialize
+ *   - notifications/initialized  (notification, no response)
+ *   - tools/list
+ *   - tools/call
+ *   - ping
+ */
+async function handle(req) {
+  const id = req.id;
+  const method = req.method;
+  const params = req.params || {};
+
+  if (method === 'initialize') {
+    return makeResult(id, {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {
+        tools: {},
+      },
+      serverInfo: SERVER_INFO,
+    });
+  }
+
+  if (method === 'notifications/initialized' || method === 'initialized') {
+    // Notifications have no id and expect no response.
+    return null;
+  }
+
+  if (method === 'ping') {
+    return makeResult(id, {});
+  }
+
+  if (method === 'tools/list') {
+    return makeResult(id, {
+      tools: TOOLS.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+      })),
+    });
+  }
+
+  if (method === 'tools/call') {
+    const name = params.name;
+    const args = params.arguments || {};
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool) {
+      return makeResult(id, {
+        content: [{ type: 'text', text: JSON.stringify({ error: 'unknown_tool', tool: name }) }],
+        isError: true,
+      });
+    }
+    try {
+      const result = await tool.handler(args);
+      return makeResult(id, {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      });
+    } catch (e) {
+      return makeResult(id, {
+        content: [{ type: 'text', text: JSON.stringify({ error: 'tool_threw', message: e.message }) }],
+        isError: true,
+      });
+    }
+  }
+
+  // Unknown method.
+  return makeError(id, -32601, `Method not found: ${method}`);
+}
+
+/**
+ * Read stdin line-by-line. Each line is a complete JSON-RPC message. Per the
+ * MCP stdio spec, embedded newlines are not allowed inside a message.
+ */
+function startStdioLoop() {
+  let buf = '';
+  let inFlight = 0;
+  let stdinEnded = false;
+
+  process.stdin.setEncoding('utf8');
+
+  async function processRequest(req) {
+    inFlight++;
+    try {
+      const resp = await handle(req);
+      if (resp !== null) send(resp);
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      process.stderr.write(`@powforge/captcha-mcp: handler error: ${e.message}\n`);
+      if (req && typeof req.id !== 'undefined') {
+        send(makeError(req.id, -32603, `Internal error: ${e.message}`));
+      }
+    } finally {
+      inFlight--;
+      if (stdinEnded && inFlight === 0) process.exit(0);
+    }
+  }
+
+  process.stdin.on('data', (chunk) => {
+    buf += chunk;
+    let idx;
+    while ((idx = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, idx).trim();
+      buf = buf.slice(idx + 1);
+      if (!line) continue;
+
+      let req;
+      try {
+        req = JSON.parse(line);
+      } catch (e) {
+        // eslint-disable-next-line no-console
+        process.stderr.write(`@powforge/captcha-mcp: malformed JSON-RPC line: ${e.message}\n`);
+        continue;
+      }
+
+      // Fire-and-track. processRequest decrements inFlight when done.
+      processRequest(req);
+    }
+  });
+
+  process.stdin.on('end', () => {
+    // Client closed the pipe. Wait for in-flight handlers to finish before
+    // exiting so async tool calls (HTTP fetches) can return their responses.
+    stdinEnded = true;
+    if (inFlight === 0) process.exit(0);
+  });
+
+  // Diagnostic banner on stderr only. Stdout is reserved for JSON-RPC.
+  process.stderr.write(
+    `@powforge/captcha-mcp ${SERVER_INFO.version} ready. ` +
+      `CAPTCHA_URL=${process.env.CAPTCHA_URL || 'http://localhost:3077'}\n`
+  );
+}
+
+startStdioLoop();