@runtab/mcp 0.0.1

package/dist/remote-signer.js

@@ -0,0 +1,157 @@
+import { isAddress, isAddressEqual, recoverTypedDataAddress } from "viem";
+import { validateControlPlaneOrigin } from "./control-plane-origin.js";
+import { InvalidEip3009AuthorizationError, parseExactEip3009Authorization, } from "./eip3009-authorization.js";
+import { currentPaymentOrigin, currentPaymentResourceUrl } from "./origin-context.js";
+import { PaymentCorrelations } from "./payment-correlation.js";
+import { PaymentObservationReporter } from "./payment-observation-reporter.js";
+import { currentPaymentSignal } from "./payment-signal.js";
+import { postRemoteSignerJson, RemoteSignerError } from "./remote-signer-http.js";
+import { redactPaymentResourceUrl } from "./resource-url.js";
+export { RemoteSignerError } from "./remote-signer-http.js";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export class TabRemoteSigner {
+    address;
+    #apiKey;
+    #correlations;
+    #endpoint;
+    #fetch;
+    #nowSeconds;
+    #observationReporter;
+    #origin;
+    #paymentProfile;
+    #reconcileEndpoint;
+    #resourceUrl;
+    #signal;
+    #signTimeoutMs;
+    constructor(options) {
+        if (!isAddress(options.address))
+            throw new Error("Agent signer address is invalid");
+        if (!options.apiKey)
+            throw new Error("TAB_AGENT_KEY is required");
+        this.address = options.address;
+        this.#apiKey = options.apiKey;
+        const apiBaseUrl = validateControlPlaneOrigin(options.apiBaseUrl);
+        this.#endpoint = new URL("/api/agent/sign", apiBaseUrl);
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#nowSeconds = options.nowSeconds ?? (() => Math.floor(Date.now() / 1_000));
+        this.#correlations = new PaymentCorrelations(this.#nowSeconds);
+        this.#origin = options.origin ?? currentPaymentOrigin;
+        this.#paymentProfile = options.paymentProfile;
+        this.#resourceUrl = options.resourceUrl ?? currentPaymentResourceUrl;
+        const reportAttempts = options.reportAttempts ?? 3;
+        const reportRetryDelayMs = options.reportRetryDelayMs ?? 250;
+        const reportTimeoutMs = options.reportTimeoutMs ?? 7_500;
+        this.#reconcileEndpoint = new URL("/api/agent/pay/reconcile", apiBaseUrl);
+        this.#signal = options.signal ?? currentPaymentSignal;
+        this.#signTimeoutMs = options.signTimeoutMs ?? 10_000;
+        if (!Number.isSafeInteger(reportAttempts) ||
+            reportAttempts < 1 ||
+            !Number.isSafeInteger(reportRetryDelayMs) ||
+            reportRetryDelayMs < 0 ||
+            !Number.isSafeInteger(reportTimeoutMs) ||
+            reportTimeoutMs < 1 ||
+            !Number.isSafeInteger(this.#signTimeoutMs) ||
+            this.#signTimeoutMs < 1) {
+            throw new Error("Agent result-report timeout is invalid");
+        }
+        this.#observationReporter = new PaymentObservationReporter({
+            apiKey: this.#apiKey,
+            attempts: reportAttempts,
+            correlations: this.#correlations,
+            endpoint: new URL("/api/agent/pay/result", apiBaseUrl),
+            fetch: this.#fetch,
+            retryDelayMs: reportRetryDelayMs,
+            timeoutMs: reportTimeoutMs,
+        });
+    }
+    async signTypedData(signerRequest) {
+        let authorization;
+        try {
+            authorization = parseExactEip3009Authorization(signerRequest, {
+                address: this.address,
+                nowSeconds: this.#nowSeconds(),
+                paymentProfile: this.#paymentProfile,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof InvalidEip3009AuthorizationError))
+                throw error;
+            throw new RemoteSignerError("INVALID_SIGNER_REQUEST", "The signer request is invalid.", 400);
+        }
+        const origin = this.#origin?.();
+        const rawResourceUrl = this.#resourceUrl?.();
+        const resourceUrl = rawResourceUrl === undefined ? undefined : redactPaymentResourceUrl(rawResourceUrl);
+        const paymentSignal = this.#signal();
+        const body = (await postRemoteSignerJson({
+            apiKey: this.#apiKey,
+            body: {
+                amount: authorization.amount,
+                asset: authorization.asset,
+                network: authorization.network,
+                ...(origin ? { origin } : {}),
+                payTo: authorization.payTo,
+                ...(resourceUrl ? { resourceUrl } : {}),
+                signerRequest: authorization.typedData,
+            },
+            endpoint: this.#endpoint,
+            fetch: this.#fetch,
+            ...(paymentSignal ? { signal: paymentSignal } : {}),
+            timeoutMs: this.#signTimeoutMs,
+        }));
+        if (typeof body.receiptId !== "string" ||
+            typeof body.signature !== "string" ||
+            !/^0x[0-9a-fA-F]{130}$/.test(body.signature)) {
+            throw new RemoteSignerError("INVALID_SIGNER_RESPONSE", "The signer response is invalid.", 502);
+        }
+        const signature = body.signature;
+        try {
+            const recovered = await recoverTypedDataAddress({
+                ...authorization.typedData,
+                signature,
+            });
+            if (!isAddressEqual(recovered, this.address))
+                throw new Error("Signer mismatch");
+        }
+        catch {
+            throw new RemoteSignerError("INVALID_SIGNER_RESPONSE", "The signer response is invalid.", 502);
+        }
+        this.#correlations.set(signature, body.receiptId, Number(authorization.typedData.message.validBefore));
+        return signature;
+    }
+    receiptIdForSignature(signature) {
+        return this.#correlations.get(signature);
+    }
+    restorePaymentCorrelation(signature, receiptId, validBeforeSeconds) {
+        this.#correlations.restore(signature, receiptId, validBeforeSeconds);
+    }
+    async reconcileExpiredPayment(receiptId) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(receiptId))
+            return false;
+        try {
+            const signal = this.#signal();
+            const acknowledgement = await postRemoteSignerJson({
+                apiKey: this.#apiKey,
+                body: { receiptId },
+                endpoint: this.#reconcileEndpoint,
+                fetch: this.#fetch,
+                ...(signal ? { signal } : {}),
+                timeoutMs: this.#signTimeoutMs,
+            });
+            return (record(acknowledgement) &&
+                acknowledgement.receiptId === receiptId &&
+                acknowledgement.status === "failed" &&
+                acknowledgement.verified === true);
+        }
+        catch {
+            return false;
+        }
+    }
+    reportPaymentObservation(context) {
+        return this.#observationReporter.report(context, this.address);
+    }
+    async flushPaymentObservations() {
+        await this.#observationReporter.flush();
+    }
+}

