@shroud-fi/mcp-server 0.1.1 → 0.1.3

package/src/http.ts

@@ -0,0 +1,217 @@
+/**
+ * HTTP transport for the MCP server.
+ *
+ * Uses node:http to stay zero-dep. Exposes three endpoints:
+ *   POST /auth/challenge   → mint EIP-191 challenge
+ *   POST /mcp              → JSON-RPC framed MCP body (auth-gated)
+ *   GET  /healthz          → public liveness ping
+ *
+ * Auth rules:
+ *   - /auth/challenge      public (clients need a way to get a challenge)
+ *   - /mcp                 requires X-Shroudfi-Wallet + X-Shroudfi-Nonce +
+ *                          X-Shroudfi-Signature headers. Signature is verified,
+ *                          consumed (single-use), allow-list checked.
+ *   - /healthz             public
+ *
+ * Privacy invariants:
+ *   - Signatures never logged or echoed.
+ *   - Errors are short tag strings; no body bytes, no key bytes.
+ *   - Allow-list is enforced when SHROUDFI_MCP_HTTP_ALLOWED_WALLETS is set;
+ *     when empty, ANY EIP-191 wallet may authenticate. Operators MUST set
+ *     the allow-list in production.
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import type { Hex } from 'viem';
+import { isHex } from 'viem';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { ALL_TOOLS, findTool } from './tools/index.js';
+import { createAuthCache, type AuthCache } from './auth.js';
+import { buildContextFromConfig, loadBootstrapConfigFromEnv } from './config.js';
+import type { McpServerBootstrapConfig, McpServerContext } from './types.js';
+import { McpInvalidArgsError, McpServerError, McpUnauthorizedError } from './errors.js';
+
+const HEADER_WALLET = 'x-shroudfi-wallet';
+const HEADER_NONCE = 'x-shroudfi-nonce';
+const HEADER_SIGNATURE = 'x-shroudfi-signature';
+
+const JSON_HEADERS = { 'content-type': 'application/json' } as const;
+
+interface RunHttpServerOptions {
+  readonly port: number;
+  readonly bootstrap?: McpServerBootstrapConfig;
+}
+
+async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(chunk as Buffer);
+    if (Buffer.concat(chunks).length > 1_048_576) {
+      throw new McpInvalidArgsError();
+    }
+  }
+  const raw = Buffer.concat(chunks).toString('utf-8');
+  if (raw.length === 0) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new McpInvalidArgsError();
+  }
+}
+
+function send(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, JSON_HEADERS);
+  res.end(JSON.stringify(body));
+}
+
+async function authenticate(
+  req: IncomingMessage,
+  authCache: AuthCache,
+  allowList: ReadonlySet<`0x${string}`>,
+): Promise<`0x${string}`> {
+  const wallet = req.headers[HEADER_WALLET];
+  const nonce = req.headers[HEADER_NONCE];
+  const sig = req.headers[HEADER_SIGNATURE];
+  if (
+    typeof wallet !== 'string' ||
+    typeof nonce !== 'string' ||
+    typeof sig !== 'string'
+  ) {
+    throw new McpUnauthorizedError();
+  }
+  if (!isHex(wallet) || wallet.length !== 42) throw new McpUnauthorizedError();
+  if (!isHex(nonce)) throw new McpUnauthorizedError();
+  if (!isHex(sig)) throw new McpUnauthorizedError();
+  const walletLc = wallet.toLowerCase() as `0x${string}`;
+  if (allowList.size > 0 && !allowList.has(walletLc)) {
+    throw new McpUnauthorizedError();
+  }
+  await authCache.verifyAndConsume({
+    wallet: walletLc,
+    nonce: nonce as Hex,
+    signature: sig as Hex,
+  });
+  return walletLc;
+}
+
+/**
+ * Direct JSON-RPC-ish dispatch — we expose the same RPC envelope MCP uses but
+ * over a synchronous request/response cycle (no SSE in v1). Clients send:
+ *   { method: 'tools/list', params: {} }
+ *   { method: 'tools/call', params: { name, arguments } }
+ */
+async function dispatch(
+  ctx: McpServerContext,
+  body: unknown,
+): Promise<unknown> {
+  if (
+    typeof body !== 'object' ||
+    body === null ||
+    !('method' in body) ||
+    typeof (body as { method: unknown }).method !== 'string'
+  ) {
+    throw new McpInvalidArgsError();
+  }
+  const method = (body as { method: string }).method;
+  const params = ((body as { params?: unknown }).params ?? {}) as unknown;
+
+  if (method === 'tools/list') {
+    ListToolsRequestSchema.parse({ method, params });
+    return {
+      tools: ALL_TOOLS.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+      })),
+    };
+  }
+  if (method === 'tools/call') {
+    const parsed = CallToolRequestSchema.parse({ method, params });
+    const tool = findTool(parsed.params.name);
+    if (tool === undefined) {
+      throw new McpInvalidArgsError();
+    }
+    const args = parsed.params.arguments ?? {};
+    const result = await tool.handler(ctx, args);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+    };
+  }
+  throw new McpInvalidArgsError();
+}
+
+export async function runHttpServer(opts: RunHttpServerOptions): Promise<{
+  readonly close: () => Promise<void>;
+}> {
+  const bootstrap = opts.bootstrap ?? loadBootstrapConfigFromEnv();
+  const ctx = buildContextFromConfig(bootstrap);
+  const authCache = createAuthCache();
+  const allowList = bootstrap.httpAllowedWallets;
+
+  const server = createServer((req, res) => {
+    void handleRequest(req, res, ctx, authCache, allowList).catch((err) => {
+      if (err instanceof McpServerError) {
+        send(res, 400, { ok: false, code: err.code });
+        return;
+      }
+      send(res, 500, { ok: false, code: 'internal_error' });
+    });
+  });
+
+  await new Promise<void>((resolve) => {
+    server.listen(opts.port, () => resolve());
+  });
+
+  return {
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+      }),
+  };
+}
+
+async function handleRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: McpServerContext,
+  authCache: AuthCache,
+  allowList: ReadonlySet<`0x${string}`>,
+): Promise<void> {
+  const url = req.url ?? '/';
+  const method = req.method ?? 'GET';
+
+  if (url === '/healthz' && method === 'GET') {
+    send(res, 200, { ok: true });
+    return;
+  }
+
+  if (url === '/auth/challenge' && method === 'POST') {
+    const body = (await readJsonBody(req)) as { wallet?: string };
+    if (
+      typeof body.wallet !== 'string' ||
+      !isHex(body.wallet) ||
+      body.wallet.length !== 42
+    ) {
+      throw new McpInvalidArgsError();
+    }
+    const challenge = authCache.issue(body.wallet.toLowerCase() as `0x${string}`);
+    send(res, 200, {
+      ok: true,
+      wallet: challenge.wallet,
+      nonce: challenge.nonce,
+      message: challenge.message,
+      expiresAtMs: challenge.expiresAtMs,
+    });
+    return;
+  }
+
+  if (url === '/mcp' && method === 'POST') {
+    await authenticate(req, authCache, allowList);
+    const body = await readJsonBody(req);
+    const result = await dispatch(ctx, body);
+    send(res, 200, { ok: true, result });
+    return;
+  }
+
+  send(res, 404, { ok: false, code: 'not_found' });
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Public barrel — @shroud-fi/mcp-server.
+ *
+ * Two consumption paths:
+ *   - `import { runStdioServer } from '@shroud-fi/mcp-server'` for stdio bin.
+ *   - `import { runHttpServer } from '@shroud-fi/mcp-server/http'` for HTTP.
+ *   - `import { ALL_TOOLS } from '@shroud-fi/mcp-server/tools'` to embed the
+ *     tool registry into a host MCP server you already own.
+ */
+
+export { runStdioServer } from './stdio.js';
+export { runHttpServer } from './http.js';
+export { buildMcpServer } from './server.js';
+export {
+  buildContextFromConfig,
+  loadBootstrapConfigFromEnv,
+  readHttpPortFromEnv,
+} from './config.js';
+export { createAuthCache } from './auth.js';
+export { ALL_TOOLS, findTool } from './tools/index.js';
+export type {
+  McpTool,
+  McpToolResult,
+  McpServerContext,
+  McpServerBootstrapConfig,
+  Eip191Challenge,
+} from './types.js';
+export {
+  McpServerError,
+  McpConfigError,
+  McpUnauthorizedError,
+  McpToolNotFoundError,
+  McpInvalidArgsError,
+  McpExecutionError,
+  McpEip191ChallengeExpiredError,
+  McpEip191SignatureInvalidError,
+} from './errors.js';
+export {
+  SHROUDFI_MCP_SERVER_NAME,
+  SHROUDFI_MCP_SERVER_VERSION,
+} from './constants.js';

package/src/server.ts

@@ -0,0 +1,103 @@
+/**
+ * MCP server core — wires our tool registry into the official MCP SDK.
+ *
+ * Transport-agnostic: this function builds the configured Server instance.
+ * stdio.ts and http.ts each connect it to their respective transport.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type Tool as MCPTool,
+} from '@modelcontextprotocol/sdk/types.js';
+import { ALL_TOOLS, findTool } from './tools/index.js';
+import {
+  SHROUDFI_MCP_SERVER_NAME,
+  SHROUDFI_MCP_SERVER_VERSION,
+} from './constants.js';
+import { McpInvalidArgsError, McpToolNotFoundError, McpServerError } from './errors.js';
+import type { McpServerContext } from './types.js';
+
+/**
+ * Build a configured MCP Server. The caller plugs in a transport via
+ * `server.connect(transport)` once this returns.
+ */
+export function buildMcpServer(ctx: McpServerContext): Server {
+  const server = new Server(
+    {
+      name: SHROUDFI_MCP_SERVER_NAME,
+      version: SHROUDFI_MCP_SERVER_VERSION,
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools: MCPTool[] = ALL_TOOLS.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema as MCPTool['inputSchema'],
+    }));
+    return { tools };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const tool = findTool(name);
+    if (tool === undefined) {
+      throw new McpToolNotFoundError();
+    }
+    try {
+      const args = (req.params.arguments ?? {}) as unknown;
+      const result = await tool.handler(ctx, args);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result),
+          },
+        ],
+      };
+    } catch (err) {
+      if (err instanceof McpInvalidArgsError || err instanceof McpToolNotFoundError) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ ok: false, code: err.code, message: err.message }),
+            },
+          ],
+        };
+      }
+      if (err instanceof McpServerError) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ ok: false, code: err.code, message: err.message }),
+            },
+          ],
+        };
+      }
+      // Wrap unexpected error — short tag only, never the raw .message.
+      const code = (err as { name?: string })?.name ?? 'execution_failed';
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ ok: false, code, message: 'Tool execution failed' }),
+          },
+        ],
+      };
+    }
+  });
+
+  return server;
+}

