@shroud-fi/mcp-server 0.1.0

package/dist/esm/tools/x402-serve.js

@@ -0,0 +1,130 @@
+/**
+ * shroud_x402_serve — server-side x402 primitives.
+ *
+ * One tool, two ops:
+ *   - op: 'challenge' → mint a 402 challenge bundle (headers + body) the
+ *     caller serves from their own HTTP framework. Each challenge derives a
+ *     FRESH stealth payTo address.
+ *   - op: 'verify' → verify a client's signed X-PAYMENT payload against a
+ *     prior challenge. Skip-facilitator mode by default — caller settles
+ *     the EIP-3009 authorization on-chain themselves.
+ *
+ * Caller is responsible for transport (Express/Fastify/Next/etc) — this
+ * stays framework-agnostic.
+ */
+import { z } from 'zod';
+import { createX402Server } from '@shroud-fi/x402';
+import { getUSDC } from '@shroud-fi/transport';
+import { McpInvalidArgsError } from '../errors.js';
+import { Uint256StringSchema } from './schema.js';
+const ChallengeArgs = z
+    .object({
+    op: z.literal('challenge'),
+    resource: z.string().min(1),
+    description: z.string().optional(),
+    priceUsdcAtomic: Uint256StringSchema.optional(),
+})
+    .strict();
+const VerifyArgs = z
+    .object({
+    op: z.literal('verify'),
+    signedPayloadBase64: z.string().min(1),
+    challenge: z.object({
+        body: z.object({
+            x402Version: z.literal(2),
+            error: z.string(),
+            accepts: z.array(z.any()),
+        }),
+        headers: z.record(z.string()),
+    }),
+    skipFacilitator: z.boolean().optional(),
+})
+    .strict();
+const ArgsSchema = z.discriminatedUnion('op', [ChallengeArgs, VerifyArgs]);
+export const shroudX402ServeTool = {
+    name: 'shroud_x402_serve',
+    description: 'Server-side x402 primitives. `op: "challenge"` mints a fresh 402 challenge (headers + body + per-call stealth payTo); caller attaches to their HTTP response. `op: "verify"` verifies a client X-PAYMENT payload against a prior challenge. Defaults to skip-facilitator mode (caller settles on-chain themselves).',
+    inputSchema: {
+        type: 'object',
+        oneOf: [
+            {
+                properties: {
+                    op: { const: 'challenge' },
+                    resource: { type: 'string' },
+                    description: { type: 'string' },
+                    priceUsdcAtomic: { type: 'string', pattern: '^\\d+$' },
+                },
+                required: ['op', 'resource'],
+            },
+            {
+                properties: {
+                    op: { const: 'verify' },
+                    signedPayloadBase64: { type: 'string' },
+                    challenge: { type: 'object' },
+                    skipFacilitator: { type: 'boolean' },
+                },
+                required: ['op', 'signedPayloadBase64', 'challenge'],
+            },
+        ],
+    },
+    async handler(ctx, raw) {
+        const parsed = ArgsSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new McpInvalidArgsError();
+        }
+        const usdc = getUSDC(ctx.chainId);
+        if (usdc === undefined) {
+            throw new McpInvalidArgsError();
+        }
+        const server = createX402Server({
+            transport: ctx.transport,
+            chainId: ctx.chainId,
+            recipientMetaAddress: ctx.agent.metaAddressEncoded,
+            asset: usdc,
+            defaultPriceAtomic: parsed.data.op === 'challenge' && parsed.data.priceUsdcAtomic !== undefined
+                ? BigInt(parsed.data.priceUsdcAtomic)
+                : 10000n,
+        });
+        if (parsed.data.op === 'challenge') {
+            const args = {
+                resource: parsed.data.resource,
+            };
+            if (parsed.data.description !== undefined)
+                args.description = parsed.data.description;
+            if (parsed.data.priceUsdcAtomic !== undefined) {
+                args.priceAtomic = BigInt(parsed.data.priceUsdcAtomic);
+            }
+            const ch = await server.challenge(args);
+            return {
+                ok: true,
+                status: ch.status,
+                headers: ch.headers,
+                body: ch.body,
+                announcement: ch.announcement,
+            };
+        }
+        // op === 'verify' — caller round-trips the same shape they received from
+        // the challenge op. Cast through unknown so the schema declaration stays
+        // permissive (zod already ran structural checks).
+        const verifyResult = await server.verify({
+            signedPayload: parsed.data.signedPayloadBase64,
+            challenge: parsed.data.challenge,
+            skipFacilitator: parsed.data.skipFacilitator ?? true,
+        });
+        if (verifyResult.valid) {
+            return {
+                ok: true,
+                valid: true,
+                ...(verifyResult.settledTxHash !== undefined
+                    ? { settledTxHash: verifyResult.settledTxHash }
+                    : {}),
+            };
+        }
+        return {
+            ok: true,
+            valid: false,
+            error: verifyResult.error,
+        };
+    },
+};
+//# sourceMappingURL=x402-serve.js.map