package/dist/resource-url.d.ts

@@ -0,0 +1,5 @@
+export declare class InvalidPaymentResourceUrlError extends Error {
+    readonly code = "INVALID_PAYMENT_RESOURCE_URL";
+    constructor();
+}
+export declare function redactPaymentResourceUrl(value: string): string;

package/dist/resource-url.js

@@ -0,0 +1,36 @@
+const MAX_RESOURCE_HOST_LENGTH = 253;
+const MAX_RESOURCE_URL_LENGTH = 2_048;
+const SUPPORTED_RESOURCE_PROTOCOLS = new Set(["http:", "https:", "mcp:"]);
+export class InvalidPaymentResourceUrlError extends Error {
+    code = "INVALID_PAYMENT_RESOURCE_URL";
+    constructor() {
+        super("Payment resource URL must be a supported absolute URL.");
+        this.name = "InvalidPaymentResourceUrlError";
+    }
+}
+export function redactPaymentResourceUrl(value) {
+    if (value.length < 1 || value.length > MAX_RESOURCE_URL_LENGTH) {
+        throw new InvalidPaymentResourceUrlError();
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new InvalidPaymentResourceUrlError();
+    }
+    if (!SUPPORTED_RESOURCE_PROTOCOLS.has(url.protocol) ||
+        url.hostname.length < 1 ||
+        url.hostname.length > MAX_RESOURCE_HOST_LENGTH) {
+        throw new InvalidPaymentResourceUrlError();
+    }
+    url.hostname = url.hostname.toLowerCase();
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    const redacted = url.toString();
+    if (redacted.length > MAX_RESOURCE_URL_LENGTH)
+        throw new InvalidPaymentResourceUrlError();
+    return redacted;
+}

package/dist/routing.d.ts

@@ -0,0 +1,13 @@
+import type { PaymentRequirements } from "@x402/core/types";
+import type { PaymentProfile } from "./payment-profile.js";
+export declare const BASE_NETWORK: "eip155:8453";
+export declare const ARBITRUM_NETWORK: "eip155:42161";
+export declare const BASE_SEPOLIA_NETWORK: "eip155:84532";
+export declare const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export declare const ARBITRUM_USDC = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831";
+export declare const BASE_SEPOLIA_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+export declare class UnsupportedPaymentNetworkError extends Error {
+    readonly code = "UNSUPPORTED_NETWORK";
+    constructor();
+}
+export declare function selectLeashPaymentRequirements(paymentProfile: PaymentProfile, x402Version: number, requirements: PaymentRequirements[]): PaymentRequirements;

