ceaser-mcp 1.0.1 → 1.1.0

package/bin/ceaser-mcp.js

@@ -3,13 +3,25 @@
 /**
  * Ceaser MCP Server - CLI entry point.
  *
- * Starts the MCP server with stdio transport for local use with Claude Code.
+ * Starts the MCP server with stdio transport, or runs CLI subcommands directly.
  *
  * Usage:
- *   npx ceaser-mcp
- *   claude mcp add --transport stdio ceaser -- npx -y ceaser-mcp
+ *   npx ceaser-mcp                         Start MCP stdio server
+ *   npx ceaser-mcp --stdio                 Start MCP stdio server (explicit)
+ *   npx ceaser-mcp shield 0.001            Shield 0.001 ETH
+ *   npx ceaser-mcp unshield <noteId> <addr> Unshield to address
+ *   npx ceaser-mcp notes                   List unspent notes
+ *   npx ceaser-mcp import <backup>         Import note from backup
+ *   npx ceaser-mcp help                    Print usage
  */
 
 import { startStdio } from '../src/transport/stdio.js';
+import { runCli } from '../src/cli.js';
 
-startStdio();
+const subcommand = process.argv[2];
+
+if (subcommand && subcommand !== '--stdio') {
+  runCli(subcommand, process.argv.slice(3));
+} else {
+  startStdio();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ceaser-mcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "MCP server for Ceaser privacy protocol - shield and unshield ETH privately on Base L2",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -0,0 +1,287 @@
+/**
+ * CLI subcommand dispatcher for ceaser-mcp.
+ *
+ * Allows bash-only agents (e.g. OpenClaw) to shield/unshield ETH without MCP.
+ * All output is JSON: stdout on success, stderr on failure.
+ */
+
+import { parseEther, Interface } from 'ethers';
+import { randomField, toBytes32 } from './lib/crypto.js';
+import { generateShieldProof, generateBurnProof } from './lib/prover.js';
+import { addNote, listNotes, getNote, markSpent, exportNote, parseBackup } from './lib/noteStore.js';
+import { buildTreeFromIndexer } from './tools/unshield.js';
+import * as api from './lib/api.js';
+import { config } from './lib/config.js';
+import {
+  DENOMINATIONS,
+  ZKWRAPPER_ABI,
+  PROTOCOL_FEE_BPS,
+  BPS_DENOMINATOR,
+} from './constants.js';
+
+function outputSuccess(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+  process.exit(0);
+}
+
+function outputError(message) {
+  process.stderr.write(JSON.stringify({ error: message }, null, 2) + '\n');
+  process.exit(1);
+}
+
+// -- Subcommand handlers --
+
+async function handleShield(args) {
+  const amount = args[0];
+  if (!amount) {
+    outputError(`Missing amount. Usage: ceaser-mcp shield <amount>\nValid denominations: ${DENOMINATIONS.map((d) => d.value).join(', ')} ETH`);
+  }
+
+  const denom = DENOMINATIONS.find((d) => d.value === amount);
+  if (!denom) {
+    outputError(`Invalid denomination: ${amount}. Valid: ${DENOMINATIONS.map((d) => d.value).join(', ')} ETH`);
+  }
+
+  const amountWei = parseEther(amount);
+  const secret = randomField();
+  const nullifier = randomField();
+  const assetId = 0n;
+
+  const { proofHex, commitment, commitmentHex } = await generateShieldProof(
+    secret, nullifier, amountWei, assetId
+  );
+
+  const iface = new Interface(ZKWRAPPER_ABI);
+  const data = iface.encodeFunctionData('shieldETH', [
+    proofHex,
+    commitmentHex,
+    amountWei,
+  ]);
+
+  const fee = (amountWei * PROTOCOL_FEE_BPS) / BPS_DENOMINATOR;
+  const totalValue = amountWei + fee;
+
+  const note = addNote({
+    secret,
+    nullifier,
+    commitment: commitment.toString(),
+    amount,
+    amountWei: amountWei.toString(),
+    assetId: '0',
+    leafIndex: null,
+  });
+
+  const backup = exportNote(note);
+
+  outputSuccess({
+    note: {
+      id: note.id,
+      amount,
+      amountWei: amountWei.toString(),
+      commitment: commitmentHex,
+      assetId: '0',
+      leafIndex: null,
+    },
+    unsignedTx: {
+      to: config.contractAddress,
+      data,
+      value: totalValue.toString(),
+      chainId: config.chainId,
+    },
+    backup,
+    instructions: [
+      'Sign and send the unsignedTx from your wallet.',
+      'The value includes the 0.25% protocol fee.',
+      `Total to send: ${totalValue.toString()} wei (${amount} ETH + fee).`,
+      'CRITICAL: Save the backup string securely. It contains private keys for this note.',
+      'After the transaction confirms, update the leaf index with: ceaser-mcp import <backup>',
+    ],
+  });
+}
+
+async function handleUnshield(args) {
+  const [noteId, recipient] = args;
+  if (!noteId || !recipient) {
+    outputError('Missing arguments. Usage: ceaser-mcp unshield <noteId> <recipient>');
+  }
+
+  if (!/^0x[0-9a-fA-F]{40}$/.test(recipient)) {
+    outputError('Invalid recipient address. Must be 0x-prefixed 40-char hex.');
+  }
+
+  const note = getNote(noteId);
+  if (!note) {
+    outputError(`Note ${noteId} not found. Run: ceaser-mcp notes`);
+  }
+
+  if (note.spent) {
+    outputError(`Note ${noteId} has already been spent.`);
+  }
+
+  if (note.leafIndex === null || note.leafIndex === undefined) {
+    outputError('Note does not have a leaf index. The shield transaction may not have confirmed yet.');
+  }
+
+  // Rebuild Merkle tree from indexer
+  process.stderr.write('[ceaser-mcp] Building Merkle tree from indexer...\n');
+  const tree = await buildTreeFromIndexer();
+
+  if (note.leafIndex >= tree.getLeafCount()) {
+    outputError(`Note leaf index ${note.leafIndex} not found in tree (tree has ${tree.getLeafCount()} leaves). Indexer may not be fully synced.`);
+  }
+
+  const { pathElements, pathIndices } = await tree.getProof(note.leafIndex);
+  const root = tree.getRoot();
+
+  // Generate burn proof
+  process.stderr.write('[ceaser-mcp] Generating unshield proof...\n');
+  const { proofHex, nullifierHashHex, rootHex } = await generateBurnProof(
+    note, recipient, pathElements, pathIndices, root
+  );
+
+  // Fee calculation
+  const amountWei = BigInt(note.amountWei);
+  const fee = (amountWei * PROTOCOL_FEE_BPS) / BPS_DENOMINATOR;
+  const netAmount = amountWei - fee;
+
+  // Settle via facilitator
+  process.stderr.write('[ceaser-mcp] Settling via facilitator...\n');
+  const settleResult = await api.settle(
+    proofHex,
+    nullifierHashHex,
+    amountWei.toString(),
+    (note.assetId || '0').toString(),
+    recipient,
+    rootHex
+  );
+
+  markSpent(noteId, settleResult.txHash);
+
+  outputSuccess({
+    success: true,
+    txHash: settleResult.txHash,
+    recipient,
+    grossAmount: amountWei.toString(),
+    feeWei: fee.toString(),
+    netAmount: netAmount.toString(),
+    noteId,
+  });
+}
+
+function handleNotes(args) {
+  const showAll = args.includes('--all');
+  const notes = listNotes(showAll);
+
+  const safeNotes = notes.map((n) => ({
+    id: n.id,
+    amount: n.amount,
+    amountWei: n.amountWei,
+    assetId: n.assetId || '0',
+    commitment: n.commitment,
+    leafIndex: n.leafIndex,
+    spent: n.spent,
+    timestamp: n.timestamp,
+    ...(n.spent ? { spentTxHash: n.spentTxHash, spentAt: n.spentAt } : {}),
+  }));
+
+  outputSuccess({
+    count: safeNotes.length,
+    notes: safeNotes,
+  });
+}
+
+function handleImport(args) {
+  const backup = args[0];
+  if (!backup) {
+    outputError('Missing backup string. Usage: ceaser-mcp import <backup>');
+  }
+
+  const noteData = parseBackup(backup);
+
+  // Check for duplicates
+  const existing = listNotes(true);
+  const duplicate = existing.find((n) => n.commitment === noteData.commitment);
+  if (duplicate) {
+    outputError(`Note already exists with ID ${duplicate.id} (commitment: ${duplicate.commitment})`);
+  }
+
+  const note = addNote({
+    secret: noteData.secret,
+    nullifier: noteData.nullifier,
+    commitment: noteData.commitment,
+    amount: noteData.amount,
+    amountWei: noteData.amountWei,
+    assetId: noteData.assetId,
+    leafIndex: noteData.leafIndex,
+  });
+
+  outputSuccess({
+    noteId: note.id,
+    amount: noteData.amount,
+    amountWei: noteData.amountWei,
+    commitment: noteData.commitment,
+    leafIndex: noteData.leafIndex,
+    assetId: noteData.assetId,
+  });
+}
+
+function handleHelp() {
+  const usage = `ceaser-mcp - Ceaser privacy protocol CLI & MCP server
+
+USAGE:
+  ceaser-mcp                          Start MCP stdio server
+  ceaser-mcp shield <amount>          Shield ETH (generate proof + unsigned tx)
+  ceaser-mcp unshield <noteId> <addr> Unshield ETH to address (gasless via x402)
+  ceaser-mcp notes [--all]            List notes (--all includes spent)
+  ceaser-mcp import <backup>          Import note from backup string
+  ceaser-mcp help                     Show this help
+
+DENOMINATIONS:
+  ${DENOMINATIONS.map((d) => d.value).join(', ')} ETH
+
+EXAMPLES:
+  ceaser-mcp shield 0.001
+  ceaser-mcp notes
+  ceaser-mcp unshield 1737000000000-a1b2c3d4 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18
+  ceaser-mcp import eyJzIjoiMTIzLi4uIn0=
+
+ENVIRONMENT:
+  CEASER_API_URL          Facilitator URL (default: https://ceaser.org)
+  CEASER_CONTRACT_ADDRESS zkWrapper address
+  CEASER_CHAIN_ID         Chain ID (default: 8453)
+  CEASER_DATA_DIR         Data directory (default: ~/.ceaser-mcp)
+
+All CLI output is JSON (stdout=success, stderr=errors/progress).
+Notes are stored at ~/.ceaser-mcp/notes.json.
+`;
+
+  process.stdout.write(usage);
+  process.exit(0);
+}
+
+// -- Dispatcher --
+
+const COMMANDS = {
+  shield: handleShield,
+  unshield: handleUnshield,
+  notes: handleNotes,
+  import: handleImport,
+  help: handleHelp,
+  '--help': handleHelp,
+  '-h': handleHelp,
+};
+
+export async function runCli(subcommand, args) {
+  const handler = COMMANDS[subcommand];
+  if (!handler) {
+    outputError(`Unknown command: ${subcommand}. Run: ceaser-mcp help`);
+  }
+
+  try {
+    await handler(args);
+  } catch (err) {
+    // Don't leak internal details for non-API errors
+    const msg = err.message?.includes('API') ? err.message : `Command failed: ${err.message}`;
+    outputError(msg);
+  }
+}

package/src/tools/unshield.js

@@ -20,7 +20,7 @@ import { log, logError } from '../lib/log.js';
  */
 const MAX_TREE_BATCHES = 200; // 200 * 1000 = 200k leaves max
 
-async function buildTreeFromIndexer() {
+export async function buildTreeFromIndexer() {
   const tree = new MerkleTree();
   await tree.init();