package/src/stdio.ts

@@ -0,0 +1,19 @@
+/**
+ * Stdio transport entry point.
+ *
+ * Reads operator config from env, builds the agent context, attaches the
+ * MCP server to stdin/stdout. Used by `.mcp.json` config in Claude Code,
+ * Cursor, Windsurf, Zed AI, etc.
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildContextFromConfig, loadBootstrapConfigFromEnv } from './config.js';
+import { buildMcpServer } from './server.js';
+
+export async function runStdioServer(): Promise<void> {
+  const bootstrap = loadBootstrapConfigFromEnv();
+  const ctx = buildContextFromConfig(bootstrap);
+  const server = buildMcpServer(ctx);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/tools/balance.ts

@@ -0,0 +1,66 @@
+/**
+ * shroud_balance — read ETH and (optionally) ERC-20 balance for a wallet.
+ *
+ * Defaults to the agent's operator wallet. Pass `address` to query a different
+ * one (e.g. a stealth address whose private key was just recovered).
+ */
+
+import { z } from 'zod';
+import { ERC20Abi } from '@shroud-fi/transport';
+import type { McpTool, McpToolResult } from '../types.js';
+import { McpInvalidArgsError } from '../errors.js';
+import { AddressSchema } from './schema.js';
+
+const ArgsSchema = z
+  .object({
+    address: AddressSchema.optional(),
+    token: AddressSchema.optional(),
+  })
+  .strict();
+
+export const shroudBalanceTool: McpTool = {
+  name: 'shroud_balance',
+  description:
+    'Read the ETH balance and (optionally) a single ERC-20 balance for a wallet. Defaults to the operator wallet. Returns wei-denominated strings.',
+  inputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      address: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$' },
+      token: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$' },
+    },
+  },
+  async handler(ctx, raw): Promise<McpToolResult> {
+    const parsed = ArgsSchema.safeParse(raw ?? {});
+    if (!parsed.success) {
+      throw new McpInvalidArgsError();
+    }
+    const target = (parsed.data.address ?? ctx.walletAddress) as
+      | `0x${string}`
+      | undefined;
+    if (target === undefined) {
+      throw new McpInvalidArgsError();
+    }
+
+    const ethBal = await ctx.transport.publicClient.getBalance({
+      address: target,
+    });
+
+    const out: Record<string, unknown> = {
+      ok: true,
+      address: target,
+      ethWei: ethBal.toString(),
+    };
+    if (parsed.data.token !== undefined) {
+      const tokenBal = (await ctx.transport.publicClient.readContract({
+        address: parsed.data.token as `0x${string}`,
+        abi: ERC20Abi,
+        functionName: 'balanceOf',
+        args: [target],
+      })) as bigint;
+      out.token = parsed.data.token;
+      out.tokenBaseUnits = tokenBal.toString();
+    }
+    return out as McpToolResult;
+  },
+};

