@aifinpay/mcp 1.5.3 → 2.0.0-rc.13

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.13",
+  "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",
@@ -80,7 +66,7 @@
   },
   "bugs": "https://github.com/AiFinPay/sdk/issues",
   "dependencies": {
-    "@aifinpay/agent": "^1.8.1",
+    "@aifinpay/agent": "2.0.0-rc.13",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "bs58": "^6.0.0",
     "tweetnacl": "^1.0.3"

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.