@runtab/mcp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blockchain Oracle (Tab)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bootstrap.d.ts

@@ -0,0 +1,18 @@
+import { type PaymentProfile } from "./payment-profile.js";
+interface ConnectLeashAgentOptions {
+    apiBaseUrl: string;
+    apiKey: string;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+}
+export interface ConnectedLeashAgent {
+    address: `0x${string}` | null;
+    paymentProfile: PaymentProfile;
+}
+export declare class LeashConnectError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}
+export declare function connectLeashAgent(options: ConnectLeashAgentOptions): Promise<ConnectedLeashAgent>;
+export {};

package/dist/bootstrap.js

@@ -0,0 +1,125 @@
+import { isAddress } from "viem";
+import { validateControlPlaneOrigin } from "./control-plane-origin.js";
+import { isPaymentProfile } from "./payment-profile.js";
+const MAX_CONNECT_RESPONSE_BYTES = 65_536;
+export class LeashConnectError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "LeashConnectError";
+    }
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorCode(value) {
+    if (!record(value) || !record(value.error) || typeof value.error.code !== "string") {
+        return "CONNECT_FAILED";
+    }
+    return /^[A-Z0-9_]{1,64}$/.test(value.error.code) ? value.error.code : "CONNECT_FAILED";
+}
+function invalidConnectResponse() {
+    throw new LeashConnectError("INVALID_CONNECT_RESPONSE", "The agent control plane returned an invalid response.", 502);
+}
+async function responseJson(response, signal) {
+    if (!response.body)
+        invalidConnectResponse();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    let rejectAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        rejectAbort = reject;
+    });
+    const cancelReader = () => {
+        void reader.cancel().catch(() => undefined);
+    };
+    const onAbort = () => {
+        cancelReader();
+        rejectAbort?.(signal.reason ?? new Error("Aborted"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        if (signal.aborted)
+            onAbort();
+        while (true) {
+            const result = await Promise.race([reader.read(), aborted]);
+            if (result.done)
+                break;
+            length += result.value.byteLength;
+            if (length > MAX_CONNECT_RESPONSE_BYTES) {
+                cancelReader();
+                invalidConnectResponse();
+            }
+            chunks.push(result.value);
+        }
+    }
+    catch (error) {
+        if (error instanceof LeashConnectError)
+            throw error;
+        cancelReader();
+        throw new LeashConnectError("CONNECT_FAILED", "The agent control plane could not be reached.", 503);
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // An aborted read may hold the lock until cancellation finishes.
+        }
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        invalidConnectResponse();
+    }
+}
+export async function connectLeashAgent(options) {
+    const fetch_ = options.fetch ?? globalThis.fetch;
+    const apiBaseUrl = validateControlPlaneOrigin(options.apiBaseUrl);
+    const timeout = AbortSignal.timeout(10_000);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    let response;
+    try {
+        response = await fetch_(new URL("/api/agent/connect", apiBaseUrl), {
+            body: JSON.stringify({ transport: "mcp" }),
+            headers: {
+                accept: "application/json",
+                authorization: `Bearer ${options.apiKey}`,
+                "content-type": "application/json",
+            },
+            method: "POST",
+            redirect: "error",
+            signal,
+        });
+    }
+    catch {
+        throw new LeashConnectError("CONNECT_FAILED", "The agent control plane could not be reached.", 503);
+    }
+    const body = await responseJson(response, signal);
+    if (!response.ok) {
+        throw new LeashConnectError(errorCode(body), "The agent control plane rejected the connection.", response.status);
+    }
+    if (!record(body) ||
+        !record(body.agent) ||
+        !("address" in body.agent) ||
+        !isPaymentProfile(body.paymentProfile)) {
+        throw new LeashConnectError("INVALID_CONNECT_RESPONSE", "The agent control plane returned an invalid response.", 502);
+    }
+    const address = body.agent.address;
+    if (address !== null && (typeof address !== "string" || !isAddress(address))) {
+        throw new LeashConnectError("INVALID_CONNECT_RESPONSE", "The agent control plane returned an invalid response.", 502);
+    }
+    return { address, paymentProfile: body.paymentProfile };
+}