package/src/tools/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Tool registry. Add new tools here so both stdio + http transports pick them up.
+ */
+
+import type { McpTool } from '../types.js';
+import { shroudRegisterTool } from './register.js';
+import { shroudSendTool } from './send.js';
+import { shroudSendToWalletTool } from './send-to-wallet.js';
+import { shroudReceiveTool } from './receive.js';
+import { shroudSweepTool } from './sweep.js';
+import { shroudBalanceTool } from './balance.js';
+import { shroudStatusTool } from './status.js';
+import { shroudX402PayTool } from './x402-pay.js';
+import { shroudX402ServeTool } from './x402-serve.js';
+
+export const ALL_TOOLS: readonly McpTool[] = [
+  shroudRegisterTool,
+  shroudSendTool,
+  shroudSendToWalletTool,
+  shroudReceiveTool,
+  shroudSweepTool,
+  shroudBalanceTool,
+  shroudStatusTool,
+  shroudX402PayTool,
+  shroudX402ServeTool,
+];
+
+export function findTool(name: string): McpTool | undefined {
+  return ALL_TOOLS.find((t) => t.name === name);
+}
+
+export {
+  shroudRegisterTool,
+  shroudSendTool,
+  shroudSendToWalletTool,
+  shroudReceiveTool,
+  shroudSweepTool,
+  shroudBalanceTool,
+  shroudStatusTool,
+  shroudX402PayTool,
+  shroudX402ServeTool,
+};

