@aifinpay/mcp 1.5.3 → 2.0.0-rc.12

package/dist/tools/{pay-with-split.d.ts → production-control.d.ts}

@@ -1,28 +1,11 @@
 import type { ToolContext } from "../server.js";
-export declare function payWithSplitTool(): {
+export declare function agentPassportResolveTool(): {
     name: string;
     description: string;
     inputSchema: {
         type: string;
         properties: {
-            chain: {
-                type: string;
-                enum: string[];
-                description: string;
-            };
-            merchant_wallet: {
-                type: string;
-                description: string;
-            };
-            merchant_amount: {
-                type: string;
-                description: string;
-            };
-            order_id: {
-                type: string;
-                description: string;
-            };
-            fee_recipient: {
+            identifier: {
                 type: string;
                 description: string;
             };
@@ -38,30 +21,69 @@ export declare function payWithSplitTool(): {
         type: string;
     };
 };
-export declare function runPayWithSplit(ctx: ToolContext, args: Record<string, unknown>): Promise<{
-    isError: boolean;
+export declare function runAgentPassportResolve(ctx: ToolContext, args: Record<string, unknown>): Promise<{
     content: {
         type: string;
         text: string;
     }[];
-} | {
+}>;
+export declare function settlementRoutesTool(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            route_class: {
+                type: string;
+                enum: string[];
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+    };
+    outputSchema: {
+        type: string;
+    };
+};
+export declare function runSettlementRoutes(ctx: ToolContext, args: Record<string, unknown>): Promise<{
     content: {
         type: string;
         text: string;
     }[];
-    structuredContent: Record<string, unknown>;
 }>;
-export declare function quoteSplitTool(): {
+export declare function settlementInvoiceTool(): {
     name: string;
     description: string;
     inputSchema: {
         type: string;
         properties: {
+            route_class: {
+                type: string;
+                enum: string[];
+            };
             chain: {
                 type: string;
                 enum: string[];
             };
-            merchant_amount: {
+            asset: {
+                type: string;
+                description: string;
+            };
+            gross_amount: {
+                type: string;
+                description: string;
+            };
+            merchant_wallet: {
+                type: string;
+                description: string;
+            };
+            order_id: {
+                type: string;
+            };
+            valid_until: {
                 type: string;
                 description: string;
             };
@@ -77,17 +99,10 @@ export declare function quoteSplitTool(): {
         type: string;
     };
 };
-export declare function runQuoteSplit(ctx: ToolContext, args: Record<string, unknown>): Promise<{
-    isError: boolean;
-    content: {
-        type: string;
-        text: string;
-    }[];
-} | {
+export declare function runSettlementInvoice(ctx: ToolContext, args: Record<string, unknown>): Promise<{
     content: {
         type: string;
         text: string;
     }[];
-    structuredContent: Record<string, unknown>;
 }>;
-//# sourceMappingURL=pay-with-split.d.ts.map
+//# sourceMappingURL=production-control.d.ts.map

package/dist/tools/production-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"production-control.d.ts","sourceRoot":"","sources":["../../src/tools/production-control.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AA+BhD,wBAAgB,wBAAwB;;;;;;;;;;;;;;;;;;;;;EAgBvC;AAED,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GAS5F;AAED,wBAAgB,oBAAoB;;;;;;;;;;;;;;;;;;;;EAgBnC;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GAQxF;AAED,wBAAgB,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsBpC;AAED,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GAuBzF"}

package/dist/tools/production-control.js

@@ -0,0 +1,132 @@
+import { apiUrl } from "../api.js";
+const DEFAULT_BASE = "https://aifinpay.io";
+const ROUTES = new Set(["AIFP-1", "AIFP-2"]);
+const CHAINS = new Set([
+    "polygon", "avalanche", "arbitrum", "bnb", "base",
+    "unichain", "optimism", "botchain", "xrplevm",
+]);
+function result(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+function errorResult(message) {
+    return { isError: true, content: [{ type: "text", text: message }] };
+}
+function base(ctx) {
+    return String(ctx.config.baseUrl || DEFAULT_BASE).replace(/\/$/, "");
+}
+async function api(ctx, path, init) {
+    const response = await ctx.agent.inner.fetchImpl(apiUrl(base(ctx), path), init);
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+        const detail = body && typeof body === "object"
+            ? JSON.stringify(body)
+            : `HTTP ${response.status}`;
+        throw new Error(detail);
+    }
+    return body;
+}
+export function agentPassportResolveTool() {
+    return {
+        name: "agent_passport_resolve",
+        description: "Resolve an AiFinPay Agent Passport by @username, permanent AIFP number, or immutable agent id. " +
+            "Returns verified public wallet bindings only. Resolution never authorizes a payment.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                identifier: { type: "string", description: "@username, AIFP-#########, or aifp_agent_* id" },
+            },
+            required: ["identifier"],
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
+        outputSchema: { type: "object" },
+    };
+}
+export async function runAgentPassportResolve(ctx, args) {
+    const identifier = String(args.identifier || "").trim();
+    if (!identifier)
+        return errorResult("missing required arg: identifier");
+    try {
+        const body = await api(ctx, `/api/agent/resolve/${encodeURIComponent(identifier)}`);
+        return result(body);
+    }
+    catch (e) {
+        return errorResult(`Agent Passport resolve failed: ${e.message}`);
+    }
+}
+export function settlementRoutesTool() {
+    return {
+        name: "settlement_routes",
+        description: "Read AiFinPay's currently runtime-verified v1.3 settlement routes. " +
+            "AIFP-1 is merchant monetisation (99% merchant / 1% AiFinPay / 0% creator). " +
+            "AIFP-2/x402 is 100% provider / 0% AiFinPay / 0% creator.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                route_class: { type: "string", enum: ["AIFP-1", "AIFP-2"] },
+            },
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
+        outputSchema: { type: "object" },
+    };
+}
+export async function runSettlementRoutes(ctx, args) {
+    const route = args.route_class == null ? "" : String(args.route_class).toUpperCase();
+    if (route && !ROUTES.has(route))
+        return errorResult("route_class must be AIFP-1 or AIFP-2");
+    try {
+        return result(await api(ctx, `/v1/settlement/routes${route ? `?route_class=${encodeURIComponent(route)}` : ""}`));
+    }
+    catch (e) {
+        return errorResult(`Settlement route lookup failed: ${e.message}`);
+    }
+}
+export function settlementInvoiceTool() {
+    return {
+        name: "settlement_invoice",
+        description: "Build and validate a NON-SIGNING v1.3 settlement invoice. This tool never moves funds. " +
+            "Use the published @aifinpay/agent v2 settlement executor to verify bytecode/profile and sign it.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                route_class: { type: "string", enum: ["AIFP-1", "AIFP-2"] },
+                chain: { type: "string", enum: [...CHAINS] },
+                asset: { type: "string", description: "Native symbol, USDC, or USDT if the route advertises it." },
+                gross_amount: { type: "string", description: "Gross payer amount in base units." },
+                merchant_wallet: { type: "string", description: "Merchant/provider EVM wallet." },
+                order_id: { type: "string" },
+                valid_until: { type: "integer", description: "Optional Unix seconds, max 20 minutes ahead." },
+            },
+            required: ["route_class", "chain", "asset", "gross_amount", "merchant_wallet", "order_id"],
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
+        outputSchema: { type: "object" },
+    };
+}
+export async function runSettlementInvoice(ctx, args) {
+    const route = String(args.route_class || "").toUpperCase();
+    const chain = String(args.chain || "").toLowerCase();
+    if (!ROUTES.has(route))
+        return errorResult("route_class must be AIFP-1 or AIFP-2");
+    if (!CHAINS.has(chain))
+        return errorResult("unsupported EVM settlement chain");
+    try {
+        const payload = {
+            route_class: route,
+            chain,
+            asset: String(args.asset || "").toUpperCase(),
+            gross_amount: String(args.gross_amount || ""),
+            merchant_wallet: String(args.merchant_wallet || ""),
+            order_id: String(args.order_id || ""),
+            ...(args.valid_until != null ? { valid_until: Number(args.valid_until) } : {}),
+        };
+        return result(await api(ctx, "/v1/settlement/invoice", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(payload),
+        }));
+    }
+    catch (e) {
+        return errorResult(`Settlement invoice failed: ${e.message}`);
+    }
+}
+//# sourceMappingURL=production-control.js.map

package/dist/tools/production-control.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aifinpay/mcp",
-  "version": "1.5.3",
-  "description": "Pay-per-call MCP server for autonomous AI agents \u2014 installs in Claude Desktop / Cursor / Continue with one config block; on-chain settlement on Polygon and Solana via x402.",
+  "version": "2.0.0-rc.12",
+  "description": "AiFinPay MCP production-RC control surface for Agent Passport resolution and runtime-verified AIFP-1/AIFP-2 settlement invoices. Signing tools remain gated until @aifinpay/agent v2 release.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,8 @@
     "dist",
     "bin",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "skills"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -32,10 +33,9 @@
     "mcp-server",
     "mcp-payments",
     "mcp-monetization",
-    "paid-mcp-tools",
+    "agent-passport",
+    "settlement",
     "x402-mcp",
-    "pay-per-call",
-    "paid-ai-tools",
     "claude-desktop",
     "claude-mcp",
     "cursor",
@@ -46,29 +46,15 @@
     "ai-agent-payments",
     "agentic-ai",
     "autonomous-agents",
-    "autonomous-payments",
     "agent-payments",
     "agent-commerce",
     "agentic-commerce",
     "agent-economy",
     "ai-commerce",
-    "ai-payment-infrastructure",
-    "ai-financial-infrastructure",
     "x402",
     "x402-payments",
     "http-402",
-    "payments",
-    "api-payments",
-    "api-monetization",
-    "machine-payments",
-    "m2m-payments",
-    "programmable-payments",
-    "crypto-payments",
-    "stablecoin-payments",
-    "polygon",
-    "solana",
-    "non-custodial",
-    "stripe-for-ai-agents"
+    "non-custodial"
   ],
   "author": "CoinSecurities (SECCO) <contact@aifinpay.io>",
   "license": "MIT",

package/skills/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: aifinpay
+description: Discover an agent wallet, retrieve payment history and prepaid quotas, resolve public Agent Passport identities, and inspect dev payment quotes through AiFinPay MCP/SDK.
+license: MIT
+---
+
+The current source and compatible package line is **2.0.0-rc.12**. Until that
+RC is published, use the checked-out source build or an explicitly pinned
+compatible package; never install `latest` for a payment test. The production
+RC tool inventory below is read-only; do not claim MCP signing or AIFP-2
+settlement is active.
+
+# AiFinPay agent workflow
+
+Use the tools actually returned by MCP tools/list. This RC exposes
+agent_address, agent_reload, agent_history, agent_quota,
+agent_passport_resolve, settlement_routes and settlement_invoice.
+With AIFINPAY_MODE=dev it also exposes dev_payment_quote.
+It does not register payable_fetch, agent_call or other payment-signing tools.
+Never tell a user a payment was sent because a quote or invoice was created.
+
+## Wallet source priority
+
+The local server selects one identity in this order:
+
+1. SEED_HASH environment variable: 32-byte hex seed, 64 hex characters,
+   optionally prefixed with 0x. Passed directly to AiFinPayAgent.fromSeed;
+   no second hash, no mnemonic conversion.
+2. ./aifinpay/agents.json relative to the MCP process working directory.
+   AIFINPAY_AGENTS_FILE may name an explicit absolute path.
+3. Legacy AIFINPAY_AGENT_SECRET base58 secret.
+4. Legacy ~/.aifinpay/agent.json (or AIFINPAY_HOME/agent.json).
+
+The project-file schema is:
+
+```json
+{"agents":[{"id":"research-agent","seed_hash":"REDACTED"}]}
+```
+
+REDACTED is a placeholder, not a usable seed. With more than one record,
+AIFINPAY_AGENT_ID must select exactly one id. Invalid configured sources stop
+loading; they never silently generate a new wallet or fall back to another.
+Keep secret files private (mode 600), outside Git and outside chat. Never ask
+for a real seed, print it, or send it to the backend. Use agent_address to
+confirm the public wallet selected. With no configured identity the server
+uses an ephemeral wallet: do not fund it.
+
+## Init and reconnect
+
+For a funded crawler or balance check, load the existing persistent identity
+first through the configured MCP identity sources or
+`AiFinPayAgent.fromEnvironment()`. If none exists, stop and ask the operator
+to configure one; never call `Agent.new()` to create a wallet that will be
+funded. `npx @aifinpay/mcp@2.0.0-rc.12 init` creates the legacy keystore only when no
+configured wallet exists. It preserves existing wallets. After init or a local
+wallet-file update, call agent_reload in the existing MCP connection, then agent_address.
+The reload returns only public addresses and preserves the old identity if
+loading fails. This server does not require a new conversation.
+
+On an interactive TTY, init may print a one-time private-key recovery line for
+the operator to back up offline. Automated agents must never request, capture,
+log or repeat that line; non-interactive runs suppress it.
+
+Installing a new package or changing launch environment variables requires the
+MCP host to launch/reconnect the server process. Shell exports cannot change an
+already running process. Whether the host can reconnect in the same UI session
+is client-specific; do not universally prescribe restarting the whole chat.
+
+## Payment history is required before reporting spend
+
+Use agent_history. Do not guess /v1/history, /v1/payments or /v1/wallet/tx.
+
+```json
+{"address":"0x…","source":"transactions","limit":25,"offset":0}
+```
+
+```json
+{"passport":"AIFP-000000042","source":"receipts","network":"polygon"}
+```
+
+An omitted address/passport uses the current wallet. With both inputs, the
+address must match the passport's verified wallet on the requested network.
+Passport accepts a public @username, AIFP number or aifp_agent_* id; a secret
+API key or holder private key is not a passport identifier. The backend
+resolver must be deployed. A 404/403/503 is unavailable history, not proof
+that the agent made no payments.
+
+Routes:
+
+- GET /v1/agents/:address/transactions?chain=polygon&limit=25&offset=0:
+  public facts from indexed AiFinPay Polygon settlements in the durable
+  ledger. Excludes arbitrary wallet transfers and may lag the chain.
+- GET /v1/agents/:address/receipts?limit=25&offset=0: retained prepaid-batch
+  metadata, including test payments. Never includes the spendable receipt JWT.
+- GET /v1/agents/:address/statement?days=7: retained billing statement.
+- GET /api/agent/resolve/:identifier: public verified passport wallet bindings,
+  only on backends with the Agent Passport service installed.
+
+On https://api.aifinpay.io the resolver path is /agent/resolve/:identifier
+because ingress adds /api. Keep /v1 paths unchanged. On the main host or a
+normal dev backend, the resolver includes /api.
+
+Amounts from the ledger are integer strings in token base units. Do not turn
+uint256 amounts into JavaScript numbers. Use next_offset for the next page.
+Receipt history is retained metadata, not a full blockchain explorer. External
+merchants may meter quotas locally; AiFinPay's remaining count can lag.
+
+Node SDK: getAgentHistory({address, passport, source, network, limit, offset,
+baseUrl}) uses the same route flow. Retrieve a paid bearer receipt separately
+with the signed recovery API; never put it in a public history report.
+
+After a settlement error, retain the original quote, transaction reference and
+idempotency context and use the recovery path before another attempt. A new
+quote or a new `fetchPaid` call may charge again; this RC has no payment
+executor. `dev.ratersapp.com` is only a hostname, not proof of testnet or dev
+settlement. Validate the 402 challenge and quote's `network_mode`, chain and
+deployed contract before any approved executor could settle.
+
+## Dev paid-content inspection
+
+Configure AIFINPAY_MODE=dev and a separate AIFINPAY_BASE_URL. The backend must
+have AIFP_DEV_MODE=true and AIFP_DEV_MERCHANT_ID pointing to an existing test
+merchant. GET /v1/dev/paid/data then uses the real receipt gate. Live merchants
+are rejected; a missing config cannot enable free access.
+
+Call dev_payment_quote({contract_version:"1.2" or "1.4", units:1000}). It reads
+the 402 and requests a batch quote. The quote must name only Amoy, test mode,
+the same merchant/resource and the requested deployed contract version.
+Changing a requested version does not redeploy a contract or relabel its ABI;
+a mismatch stops the flow. The operator must configure the corresponding
+verified SPLITTER_ADDRESS_AMOY deployment first. Minimum-unit and cap errors
+stop the request; do not lower units below the server minimum, edit quote
+responses, or invent manual nonces, receipts or transactions.
+
+This tool never broadcasts. Current MCP has no settlement executor; SDK
+fetchPaid remains gated and is not a general Amoy 1.2/1.4 executor. Finish
+that executor's deployment verification and paid testnet E2E before claiming
+the full dev payment loop works. A prepaid batch means one settlement funding
+multiple API calls, not an arbitrary batch of on-chain transfers.
+
+After any actual settlement, retain its quote and transaction reference.
+Retry receipt issuance on temporary errors without paying again. Inspect
+agent_history(source:"receipts") and agent_quota to report the result.

package/dist/directory.d.ts

@@ -1,55 +0,0 @@
-/**
- * createDirectoryServer — the READ-ONLY MCP server submitted to the OpenAI
- * ChatGPT App Directory. Distinct from `createServer` (the full BYO-MCP
- * connector with payment execution): this one exposes ONLY the read-only
- * directory tools, requires NO agent identity and NO auth, and never moves
- * money — so it is reviewable under OpenAI's directory policy (Obsidian/32 /34).
- *
- * One codebase, two profiles: the HTTP wrapper picks this when
- * AIFINPAY_MCP_PROFILE=directory.
- */
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-export interface DirectoryServerConfig {
-    /** Public API base for the wrapped GET endpoints. Defaults to production. */
-    apiBase?: string;
-    /** Per-request timeout (ms). */
-    timeoutMs?: number;
-    log?: (level: "info" | "warn" | "error", msg: string) => void;
-}
-export declare function createDirectoryServer(config?: DirectoryServerConfig): Promise<{
-    server: Server<{
-        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;
-    }>;
-}>;
-//# sourceMappingURL=directory.d.ts.map

package/dist/directory.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAYnE,MAAM,WAAW,qBAAqB;IACpC,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/D;AAwBD,wBAAsB,qBAAqB,CAAC,MAAM,GAAE,qBAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2B7E"}

package/dist/directory.js

@@ -1,56 +0,0 @@
-/**
- * createDirectoryServer — the READ-ONLY MCP server submitted to the OpenAI
- * ChatGPT App Directory. Distinct from `createServer` (the full BYO-MCP
- * connector with payment execution): this one exposes ONLY the read-only
- * directory tools, requires NO agent identity and NO auth, and never moves
- * money — so it is reviewable under OpenAI's directory policy (Obsidian/32 /34).
- *
- * One codebase, two profiles: the HTTP wrapper picks this when
- * AIFINPAY_MCP_PROFILE=directory.
- */
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { directoryTools, runDirectoryTool, DIRECTORY_API_BASE, } from "./tools/directory.js";
-// Server-wide instructions returned at initialize. ChatGPT/Codex use these as a
-// cross-tool guide (OpenAI readiness checklist item; the audit found it ABSENT
-// on the connector server). States the read-only contract, networks, and limits.
-const DIRECTORY_INSTRUCTIONS = [
-    "AiFinPay is payment infrastructure for AI agents. THIS server is the",
-    "read-only directory surface: it answers questions about the AiFinPay agent",
-    "economy and prices AI services — it does NOT move money, hold funds, sign",
-    "transactions, or execute any payment. Every tool is read-only.",
-    "",
-    "Use it to: list available AI providers and their per-call prices",
-    "(list_providers / provider_info / provider_status / service_coverage),",
-    "preview a fee-on-top cost breakdown without paying (quote_cost), read public",
-    "protocol stats (network_stats) and the on-chain agent leaderboard",
-    "(leaderboard), verify an agent's AgentPassport (verify_passport), and look up",
-    "a public agent profile (agent_profile).",
-    "",
-    "Networks: Polygon and Solana mainnet. Data is public on-chain / registry",
-    "information. To actually execute a payment, an agent uses the separate",
-    "AiFinPay connector or SDK — not this directory app. Requests are rate limited;",
-    "on HTTP 429 (rate_limit_exceeded), back off and retry.",
-].join("\n");
-export async function createDirectoryServer(config = {}) {
-    const log = config.log ?? ((lvl, msg) => process.stderr.write(`[${lvl}] ${msg}\n`));
-    const ctx = {
-        apiBase: (config.apiBase || DIRECTORY_API_BASE).replace(/\/$/, ""),
-        timeoutMs: config.timeoutMs ?? 15000,
-        log,
-    };
-    const server = new Server({ name: "@aifinpay/mcp-directory", version: "1.0.0" }, {
-        capabilities: { tools: {} },
-        instructions: DIRECTORY_INSTRUCTIONS,
-    });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: directoryTools(),
-    }));
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const { name, arguments: args } = request.params;
-        return runDirectoryTool(ctx, name, args ?? {});
-    });
-    log("info", `[aifinpay-mcp-directory] read-only profile · api=${ctx.apiBase}`);
-    return { server };
-}
-//# sourceMappingURL=directory.js.map