package/dist/routing.js

@@ -0,0 +1,42 @@
+export const BASE_NETWORK = "eip155:8453";
+export const ARBITRUM_NETWORK = "eip155:42161";
+export const BASE_SEPOLIA_NETWORK = "eip155:84532";
+export const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export const ARBITRUM_USDC = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831";
+export const BASE_SEPOLIA_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+export class UnsupportedPaymentNetworkError extends Error {
+    code = "UNSUPPORTED_NETWORK";
+    constructor() {
+        super("The resource does not accept a supported Agent payment network.");
+        this.name = "UnsupportedPaymentNetworkError";
+    }
+}
+const PROFILE_NETWORKS = {
+    base_sepolia_integration: [
+        { asset: BASE_SEPOLIA_USDC, name: "USDC", network: BASE_SEPOLIA_NETWORK },
+    ],
+    mainnet: [
+        { asset: BASE_USDC, name: "USD Coin", network: BASE_NETWORK },
+        { asset: ARBITRUM_USDC, name: "USD Coin", network: ARBITRUM_NETWORK },
+    ],
+};
+function supportedNetwork(paymentProfile, requirement) {
+    return PROFILE_NETWORKS[paymentProfile].find((entry) => requirement.network === entry.network &&
+        requirement.asset.toLowerCase() === entry.asset.toLowerCase() &&
+        requirement.extra.name === entry.name &&
+        requirement.extra.version === "2");
+}
+export function selectLeashPaymentRequirements(paymentProfile, x402Version, requirements) {
+    if (x402Version !== 2)
+        throw new UnsupportedPaymentNetworkError();
+    const exact = requirements.filter((requirement) => requirement.scheme === "exact" &&
+        supportedNetwork(paymentProfile, requirement) !== undefined &&
+        (requirement.extra.assetTransferMethod === undefined ||
+            requirement.extra.assetTransferMethod === "eip3009"));
+    for (const entry of PROFILE_NETWORKS[paymentProfile]) {
+        const match = exact.find((requirement) => requirement.network === entry.network);
+        if (match)
+            return match;
+    }
+    throw new UnsupportedPaymentNetworkError();
+}

package/dist/runtime.d.ts

@@ -0,0 +1,13 @@
+import type { Readable, Writable } from "node:stream";
+import type { LeashCliConfig } from "./cli-config.js";
+interface StartLeashMcpOptions {
+    config: LeashCliConfig;
+    fetch?: typeof globalThis.fetch;
+    stdin?: Readable;
+    stdout?: Writable;
+}
+export interface LeashMcpRuntime {
+    close(): Promise<void>;
+}
+export declare function startLeashMcp(options: StartLeashMcpOptions): Promise<LeashMcpRuntime>;
+export {};

package/dist/runtime.js