package/src/tools/receive.ts

@@ -0,0 +1,105 @@
+/**
+ * shroud_receive — scan a block range for incoming stealth payments to the
+ * configured agent. Stateless: caller supplies fromBlock + toBlock; server
+ * returns every detection in that window.
+ *
+ * Privacy: stealthPrivateKey is exposed in the response because the caller is
+ * the same operator that holds the spending key in the server process — the
+ * key was derived from their own seed. The MCP transport must be local stdio
+ * or authenticated HTTP (EIP-191) to keep this safe. See HTTP transport gate.
+ */
+
+import { z } from 'zod';
+import { createScanner } from '@shroud-fi/scanning';
+import type { DetectedPayment } from '@shroud-fi/scanning';
+import type { McpTool, McpToolResult } from '../types.js';
+import { McpInvalidArgsError } from '../errors.js';
+import { Uint256StringSchema, toBigInt } from './schema.js';
+
+const ArgsSchema = z
+  .object({
+    fromBlock: Uint256StringSchema,
+    toBlock: z.union([Uint256StringSchema, z.literal('latest')]).optional(),
+    finality: z.enum(['unsafe', 'safe', 'finalized']).optional(),
+    /** Hard cap on detections returned in a single call. Defaults to 100. */
+    limit: z.number().int().positive().max(1000).optional(),
+  })
+  .strict();
+
+export const shroudReceiveTool: McpTool = {
+  name: 'shroud_receive',
+  description:
+    'Scan a block range for incoming stealth payments to the agent. Returns the list of detections (each includes stealthAddress, ephemeralPubKey, stealthPrivateKey, txHash, blockNumber). Stateless: caller drives the cursor by passing fromBlock + toBlock.',
+  inputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      fromBlock: { type: 'string', pattern: '^\\d+$' },
+      toBlock: { oneOf: [{ type: 'string', pattern: '^\\d+$' }, { const: 'latest' }] },
+      finality: { type: 'string', enum: ['unsafe', 'safe', 'finalized'] },
+      limit: { type: 'integer', minimum: 1, maximum: 1000 },
+    },
+    required: ['fromBlock'],
+  },
+  async handler(ctx, raw): Promise<McpToolResult> {
+    const parsed = ArgsSchema.safeParse(raw);
+    if (!parsed.success) {
+      throw new McpInvalidArgsError();
+    }
+    const { fromBlock, toBlock, finality, limit } = parsed.data;
+    const fromB = toBigInt(fromBlock);
+
+    let toB: bigint;
+    if (toBlock === undefined || toBlock === 'latest') {
+      const tag: 'finalized' | 'safe' | 'latest' =
+        finality === 'finalized'
+          ? 'finalized'
+          : finality === 'safe'
+            ? 'safe'
+            : 'latest';
+      const block = await ctx.transport.publicClient.getBlock({ blockTag: tag });
+      toB = block.number ?? fromB;
+    } else {
+      toB = toBigInt(toBlock);
+    }
+
+    if (toB < fromB) {
+      return { ok: true, fromBlock: fromB.toString(), toBlock: toB.toString(), detections: [] };
+    }
+
+    const scanner = createScanner({
+      transport: ctx.transport,
+      scanningKey: ctx.agent.identity.keys.scanningKey,
+      spendingKey: ctx.agent.identity.keys.spendingKey,
+      startBlock: fromB,
+      ...(finality !== undefined ? { finality } : {}),
+    });
+
+    const out: Array<Record<string, unknown>> = [];
+    const cap = limit ?? 100;
+    try {
+      for await (const d of scanner.scanRange(fromB, toB) as AsyncIterable<DetectedPayment>) {
+        out.push({
+          stealthAddress: d.stealthAddress,
+          ephemeralPubKey: d.ephemeralPubKey,
+          stealthPrivateKey: d.stealthPrivateKey,
+          txHash: d.txHash,
+          blockNumber: d.blockNumber.toString(),
+          blockHash: d.blockHash,
+          logIndex: d.logIndex,
+          finality: d.finality,
+        });
+        if (out.length >= cap) break;
+      }
+    } finally {
+      scanner.close();
+    }
+
+    return {
+      ok: true,
+      fromBlock: fromB.toString(),
+      toBlock: toB.toString(),
+      detections: out,
+    };
+  },
+};