package/dist/directory.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"directory.js","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,kBAAkB,GAEnB,MAAM,sBAAsB,CAAC;AAU9B,gFAAgF;AAChF,+EAA+E;AAC/E,iFAAiF;AACjF,MAAM,sBAAsB,GAAG;IAC7B,sEAAsE;IACtE,4EAA4E;IAC5E,2EAA2E;IAC3E,gEAAgE;IAChE,EAAE;IACF,kEAAkE;IAClE,wEAAwE;IACxE,8EAA8E;IAC9E,mEAAmE;IACnE,+EAA+E;IAC/E,yCAAyC;IACzC,EAAE;IACF,0EAA0E;IAC1E,wEAAwE;IACxE,gFAAgF;IAChF,wDAAwD;CACzD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,SAAgC,EAAE;IAC5E,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC;IACpF,MAAM,GAAG,GAAqB;QAC5B,OAAO,EAAE,CAAC,MAAM,CAAC,OAAO,IAAI,kBAAkB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QAClE,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,KAAK;QACpC,GAAG;KACJ,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,OAAO,EAAE,EACrD;QACE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAC3B,YAAY,EAAE,sBAAsB;KACrC,CACF,CAAC;IAEF,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QAC5D,KAAK,EAAE,cAAc,EAAE;KACxB,CAAC,CAAC,CAAC;IAEJ,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAChE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;QACjD,OAAO,gBAAgB,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,MAAM,EAAE,oDAAoD,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/E,OAAO,EAAE,MAAM,EAAE,CAAC;AACpB,CAAC"}