@@ -0,0 +1,92 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { connectLeashAgent } from "./bootstrap.js";
+import { createDurableMcpPayment } from "./durable-mcp-payment.js";
+import { createPaidFetchServer } from "./paid-fetch-server.js";
+import { createLeashPaymentClient } from "./payment-client.js";
+import { defaultPaymentStateDirectory, PaymentEnvelopeStore } from "./payment-envelope-store.js";
+import { createLeashProxyServer } from "./proxy.js";
+import { TabRemoteSigner } from "./remote-signer.js";
+import { connectStreamableHttpUpstream } from "./upstream.js";
+export async function startLeashMcp(options) {
+    const fetch_ = options.fetch ?? globalThis.fetch;
+    const agent = await connectLeashAgent({
+        apiBaseUrl: options.config.apiBaseUrl,
+        apiKey: options.config.apiKey,
+        fetch: fetch_,
+    });
+    let signer;
+    let upstreamConnection;
+    if (agent.address) {
+        signer = new TabRemoteSigner({
+            address: agent.address,
+            apiBaseUrl: options.config.apiBaseUrl,
+            apiKey: options.config.apiKey,
+            fetch: fetch_,
+            paymentProfile: agent.paymentProfile,
+        });
+    }
+    if (options.config.upstreamUrl) {
+        upstreamConnection = await connectStreamableHttpUpstream(options.config.upstreamUrl, {
+            allowDevelopmentLoopback: options.config.allowDevelopmentLoopback,
+            fetch: fetch_,
+        });
+    }
+    const upstream = upstreamConnection?.client;
+    const server = upstream
+        ? createLeashProxyServer({
+            ...(signer
+                ? {
+                    payment: createDurableMcpPayment({
+                        address: signer.address,
+                        client: createLeashPaymentClient(signer, agent.paymentProfile),
+                        paymentProfile: agent.paymentProfile,
+                        signer,
+                        store: new PaymentEnvelopeStore(signer.address, defaultPaymentStateDirectory()),
+                    }),
+                }
+                : {}),
+            upstream,
+        })
+        : createPaidFetchServer({
+            address: agent.address,
+            allowDevelopmentLoopback: options.config.allowDevelopmentLoopback,
+            apiBaseUrl: options.config.apiBaseUrl,
+            apiKey: options.config.apiKey,
+            fetch: fetch_,
+            paymentProfile: agent.paymentProfile,
+            ...(signer ? { signer } : {}),
+        });
+    let resourceClosePromise;
+    const closeResources = () => {
+        resourceClosePromise ??= (async () => {
+            if (signer)
+                await signer.flushPaymentObservations();
+            if (upstreamConnection)
+                await upstreamConnection.close();
+        })();
+        return resourceClosePromise;
+    };
+    const closeServerResources = server.onclose;
+    server.onclose = () => {
+        closeServerResources?.();
+        void closeResources();
+    };
+    const transport = new StdioServerTransport(options.stdin, options.stdout);
+    try {
+        await server.connect(transport);
+    }
+    catch (error) {
+        await closeResources();
+        throw error;
+    }
+    let closePromise;
+    return {
+        close() {
+            closePromise ??= (async () => {
+                await server.close();
+                await closeResources();
+            })();
+            return closePromise;
+        },
+    };
+}

package/dist/upstream.d.ts

@@ -0,0 +1,43 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { type PaymentTargetLookup } from "./payment-target-network.js";
+export declare function connectStreamableHttpUpstream(endpoint: string, options?: {
+    allowDevelopmentLoopback?: boolean;
+    fetch?: typeof globalThis.fetch;
+    lookup?: PaymentTargetLookup;
+}): Promise<{
+    client: Client<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    close(): Promise<void>;
+}>;

package/dist/upstream.js

@@ -0,0 +1,38 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { createPinnedPaymentFetch } from "./payment-target-network.js";
+export async function connectStreamableHttpUpstream(endpoint, options = {}) {
+    const client = new Client({ name: "tab-mcp-upstream", version: "0.0.1" });
+    const policy = createPinnedPaymentFetch({
+        allowDevelopmentLoopback: options.allowDevelopmentLoopback === true,
+        fetch: options.fetch ?? globalThis.fetch,
+        ...(options.lookup ? { lookup: options.lookup } : {}),
+    });
+    const transport = new StreamableHTTPClientTransport(new URL(endpoint), {
+        fetch: policy.fetch,
+    });
+    try {
+        // SDK 1.29's exact-optional transport declarations are structurally incompatible.
+        await client.connect(transport);
+        let closePromise;
+        return {
+            client,
+            close() {
+                closePromise ??= (async () => {
+                    try {
+                        await client.close();
+                    }
+                    finally {
+                        await policy.close();
+                    }
+                })();
+                return closePromise;
+            },
+        };
+    }
+    catch (error) {
+        await transport.close().catch(() => undefined);
+        await policy.close().catch(() => undefined);
+        throw error;
+    }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@runtab/mcp",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "tab-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./fetch": {
+      "types": "./dist/fetch.d.ts",
+      "import": "./dist/fetch.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc --build tsconfig.build.json --force",
+    "dev": "tsc --watch --preserveWatchOutput --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "lint": "biome check .",
+    "verify:pack": "node scripts/verify-packed-artifact.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@x402/core": "~2.17.0",
+    "@x402/evm": "~2.17.0",
+    "@x402/mcp": "~2.17.0",
+    "fs-native-extensions": "1.5.0",
+    "undici": "7.28.0",
+    "viem": "^2.48.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "4.23.1",
+    "typescript": "^5.8",
+    "vitest": "^4.1.10"
+  },
+  "description": "Tab MCP proxy: lets an AI agent pay x402 (HTTP 402) charges in USDC under a server-enforced spending cap \u2014 the agent never holds a key.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Blockchain-Oracle/tab.git",
+    "directory": "apps/agent"
+  },
+  "keywords": [
+    "mcp",
+    "x402",
+    "ai-agent",
+    "payments",
+    "usdc",
+    "model-context-protocol"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}