package/src/tools/register.ts

@@ -0,0 +1,37 @@
+/**
+ * shroud_register — publish the agent's stealth meta-address into ERC-6538.
+ *
+ * Idempotent. Returns `{ registered: false }` if the wallet already has an
+ * on-chain entry.
+ */
+
+import { z } from 'zod';
+import type { McpTool, McpToolResult } from '../types.js';
+import { McpInvalidArgsError } from '../errors.js';
+
+const ArgsSchema = z.object({}).strict();
+
+export const shroudRegisterTool: McpTool = {
+  name: 'shroud_register',
+  description:
+    'Publish the agent stealth meta-address into ERC-6538. Idempotent — no-op when already registered. Returns the registration tx hash on first call.',
+  inputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {},
+    required: [],
+  },
+  async handler(ctx, raw): Promise<McpToolResult> {
+    const parsed = ArgsSchema.safeParse(raw ?? {});
+    if (!parsed.success) {
+      throw new McpInvalidArgsError();
+    }
+    const result = await ctx.agent.ensureRegistered();
+    return {
+      ok: true,
+      registered: result.registered,
+      ...(result.txHash !== undefined ? { txHash: result.txHash } : {}),
+      metaAddress: ctx.agent.metaAddressEncoded,
+    };
+  },
+};

package/src/tools/schema.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared zod schemas + helpers for tool argument validation.
+ */
+
+import { z } from 'zod';
+
+/** 0x-prefixed lowercase EVM address (case preserved by viem checks). */
+export const AddressSchema = z
+  .string()
+  .regex(/^0x[0-9a-fA-F]{40}$/, '0x-prefixed 20-byte hex required');
+
+/** Asset descriptor used by send tools: 'ETH' or token address. */
+export const AssetSchema = z.union([
+  z.literal('ETH'),
+  z.object({ token: AddressSchema }),
+]);
+
+/** Positive integer string that parses to bigint. */
+export const Uint256StringSchema = z
+  .string()
+  .regex(/^\d+$/, 'positive integer required');
+
+export function toBigInt(v: string): bigint {
+  return BigInt(v);
+}