@hpp-io/x402-mcp-bridge 0.0.1

package/dist/config.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Env parsing + validation. The bridge runs as a stdio subprocess spawned
+ * by the MCP host; *all* of its inputs come from env. We surface clear
+ * errors before doing any I/O so misconfigured Claude Desktop entries fail
+ * loudly at startup rather than mid-call.
+ */
+import { z } from "zod";
+declare const Schema: z.ZodObject<{
+    DELEGATE_PRIVATE_KEY: z.ZodString;
+    SAFE_ADDRESS: z.ZodString;
+    ALLOWANCE_MODULE_ADDRESS: z.ZodString;
+    USDCE_ADDRESS: z.ZodString;
+    RESOURCE_SERVER_URL: z.ZodString;
+    HPP_RPC_URL: z.ZodString;
+    HPP_NETWORK: z.ZodString;
+    TOPUP_AMOUNT_ATOMIC: z.ZodOptional<z.ZodString>;
+    TOPUP_HEADROOM_X: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    LOG_LEVEL: z.ZodDefault<z.ZodOptional<z.ZodEnum<["off", "info", "debug"]>>>;
+}, "strip", z.ZodTypeAny, {
+    DELEGATE_PRIVATE_KEY: string;
+    SAFE_ADDRESS: string;
+    ALLOWANCE_MODULE_ADDRESS: string;
+    USDCE_ADDRESS: string;
+    RESOURCE_SERVER_URL: string;
+    HPP_RPC_URL: string;
+    HPP_NETWORK: string;
+    TOPUP_HEADROOM_X: string;
+    LOG_LEVEL: "off" | "info" | "debug";
+    TOPUP_AMOUNT_ATOMIC?: string | undefined;
+}, {
+    DELEGATE_PRIVATE_KEY: string;
+    SAFE_ADDRESS: string;
+    ALLOWANCE_MODULE_ADDRESS: string;
+    USDCE_ADDRESS: string;
+    RESOURCE_SERVER_URL: string;
+    HPP_RPC_URL: string;
+    HPP_NETWORK: string;
+    TOPUP_AMOUNT_ATOMIC?: string | undefined;
+    TOPUP_HEADROOM_X?: string | undefined;
+    LOG_LEVEL?: "off" | "info" | "debug" | undefined;
+}>;
+export type Config = z.infer<typeof Schema> & {
+    chainId: number;
+};
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;
+export {};

package/dist/config.js