package/dist/esm/tools/x402-serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-serve.js","sourceRoot":"","sources":["../../../src/tools/x402-serve.ts"],"names":[],"mappings":"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"}

package/dist/esm/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Public types for @shroud-fi/mcp-server.
+ */
+import type { Hex } from 'viem';
+import type { ShroudAgent } from '@shroud-fi/agent-runtime';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+/**
+ * Resolved server context — what every tool handler receives.
+ *
+ * Built once by createMcpServer/bootstrap and reused for every tool call.
+ * No mutable state lives here; the scanner cursor is owned by the agent.
+ */
+export interface McpServerContext {
+    readonly agent: ShroudAgent;
+    readonly transport: ShroudFiTransport;
+    readonly chainId: number;
+    /** Resolution of the operator's signing wallet, when present. */
+    readonly walletAddress: `0x${string}` | undefined;
+}
+/** JSON-safe tool result shape. MCP wraps this in a `content` array. */
+export interface McpToolResult {
+    readonly ok: boolean;
+    readonly [k: string]: unknown;
+}
+/**
+ * Minimal tool descriptor. We mirror the MCP SDK shape but stay decoupled so
+ * tests can exercise tools without spinning up the full MCP server.
+ */
+export interface McpTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: object;
+    readonly handler: (ctx: McpServerContext, args: unknown) => Promise<McpToolResult>;
+}
+/**
+ * EIP-191 challenge record. The HTTP transport caches outstanding challenges
+ * keyed by client wallet address until they expire or are consumed.
+ */
+export interface Eip191Challenge {
+    readonly wallet: `0x${string}`;
+    readonly nonce: Hex;
+    readonly issuedAtMs: number;
+    readonly expiresAtMs: number;
+    readonly message: string;
+}
+/** Resolved server bootstrap config. */
+export interface McpServerBootstrapConfig {
+    readonly chainId: number;
+    readonly rpcUrl: string;
+    readonly privateKey: Hex | undefined;
+    readonly startBlock: bigint;
+    /**
+     * Optional 32-byte deterministic master seed. When supplied, the
+     * ShroudAgent's stealth meta-address derivation is identical across every
+     * process that loads this config — required for multi-surface deployments
+     * (MCP + REST + UI) to agree on the operator's recipient identity. When
+     * undefined, ShroudAgent generates a random seed per boot.
+     */
+    readonly masterSeed: Uint8Array | undefined;
+    /**
+     * If non-empty, the HTTP transport rejects every authenticated request
+     * whose recovered wallet is not in this set. Stdio transport ignores it.
+     */
+    readonly httpAllowedWallets: ReadonlySet<`0x${string}`>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,aAAa,EAAE,KAAK,MAAM,EAAE,GAAG,SAAS,CAAC;CACnD;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAChB,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,OAAO,KACV,OAAO,CAAC,aAAa,CAAC,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wCAAwC;AACxC,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,GAAG,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;CACzD"}

package/dist/esm/types.js

@@ -0,0 +1,5 @@
+/**
+ * Public types for @shroud-fi/mcp-server.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}