package/dist/tools/agent-call.d.ts

@@ -1,68 +0,0 @@
-import type { ToolContext } from "../server.js";
-/**
- * `agent_call` — unified registry-resolved paid HTTP call.
- *
- * The agent picks a provider by name ("exa", "io-net", "venice", …),
- * the SDK looks up the bridge URL + price from the public AiFinPay
- * registry, negotiates the 402 challenge, settles on Polygon via
- * B2BSplitter.payMatic, retries with proof, and returns the upstream
- * response body.
- *
- * Use this in preference to `payable_fetch` when you have a registered
- * provider name — it auto-routes price, chain, and bridge URL.
- *
- * Requires the EVM address (from `agent_address`) to be funded with POL
- * on Polygon mainnet (gas + payment), or USDC if the provider quotes in
- * stablecoin.
- */
-export declare function agentCallTool(): {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: string;
-        properties: {
-            provider: {
-                type: string;
-                description: string;
-            };
-            body: {
-                type: string;
-                description: string;
-                additionalProperties: boolean;
-            };
-            method: {
-                type: string;
-                enum: string[];
-                default: string;
-                description: string;
-            };
-            cost: {
-                type: string;
-                description: string;
-            };
-        };
-        required: string[];
-    };
-    annotations: {
-        readOnlyHint: boolean;
-        openWorldHint: boolean;
-        destructiveHint: boolean;
-    };
-    outputSchema: {
-        type: string;
-    };
-};
-export declare function runAgentCall(ctx: ToolContext, args: Record<string, unknown>): Promise<{
-    isError: boolean;
-    content: {
-        type: string;
-        text: string;
-    }[];
-} | {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError?: undefined;
-}>;
-//# sourceMappingURL=agent-call.d.ts.map