@@ -0,0 +1,59 @@
+/**
+ * Env parsing + validation. The bridge runs as a stdio subprocess spawned
+ * by the MCP host; *all* of its inputs come from env. We surface clear
+ * errors before doing any I/O so misconfigured Claude Desktop entries fail
+ * loudly at startup rather than mid-call.
+ */
+import { z } from "zod";
+const HEX_ADDR = /^0x[0-9a-fA-F]{40}$/;
+const HEX_KEY = /^0x[0-9a-fA-F]{64}$/;
+const Schema = z.object({
+    // Delegate EOA — signs EIP-3009 payments + executeAllowanceTransfer.
+    // NOTE: PoC accepts the raw key. Future signers (keychain, server-wallet)
+    // will short-circuit this field.
+    DELEGATE_PRIVATE_KEY: z.string().regex(HEX_KEY, "expected 0x + 64 hex chars"),
+    // Safe wallet that holds the user's USDC.e.
+    SAFE_ADDRESS: z.string().regex(HEX_ADDR),
+    // Deployed AllowanceModule.
+    ALLOWANCE_MODULE_ADDRESS: z.string().regex(HEX_ADDR),
+    // Asset paid in (USDC.e on HPP).
+    USDCE_ADDRESS: z.string().regex(HEX_ADDR),
+    // Remote MCP server we proxy to (the seller).
+    RESOURCE_SERVER_URL: z.string().url(),
+    // Chain RPC.
+    HPP_RPC_URL: z.string().url(),
+    // CAIP-2 network identifier used by @x402/evm.
+    // e.g. "eip155:181228" (HPP Sepolia) / "eip155:190415" (HPP Mainnet).
+    HPP_NETWORK: z.string().regex(/^eip155:\d+$/),
+    // Optional knobs ------------------------------------------------------
+    // How much to pull on each topup, in atomic USDC.e units. If unset,
+    // the bridge tops up "just enough" for the upcoming payment + small
+    // headroom (10x the price, capped to remaining allowance).
+    TOPUP_AMOUNT_ATOMIC: z
+        .string()
+        .regex(/^\d+$/)
+        .optional(),
+    // Headroom multiplier for the dynamic topup amount above. 10 = pull
+    // 10× the next payment so subsequent calls don't always trigger a
+    // topup tx. Defaults to 10.
+    TOPUP_HEADROOM_X: z
+        .string()
+        .regex(/^\d+$/)
+        .optional()
+        .default("10"),
+    // Logging. "off" = silent (good for clean stdio), "debug" = verbose stderr.
+    LOG_LEVEL: z.enum(["off", "info", "debug"]).optional().default("info"),
+});
+export function loadConfig(env = process.env) {
+    const parsed = Schema.safeParse(env);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("\n");
+        throw new Error("x402-mcp-bridge: invalid config from env\n" + issues + "\n");
+    }
+    const v = parsed.data;
+    const chainId = Number(v.HPP_NETWORK.split(":")[1]);
+    return { ...v, chainId };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,QAAQ,GAAG,qBAAqB,CAAC;AACvC,MAAM,OAAO,GAAG,qBAAqB,CAAC;AAEtC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IACtB,qEAAqE;IACrE,0EAA0E;IAC1E,iCAAiC;IACjC,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,4BAA4B,CAAC;IAE7E,4CAA4C;IAC5C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC;IAExC,4BAA4B;IAC5B,wBAAwB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC;IAEpD,iCAAiC;IACjC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC;IAEzC,8CAA8C;IAC9C,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAErC,aAAa;IACb,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAE7B,+CAA+C;IAC/C,sEAAsE;IACtE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC;IAE7C,wEAAwE;IACxE,oEAAoE;IACpE,oEAAoE;IACpE,2DAA2D;IAC3D,mBAAmB,EAAE,CAAC;SACnB,MAAM,EAAE;SACR,KAAK,CAAC,OAAO,CAAC;SACd,QAAQ,EAAE;IAEb,oEAAoE;IACpE,kEAAkE;IAClE,4BAA4B;IAC5B,gBAAgB,EAAE,CAAC;SAChB,MAAM,EAAE;SACR,KAAK,CAAC,OAAO,CAAC;SACd,QAAQ,EAAE;SACV,OAAO,CAAC,IAAI,CAAC;IAEhB,4EAA4E;IAC5E,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;CACvE,CAAC,CAAC;AAMH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aAC/D,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CACb,4CAA4C,GAAG,MAAM,GAAG,IAAI,CAC7D,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;IACtB,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare function runBridge(env?: NodeJS.ProcessEnv): Promise<void>;

package/dist/index.js

