@nonagon-link/mcp 0.3.2 → 0.3.4

package/README.md

@@ -80,7 +80,7 @@ Three settings are needed, plus one argument per call:
 3. `MCP_MAX_PAYMENT_EVM_USDC_CAP` — the most this server may pay per EVM USDC call, written in decimal notation with at most 6 fractional digits. The allowed range comes from the pinned USDC price range of this server's network family (2–10 USDC today). Unset or empty = EVM USDC is never paid. In the `.mcpb` settings this is "EVM USDC payment cap".
 4. Pass `maxPaymentEvmUsdc` (USDC, at most 6 decimals, at most the cap) to `pay_and_call`. `maxPaymentUsdc` applies to Solana USDC only and is never used for EVM USDC.
 
-| Situation | Response (`paymentStatus: "not_paid"`, nothing signed) |
+| Situation | Response (`paymentStatus: "not_paid"`, `paymentSignatureSent:false` for these pre-signing errors) |
 |---|---|
 | Cap not set | `EVM_NOT_SUPPORTED` with `reason: "evm_usdc_not_enabled"` and a hint naming the settings (only when setting them would make the 402 payable) |
 | Cap set, no EVM wallet | `EVM_WALLET_NOT_CONFIGURED` with `currency: "USDC"` |
@@ -97,6 +97,10 @@ The cap is checked again right before signing, so a call that bypasses the tool'
 
 ### Payment status
 
+GET listings take query (an object of strings, finite numbers or booleans); POST takes body (any JSON object / array / scalar / null). Map search_listings httpMethod to method. GET body, nonempty POST query, duplicate decoded keys and collisions with existing URL keys are rejected before any request; POST query:{} is treated as omitted. Existing URL encoding is preserved; query is limited to 64 parameters and 4096 serialized characters including existing values. Example: {"method":"GET","query":{"query":"日本語 & + %","page":0,"include":false}}. Only an unsigned GET402 whose final URL has zero query parameters is checked against an available queryParams schema before signing. If schema is absent, invalid, unsupported or over budget, validation is skipped and the existing payment policy still applies; payment proceeds as before. Nonempty queries use the gateway validation, including page-size clamping.
+
+not_paid means the MCP can determine that payment was not executed. Every executed tool result includes boolean paymentSignatureSent; not_paid is not synonymous with unsigned. Classifying a signed GET422 as not_paid requires NONAGON_LINK_BASE_URL to be configured with an official (nnglink.ai / *.nnglink.ai) or local (localhost / 127.0.0.1) host, the same origin, the exact /api/proxy/{providerSlug}/{listingSlug} route, a complete JSON body within 8 KiB with code SCHEMA_VALIDATION_FAILED / QUERY_TOO_LARGE / SCHEMA_UNSUPPORTED, and no PAYMENT-RESPONSE, X-PAYMENT-RESPONSE (including the saved receipt) or X-Proxy-Payment-Id. This is the configured gateway's rejection before payment execution; correct query and retry. For EVM retain authorization (network / asset / from / nonce / validBefore): it remains valid until validBefore. A signed not_paid result does not independently prove on-chain non-execution. Other signed 422 responses and communication failures retain paid / unknown according to the receipt; on unknown do not retry automatically and check authorizationState(from, nonce).
+
 NONAGON LINK can reject an unsigned request before issuing a nonce: payment-option policy is checked first (`409 PAYMENT_OPTION_DISABLED` / `503 PAYMENT_OPTIONS_UNAVAILABLE`), then EVM native readiness. Gas uses POL on Polygon or ETH on Ethereum / Base, separately from USDC / JPYC. A readiness snapshot does not reserve a USD budget or guarantee a later settlement.
 
 | HTTP | Code | Fixed message |
@@ -106,11 +110,11 @@ NONAGON LINK can reject an unsigned request before issuing a nonce: payment-opti
 | 503 | `EVM_GAS_LIMIT_EXCEEDED` | Estimated gas exceeds the supported limit |
 | 503 | `EVM_TRANSACTION_ESTIMATE_UNAVAILABLE` | Gas estimation is unavailable |
 
