@blackpool/cli 0.2.1 → 0.3.0

package/AGENTS.md

@@ -8,6 +8,7 @@ Private payments for AI agents and scripts. This file is the complete guide to u
 | Mirrors | https://raw.githubusercontent.com/blackpooldev/blackpool/main/AGENTS.md · inside the npm package at `node_modules/@blackpool/cli/AGENTS.md` |
 | Index for LLMs | https://blackpool.cash/llms.txt |
 | CLI | [`@blackpool/cli`](https://www.npmjs.com/package/@blackpool/cli) — Node.js 18+ |
+| MCP | local: `npx -y @blackpool/cli@latest mcp` · hosted read-only: `https://mcp.blackpool.cash/mcp` (§9) |
 | API | `https://api.blackpool.cash` (the CLI calls it for you) |
 | Live status | https://blackpool.cash/status |
 | Human docs | https://blackpool.cash/docs |
@@ -27,6 +28,8 @@ blackpool send 0xRECIPIENT 10 --pool usdc --chain base # private payment, relaye
 blackpool balance --chain base --pool usdc             # → {"ok":true,…,"balance":"13.965",…}
 ```
 
+Agent app with MCP support? Skip the shell entirely: see §9.
+
 Paste this into your agent's instructions:
 
 ```text
@@ -318,7 +321,83 @@ Implement it with the Node or Python wrapper above. Allow-list the first argumen
 
 ---
 
-## 9. Output contract
+## 9. MCP servers
+
+Blackpool speaks the [Model Context Protocol](https://modelcontextprotocol.io), so any MCP-capable agent app can call it as tools instead of running shell commands. There are two servers.
+
+### 9.1 Local server — payments (recommended)
+
+Runs on your machine over stdio and exposes the full CLI as tools. The wallet key stays in the local environment; tools behave exactly like the commands in §4 and return the same JSON.
+
+Add it to your app's MCP configuration (most apps use this `mcpServers` format):
+
+```json
+{
+  "mcpServers": {
+    "blackpool": {
+      "command": "npx",
+      "args": ["-y", "@blackpool/cli@latest", "mcp"],
+      "env": {
+        "BLACKPOOL_KEY": "0x<agent-wallet-private-key>",
+        "BLACKPOOL_MCP_TOOLS": "balance,send,bridges"
+      }
+    }
+  }
+}
+```
+
+With the CLI installed globally, `"command": "blackpool", "args": ["mcp"]` works too. Apps that add servers from a terminal take the same command: `npx -y @blackpool/cli@latest mcp`.
+
+| Tool | Does | Annotations |
+|---|---|---|
+| `blackpool_address` | Agent wallet address | read-only |
+| `blackpool_balance` | Private and public balances (`chain`, `pool`, `wait`) | read-only |
+| `blackpool_deposit` | Shield from the agent wallet (`amount`, `pool`, `chain`) | destructive |
+| `blackpool_send` | Private payment (`recipient`, `amount`, `pool`, `chain`) | destructive |
+| `blackpool_swap` | Private same-chain swap (`amount`, `from`, `chain`, `slippage_bps`) | destructive |
+| `blackpool_bridge` | Private bridge (`dest_asset`, `recipient`, `amount`, `from`, `wait`) | destructive |
+| `blackpool_bridges` | Bridge history and status | read-only |
+| `blackpool_assets` | Bridge destinations and origins | read-only |
+| `blackpool_recover` | Sweep stranded burners (`chain`, `to`) | idempotent |
+
+Resource: `blackpool://agents.md` (this guide).
+
+Limit what the agent can do from the configuration:
+
+| Variable | Effect |
+|---|---|
+| `BLACKPOOL_MCP_TOOLS` | Comma-separated allow-list, e.g. `balance,send,bridges` (with or without the `blackpool_` prefix). |
+| `BLACKPOOL_MCP_READONLY` | `1` exposes only read-only tools. |
+| `BLACKPOOL_HOME`, `BLACKPOOL_API` | Same as for the CLI (§3.2). |
+
+Every tool result carries the command's JSON as `structuredContent` (and as text); `isError` is `true` when `"ok": false`. The retry rules in §12 apply unchanged: never repeat `blackpool_deposit`, `blackpool_send`, `blackpool_swap` or `blackpool_bridge` after a timeout without checking `blackpool_balance` or `blackpool_bridges` first.
+
+### 9.2 Hosted server — read-only
+
+`https://mcp.blackpool.cash/mcp` (Streamable HTTP, no sign-in). It never receives keys or signatures, so it can only answer questions:
+
+| Tool | Returns |
+|---|---|
+| `blackpool_status` | API health, configured pools, relayer gas per chain |
+| `blackpool_fees` | Flat fee, rate, minimum deposit and minimum spend per pool |
+| `blackpool_assets` | Bridge destinations and origins |
+| `blackpool_bridge_quote` | Indicative quote (`from`, `to`, `amount`) |
+| `blackpool_analytics` | Shielded notes per chain and pool, relayer fees |
+| `blackpool_guide` | This guide, whole or one section (`section`) |
+
+```json
+{
+  "mcpServers": {
+    "blackpool-info": { "url": "https://mcp.blackpool.cash/mcp" }
+  }
+}
+```
+
+Use the hosted server to plan (fees, routes, quotes, status) and the local server to act.
+
+---
+
+## 10. Output contract
 
 - stdout: exactly one line of JSON when `--json` (or `BLACKPOOL_JSON=1`) is set. stderr: human progress, safe to log.
 - Envelope: `{"ok": true, "command": "<name>", …fields}` or `{"ok": false, "command": "<name>", "error": "<message>"}`.
@@ -328,7 +407,7 @@ Implement it with the Node or Python wrapper above. Allow-list the first argumen
 
 ---
 
-## 10. Errors and what to do
+## 11. Errors and what to do
 
 | `error` contains | Meaning | Do |
 |---|---|---|
@@ -348,7 +427,7 @@ Implement it with the Node or Python wrapper above. Allow-list the first argumen
 
 ---
 
-## 11. Retries, timeouts, concurrency
+## 12. Retries, timeouts, concurrency
 
 - Safe to retry any time: `address`, `balance`, `assets`, `bridges`, `recover`, `version`, `latest`.
 - **Not** safe to retry blindly: `deposit`, `send`, `swap`, `bridge`. A timeout can mean the transaction landed. Check `balance --wait` (or `bridges`) and only retry if the balance is unchanged.
@@ -358,7 +437,7 @@ Implement it with the Node or Python wrapper above. Allow-list the first argumen
 
 ---
 
-## 12. Security
+## 13. Security
 
 - **Dedicated agent wallet.** Fund it with only what the agent may spend. Never use a personal or treasury key.
 - `BLACKPOOL_KEY` never leaves the machine: it signs the sign-in message, deposit approvals and deposit transactions locally.
@@ -369,7 +448,7 @@ Implement it with the Node or Python wrapper above. Allow-list the first argumen
 
 ---
 
-## 13. Direct API (advanced)
+## 14. Direct API (advanced)
 
 The CLI is the supported interface. If you cannot run Node.js, the same operations are HTTP calls on `https://api.blackpool.cash` (`/api/balance`, `/api/deposit/prepare`, `/api/withdraw`, `/api/swap-private`, `/api/bridge/quote`, `/api/swap`, `/api/intents`, `/api/burner/*`, `/api/health`), all JSON. They need the sign-in signature (EIP-191 signature of the exact message below by the agent wallet), and deposits need you to sign and broadcast the returned transaction yourself. Endpoint list: https://blackpool.cash/docs#api
 
@@ -388,6 +467,6 @@ The message is part of the account: a different message, even by one character,
 
 ---
 
-## 14. Working on this repository
+## 15. Working on this repository
 
 If you are a coding agent editing this repository rather than using the CLI: the CLI lives in `cli/`, contracts in `contracts/`, circuits in `circuits/`, client libraries in `src/`, the web app in `frontend/`. Run `npx hardhat test` before changing contracts or core libraries. Keep the sign-in message, note format and circuit byte-identical across `src/`, `cli/` and `frontend/` (changing any of them changes every account). Never commit keys, `.env` files or credentials. Keep this file in sync with `cli/bin/blackpool.js` when commands or output fields change.

package/README.md

@@ -131,3 +131,13 @@ Docs: [docs.blackpool.cash/agents](https://docs.blackpool.cash/agents) · Site:
 ## Agents
 
 Run any command with `--json` (or `BLACKPOOL_JSON=1`) to get one JSON object on stdout and progress on stderr; exit codes are `0` ok, `1` failed, `2` usage. [`AGENTS.md`](AGENTS.md) (also at https://blackpool.cash/AGENTS.md) documents every command's fields, minimums, retry rules and security notes.
+
+## MCP
+
+`blackpool mcp` runs a Model Context Protocol server over stdio, so agent apps can call Blackpool as tools:
+
+```json
+{ "mcpServers": { "blackpool": { "command": "npx", "args": ["-y", "@blackpool/cli@latest", "mcp"], "env": { "BLACKPOOL_KEY": "0x..." } } } }
+```
+
+`BLACKPOOL_MCP_TOOLS=balance,send` limits the tools, `BLACKPOOL_MCP_READONLY=1` exposes read-only ones. A hosted read-only server (status, fees, assets, quotes, analytics, guide) runs at `https://mcp.blackpool.cash/mcp`. Details: [AGENTS.md §9](AGENTS.md).

package/bin/blackpool.js

@@ -1358,6 +1358,7 @@ ${color('Commands:', c.bold)}
                                  Run 'blackpool assets' for the destination list.
   assets                         List supported bridge destination assets.
   bridges                        List your cross-chain bridges + status (where a refund went).
+  mcp                            Run a Model Context Protocol server over stdio (agent apps).
   recover [--to <addr>] [--chain]   Sweep any stranded funds from burner wallets.
                                  --chain all sweeps every chain in one run (idempotent).
   version                        Print CLI version.
@@ -1418,6 +1419,7 @@ async function main() {
       case 'login':   await cmdLogin();          break
       case 'logout':  await cmdLogout();         break
       case 'address': await cmdAddress();        break
+      case 'mcp':     await require('./mcp.js').serve(); process.exit(0)
       case 'balance': await cmdBalance(args);    break
       case 'deposit': await cmdDeposit(args);    break
       case 'send':    await cmdSend(args);       break

package/bin/mcp.js

@@ -0,0 +1,184 @@
+'use strict'
+/**
+ * blackpool mcp — Model Context Protocol server over stdio (newline-delimited JSON-RPC 2.0).
+ *
+ * Every tool runs the CLI itself as a child process with --json, so tools behave exactly like the commands documented
+ * in AGENTS.md, and a failing command can never take the server down. The wallet key stays in this process's
+ * environment (BLACKPOOL_KEY) and is only passed to the child; nothing is written to stdout except protocol messages.
+ *
+ * Optional environment:
+ *   BLACKPOOL_MCP_TOOLS     comma-separated allow-list of tool names (default: all)
+ *   BLACKPOOL_MCP_READONLY  1 = expose read-only tools only
+ */
+const path = require('path')
+const fs = require('fs')
+const { spawn } = require('child_process')
+
+const VERSION = require('../package.json').version
+const CLI = path.join(__dirname, 'blackpool.js')
+const SUPPORTED = ['2025-06-18', '2025-03-26', '2024-11-05']
+
+const CHAIN = { type: 'string', enum: ['base', 'robinhood', 'arbitrum', 'bsc'], description: 'Chain. Default base.' }
+const POOL = { type: 'string', description: 'Pool on that chain: eth|usdc (base, arbitrum), eth|usdg (robinhood), bnb|usdc|usdt (bsc). Default: the chain\'s stablecoin pool.' }
+const AMOUNT = { type: 'string', pattern: '^[0-9]+(\\.[0-9]+)?$', description: 'Decimal amount in token units, e.g. "10" or "0.25". Never wei.' }
+
+const TOOLS = [
+  {
+    name: 'blackpool_address', title: 'Wallet address', readOnly: true,
+    description: 'Address of the agent wallet. Fund it with the asset to shield plus a little native gas for deposits.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    args: () => ['address'],
+  },
+  {
+    name: 'blackpool_balance', title: 'Balances', readOnly: true,
+    description: 'Private (shielded) and public balances. With pool: one private pool only. wait=true polls up to 30 s while a private balance reads 0 (right after a deposit).',
+    inputSchema: { type: 'object', properties: { chain: { ...CHAIN, enum: [...CHAIN.enum, 'all'], description: 'Chain, or "all". Default base.' }, pool: POOL, wait: { type: 'boolean' } }, additionalProperties: false },
+    args: (a) => ['balance', ...opt('--chain', a.chain), ...opt('--pool', a.pool), ...(a.wait ? ['--wait'] : [])],
+  },
+  {
+    name: 'blackpool_deposit', title: 'Shield (deposit)', destructive: true,
+    description: 'Shield public funds from the agent wallet into the private pool. Signs and pays gas from the agent wallet. Takes 30-90 s. Do not retry after a timeout without checking blackpool_balance.',
+    inputSchema: { type: 'object', properties: { amount: AMOUNT, pool: POOL, chain: CHAIN }, required: ['amount'], additionalProperties: false },
+    args: (a) => ['deposit', String(a.amount), ...opt('--pool', a.pool), ...opt('--chain', a.chain)],
+  },
+  {
+    name: 'blackpool_send', title: 'Private send', destructive: true,
+    description: 'Pay any EVM address privately from the private balance. The relayer pays gas; the recipient receives amount minus the fee (flat + 0.35%). Takes 30-90 s. Never retry after a timeout without checking blackpool_balance.',
+    inputSchema: { type: 'object', properties: { recipient: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$' }, amount: AMOUNT, pool: POOL, chain: CHAIN }, required: ['recipient', 'amount'], additionalProperties: false },
+    args: (a) => ['send', a.recipient, String(a.amount), ...opt('--pool', a.pool), ...opt('--chain', a.chain)],
+  },
+  {
+    name: 'blackpool_swap', title: 'Private swap', destructive: true,
+    description: 'Private same-chain swap between the native pool and the stablecoin pool; output is re-shielded. If it stops half-way, run blackpool_recover.',
+    inputSchema: { type: 'object', properties: { amount: AMOUNT, from: { type: 'string', description: 'Pool to swap from (eth|usdc on base/arbitrum, eth|usdg on robinhood, bnb|usdt on bsc).' }, chain: CHAIN, slippage_bps: { type: 'integer', minimum: 10, maximum: 500 } }, required: ['amount', 'from'], additionalProperties: false },
+    args: (a) => ['swap', String(a.amount), '--from', a.from, ...opt('--chain', a.chain), ...opt('--slippage', a.slippage_bps)],
+  },
+  {
+    name: 'blackpool_bridge', title: 'Private bridge', destructive: true,
+    description: 'Private cross-chain transfer via NEAR Intents. from = origin private pool (base_eth, base_usdc, hood_eth, hood_usdg, arb_eth, arb_usdc, bsc_bnb, bsc_usdc, bsc_usdt); dest_asset from blackpool_assets; recipient is EVM 0x… or a Solana address for sol_*. Returns once submitted unless wait=true.',
+    inputSchema: { type: 'object', properties: { dest_asset: { type: 'string' }, recipient: { type: 'string' }, amount: AMOUNT, from: { type: 'string' }, wait: { type: 'boolean', description: 'Poll delivery up to 6 minutes. Default false.' } }, required: ['dest_asset', 'recipient', 'amount', 'from'], additionalProperties: false },
+    args: (a) => ['bridge', a.dest_asset, a.recipient, String(a.amount), '--from', a.from, ...(a.wait ? [] : ['--no-wait'])],
+  },
+  {
+    name: 'blackpool_bridges', title: 'Bridge history', readOnly: true,
+    description: 'Every bridge of this account with status (PENDING_DEPOSIT, PROCESSING, SUCCESS, REFUNDED, FAILED) and refund address.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    args: () => ['bridges'],
+  },
+  {
+    name: 'blackpool_assets', title: 'Bridge assets', readOnly: true,
+    description: 'Bridge destination assets and valid origins.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    args: () => ['assets'],
+  },
+  {
+    name: 'blackpool_recover', title: 'Recover', idempotent: true,
+    description: 'Sweep every registered burner that still holds funds back to the agent wallet (or to). Safe to run any time.',
+    inputSchema: { type: 'object', properties: { chain: { ...CHAIN, enum: [...CHAIN.enum, 'all'] }, to: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$' } }, additionalProperties: false },
+    args: (a) => ['recover', ...opt('--chain', a.chain || 'all'), ...opt('--to', a.to)],
+  },
+]
+
+function opt(flag, v) { return v === undefined || v === null || v === '' ? [] : [flag, String(v)] }
+
+function enabledTools() {
+  let list = TOOLS
+  if (process.env.BLACKPOOL_MCP_READONLY === '1') list = list.filter(t => t.readOnly)
+  const allow = (process.env.BLACKPOOL_MCP_TOOLS || '').split(',').map(s => s.trim()).filter(Boolean)
+  if (allow.length) list = list.filter(t => allow.includes(t.name) || allow.includes(t.name.replace(/^blackpool_/, '')))
+  return list
+}
+
+function describe(t) {
+  return {
+    name: t.name, title: t.title, description: t.description, inputSchema: t.inputSchema,
+    annotations: { title: t.title, readOnlyHint: !!t.readOnly, destructiveHint: !!t.destructive, idempotentHint: !!(t.readOnly || t.idempotent), openWorldHint: true },
+  }
+}
+
+function runCli(args, timeoutMs) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [CLI, ...args, '--json'], { env: { ...process.env, BLACKPOOL_JSON: '1' }, stdio: ['ignore', 'pipe', 'pipe'] })
+    let out = '', err = ''
+    const timer = setTimeout(() => { child.kill('SIGTERM') }, timeoutMs)
+    child.stdout.on('data', d => { out += d })
+    child.stderr.on('data', d => { err += d; if (err.length > 20000) err = err.slice(-20000) })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      const last = out.trim().split('\n').pop() || ''
+      try { resolve({ code, json: JSON.parse(last) }) }
+      catch { resolve({ code, json: { ok: false, error: code === null ? `timed out after ${Math.round(timeoutMs / 1000)} s; check balance before retrying` : (err.trim().split('\n').pop() || 'no output') } }) }
+    })
+  })
+}
+
+function agentsDoc() {
+  try { return fs.readFileSync(path.join(__dirname, '..', 'AGENTS.md'), 'utf8') } catch { return 'See https://blackpool.cash/AGENTS.md' }
+}
+
+async function handle(msg) {
+  const { id, method, params = {} } = msg
+  switch (method) {
+    case 'initialize': {
+      const v = SUPPORTED.includes(params.protocolVersion) ? params.protocolVersion : SUPPORTED[0]
+      return {
+        protocolVersion: v,
+        capabilities: { tools: { listChanged: false }, resources: { listChanged: false } },
+        serverInfo: { name: 'blackpool', title: 'Blackpool', version: VERSION },
+        instructions: 'Private payments with zero-knowledge pools. Check blackpool_balance before paying; deposit first if the private balance is short. Never retry deposit, send, swap or bridge after a timeout without checking blackpool_balance or blackpool_bridges. blackpool_recover is always safe. Full guide: resource blackpool://agents.md.',
+      }
+    }
+    case 'ping': return {}
+    case 'tools/list': return { tools: enabledTools().map(describe) }
+    case 'tools/call': {
+      const t = enabledTools().find(x => x.name === params.name)
+      if (!t) throw rpcError(-32602, `unknown tool: ${params.name}`)
+      const a = params.arguments || {}
+      for (const r of t.inputSchema.required || []) if (a[r] === undefined || a[r] === '') return toolResult({ ok: false, error: `missing argument: ${r}` })
+      const { json } = await runCli(t.args(a), t.name === 'blackpool_bridge' && a.wait ? 450_000 : 330_000)
+      return toolResult(json)
+    }
+    case 'resources/list':
+      return { resources: [{ uri: 'blackpool://agents.md', name: 'AGENTS.md', title: 'Blackpool guide for agents', mimeType: 'text/markdown', description: 'Setup, commands, JSON fields, limits, recipes, errors and security rules.' }] }
+    case 'resources/read':
+      if (params.uri !== 'blackpool://agents.md') throw rpcError(-32002, 'resource not found')
+      return { contents: [{ uri: params.uri, mimeType: 'text/markdown', text: agentsDoc() }] }
+    case 'resources/templates/list': return { resourceTemplates: [] }
+    case 'prompts/list': return { prompts: [] }
+    default: throw rpcError(-32601, `method not found: ${method}`)
+  }
+}
+
+function toolResult(json) {
+  return { content: [{ type: 'text', text: JSON.stringify(json) }], structuredContent: json, isError: json.ok === false }
+}
+function rpcError(code, message) { return Object.assign(new Error(message), { rpc: { code, message } }) }
+
+function serve() {
+  return new Promise((resolve) => {
+    const send = (obj) => process.stdout.write(JSON.stringify(obj) + '\n')
+    let buf = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (chunk) => {
+      buf += chunk
+      let i
+      while ((i = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1)
+        if (!line) continue
+        let msg
+        try { msg = JSON.parse(line) } catch { send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } }); continue }
+        const batch = Array.isArray(msg) ? msg : [msg]
+        for (const m of batch) {
+          if (m.id === undefined || m.id === null) continue // notification (initialized, cancelled, …)
+          handle(m).then(
+            (result) => send({ jsonrpc: '2.0', id: m.id, result }),
+            (e) => send({ jsonrpc: '2.0', id: m.id, error: e.rpc || { code: -32603, message: String(e.message || e) } }),
+          )
+        }
+      }
+    })
+    process.stdin.on('end', resolve)
+  })
+}
+
+module.exports = { serve, TOOLS }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackpool/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Private payments for onchain agents. CLI for BLACKPOOL - shield, send, swap, bridge with zero-knowledge privacy on Base, Robinhood Chain, Arbitrum, and BNB Smart Chain.",
   "bin": {
     "blackpool": "bin/blackpool.js"
@@ -18,6 +18,8 @@
     "ethers": "^5.7.2"
   },
   "keywords": [
+    "mcp",
+    "model-context-protocol",
     "agents",
     "arbitrum",
     "base",