@@ -0,0 +1,70 @@
+/**
+ * Bridge entry — wires config → signer → autoTopup → upstream client →
+ * stdio server, then runs forever (until the host closes our stdin).
+ *
+ * Public surface for callers (npx, programmatic):
+ *   - default export: `runBridge()` — runs main loop
+ *   - named exports: types only (config, signer, autoTopup) for tests
+ */
+import { loadConfig } from "./config.js";
+import { setLogLevel, log } from "./log.js";
+import { RawEoaSigner } from "./signers/raw-eoa.js";
+import { AutoTopup } from "./autoTopup.js";
+import { connectUpstream } from "./client.js";
+import { startBridgeServer } from "./server.js";
+const PKG_NAME = "@hpp-io/x402-mcp-bridge";
+const PKG_VERSION = "0.0.1"; // mirrors package.json — bump together
+export async function runBridge(env = process.env) {
+    const cfg = loadConfig(env);
+    setLogLevel(cfg.LOG_LEVEL);
+    log.info("bridge.start", {
+        name: PKG_NAME,
+        version: PKG_VERSION,
+        chain: cfg.HPP_NETWORK,
+        safe: cfg.SAFE_ADDRESS,
+        resourceServer: cfg.RESOURCE_SERVER_URL,
+    });
+    // ---- Signer (PoC: raw EOA from env) ---------------------------------
+    const signer = new RawEoaSigner(cfg.DELEGATE_PRIVATE_KEY);
+    log.info("signer.loaded", { address: signer.address });
+    // ---- AutoTopup --------------------------------------------------------
+    const autoTopup = new AutoTopup(signer, cfg.SAFE_ADDRESS, cfg.ALLOWANCE_MODULE_ADDRESS, cfg.USDCE_ADDRESS, cfg.chainId, cfg.HPP_RPC_URL, {
+        headroomX: BigInt(cfg.TOPUP_HEADROOM_X),
+        fixedAmountAtomic: cfg.TOPUP_AMOUNT_ATOMIC
+            ? BigInt(cfg.TOPUP_AMOUNT_ATOMIC)
+            : undefined,
+    });
+    // ---- Upstream MCP client (with x402 payment wrapper) ----------------
+    const upstream = await connectUpstream({
+        url: cfg.RESOURCE_SERVER_URL,
+        network: cfg.HPP_NETWORK,
+        signer,
+        autoTopup,
+        bridgeName: PKG_NAME,
+        bridgeVersion: PKG_VERSION,
+    });
+    // ---- stdio MCP server (host-facing) ---------------------------------
+    await startBridgeServer({
+        upstream,
+        name: PKG_NAME,
+        version: PKG_VERSION,
+    });
+    // Graceful shutdown: when the host closes our stdin (or Claude Desktop
+    // restarts), node exits. Belt-and-suspenders: handle signals too.
+    const shutdown = async (sig) => {
+        log.info("bridge.shutdown", { signal: sig });
+        await upstream.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+}
+// Auto-run when invoked directly (npx, node dist/index.js).
+// `import.meta.url` matches `process.argv[1]` only for the entry script.
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runBridge().catch((err) => {
+        log.error("bridge.fatal", { err: err.message });
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/log.d.ts

@@ -0,0 +1,16 @@
+/**
+ * stderr-only logger.
+ *
+ * stdin/stdout are reserved for the MCP JSON-RPC protocol; any log line
+ * on stdout corrupts the protocol stream and will crash the host. All
+ * logging goes to stderr (which Claude Desktop / OpenClaw discard or
+ * route to their own debug output).
+ */
+type Level = "off" | "info" | "debug";
+export declare function setLogLevel(level: Level): void;
+export declare const log: {
+    info: (msg: string, extra?: Record<string, unknown>) => void;
+    debug: (msg: string, extra?: Record<string, unknown>) => void;
+    error: (msg: string, extra?: Record<string, unknown>) => void;
+};
+export {};

package/dist/log.js

@@ -0,0 +1,24 @@
+const order = { off: 0, info: 1, debug: 2 };
+let current = "info";
+export function setLogLevel(level) {
+    current = level;
+}
+function emit(level, msg, extra) {
+    if (order[current] < order[level])
+        return;
+    const line = extra
+        ? `[${level}] ${msg} ${JSON.stringify(extra)}`
+        : `[${level}] ${msg}`;
+    process.stderr.write(line + "\n");
+}
+export const log = {
+    info: (msg, extra) => emit("info", msg, extra),
+    debug: (msg, extra) => emit("debug", msg, extra),
+    error: (msg, extra) => {
+        // Errors always emit, regardless of level (off still suppresses).
+        if (current === "off")
+            return;
+        process.stderr.write(`[error] ${msg}` + (extra ? " " + JSON.stringify(extra) : "") + "\n");
+    },
+};
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAUA,MAAM,KAAK,GAA0B,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAEnE,IAAI,OAAO,GAAU,MAAM,CAAC;AAE5B,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,OAAO,GAAG,KAAK,CAAC;AAClB,CAAC;AAED,SAAS,IAAI,CAAC,KAAY,EAAE,GAAW,EAAE,KAA+B;IACtE,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO;IAC1C,MAAM,IAAI,GAAG,KAAK;QAChB,CAAC,CAAC,IAAI,KAAK,KAAK,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE;QAC9C,CAAC,CAAC,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;IACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,IAAI,EAAE,CAAC,GAAW,EAAE,KAA+B,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC;IAChF,KAAK,EAAE,CAAC,GAAW,EAAE,KAA+B,EAAE,EAAE,CACtD,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC;IAC3B,KAAK,EAAE,CAAC,GAAW,EAAE,KAA+B,EAAE,EAAE;QACtD,kEAAkE;QAClE,IAAI,OAAO,KAAK,KAAK;YAAE,OAAO;QAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,WAAW,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CACrE,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import type { UpstreamClient } from "./client.js";
+export interface BridgeServerOptions {
+    upstream: UpstreamClient;
+    name: string;
+    version: string;
+}
+export declare function startBridgeServer(opts: BridgeServerOptions): Promise<void>;

package/dist/server.js

@@ -0,0 +1,56 @@
+/**
+ * stdio MCP server — what the host (Claude Desktop / OpenClaw / Cursor)
+ * actually connects to.
+ *
+ * It's a thin proxy: tools are pulled from upstream on listTools, and
+ * callTool forwards through the payment-wrapped upstream client. The host
+ * sees a normal MCP server with paid tools that "just work".
+ *
+ * If autoTopup or the payment retry fails, the bridge surfaces the error
+ * as a tool-result with `isError: true` so the LLM can see what happened
+ * (e.g. "spend cap exceeded"). Throwing instead would crash the MCP RPC
+ * stream.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { log } from "./log.js";
+export async function startBridgeServer(opts) {
+    const server = new Server({ name: opts.name, version: opts.version }, { capabilities: { tools: {} } });
+    // ---- listTools — pass through from upstream -------------------------
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const upstreamTools = await opts.upstream.base.listTools();
+        log.debug("listTools", { count: upstreamTools.tools.length });
+        return { tools: upstreamTools.tools };
+    });
+    // ---- callTool — forward through x402-aware wrapper ------------------
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args } = req.params;
+        log.info("callTool.start", { name });
+        try {
+            const result = await opts.upstream.x402.callTool(name, (args ?? {}));
+            log.info("callTool.done", {
+                name,
+                paymentMade: result.paymentMade ?? false,
+            });
+            // Strip bridge-internal fields (paymentMade, paymentResponse) before
+            // returning to host — they're not part of the MCP CallToolResult shape.
+            return {
+                content: result.content,
+                isError: result.isError,
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log.error("callTool.failed", { name, err: msg });
+            return {
+                content: [{ type: "text", text: `bridge error: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log.info("bridge.ready");
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oCAAoC,CAAC;AAG5C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAQ/B,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAyB;IAC/D,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAC1C,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;IAEF,wEAAwE;IACxE,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QAC3D,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9D,OAAO,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,EAAE,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,wEAAwE;IACxE,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QAC5D,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC;QAC7C,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAErC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAC9C,IAAI,EACJ,CAAC,IAAI,IAAI,EAAE,CAA4B,CACxC,CAAC;YAEF,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE;gBACxB,IAAI;gBACJ,WAAW,EAAG,MAAoC,CAAC,WAAW,IAAI,KAAK;aACxE,CAAC,CAAC;YAEH,qEAAqE;YACrE,wEAAwE;YACxE,OAAO;gBACL,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,OAAO,EAAE,MAAM,CAAC,OAAO;aACxB,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,GAAG,CAAC,KAAK,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;YACjD,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,iBAAiB,GAAG,EAAE,EAAE,CAAC;gBAClE,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAC3B,CAAC"}

package/dist/signer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Signer abstraction.
+ *
+ * The bridge needs two signing capabilities:
+ *   1. EIP-712 typed-data — for x402 EIP-3009 transferWithAuthorization
+ *      and AllowanceModule.AllowanceTransfer.
+ *   2. Generic transactions — for sending the executeAllowanceTransfer
+ *      call (the delegate is the tx sender + payer of gas).
+ *
+ * The PoC implementation is a raw-key viem account (`signers/raw-eoa.ts`).
+ * Future implementations swap in:
+ *   - OS keychain wrapper (still raw key, just unsealed lazily)
+ *   - HPP self-hosted server-wallet API (HTTP signing)
+ *   - Coinbase CDP / Turnkey / Privy (if HPP support arrives)
+ *   - ERC-4337 smart account session keys
+ *
+ * Importantly, x402 EIP-3009 verification on USDC.e (FiatTokenV2_2) accepts
+ * EIP-1271 contract signatures (verified 2026-04-30) — so a *contract*
+ * wallet (Safe, smart account) can also fit this interface, returning a
+ * Safe-format signature blob from `signTypedData`.
+ */
+import type { Address, Hex, TypedDataDomain } from "viem";
+export interface Signer {
+    /** Address that x402 / AllowanceModule sees as the signer / sender. */
+    readonly address: Address;
+    /**
+     * Sign EIP-712 typed data. The bridge uses this for:
+     *   - EIP-3009 TransferWithAuthorization (x402 payment)
+     *   - AllowanceModule AllowanceTransfer (autoTopup)
+     *
+     * Returns the signature in the form the verifier expects:
+     *   - EOA: 65-byte ECDSA (r ‖ s ‖ v)
+     *   - Contract wallet: implementation-specific blob accepted by
+     *     EIP-1271 isValidSignature
+     */
+    signTypedData(args: {
+        domain: TypedDataDomain;
+        types: Record<string, {
+            name: string;
+            type: string;
+        }[]>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<Hex>;
+}

package/dist/signer.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=signer.js.map

package/dist/signer.js.map

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

package/dist/signers/raw-eoa.d.ts

@@ -0,0 +1,12 @@
+import type { Address, Hex, PrivateKeyAccount } from "viem";
+import type { Signer } from "../signer.js";
+export declare class RawEoaSigner implements Signer {
+    readonly address: Address;
+    private readonly account;
+    constructor(privateKey: Hex);
+    /** Expose the underlying viem account for callers that need it
+     *  (writeContract / sendTransaction). Not part of the Signer interface;
+     *  bridge-internal use only. */
+    get viemAccount(): PrivateKeyAccount;
+    signTypedData(args: Parameters<Signer["signTypedData"]>[0]): Promise<Hex>;
+}

package/dist/signers/raw-eoa.js

@@ -0,0 +1,29 @@
+/**
+ * RawEoaSigner — viem PrivateKeyAccount wrapped to fit `Signer`.
+ *
+ * The most permissive signer. Accepts a 0x-prefixed 32-byte private key
+ * directly. Used as the PoC default; production deployments should layer
+ * an OS keychain or wallet service in front of this.
+ */
+import { privateKeyToAccount } from "viem/accounts";
+export class RawEoaSigner {
+    address;
+    account;
+    constructor(privateKey) {
+        this.account = privateKeyToAccount(privateKey);
+        this.address = this.account.address;
+    }
+    /** Expose the underlying viem account for callers that need it
+     *  (writeContract / sendTransaction). Not part of the Signer interface;
+     *  bridge-internal use only. */
+    get viemAccount() {
+        return this.account;
+    }
+    async signTypedData(args) {
+        // viem's signTypedData uses overload narrowing keyed on `primaryType`
+        // and the literal `types` shape. The bridge passes user-built typed
+        // data at runtime, so we widen via the loose overload.
+        return this.account.signTypedData(args);
+    }
+}
+//# sourceMappingURL=raw-eoa.js.map

package/dist/signers/raw-eoa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-eoa.js","sourceRoot":"","sources":["../../src/signers/raw-eoa.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAKpD,MAAM,OAAO,YAAY;IACd,OAAO,CAAU;IACT,OAAO,CAAoB;IAE5C,YAAY,UAAe;QACzB,IAAI,CAAC,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;QAC/C,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;IACtC,CAAC;IAED;;oCAEgC;IAChC,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,IAA4C;QAC9D,sEAAsE;QACtE,oEAAoE;QACpE,uDAAuD;QACvD,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,IAAyD,CAAC,CAAC;IAC/F,CAAC;CACF"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@hpp-io/x402-mcp-bridge",
+  "version": "0.0.1",
+  "description": "MCP stdio bridge that lets Claude Desktop / OpenClaw / other MCP hosts make x402 payments on HPP — autoTopup from a Safe via AllowanceModule, signs EIP-3009 with a delegate EOA.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "x402-mcp-bridge": "bin/x402-mcp-bridge.js",
+    "hpp-x402-safe-setup": "bin/hpp-x402-safe-setup.js",
+    "hpp-x402-safe-revoke": "bin/hpp-x402-safe-revoke.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@x402/core": "^2.10.0",
+    "@x402/evm": "^2.10.0",
+    "@x402/mcp": "^2.10.0",
+    "viem": "^2.21.54",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0"
+  }
+}