-Existing `GAS_LIMIT_EXCEEDED` is the USD per-transaction cap, distinct from the EVM gas quantity limit. `GAS_ESTIMATE_UNAVAILABLE`, `DAILY_GAS_CAP`, `GAS_BUDGET_UNAVAILABLE`, `TX_TIMEOUT`, `TX_FAILED` and `EVM_SETTLE_FAILED` remain. The MCP classifies a request that sent no signed payment as `not_paid`; after submission it does not infer non-payment from any HTTP status or error code, including these 503 errors.
+Existing `GAS_LIMIT_EXCEEDED` is the USD per-transaction cap, distinct from the EVM gas quantity limit. `GAS_ESTIMATE_UNAVAILABLE`, `DAILY_GAS_CAP`, `GAS_BUDGET_UNAVAILABLE`, `TX_TIMEOUT`, `TX_FAILED` and `EVM_SETTLE_FAILED` remain. The MCP classifies a request that sent no signed payment as `not_paid`; after submission only the configured gateway pre-payment GET422 contract described below can be classified as not_paid. These 503 errors retain the existing receipt-based classification.
 
 | `paymentStatus` | Meaning | What to do |
 |---|---|---|
-| `not_paid` | No payment was sent (rejected 402, limit exceeded, not configured, error before signing) | Fix the cause and retry |
+| `not_paid` | MCP can determine payment was not executed (including a configured gateway pre-payment query rejection after signing) | Fix the cause and retry |
 | `paid` | The paid request's response carried a successful receipt (even if the API itself then returned an error) | Retrying is a new payment |
 | `unknown` | A signed payment was sent but the result is not confirmed (timeout, connection loss, error response, missing receipt). The response body is **not** trusted — the host could claim anything | **Do not retry automatically** (a retry signs a new authorization and can pay twice). For EVM payments (JPYC and EVM USDC) the response includes `authorization` (`network`, `asset`, `from`, `nonce`, `validBefore`): call `authorizationState(from, nonce)` on the token contract. It can never execute only after `validBefore` has passed and `authorizationState` is `false`. `reportedTransaction`, if any, is the host's unverified claim: independently check its receipt on the saved network and require `transactionHash` to equal the requested hash before reading status. A missing / different-hash receipt does not prove non-payment. Keep the original authorization lookup fields and check again after `validBefore`; a false state before expiry is insufficient. Do not reuse the authorization or automatically create another payment |
 
@@ -125,7 +129,7 @@ Add to your MCP client config (e.g. `.claude/settings.json` or `claude_desktop_c
   "mcpServers": {
     "nonagon-link": {
       "command": "npx",
-      "args": ["-y", "--ignore-scripts", "@nonagon-link/mcp@0.3.2"],
+      "args": ["-y", "--ignore-scripts", "@nonagon-link/mcp@0.3.4"],
       "env": {
         "NONAGON_PRIVATE_KEY": "<Base58 Solana secret key>",
         "NONAGON_LINK_BASE_URL": "https://api.nnglink.ai",
@@ -136,7 +140,7 @@ Add to your MCP client config (e.g. `.claude/settings.json` or `claude_desktop_c
 }
 ```
 
-> **Always pin an exact version** (`@nonagon-link/mcp@0.3.2`). Never use an unversioned `@nonagon-link/mcp` — your private key is passed to the process environment, so an unpinned install would expose it to whatever the latest published version is. `--ignore-scripts` additionally prevents dependency install scripts from running with your environment.
+> **Always pin an exact version** (`@nonagon-link/mcp@0.3.4`). Never use an unversioned `@nonagon-link/mcp` — your private key is passed to the process environment, so an unpinned install would expose it to whatever the latest published version is. `--ignore-scripts` additionally prevents dependency install scripts from running with your environment.
 >
 > **Set `NONAGON_PAY_TO`** to the NONAGON LINK Solana platform wallet (see [NONAGON LINK payees](#nonagon-link-payees)) — do not copy `payTo` from an untrusted 402. Unset = every **Solana USDC** payment is refused. EVM payments (JPYC, EVM USDC) are allowed separately by `NONAGON_EVM_PAY_TO`; unset, every EVM payment is refused.
 
@@ -154,7 +158,7 @@ The current values are also listed at https://nnglink.ai/docs/mcp.
 For stricter isolation, install once and reference the binary directly:
 
 ```bash
-npm install -g @nonagon-link/mcp@0.3.2
+npm install -g @nonagon-link/mcp@0.3.4
 ```
 
 ```json