package/dist/cli-config.d.ts

@@ -0,0 +1,11 @@
+export interface LeashCliConfig {
+    allowDevelopmentLoopback: boolean;
+    apiBaseUrl: string;
+    apiKey: string;
+    upstreamUrl: string | null;
+}
+export declare class CliConfigurationError extends Error {
+    readonly code = "INVALID_CONFIGURATION";
+    constructor(message: string);
+}
+export declare function parseLeashCliConfig(arguments_: readonly string[], environment: Readonly<Record<string, string | undefined>>): LeashCliConfig;

package/dist/cli-config.js

@@ -0,0 +1,59 @@
+import { validateControlPlaneOrigin } from "./control-plane-origin.js";
+import { validatePaymentTarget } from "./payment-target-policy.js";
+const LEASH_KEY_PATTERN = /^agent_sk_[A-Za-z0-9_-]{43}$/;
+export class CliConfigurationError extends Error {
+    code = "INVALID_CONFIGURATION";
+    constructor(message) {
+        super(message);
+        this.name = "CliConfigurationError";
+    }
+}
+function httpUrl(value, field, allowDevelopmentLoopback) {
+    try {
+        return validatePaymentTarget(value, { allowDevelopmentLoopback });
+    }
+    catch {
+        throw new CliConfigurationError(`${field} must use HTTPS, except for loopback development.`);
+    }
+}
+function apiBaseUrl(value) {
+    if (!value || value.trim() !== value) {
+        throw new CliConfigurationError("TAB_API_BASE_URL is required.");
+    }
+    try {
+        return validateControlPlaneOrigin(value);
+    }
+    catch {
+        throw new CliConfigurationError("TAB_API_BASE_URL must be an HTTPS origin, except for loopback development.");
+    }
+}
+function apiKey(value) {
+    if (!value || !LEASH_KEY_PATTERN.test(value)) {
+        throw new CliConfigurationError("TAB_AGENT_KEY is missing or malformed.");
+    }
+    return value;
+}
+function developmentLoopback(value) {
+    if (value === undefined || value === "0")
+        return false;
+    if (value === "1")
+        return true;
+    throw new CliConfigurationError("TAB_ALLOW_DEVELOPMENT_LOOPBACK must be 0 or 1.");
+}
+function upstreamUrl(arguments_, allowDevelopmentLoopback) {
+    if (arguments_.length === 0)
+        return null;
+    if (arguments_.length !== 2 || arguments_[0] !== "--upstream" || !arguments_[1]) {
+        throw new CliConfigurationError("Usage: tab-mcp [--upstream <absolute-http-url>]");
+    }
+    return httpUrl(arguments_[1], "--upstream", allowDevelopmentLoopback);
+}
+export function parseLeashCliConfig(arguments_, environment) {
+    const allowDevelopmentLoopback = developmentLoopback(environment.TAB_ALLOW_DEVELOPMENT_LOOPBACK);
+    return {
+        allowDevelopmentLoopback,
+        apiBaseUrl: apiBaseUrl(environment.TAB_API_BASE_URL),
+        apiKey: apiKey(environment.TAB_AGENT_KEY),
+        upstreamUrl: upstreamUrl(arguments_, allowDevelopmentLoopback),
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { LeashConnectError } from "./bootstrap.js";
+import { CliConfigurationError, parseLeashCliConfig } from "./cli-config.js";
+import { startLeashMcp } from "./runtime.js";
+function startupMessage(error) {
+    if (error instanceof CliConfigurationError || error instanceof LeashConnectError) {
+        return error.message;
+    }
+    return "Tab MCP could not start.";
+}
+async function main() {
+    const config = parseLeashCliConfig(process.argv.slice(2), process.env);
+    const runtime = await startLeashMcp({ config });
+    let closing = false;
+    const close = () => {
+        if (closing)
+            return;
+        closing = true;
+        void runtime.close().catch(() => {
+            process.exitCode = 1;
+        });
+    };
+    process.stdin.once("end", close);
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+}
+try {
+    await main();
+}
+catch (error) {
+    process.stderr.write(`tab-mcp: ${startupMessage(error)}\n`);
+    process.exitCode = 1;
+}

package/dist/control-plane-origin.d.ts

@@ -0,0 +1,4 @@
+export declare class InvalidControlPlaneOriginError extends Error {
+    constructor();
+}
+export declare function validateControlPlaneOrigin(value: string): string;

package/dist/control-plane-origin.js

@@ -0,0 +1,27 @@
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "localhost"]);
+export class InvalidControlPlaneOriginError extends Error {
+    constructor() {
+        super("The agent control-plane origin is invalid.");
+        this.name = "InvalidControlPlaneOriginError";
+    }
+}
+export function validateControlPlaneOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new InvalidControlPlaneOriginError();
+    }
+    const secure = url.protocol === "https:";
+    const loopbackDevelopment = url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+    if ((!secure && !loopbackDevelopment) ||
+        url.username.length > 0 ||
+        url.password.length > 0 ||
+        url.pathname !== "/" ||
+        url.search.length > 0 ||
+        url.hash.length > 0) {
+        throw new InvalidControlPlaneOriginError();
+    }
+    return url.toString();
+}

