@forum-labs/payfetch 1.0.0 → 1.0.1

package/README.md

@@ -1,5 +1,7 @@
 # payfetch
 
+[![smithery badge](https://smithery.ai/badge/forum-labs/payfetch)](https://smithery.ai/servers/forum-labs/payfetch)
+
 payfetch lets an AI agent fetch a URL and, when the server answers HTTP 402 (the
 x402 payment protocol), pay for it automatically, but only within a spending policy
 you control. It is non-custodial: you bring your own wallet, the key stays on your
@@ -122,8 +124,8 @@ Pay for real with `paid_fetch`:
 ```
 
 `maxAmountUsd` tightens the per-call cap for this one call. It can only lower the
-limit, never raise it. If the price is above your approval threshold, a human is
-asked to confirm (see Approvals). The result carries the response body, the payment
+limit, never raise it. If the price is above your approval threshold, approval is
+required first (see Approvals). The result carries the response body, the payment
 outcome and transaction reference, any warnings, and a `receiptId`.
 
 ## The spending policy
@@ -172,8 +174,11 @@ allow", and it never widens future authority.
 - `elicit` (default): the client prompts a human with the host, resource, amount,
   network and asset, guard results, and today's remaining budgets. They approve once
   or deny. The prompt times out after 120 seconds and is then treated as a denial.
-  Some MCP clients cannot service an elicitation prompt (Claude Desktop cancels it
-  immediately; Claude Code supports it). payfetch tells apart a real human "deny"
+  Some MCP clients cannot service an elicitation prompt: as of Claude Code v2.1.198
+  and current Claude Desktop, neither does (Claude Code does not advertise the
+  elicitation capability; Claude Desktop advertises it but cancels the prompt
+  immediately). When a client adds elicitation support, the prompt works with no
+  payfetch change. payfetch tells apart a real human "deny"
   from a client that simply cannot ask, and it never treats "cannot ask" as a silent
   denial. When a payment is blocked only because the client cannot elicit, the tool
   result says so and names the ways to allow it.
@@ -373,18 +378,20 @@ Defaults, from `{dataDir}/config.json`, schema `p3f.policy.v1`:
 | `caps.dailyUsd` | `2.00` | Max per UTC day. |
 | `caps.perHostDailyUsd` | `1.00` | Max per host per UTC day. |
 | `caps.totalUsd` | `null` | Optional lifetime cap. |
-| `approval.thresholdUsd` | `0.10` | Above this, a human approves. |
+| `approval.thresholdUsd` | `0.10` | Above this, approval is required. |
 | `approval.mode` | `"elicit"` | `elicit`, `queue`, or `deny`. |
 | `approval.elicitFallback` | `"deny"` | Used when the client cannot elicit. Fail-closed. |
 | `approval.preApprovedUpToUsd` | `null` | No-dialog ceiling for above-threshold payments. |
 | `approval.preApprovedHosts` | `[]` | Hosts pre-approved to auto-pay above threshold. |
 | `guards.trust.enabled` | `true` | The default-on trust check. |
 | `guards.trust.mode` | `"advisory"` | `advisory` warns; `enforce` blocks. |
+| `guards.trust.minScore` | `null` | Minimum acceptable TrustScore; below it the guard blocks or warns. `null` uses verdict-based blocking only, and it is ignored when the API returns a null score. |
 | `guards.trust.blockVerdicts` | `["unreliable"]` | Verdicts that block or warn. |
 | `guards.trust.blockUnrated` | `false` | `unrated` passes by default. |
 | `guards.trust.onUnavailable` | `"block"` | Enforce-mode behavior when the guard cannot answer. |
 | `guards.trust.dailyBudgetUsd` | `0` | 0 means free tier only. |
 | `guards.safety.enabled` | `false` | Token safety screen; needs `tokenAddress`. |
+| `guards.safety.mode` | `"enforce"` | `advisory` warns; `enforce` blocks. Applies only when the safety guard is enabled. |
 | `guards.safety.depth` | `"basic"` | `deep` is always paid. |
 | `guards.safety.blockVerdicts` | `["danger"]` | Token verdicts that block. |
 | `guards.safety.blockDeployerVerdicts` | `["serial_rugger"]` | Deployer verdicts, deep only. |

package/dist/src/core/pipeline.d.ts

@@ -140,4 +140,5 @@ export declare function classifyFromParts(status: number, settlement: {
     success: boolean;
     transaction?: string;
 } | null, _quote: PaymentQuote): TerminalClass;
+export declare function applyJsonContentTypeDefault(headers: Record<string, string>, body: string | null): Record<string, string>;
 export declare function stripReservedHeaders(headers: RequestInit["headers"]): Record<string, string>;

package/dist/src/core/pipeline.js

@@ -155,8 +155,8 @@ export class PayfetchEngine {
         const policy = pol.policy;
         const caps = this.capsOf(policy);
         const method = (init.method ?? "GET").toUpperCase();
-        const userHeaders = stripReservedHeaders(init.headers);
         const body = typeof init.body === "string" ? init.body : null;
+        const userHeaders = applyJsonContentTypeDefault(stripReservedHeaders(init.headers), body);
         const responseMode = opts.responseMode ?? "inline";
         const dry = quoteMode || Boolean(opts.dryRun);
         const io = this.transportIo();
@@ -739,6 +739,24 @@ function preApprovedNote(policy, host, quote) {
 function microUsd(x) {
     return Number.isFinite(x) ? Math.round(x * 1_000_000) : Number.POSITIVE_INFINITY;
 }
+export function applyJsonContentTypeDefault(headers, body) {
+    if (body === null || body.length === 0)
+        return headers;
+    for (const k of Object.keys(headers)) {
+        if (k.toLowerCase() === "content-type")
+            return headers;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return headers;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return headers;
+    return { ...headers, "Content-Type": "application/json" };
+}
 export function stripReservedHeaders(headers) {
     const reserved = new Set([
         X_PAYMENT_HEADER.toLowerCase(),

package/dist/src/index.d.ts

@@ -56,3 +56,6 @@ export { adaptFetch, parseIpv4 };
 export type { Decision, SpendStatus, FetchOpts };
 export type { Policy } from "./core/policy.js";
 export type { Receipt } from "./core/ledger.js";
+export { buildFromEnv, realConfigIo } from "./config.js";
+export type { ConfigIo, EnvRecord } from "./config.js";
+export { policyLockNotice, paymentRejectedHint } from "./mcp/tools.js";

package/dist/src/index.js

@@ -149,3 +149,5 @@ function createPinnedHttpClient(resolve, policy) {
     return client;
 }
 export { adaptFetch, parseIpv4 };
+export { buildFromEnv, realConfigIo } from "./config.js";
+export { policyLockNotice, paymentRejectedHint } from "./mcp/tools.js";

package/dist/src/mcp/tools.d.ts

@@ -7,11 +7,11 @@ export declare const TOOL_NAMES: {
     readonly APPROVE_PENDING: "approve_pending";
 };
 export declare const TOOL_DESCRIPTIONS: {
-    readonly paid_fetch: "Fetch a URL, automatically paying if it requires payment (HTTP 402, x402 protocol) — within the operator's spending policy. Free URLs are fetched normally at no cost. Use payment_quote first if you only want to know the price. Payments above the operator's approval threshold will ask the human for confirmation.";
-    readonly payment_quote: "Check what a paid URL costs and whether the current spending policy would allow paying it, WITHOUT paying. Returns the price, payment terms, trust-check results, and the policy decision.";
-    readonly spend_status: "Show today's agent spending: totals, remaining budgets overall and per host, active holds, and recent payments.";
-    readonly list_receipts: "Query the local payment receipt ledger (audit trail). Filter by time, host, or outcome.";
-    readonly approve_pending: "List or resolve payments waiting for human approval (queue mode). Approving grants a one-time re-run permission for that exact payment.";
+    readonly paid_fetch: "Fetch a URL, automatically paying if it requires payment (HTTP 402, x402 protocol) — within the operator's spending policy. Free URLs are fetched normally at no cost. Use payment_quote first if you only want to know the price. Payments above the operator's approval threshold will ask the human for confirmation. Spending policy is operator-owned config; no tool can widen it.";
+    readonly payment_quote: "Check what a paid URL costs and whether the current spending policy would allow paying it, WITHOUT paying. Returns the price, payment terms, trust-check results, and the policy decision. Spending policy is operator-owned config; no tool can widen it.";
+    readonly spend_status: "Show today's agent spending: totals, remaining budgets overall and per host, active holds, and recent payments. Spending policy is operator-owned config; no tool can widen it.";
+    readonly list_receipts: "Query the local payment receipt ledger (audit trail). Filter by time, host, or outcome. Spending policy is operator-owned config; no tool can widen it.";
+    readonly approve_pending: "List or resolve payments waiting for human approval (queue mode). Approving grants a one-time re-run permission for that exact payment. It only resolves payments already queued for approval; it cannot change spending policy — no payfetch tool can widen operator-owned limits.";
 };
 export type JsonSchema = {
     type: "object";
@@ -31,6 +31,7 @@ export type ToolDefinition = {
 };
 export declare const PAYFETCH_TOOLS: readonly ToolDefinition[];
 export declare function policyLockNotice(dataDir: string): string;
+export declare function paymentRejectedHint(status: number): string;
 export declare class UnknownToolError extends Error {
     readonly toolName: string;
     constructor(toolName: string);

package/dist/src/mcp/tools.js

@@ -8,11 +8,11 @@ export const TOOL_NAMES = {
     APPROVE_PENDING: "approve_pending",
 };
 export const TOOL_DESCRIPTIONS = {
-    paid_fetch: "Fetch a URL, automatically paying if it requires payment (HTTP 402, x402 protocol) — within the operator's spending policy. Free URLs are fetched normally at no cost. Use payment_quote first if you only want to know the price. Payments above the operator's approval threshold will ask the human for confirmation.",
-    payment_quote: "Check what a paid URL costs and whether the current spending policy would allow paying it, WITHOUT paying. Returns the price, payment terms, trust-check results, and the policy decision.",
-    spend_status: "Show today's agent spending: totals, remaining budgets overall and per host, active holds, and recent payments.",
-    list_receipts: "Query the local payment receipt ledger (audit trail). Filter by time, host, or outcome.",
-    approve_pending: "List or resolve payments waiting for human approval (queue mode). Approving grants a one-time re-run permission for that exact payment.",
+    paid_fetch: "Fetch a URL, automatically paying if it requires payment (HTTP 402, x402 protocol) — within the operator's spending policy. Free URLs are fetched normally at no cost. Use payment_quote first if you only want to know the price. Payments above the operator's approval threshold will ask the human for confirmation. Spending policy is operator-owned config; no tool can widen it.",
+    payment_quote: "Check what a paid URL costs and whether the current spending policy would allow paying it, WITHOUT paying. Returns the price, payment terms, trust-check results, and the policy decision. Spending policy is operator-owned config; no tool can widen it.",
+    spend_status: "Show today's agent spending: totals, remaining budgets overall and per host, active holds, and recent payments. Spending policy is operator-owned config; no tool can widen it.",
+    list_receipts: "Query the local payment receipt ledger (audit trail). Filter by time, host, or outcome. Spending policy is operator-owned config; no tool can widen it.",
+    approve_pending: "List or resolve payments waiting for human approval (queue mode). Approving grants a one-time re-run permission for that exact payment. It only resolves payments already queued for approval; it cannot change spending policy — no payfetch tool can widen operator-owned limits.",
 };
 const LIST_RECEIPTS_DEFAULT_LIMIT = 50;
 const LIST_RECEIPTS_MAX_LIMIT = 200;
@@ -26,7 +26,11 @@ export const PAID_FETCH_INPUT_SCHEMA = {
         method: { enum: [...HTTP_METHOD_ENUM], default: "GET" },
         headers: { type: "object", additionalProperties: { type: "string" } },
         body: { type: "string" },
-        maxAmountUsd: { type: "number", minimum: 0 },
+        maxAmountUsd: {
+            type: "number",
+            minimum: 0,
+            description: "Tightens the per-call cap for this one call. Can only LOWER the limit, never raise it.",
+        },
         dryRun: { type: "boolean", default: false },
         responseMode: { enum: [...RESPONSE_MODE_ENUM], default: "inline" },
         tokenAddress: { type: "string" },
@@ -103,6 +107,12 @@ export const PAYFETCH_TOOLS = [
 export function policyLockNotice(dataDir) {
     return `Spending limits and lists are set by the operator in ${dataDir}/config.json — they cannot be changed from this session.`;
 }
+export function paymentRejectedHint(status) {
+    return (`The server rejected the paid request (HTTP ${status}) — this usually means the request ` +
+        `was malformed, so check the request headers and body (for example, a JSON body needs a ` +
+        `Content-Type: application/json header). This does NOT confirm settlement: you were ` +
+        `charged only if a settlement transaction is shown.`);
+}
 export class UnknownToolError extends Error {
     toolName;
     constructor(toolName) {
@@ -201,6 +211,11 @@ async function mapPaidFetchResult(dataDir, receipt, response, responseMode) {
         (receipt.notes.includes("elicit_unsupported") || receipt.notes.includes("elicit_cancelled"))) {
         denied.approvalGuidance = elicitBlockedGuidance(dataDir);
     }
+    if (receipt.outcome === "payment_rejected") {
+        const st = receipt.http?.status ?? null;
+        if (st !== null && st >= 400 && st < 500)
+            denied.hint = paymentRejectedHint(st);
+    }
     return denied;
 }
 function elicitBlockedGuidance(dataDir) {

package/mcpb/manifest.json

@@ -2,8 +2,8 @@
   "manifest_version": "0.2",
   "name": "payfetch",
   "display_name": "payfetch",
-  "version": "1.0.0",
-  "description": "Buy-side paying-fetch client: fetch URLs and pay HTTP 402 (x402) paywalls automatically, under operator-owned spending policy (caps, allow/deny lists, human approval, trust checks, receipts). Non-custodial — bring your own wallet.",
+  "version": "1.0.1",
+  "description": "Buy-side paying-fetch client: fetch URLs and pay HTTP 402 (x402) paywalls automatically, under operator-owned spending policy (caps, allow/deny lists, human approval, trust checks, receipts). Non-custodial \u2014 bring your own wallet.",
   "long_description": "payfetch lets an AI agent fetch a URL and, if it returns HTTP 402 (x402 protocol), pay for it automatically WITHIN a policy the operator controls: per-call / per-day / per-host / lifetime spend caps, host allow/deny lists, a human-approval threshold, a default-ON trust check against the Forum Labs trust API, and an immutable local receipt for every attempt. The agent can never raise its own limits. Keys are never transmitted or logged. Directory submission is not offered (payment connectors are policy-blocked); this bundle is for MANUAL install only.",
   "author": {
     "name": "Forum Labs"
@@ -13,7 +13,9 @@
     "entry_point": "server/payfetch-mcp.mjs",
     "mcp_config": {
       "command": "node",
-      "args": ["${__dirname}/server/payfetch-mcp.mjs"],
+      "args": [
+        "${__dirname}/server/payfetch-mcp.mjs"
+      ],
       "env": {
         "PAYFETCH_PRIVATE_KEY": "${user_config.private_key}",
         "PAYFETCH_KEY_FILE": "${user_config.key_file}",
@@ -29,24 +31,39 @@
     }
   },
   "tools": [
-    { "name": "paid_fetch", "description": "Fetch a URL, paying an HTTP 402 (x402) paywall automatically within policy." },
-    { "name": "payment_quote", "description": "Check what a paid URL costs and whether policy would allow paying it, without paying." },
-    { "name": "spend_status", "description": "Show today's spending: totals, remaining budgets, holds, recent payments." },
-    { "name": "list_receipts", "description": "Query the local payment receipt ledger (audit trail)." },
-    { "name": "approve_pending", "description": "List or resolve payments waiting for human approval (queue mode)." }
+    {
+      "name": "paid_fetch",
+      "description": "Fetch a URL, paying an HTTP 402 (x402) paywall automatically within policy."
+    },
+    {
+      "name": "payment_quote",
+      "description": "Check what a paid URL costs and whether policy would allow paying it, without paying."
+    },
+    {
+      "name": "spend_status",
+      "description": "Show today's spending: totals, remaining budgets, holds, recent payments."
+    },
+    {
+      "name": "list_receipts",
+      "description": "Query the local payment receipt ledger (audit trail)."
+    },
+    {
+      "name": "approve_pending",
+      "description": "List or resolve payments waiting for human approval (queue mode)."
+    }
   ],
   "user_config": {
     "private_key": {
       "type": "string",
       "title": "Wallet private key (0x-hex)",
-      "description": "Signer option 1 of 3. A 0x-hex EVM private key. SECRET — stored in the OS keychain, never transmitted or logged. Use a DEDICATED low-balance wallet. Set exactly ONE signer option.",
+      "description": "Signer option 1 of 3. A 0x-hex EVM private key. SECRET \u2014 stored in the OS keychain, never transmitted or logged. Use a DEDICATED low-balance wallet. Set exactly ONE signer option.",
       "sensitive": true,
       "required": false
     },
     "key_file": {
       "type": "file",
       "title": "Wallet key file",
-      "description": "Signer option 1 (alt): path to a file containing a 0x-hex private key. REFUSED at startup if the file is group/world-readable — chmod 600 it.",
+      "description": "Signer option 1 (alt): path to a file containing a 0x-hex private key. REFUSED at startup if the file is group/world-readable \u2014 chmod 600 it.",
       "required": false
     },
     "cdp_api_key_id": {
@@ -59,14 +76,14 @@
     "cdp_api_key_secret": {
       "type": "string",
       "title": "CDP API key secret",
-      "description": "Coinbase CDP API key secret. SECRET — stored in the OS keychain.",
+      "description": "Coinbase CDP API key secret. SECRET \u2014 stored in the OS keychain.",
       "sensitive": true,
       "required": false
     },
     "cdp_wallet_secret": {
       "type": "string",
       "title": "CDP wallet secret",
-      "description": "Coinbase CDP wallet secret. SECRET — stored in the OS keychain.",
+      "description": "Coinbase CDP wallet secret. SECRET \u2014 stored in the OS keychain.",
       "sensitive": true,
       "required": false
     },
@@ -91,7 +108,7 @@
     "approver": {
       "type": "string",
       "title": "Approval authority (set to 1 to enable)",
-      "description": "Set to 1 to grant this session approval authority. NOTE: for safety, the server REFUSES TO START if this is set together with a queue-capable approval mode (approval.mode 'queue', or 'elicit' with elicitFallback 'queue') — the agent must not approve its own payments. The supported human gate is elicit-to-human. Blank = list-only.",
+      "description": "Set to 1 to grant this session approval authority. NOTE: for safety, the server REFUSES TO START if this is set together with a queue-capable approval mode (approval.mode 'queue', or 'elicit' with elicitFallback 'queue') \u2014 the agent must not approve its own payments. The supported human gate is elicit-to-human. Blank = list-only.",
       "required": false
     },
     "via": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forum-labs/payfetch",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "mcpName": "io.github.forum-labs/payfetch",
   "description": "Buy-side x402/HTTP-402 paying-fetch client for AI agents, under operator-owned spending policy (caps, allow/deny, human approval, trust checks, local receipts). Non-custodial.",
   "keywords": [
@@ -67,6 +67,6 @@
     "@modelcontextprotocol/sdk": "1.29.0",
     "@x402/core": "2.17.0",
     "undici": "8.5.0",
-    "viem": "2.54.1"
+    "viem": "2.54.6"
   }
 }