@a3stack/data 0.1.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@a3stack/data",
+  "version": "0.1.0",
+  "description": "MCP server/client helpers with built-in identity verification and payment gating",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --outDir dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@a3stack/identity": "file:../identity",
+    "@a3stack/payments": "file:../payments",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "viem": "^2.39.3",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,189 @@
+/**
+ * createAgentMcpClient — MCP client with identity resolution + payment support
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { getMcpEndpoint, verifyAgent } from "@a3stack/identity";
+import { PaymentClient } from "@a3stack/payments";
+import type { AgentMcpClientConfig } from "./types.js";
+
+type ToolResult = {
+  content: Array<{ type: string; text?: string; data?: unknown }>;
+  isError?: boolean;
+};
+
+type ResourceContent = {
+  uri: string;
+  text?: string;
+  blob?: string;
+  mimeType?: string;
+};
+
+/**
+ * A connected MCP client with optional identity verification + payment
+ */
+export class AgentMcpClientInstance {
+  private client: Client;
+  private transport: StreamableHTTPClientTransport;
+  private config: AgentMcpClientConfig;
+  private payer?: PaymentClient;
+  private _agentVerification?: Awaited<ReturnType<typeof verifyAgent>>;
+  private _url: URL;
+
+  constructor(
+    client: Client,
+    transport: StreamableHTTPClientTransport,
+    config: AgentMcpClientConfig,
+    url: URL,
+    payer?: PaymentClient,
+    verification?: Awaited<ReturnType<typeof verifyAgent>>
+  ) {
+    this.client = client;
+    this.transport = transport;
+    this.config = config;
+    this._url = url;
+    this.payer = payer;
+    this._agentVerification = verification;
+  }
+
+  /**
+   * List available tools from the server
+   */
+  async listTools(): Promise<
+    Array<{ name: string; description?: string; inputSchema?: unknown }>
+  > {
+    const result = await this.client.listTools();
+    return result.tools;
+  }
+
+  /**
+   * Call a tool on the server
+   */
+  async callTool(name: string, args?: Record<string, unknown>): Promise<ToolResult> {
+    return this.client.callTool({ name, arguments: args ?? {} }) as Promise<ToolResult>;
+  }
+
+  /**
+   * List available resources from the server
+   */
+  async listResources(): Promise<Array<{ uri: string; name?: string; description?: string }>> {
+    const result = await this.client.listResources();
+    return result.resources;
+  }
+
+  /**
+   * Read a resource at a given URI
+   */
+  async readResource(uri: string): Promise<ResourceContent[]> {
+    const result = await this.client.readResource({ uri });
+    return result.contents as ResourceContent[];
+  }
+
+  /**
+   * Read the agent's identity resource (shorthand)
+   */
+  async getAgentIdentity(): Promise<Record<string, unknown> | null> {
+    try {
+      const contents = await this.readResource("agent://identity");
+      if (!contents.length || !contents[0].text) return null;
+      return JSON.parse(contents[0].text);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get the verification result for this agent (if connected by global ID)
+   */
+  get verification() {
+    return this._agentVerification ?? null;
+  }
+
+  /**
+   * Get the connected server URL
+   */
+  get url(): URL {
+    return this._url;
+  }
+
+  /**
+   * Close the connection
+   */
+  async close(): Promise<void> {
+    await this.client.close();
+  }
+}
+
+/**
+ * Connect to an MCP server by ERC-8004 global ID or direct URL.
+ *
+ * @example
+ * // By identity
+ * const client = await createAgentMcpClient({
+ *   agentId: "eip155:8453:0x8004...#2376",
+ *   payer: { account },
+ * });
+ *
+ * @example
+ * // By URL
+ * const client = await createAgentMcpClient({ url: "https://mcp.agent.eth/mcp" });
+ */
+export async function createAgentMcpClient(
+  config: AgentMcpClientConfig
+): Promise<AgentMcpClientInstance> {
+  if (!config.agentId && !config.url) {
+    throw new Error("Must provide either agentId (ERC-8004 global ID) or url");
+  }
+
+  let mcpUrl: string;
+  let verification: Awaited<ReturnType<typeof verifyAgent>> | undefined;
+
+  if (config.agentId) {
+    // Verify identity and resolve MCP endpoint
+    verification = await verifyAgent(config.agentId);
+
+    if (!verification.valid) {
+      throw new Error(
+        `Cannot connect to agent "${config.agentId}": ${verification.error ?? "Identity verification failed"}`
+      );
+    }
+
+    const endpoint = await getMcpEndpoint(config.agentId);
+    if (!endpoint) {
+      throw new Error(
+        `Agent "${config.agentId}" does not expose an MCP endpoint. ` +
+          `Check their registration's services array for a "MCP" service entry.`
+      );
+    }
+
+    mcpUrl = endpoint;
+  } else {
+    mcpUrl = config.url!;
+  }
+
+  // Set up payment client if payer is configured
+  let payer: PaymentClient | undefined;
+  if (config.payer) {
+    payer = new PaymentClient({
+      account: config.payer.account,
+      maxAmountPerRequest: config.payer.maxAmount,
+    });
+  }
+
+  // Create MCP client with optional payment-wrapped fetch
+  const client = new Client({
+    name: "a3stack-client",
+    version: "0.1.0",
+  });
+
+  const transportFetch = payer ? payer.fetch : fetch;
+  const transport = new StreamableHTTPClientTransport(new URL(mcpUrl), {
+    // Use payment-aware fetch if payer configured
+    fetch: transportFetch as typeof fetch,
+  });
+
+  await client.connect(transport);
+
+  return new AgentMcpClientInstance(client, transport, config, new URL(mcpUrl), payer, verification);
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @a3stack/data
+ * MCP server/client helpers with built-in identity verification and payment gating
+ */
+
+export { AgentMcpServerInstance, createAgentMcpServer } from "./server.js";
+export { AgentMcpClientInstance, createAgentMcpClient } from "./client.js";
+export { probeAgent } from "./probe.js";
+export type { AgentMcpServerConfig, AgentMcpClientConfig, AgentMcpServer } from "./types.js";
+export type { AgentProbeResult } from "./probe.js";

package/src/probe.ts

@@ -0,0 +1,153 @@
+/**
+ * probeAgent — discover what an agent offers before connecting
+ * 
+ * Resolves identity, checks payment requirements, lists available endpoints.
+ * All read-only, no wallet needed.
+ */
+
+import { verifyAgent, getMcpEndpoint, getA2aEndpoint, parseAgentId } from "@a3stack/identity";
+import type { AgentRegistrationFile, VerificationResult } from "@a3stack/identity";
+
+export interface AgentProbeResult {
+  /** The global agent ID that was probed */
+  globalId: string;
+
+  /** Whether the agent's identity is verified on-chain */
+  verified: boolean;
+
+  /** The owner wallet address */
+  owner: string | null;
+
+  /** The payment wallet (or null if defaults to owner) */
+  paymentWallet: string | null;
+
+  /** The full registration file (if fetchable) */
+  registration: AgentRegistrationFile | null;
+
+  /** Resolved service endpoints */
+  endpoints: {
+    mcp: string | null;
+    a2a: string | null;
+    web: string | null;
+  };
+
+  /** Whether the agent accepts x402 payments */
+  acceptsPayment: boolean;
+
+  /** Whether the agent is marked as active */
+  active: boolean;
+
+  /** All services exposed */
+  services: Array<{ name: string; endpoint: string; version?: string }>;
+
+  /** Cross-chain registrations */
+  registrations: Array<{ agentId: number; agentRegistry: string }>;
+
+  /** Payment details from probing the MCP endpoint (if reachable) */
+  paymentRequirements?: {
+    amount?: string;
+    network?: string;
+    payTo?: string;
+  };
+
+  /** Any error during probing */
+  error?: string;
+}
+
+/**
+ * Probe an agent to discover its capabilities without connecting.
+ * Read-only operation — no wallet or payment needed.
+ * 
+ * @example
+ * ```ts
+ * const info = await probeAgent("eip155:8453:0x8004...#2376");
+ * console.log(info.verified);              // true
+ * console.log(info.endpoints.mcp);         // "https://mcp.agent.eth/mcp"
+ * console.log(info.acceptsPayment);        // true
+ * console.log(info.paymentRequirements);   // { amount: "10000", network: "eip155:8453" }
+ * ```
+ */
+export async function probeAgent(globalId: string): Promise<AgentProbeResult> {
+  const ref = parseAgentId(globalId);
+
+  const result: AgentProbeResult = {
+    globalId,
+    verified: false,
+    owner: null,
+    paymentWallet: null,
+    registration: null,
+    endpoints: { mcp: null, a2a: null, web: null },
+    acceptsPayment: false,
+    active: false,
+    services: [],
+    registrations: [],
+  };
+
+  // Step 1: Verify on-chain identity
+  let verification: VerificationResult;
+  try {
+    verification = await verifyAgent(globalId);
+  } catch (e) {
+    result.error = `Verification failed: ${(e as Error).message}`;
+    return result;
+  }
+
+  result.verified = verification.valid;
+  result.owner = verification.owner;
+  result.paymentWallet = verification.paymentWallet;
+  result.registration = verification.registration;
+
+  if (!verification.valid) {
+    result.error = verification.error ?? "Identity verification failed";
+    return result;
+  }
+
+  // Step 2: Extract registration data
+  if (verification.registration) {
+    const reg = verification.registration;
+    result.active = reg.active;
+    result.acceptsPayment = reg.x402Support;
+    result.services = reg.services ?? [];
+    result.registrations = reg.registrations ?? [];
+
+    // Resolve known endpoints
+    const mcpSvc = reg.services?.find(s => s.name.toUpperCase() === "MCP");
+    const a2aSvc = reg.services?.find(s => s.name.toUpperCase() === "A2A");
+    const webSvc = reg.services?.find(s => s.name.toLowerCase() === "web");
+
+    result.endpoints.mcp = mcpSvc?.endpoint ?? null;
+    result.endpoints.a2a = a2aSvc?.endpoint ?? null;
+    result.endpoints.web = webSvc?.endpoint ?? null;
+  }
+
+  // Step 3: If MCP endpoint exists and agent accepts payments, probe for requirements
+  if (result.endpoints.mcp && result.acceptsPayment) {
+    try {
+      const response = await fetch(result.endpoints.mcp, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", method: "ping", id: 1 }),
+      });
+
+      if (response.status === 402) {
+        const reqHeader = response.headers.get("x-payment-required") ??
+          response.headers.get("X-PAYMENT-REQUIRED");
+        if (reqHeader) {
+          try {
+            const decoded = JSON.parse(Buffer.from(reqHeader, "base64").toString("utf8"));
+            const first = Array.isArray(decoded.accepts) ? decoded.accepts[0] : decoded;
+            result.paymentRequirements = {
+              amount: first.maxAmountRequired,
+              network: first.network,
+              payTo: first.payTo,
+            };
+          } catch { /* ignore parse errors */ }
+        }
+      }
+    } catch {
+      // MCP endpoint not reachable — that's fine, not an error
+    }
+  }
+
+  return result;
+}

package/src/server.ts

@@ -0,0 +1,336 @@
+/**
+ * createAgentMcpServer — MCP server with built-in identity + payment support
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { randomUUID } from "node:crypto";
+import { McpServer, type RegisteredTool as McpRegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { createPublicClient, http } from "viem";
+import { z } from "zod";
+import {
+  fetchRegistrationFile,
+  IDENTITY_REGISTRY_ADDRESS,
+  IDENTITY_REGISTRY_ABI,
+  SUPPORTED_CHAINS,
+} from "@a3stack/identity";
+import { PaymentServer, USDC_BASE, DEFAULT_NETWORK } from "@a3stack/payments";
+import type { AgentMcpServerConfig } from "./types.js";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ToolHandler<T = any> = (args: T) => Promise<CallToolResult>;
+
+interface InternalRegisteredTool {
+  requiresPayment: boolean;
+}
+
+/**
+ * Agent MCP Server wrapping @modelcontextprotocol/sdk with payment + identity support
+ */
+export class AgentMcpServerInstance {
+  private config: Required<Omit<AgentMcpServerConfig, "payment" | "identity">> & {
+    payment?: AgentMcpServerConfig["payment"];
+    identity?: AgentMcpServerConfig["identity"];
+  };
+  private mcp: McpServer;
+  private paymentServer?: PaymentServer;
+  private tools = new Map<string, InternalRegisteredTool>();
+  private httpServer?: ReturnType<typeof createServer>;
+
+  constructor(config: AgentMcpServerConfig) {
+    this.config = {
+      name: config.name,
+      version: config.version,
+      port: config.port ?? 3000,
+      cors: config.cors ?? true,
+      identity: config.identity,
+      payment: config.payment,
+    };
+
+    this.mcp = new McpServer({
+      name: config.name,
+      version: config.version,
+    });
+
+    if (config.payment) {
+      this.paymentServer = new PaymentServer({
+        payTo: config.payment.payTo,
+        amount: config.payment.amount,
+        asset: config.payment.asset ?? USDC_BASE,
+        network: config.payment.network ?? DEFAULT_NETWORK,
+        description: config.payment.description ?? `${config.name} MCP service`,
+        maxTimeoutSeconds: config.payment.maxTimeoutSeconds,
+      });
+    }
+
+    // Register built-in tools
+    this._registerBuiltinTools();
+
+    // Register identity resource if configured
+    if (config.identity) {
+      this._registerIdentityResource();
+    }
+  }
+
+  private _registerBuiltinTools() {
+    // Ping — always free
+    this.mcp.tool(
+      "ping",
+      "Check if the server is alive",
+      {},
+      async () => ({
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({
+              status: "ok",
+              server: this.config.name,
+              version: this.config.version,
+              timestamp: new Date().toISOString(),
+              requiresPayment: !!this.config.payment,
+              ...(this.config.payment
+                ? {
+                    paymentInfo: {
+                      amount: this.config.payment.amount,
+                      network: this.config.payment.network ?? DEFAULT_NETWORK,
+                      payTo: this.config.payment.payTo,
+                    },
+                  }
+                : {}),
+            }),
+          },
+        ],
+      })
+    );
+  }
+
+  private _registerIdentityResource() {
+    const identityConfig = this.config.identity!;
+
+    // Register as MCP resource at agent://identity
+    this.mcp.resource(
+      "agent-identity",
+      "agent://identity",
+      { description: "The agent's ERC-8004 on-chain identity registration", mimeType: "application/json" },
+      async (_uri: URL) => {
+        try {
+          const chainDefaults = SUPPORTED_CHAINS[identityConfig.chainId];
+          const rpcUrl = identityConfig.rpc ?? chainDefaults?.rpc;
+
+          if (!rpcUrl) {
+            return {
+              contents: [
+                {
+                  uri: "agent://identity",
+                  text: JSON.stringify({
+                    error: `No RPC available for chain ${identityConfig.chainId}`,
+                  }),
+                  mimeType: "application/json",
+                },
+              ],
+            };
+          }
+
+          const client = createPublicClient({ transport: http(rpcUrl) });
+          const registry = identityConfig.registry ?? IDENTITY_REGISTRY_ADDRESS;
+
+          const agentUri = (await client.readContract({
+            address: registry,
+            abi: IDENTITY_REGISTRY_ABI,
+            functionName: "tokenURI",
+            args: [BigInt(identityConfig.agentId)],
+          })) as string;
+
+          const registration = await fetchRegistrationFile(agentUri);
+
+          return {
+            contents: [
+              {
+                uri: "agent://identity",
+                text: JSON.stringify(
+                  {
+                    globalId: `eip155:${identityConfig.chainId}:${registry}#${identityConfig.agentId}`,
+                    ...registration,
+                  },
+                  null,
+                  2
+                ),
+                mimeType: "application/json",
+              },
+            ],
+          };
+        } catch (e) {
+          return {
+            contents: [
+              {
+                uri: "agent://identity",
+                text: JSON.stringify({ error: (e as Error).message }),
+                mimeType: "application/json",
+              },
+            ],
+          };
+        }
+      }
+    );
+  }
+
+  /**
+   * Register a tool (wraps McpServer.tool())
+   * The handler must return a CallToolResult-compatible object.
+   */
+  tool(
+    name: string,
+    description: string,
+    paramsSchema: Record<string, z.ZodTypeAny>,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handler: ToolHandler<any>
+  ): McpRegisteredTool {
+    const freeTools = this.config.payment?.freeTools ?? ["ping"];
+    this.tools.set(name, {
+      requiresPayment: !!this.config.payment && !freeTools.includes(name),
+    });
+    return this.mcp.tool(name, description, paramsSchema, handler);
+  }
+
+  /**
+   * Register a resource (wraps McpServer.resource())
+   */
+  resource(
+    name: string,
+    uri: string,
+    description: string,
+    handler: (uri: URL) => Promise<{ contents: Array<{ uri: string; text: string; mimeType?: string }> }>
+  ): void {
+    this.mcp.resource(name, uri, { description }, handler);
+  }
+
+  /**
+   * Start the HTTP server
+   */
+  async listen(port?: number): Promise<{ url: string }> {
+    const listenPort = port ?? this.config.port;
+    const transports = new Map<string, StreamableHTTPServerTransport>();
+
+    this.httpServer = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+      // CORS headers
+      if (this.config.cors) {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+        res.setHeader(
+          "Access-Control-Allow-Headers",
+          "Content-Type, MCP-Session-Id, X-PAYMENT, X-PAYMENT-REQUIRED"
+        );
+        if (req.method === "OPTIONS") {
+          res.writeHead(204);
+          res.end();
+          return;
+        }
+      }
+
+      // Only handle /mcp path
+      if (req.url !== "/mcp" && req.url !== "/") {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not found", hint: "MCP endpoint is at /mcp" }));
+        return;
+      }
+
+      // Check payment for POST requests (tool calls)
+      if (req.method === "POST" && this.paymentServer) {
+        const paymentHeader = req.headers["x-payment"] as string | undefined;
+
+        if (!paymentHeader) {
+          const requirementsHeader = this.paymentServer.buildRequirementsHeader(
+            `https://${req.headers.host ?? "localhost"}${req.url ?? "/mcp"}`
+          );
+          res.writeHead(402, {
+            "Content-Type": "application/json",
+            "X-PAYMENT-REQUIRED": requirementsHeader,
+          });
+          res.end(
+            JSON.stringify({
+              error: "Payment Required",
+              message:
+                `This MCP server requires x402 payment. ` +
+                `Use a payment-capable client or pay ${this.config.payment!.amount} USDC on ${this.config.payment!.network ?? DEFAULT_NETWORK}.`,
+            })
+          );
+          return;
+        }
+
+        const payResult = await this.paymentServer.verify(req);
+        if (!payResult.valid) {
+          res.writeHead(402, { "Content-Type": "application/json" });
+          res.end(
+            JSON.stringify({ error: "Invalid Payment", message: payResult.error })
+          );
+          return;
+        }
+      }
+
+      // Handle MCP protocol
+      const sessionId = req.headers["mcp-session-id"] as string | undefined;
+      let transport: StreamableHTTPServerTransport;
+
+      if (sessionId && transports.has(sessionId)) {
+        transport = transports.get(sessionId)!;
+      } else if (!sessionId && req.method === "POST") {
+        // New session
+        const newSessionId = randomUUID();
+        transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => newSessionId,
+        });
+        transports.set(newSessionId, transport);
+        transport.onclose = () => {
+          transports.delete(newSessionId);
+        };
+        await this.mcp.connect(transport);
+      } else if (req.method === "GET") {
+        // SSE connection for existing session — create standalone transport for streaming
+        transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: undefined, // stateless for GET
+        });
+        await this.mcp.connect(transport);
+      } else {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Bad Request", message: "Missing MCP-Session-Id" }));
+        return;
+      }
+
+      await transport.handleRequest(req, res);
+    });
+
+    await new Promise<void>((resolve) => {
+      this.httpServer!.listen(listenPort, resolve);
+    });
+
+    const url = `http://localhost:${listenPort}/mcp`;
+    return { url };
+  }
+
+  /**
+   * Stop the server
+   */
+  async close(): Promise<void> {
+    await this.mcp.close();
+    if (this.httpServer) {
+      await new Promise<void>((resolve, reject) => {
+        this.httpServer!.close((err) => (err ? reject(err) : resolve()));
+      });
+    }
+  }
+
+  /** Access the raw McpServer for advanced usage */
+  get server(): McpServer {
+    return this.mcp;
+  }
+}
+
+/**
+ * Create an MCP server with built-in identity + payment support
+ */
+export function createAgentMcpServer(
+  config: AgentMcpServerConfig
+): AgentMcpServerInstance {
+  return new AgentMcpServerInstance(config);
+}