package/dist/detect.d.ts

@@ -0,0 +1,10 @@
+import type { PaymentRequired } from "@x402/core/types";
+interface LegacyPaymentRequired {
+    accepts: unknown[];
+    error?: string;
+    x402Version: 1;
+}
+export type DetectedPaymentRequired = PaymentRequired | LegacyPaymentRequired;
+export declare function detectMcpPaymentRequired(value: unknown): PaymentRequired | null;
+export declare function detectHttpPaymentRequired(response: Response): Promise<DetectedPaymentRequired | null>;
+export {};

package/dist/detect.js

@@ -0,0 +1,74 @@
+import { decodePaymentRequiredHeader } from "@x402/core/http";
+import { extractPaymentRequiredFromError, isPaymentRequiredError } from "@x402/mcp";
+function record(value) {
+    return typeof value === "object" && value !== null;
+}
+function paymentRequired(value) {
+    if (!record(value) || typeof value.x402Version !== "number")
+        return null;
+    if (!Array.isArray(value.accepts) || value.accepts.length === 0)
+        return null;
+    if (!record(value.resource) || typeof value.resource.url !== "string")
+        return null;
+    return value;
+}
+function legacyPaymentRequired(value) {
+    if (!record(value) || value.x402Version !== 1)
+        return null;
+    if (!Array.isArray(value.accepts) || value.accepts.length === 0)
+        return null;
+    return value;
+}
+function paymentRequiredFromText(value) {
+    if (!record(value) || value.type !== "text" || typeof value.text !== "string")
+        return null;
+    try {
+        return paymentRequired(JSON.parse(value.text));
+    }
+    catch {
+        return null;
+    }
+}
+export function detectMcpPaymentRequired(value) {
+    if (isPaymentRequiredError(value)) {
+        const extracted = extractPaymentRequiredFromError(value);
+        if (extracted)
+            return extracted;
+        const data = value.data;
+        if (record(data)) {
+            return paymentRequired(data.x402) ?? paymentRequired(data);
+        }
+    }
+    if (!record(value) || value.isError !== true)
+        return null;
+    const structured = paymentRequired(value.structuredContent);
+    if (structured)
+        return structured;
+    if (!Array.isArray(value.content))
+        return null;
+    for (const item of value.content) {
+        const detected = paymentRequiredFromText(item);
+        if (detected)
+            return detected;
+    }
+    return null;
+}
+export async function detectHttpPaymentRequired(response) {
+    if (response.status !== 402)
+        return null;
+    const header = response.headers.get("PAYMENT-REQUIRED");
+    if (header) {
+        try {
+            return paymentRequired(decodePaymentRequiredHeader(header));
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        return legacyPaymentRequired(await response.clone().json());
+    }
+    catch {
+        return null;
+    }
+}

package/dist/durable-mcp-payment.d.ts

@@ -0,0 +1,40 @@
+import { type x402Client } from "@x402/core/client";
+import type { PaymentPayload, PaymentRequired, SettleResponse } from "@x402/core/types";
+import type { readPaymentAuthorizationState } from "./payment-authorization-state.js";
+import type { PaymentEnvelopeStore } from "./payment-envelope-store.js";
+import type { PaymentProfile } from "./payment-profile.js";
+import type { TabRemoteSigner } from "./remote-signer.js";
+export declare const MCP_PAYMENT_IDEMPOTENCY_META_KEY = "tab/payment-idempotency-key";
+interface DurableMcpPaymentOptions {
+    address: `0x${string}`;
+    authorizationState?: typeof readPaymentAuthorizationState;
+    client: x402Client;
+    nowSeconds?: () => number;
+    paymentProfile: PaymentProfile;
+    signer: TabRemoteSigner;
+    store: PaymentEnvelopeStore;
+}
+export interface McpPaymentContext {
+    idempotencyKey: string;
+    payload: PaymentPayload;
+    requestFingerprint: string;
+}
+export declare function createDurableMcpPayment(options: DurableMcpPaymentOptions): {
+    create(params: Record<string, unknown>, challenge: PaymentRequired): Promise<McpPaymentContext>;
+    load(params: Record<string, unknown>): Promise<McpPaymentContext | null>;
+    observe(context: McpPaymentContext, settlement: SettleResponse): Promise<{
+        status: "failed";
+        verified: true;
+    } | {
+        status: "pending";
+        verified: false;
+    } | {
+        status: "settled";
+        verified: true;
+    } | {
+        readonly status: "ignored";
+        readonly verified: false;
+    }>;
+};
+export type DurableMcpPayment = ReturnType<typeof createDurableMcpPayment>;
+export {};

package/dist/durable-mcp-payment.js

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import { x402HTTPClient } from "@x402/core/client";
+import { MCP_PAYMENT_META_KEY } from "@x402/mcp";
+import { newPaymentEnvelope } from "./payment-envelope.js";
+import { PaymentEnvelopeJournal, PaymentIdempotencyRequiredError, } from "./payment-envelope-journal.js";
+import { validatePaymentIdempotencyKey } from "./payment-envelope-model.js";
+export const MCP_PAYMENT_IDEMPOTENCY_META_KEY = "tab/payment-idempotency-key";
+const MAX_MCP_PAYMENT_REQUEST_BYTES = 1_048_576;
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function canonical(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (record(value)) {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, canonical(value[key])]));
+    }
+    throw new Error("The MCP payment request is invalid");
+}
+function paymentRequest(params) {
+    const copy = { ...params };
+    if (record(copy._meta)) {
+        const meta = { ...copy._meta };
+        delete meta[MCP_PAYMENT_IDEMPOTENCY_META_KEY];
+        delete meta[MCP_PAYMENT_META_KEY];
+        copy._meta = meta;
+    }
+    const serialized = JSON.stringify(canonical(copy));
+    if (Buffer.byteLength(serialized) > MAX_MCP_PAYMENT_REQUEST_BYTES) {
+        throw new Error("The MCP payment request is invalid");
+    }
+    return createHash("sha256").update(serialized).digest("hex");
+}
+function paymentKey(params) {
+    const value = record(params._meta) ? params._meta[MCP_PAYMENT_IDEMPOTENCY_META_KEY] : undefined;
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new PaymentIdempotencyRequiredError();
+    return validatePaymentIdempotencyKey(value);
+}
+export function createDurableMcpPayment(options) {
+    const httpClient = new x402HTTPClient(options.client);
+    const journal = new PaymentEnvelopeJournal({
+        address: options.address,
+        ...(options.authorizationState ? { authorizationState: options.authorizationState } : {}),
+        ...(options.nowSeconds ? { nowSeconds: options.nowSeconds } : {}),
+        paymentProfile: options.paymentProfile,
+        signer: options.signer,
+        store: options.store,
+    });
+    async function parseContext(params, requireKey) {
+        const idempotencyKey = paymentKey(params);
+        if (requireKey && !idempotencyKey)
+            throw new PaymentIdempotencyRequiredError();
+        return {
+            ...(idempotencyKey ? { idempotencyKey } : {}),
+            requestFingerprint: paymentRequest(params),
+        };
+    }
+    return {
+        async create(params, challenge) {
+            const context = await parseContext(params, true);
+            const idempotencyKey = context.idempotencyKey;
+            const envelope = await journal.getOrCreate(idempotencyKey, context.requestFingerprint, async () => {
+                const payload = await options.client.createPaymentPayload(challenge);
+                const header = httpClient.encodePaymentSignatureHeader(payload)["PAYMENT-SIGNATURE"];
+                if (!header)
+                    throw new Error("The x402 payment payload is invalid");
+                return newPaymentEnvelope(payload, header, options.signer);
+            });
+            const parsed = await journal.parse(envelope);
+            return { ...context, idempotencyKey, payload: parsed.payload };
+        },
+        async load(params) {
+            const context = await parseContext(params, false);
+            if (!context.idempotencyKey)
+                return null;
+            const envelope = await journal.load(context.idempotencyKey, context.requestFingerprint);
+            if (!envelope)
+                return null;
+            const parsed = await journal.parse(envelope);
+            await journal.reconcileObserved(context.idempotencyKey, context.requestFingerprint, envelope, parsed);
+            return { ...context, idempotencyKey: context.idempotencyKey, payload: parsed.payload };
+        },
+        async observe(context, settlement) {
+            const parsed = { payload: context.payload };
+            const observed = await journal.recordObservation(context.idempotencyKey, context.requestFingerprint, parsed, settlement);
+            if (!observed)
+                return { status: "ignored", verified: false };
+            await options.client.handlePaymentResponse({
+                paymentPayload: context.payload,
+                requirements: context.payload.accepted,
+                settleResponse: settlement,
+            });
+            return journal.reconcileObserved(context.idempotencyKey, context.requestFingerprint, observed, parsed);
+        },
+    };
+}

package/dist/durable-payment-fetch.d.ts

@@ -0,0 +1,19 @@
+import { type x402Client } from "@x402/core/client";
+import type { readPaymentAuthorizationState } from "./payment-authorization-state.js";
+import { PaymentIdempotencyRequiredError, PaymentReconciliationRequiredError } from "./payment-envelope-journal.js";
+import type { PaymentEnvelopeStore } from "./payment-envelope-store.js";
+import type { PaymentProfile } from "./payment-profile.js";
+import type { TabRemoteSigner } from "./remote-signer.js";
+interface DurablePaymentFetchOptions {
+    address: `0x${string}`;
+    authorizationState?: typeof readPaymentAuthorizationState;
+    client: x402Client;
+    fetch: typeof globalThis.fetch;
+    idempotencyKey: () => string | undefined;
+    nowSeconds?: () => number;
+    paymentProfile: PaymentProfile;
+    signer: TabRemoteSigner;
+    store: PaymentEnvelopeStore;
+}
+export declare function createDurablePaymentFetch(options: DurablePaymentFetchOptions): (input: Request | string | URL, init?: RequestInit) => Promise<Response>;
+export { PaymentIdempotencyRequiredError, PaymentReconciliationRequiredError };