package/src/types.ts

@@ -0,0 +1,82 @@
+/**
+ * @a3stack/data — Type Definitions
+ */
+
+import type { PaymentServerConfig } from "@a3stack/payments";
+
+export interface AgentMcpServerConfig {
+  /** MCP server name (shown to clients) */
+  name: string;
+  /** MCP server version */
+  version: string;
+
+  /**
+   * Auto-expose the agent's ERC-8004 identity as an MCP resource.
+   * If provided, adds an "agent://identity" resource.
+   */
+  identity?: {
+    chainId: number;
+    agentId: number;
+    registry?: `0x${string}`;
+    rpc?: string;
+  };
+
+  /**
+   * Require x402 payment before serving paid tools.
+   * Free tools (like ping, identity) are always accessible.
+   */
+  payment?: PaymentServerConfig & {
+    /** Tool names that don't require payment. Defaults to ["ping"] */
+    freeTools?: string[];
+  };
+
+  /** Port to listen on. Defaults to 3000. */
+  port?: number;
+
+  /** Enable CORS. Defaults to true. */
+  cors?: boolean;
+}
+
+export interface AgentMcpClientConfig {
+  /**
+   * Connect by ERC-8004 global ID — auto-resolves MCP endpoint.
+   * Format: "eip155:{chainId}:{registry}#{agentId}"
+   */
+  agentId?: string;
+
+  /** Connect by direct MCP URL */
+  url?: string;
+
+  /**
+   * If the server requires x402 payment, configure a payer.
+   * If not provided, the client will fail on 402 responses.
+   */
+  payer?: {
+    /** viem Account (e.g. from privateKeyToAccount()) */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    account: any;
+    /** Max USDC to auto-pay per session. Default: 10 USDC */
+    maxAmount?: string;
+  };
+}
+
+export interface AgentMcpServer {
+  /** The underlying McpServer instance */
+  mcp: unknown;
+  /**
+   * Register a tool (passthrough to McpServer.tool())
+   */
+  tool(name: string, paramsSchema: unknown, handler: unknown): void;
+  /**
+   * Register a resource (passthrough to McpServer.resource())
+   */
+  resource(name: string, uri: string, handler: unknown): void;
+  /**
+   * Start listening
+   */
+  listen(port?: number): Promise<{ url: string }>;
+  /**
+   * Stop the server
+   */
+  close(): Promise<void>;
+}