nanoparse-mcp 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.0.1 — 2026-11-14
+
+- Price: $0.005 → **$0.002** per parse. Copy only: the hosted endpoint takes the
+  amount from the live 402 challenge, so no client change is needed.
+
 # Changelog
 
 All notable changes to nanoparse-mcp will be documented in this file.

package/README.md

@@ -3,12 +3,15 @@
 [![npm version](https://img.shields.io/npm/v/nanoparse-mcp)](https://www.npmjs.com/package/nanoparse-mcp)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Website](https://img.shields.io/badge/web-nanoparse.app-22D3EE)](https://nanoparse.app)
+[![MCP Score](https://checkmcp.dev/badge/nanoparse-app.svg?url=https%3A%2F%2Fnanoparse.app%2Fmcp)](https://checkmcp.dev/mcp/nanoparse-app)
+[![MCPLookup Trust Index](https://mcplookup.com/badge/io.github.nanoparse-dev/nanoparse-mcp)](https://mcplookup.com/server/io.github.nanoparse-dev/nanoparse-mcp)
+[![Listed on HookMCP](https://hookmcp.com/badge.svg)](https://hookmcp.com)
 
 **The easiest way for AI agents to read the web.** NanoParse MCP is a hosted Model Context Protocol server at `https://nanoparse.app/mcp` that turns any URL into clean Markdown your agent can actually use — with machine-readable trust signals attached.
 
 No install. No wallet key. No `.env`. Connect once and your agent can read the web.
 
-**Why agents choose NanoParse over Firecrawl or Jina Reader:** no account, no subscription, no API key. Pay $0.005 per parse via x402 when the free tier runs out. Full JavaScript/SPA rendering, native GFM tables, and Litmus trust signals — built for agents, not humans.
+**Why agents choose NanoParse over Firecrawl or Jina Reader:** every page comes back with **Litmus** — 20 machine-readable signals that tell your agent *whether to trust and cite the page* before it reads a word. Pay $0.002 per parse via x402 once the free tier runs out. Full JavaScript/SPA rendering, native GFM tables. No account, no subscription, no API key.
 
 ## Quick start
 
@@ -18,6 +21,7 @@ Add this to your MCP client config:
 {
   "mcpServers": {
     "nanoparse": {
+      "type": "http",
       "url": "https://nanoparse.app/mcp"
     }
   }
@@ -43,41 +47,48 @@ That's it. Your agent can now fetch pages from inside any MCP-compatible client
 
 ## Real output
 
-Every parse returns `markdown` + `metadata` + `litmus`. Example — parsing an arXiv paper (`examples/example-output.json`, complete and unmodified):
+Every parse returns `markdown` + `metadata` + `litmus`. Here is the full `litmus` object from a real parse of an arXiv paper (`examples/example-output.json` — markdown truncated there, litmus complete and unmodified):
 
 ```json
 {
   "litmus": {
     "source": { "type": "academic", "authority": 0.85, "rationale": "academic source" },
-    "freshness": { "published": null, "stale_warning": "No publish date found — verify independently" },
+    "freshness": { "published": null, "age": "unknown", "stale_warning": "No publish date found — verify independently", "modified": null, "has_correction": false, "correction_note": null },
     "tldr": "Abstract page for arXiv paper 2401.14295: Demystifying Chains, Trees, and Graphs of Thoughts",
     "key_figures": [ { "value": "2,247", "context": "Thu, 25 Jan 2024 16:34:00 UTC (2,247 KB)" } ],
+    "structural_trust_score": { "level": "medium", "trust_factors": ["High-authority source", "No publish date found — verify independently"] },
+    "hedge_language": { "density": "low", "markers_found": 0, "per_500_words": 0 },
+    "content_density": { "thin_content": false, "substantive_sentence_ratio": 0.76 },
+    "syndication": { "detected": false, "note": null },
+    "paywall": { "detected": false, "note": null },
     "content_type": "academic_paper",
     "reading_time": { "minutes": 4 },
-    "hedge_language": { "density": "low", "markers_found": 0 },
-    "syndication": { "detected": false },
-    "paywall": { "detected": false }
+    "is_archived": { "archive_org": true, "archive_is": false },
+    "outbound_authority": { "score": 0.54, "top_domains": ["ui.adsabs.harvard.edu", "scholar.google.com"] },
+    "boilerplate_ratio": { "ratio": 0.08, "confidence": "high" }
   }
 }
 ```
 
-The agent learns *before reading a word*: this is an academic source (0.85 authority), no publish date was found (verify independently), here's the one-sentence summary, the key numbers, and there's no paywall or syndication flag. See [`examples/agent-conversation.md`](examples/agent-conversation.md) for a full worked round-trip.
+The agent learns *before reading a word*: this is an academic source (0.85 authority), structural trust is **medium** — high authority, but no publish date found, so verify independently. It also gets the one-sentence summary, the key numbers, and confirmation there's no paywall or syndication flag. See [`examples/agent-conversation.md`](examples/agent-conversation.md) for a full worked round-trip.
 
 ## Payments
 
-- **First 10 parses per network (subnet) are free** — lifetime, shared across your whole network. No account, no API key, no human required.
-- **After that: $0.005 per parse** (flat, no subscriptions) via **x402** — an open micropayment protocol. Your agent's wallet signs the payment automatically. To give your agent a Coinbase wallet, run `npx @coinbase/payments-mcp` and connect it alongside NanoParse.
+- **10 free parses per month with a signed wallet** (sign the claim message — no payment), or 3 anonymous free tries per network. No account, no API key, no human required.
+- **After that: $0.002 per parse** (flat, no subscriptions) via **x402** — an open micropayment protocol. Your agent's wallet signs the payment automatically. To give your agent a Coinbase wallet, run `npx @coinbase/payments-mcp` and connect it alongside NanoParse.
+
+Copy-paste recipe for both paths — the wallet-MCP one with no code, and a ~40-line REST client — including the exact `402 → sign → retry` loop and the error codes worth branching on: [`examples/pay-with-x402.md`](examples/pay-with-x402.md).
 
 ## How payments work under the hood
 
-When an agent without free quota calls `nanoparse_fetch`, the endpoint responds with an **HTTP 402 — Payment Required** carrying x402 payment instructions. The agent's wallet signs a $0.005 USDC (Base) transfer, the facilitator settles it, and the parse proceeds. The hosted endpoint handles the entire challenge → settlement flow — the agent never needs a private key on your machine.
+When an agent without free quota calls `nanoparse_fetch`, the endpoint responds with an **HTTP 402 — Payment Required** carrying x402 payment instructions. The agent's wallet signs a $0.002 USDC (Base) transfer, the facilitator settles it, and the parse proceeds. The hosted endpoint handles the entire challenge → settlement flow — the agent never needs a private key on your machine.
 
 ## Pricing vs Firecrawl
 
 | | NanoParse | Firecrawl Hobby |
 |---|---|---|
-| Billing | **$0.005 per parse, flat** | $16/mo subscription, credits expire monthly |
-| 5,000 parses | **$50.00** | $16 base — but ~$145 with JSON/extraction modes (9× credit burn) |
+| Billing | **$0.002 per parse, flat** | $16/mo subscription, credits expire monthly |
+| 5,000 parses | **$25.00** | $16 base — but ~$145 with JSON/extraction modes (9× credit burn) |
 | Account / API key | **None** | Required |
 | Agent can pay directly (x402) | **Yes** | No |
 
@@ -110,5 +121,7 @@ is the current, supported integration.
 - Quick start & integration: [nanoparse.app/quickstart](https://nanoparse.app/quickstart)
 - Compare & pricing: [nanoparse.app/compare](https://nanoparse.app/compare)
 - API + MCP endpoint: [nanoparse.app](https://nanoparse.app)
+- Security policy: [SECURITY.md](SECURITY.md) — report a vulnerability to hello@nanoparse.app
+  (also published at `https://nanoparse.app/.well-known/security.txt`)
 
 MIT licensed.

package/examples/agent-conversation.md

@@ -36,6 +36,13 @@ word of the paper.
       { "value": "2,247", "context": "Thu, 25 Jan 2024 16:34:00 UTC (2,247 KB)" },
       { "value": "2,290", "context": "Sat, 30 Mar 2024 16:36:33 UTC (2,290 KB)" }
     ],
+    "structural_trust_score": {
+      "level": "medium",
+      "trust_factors": [
+        "High-authority source",
+        "No publish date found — verify independently"
+      ]
+    },
     "content_type": "academic_paper",
     "reading_time": { "minutes": 4 },
     "hedge_language": { "density": "low", "markers_found": 0, "per_500_words": 0 },
@@ -47,6 +54,10 @@ word of the paper.
 
 ## How the agent reasons about it
 
+- **Structural trust: medium** — Litmus flags this as high-authority
+  (academic, 0.85) but with no publish date found, so the verdict is "verify
+  independently," not "trust blindly." The agent treats it as a solid source
+  it still needs to date-check.
 - **Authority 0.85, academic** — high-trust source class. Claims from this
   paper can be weighed accordingly. (Litmus scores the *source class*, not
   the truth of the content — the agent still reads and thinks.)

package/examples/costs.md

@@ -1,6 +1,6 @@
 # Cost comparison: NanoParse vs Firecrawl
 
-Pricing verified 2026-08-28. NanoParse: **$0.01 per parse, flat** — no
+Pricing verified 2026-08-28 (Firecrawl); NanoParse updated to the current flat rate. NanoParse: **$0.002 per parse, flat** — no
 subscription, no account, no API key. Litmus signals, full JS/SPA rendering,
 and GFM tables are included in every parse — there are no feature
 multipliers.
@@ -19,11 +19,11 @@ Two things the base rate hides:
 
 1. **Credits do not roll over.** A Hobby subscription is $16 every month —
    use 1,000 of 5,000 credits and you still paid $16. NanoParse bills only
-   what you use: $10 for exactly 1,000 parses.
+   what you use: $5 for exactly 1,000 parses.
 2. **Feature multipliers.** JSON extraction and enhanced mode each add
    credits per page (up to 9 credits/page combined). At Hobby that makes a
-   fully-featured parse ~$0.029/page — ~3× NanoParse's flat rate. Litmus,
-   structured output, and rendering are included in NanoParse's $0.01 with
+   fully-featured parse ~$0.029/page — ~6× NanoParse's flat rate. Litmus,
+   structured output, and rendering are included in NanoParse's $0.002 with
    no multiplier.
 
 ## What a month of 5,000 parses costs
@@ -31,9 +31,9 @@ Two things the base rate hides:
 | | NanoParse | Firecrawl Hobby |
 |---|---|---|
 | Subscription | None — pay per parse | $16/mo, billed every month |
-| 5,000 plain scrapes | **$50.00** | $16 (base rate) |
-| 5,000 with extraction/features | **$50.00** | ~$145 (9× credit burn) |
-| Use only 1,000 of your quota | **$10.00** | $16 (credits expire) |
+| 5,000 plain scrapes | **$25.00** | $16 (base rate) |
+| 5,000 with extraction/features | **$25.00** | ~$145 (9× credit burn) |
+| Use only 1,000 of your quota | **$5.00** | $16 (credits expire) |
 | Account / API key needed | No | Yes |
 | Agent can pay directly (x402) | Yes | No |
 

package/examples/pay-with-x402.md

@@ -0,0 +1,272 @@
+# Paying for a parse with x402
+
+NanoParse answers an unauthenticated call with **HTTP 402** and machine-readable
+terms — the price, the token, the chain, the recipient, and what a valid signature
+must look like. No account, no API key, no card, no subscription.
+
+- **10 free parses per month with a signed wallet**, or 3 anonymous free tries per
+  network.
+- **After that: $0.002 USDC on Base per parse**, flat.
+- Settlement runs **after** a page is read. A page that cannot be read — bot wall,
+  consent wall, paywall, JS shell with no text — is reported with a named reason
+  and **never charged**.
+
+Every parse returns clean Markdown plus **Litmus** — 20 machine-readable signals
+(source authority, freshness, structural trust, content density, syndication,
+paywall state) in the same response, not as a second billed call.
+
+Two ways to pay. Pick one.
+
+---
+
+## Option A — give the agent a wallet, write no code
+
+Add NanoParse to your MCP client, and give the agent a wallet that can sign:
+
+```json
+{
+  "mcpServers": {
+    "nanoparse": {
+      "url": "https://nanoparse.app/mcp"
+    }
+  }
+}
+```
+
+```
+npx @coinbase/payments-mcp
+```
+
+(The Coinbase agentic wallet MCP — self-custody, funded via Apple Pay. Docs:
+<https://docs.cdp.coinbase.com/agentic-wallet/mcp/welcome>.)
+
+Then the loop is two calls:
+
+1. `nanoparse_fetch(url)`. Once the free tier is spent, the tool returns an
+   `isError` result whose **`structuredContent` is the PaymentRequired object** —
+   `x402Version`, `accepts[]`, `extensions`. It is the quote, not a failure.
+2. Sign `accepts[0]` and retry the same tool with
+   `payment_signature` = the base64url JSON envelope. This argument works in
+   **every** MCP client; there are no custom headers to set. A client that can
+   set headers may instead send the same payload as `Payment-Signature`, or put
+   the envelope object in `_meta["x402/payment"]`.
+
+`nanoparse_status(address)` is free and tells the agent what it needs to know
+before spending: free parses remaining, wallet and USDC balance, whether the next
+call will go through without payment.
+
+---
+
+## Option B — a REST client that pays its own way
+
+~40 lines of Node with [`viem`](https://viem.sh). No SDK, no server-side key:
+the wallet is the caller's.
+
+```js
+// read-page.mjs — read one page, paying $0.002 in USDC on Base only if asked.
+// Usage:  npm i viem && WALLET_KEY=0x... node read-page.mjs https://example.com
+//
+// 1. Try the free tier (10/month with a signed wallet, or 3 anonymous tries): a plain POST.
+// 2. A 402 is the quote, not an error. Read the terms out of it.
+// 3. Sign an EIP-3009 permit over those terms (gas is the facilitator's).
+// 4. Retry with the signed envelope; poll /status (free) until the page lands.
+import { privateKeyToAccount } from "viem/accounts";
+
+const ENDPOINT = "https://nanoparse.app/fetch";
+const account = privateKeyToAccount(process.env.WALLET_KEY);
+const b64 = (o) => Buffer.from(JSON.stringify(o)).toString("base64");
+
+async function readPage(url) {
+  const post = (headers) =>
+    fetch(ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify({ url }),
+    });
+
+  // 1. Free tier first — no payment, no key, no account.
+  let res = await post();
+  if (res.status !== 402) {
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+    return poll(await res.json());
+  }
+
+  // 2. The terms. `amount` is micro-USDC ("2000" = $0.002) and `payTo` is the
+  //    only address a permit should ever be signed for.
+  const terms = (await res.json()).payment_required.accepts[0];
+  const now = Math.floor(Date.now() / 1000);
+  const nonce = "0x" + Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("hex");
+  const authorization = {
+    from: account.address,
+    to: terms.payTo,
+    value: terms.amount,
+    validAfter: String(now - 5),
+    validBefore: String(now + 895), // within maxTimeoutSeconds from the challenge
+    nonce,
+  };
+
+  // 3. EIP-3009 transferWithAuthorization. The EIP-712 domain belongs to the
+  //    token contract, so take it from the challenge: extra.name is the domain
+  //    name "USD Coin" — signing against the ticker "USDC" fails verification.
+  const signature = await account.signTypedData({
+    domain: {
+      name: terms.extra.name,
+      version: terms.extra.version,
+      chainId: 8453, // Base
+      verifyingContract: terms.asset,
+    },
+    types: {
+      TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+      ],
+    },
+    primaryType: "TransferWithAuthorization",
+    message: {
+      ...authorization,
+      value: BigInt(authorization.value),
+      validAfter: BigInt(authorization.validAfter),
+      validBefore: BigInt(authorization.validBefore),
+    },
+  });
+
+  // 4. Retry with the envelope the challenge quoted: accepted[] echoed verbatim.
+  res = await post({
+    "Payment-Signature": b64({ x402Version: 2, accepted: terms, payload: { signature, authorization } }),
+  });
+  const job = await res.json();
+  if (!res.ok) throw new Error(`${job.error_code}: ${job.message}`);
+  return poll(job); // 202 { jobId, statusUrl }
+}
+
+// /status is free and unauthenticated: watch a job without spending anything.
+async function poll(job) {
+  for (;;) {
+    const out = await (await fetch(job.statusUrl)).json();
+    if (out.status === "completed") return out; // { markdown, metadata, litmus }
+    if (out.status !== "processing") throw new Error(`${out.status}: ${out.error_code ?? ""}`);
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+}
+
+console.log((await readPage(process.argv[2])).markdown);
+```
+
+---
+
+## The 402 is the quote
+
+Captured live, free tier exhausted, no payment attached:
+
+```json
+{
+  "error": "payment_required",
+  "error_code": "free_tier_exhausted",
+  "free_calls_used": 10,
+  "free_calls_limit": 10,
+  "payment_required": {
+    "x402Version": 2,
+    "accepts": [
+      {
+        "scheme": "exact",
+        "network": "eip155:8453",
+        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        "amount": "2000",
+        "payTo": "0x57a1d06873db575baeae1f6af30862a75c7bd570",
+        "maxTimeoutSeconds": 60,
+        "extra": { "assetTransferMethod": "eip3009", "name": "USD Coin", "version": "2" }
+      }
+    ]
+  }
+}
+```
+
+The same terms travel base64url-encoded in the `payment-required` response header,
+and the recipient is repeated as a CAIP-style `pay-to: ethereum:base:0x…` header.
+`access-control-allow-origin: *` and the `Content-Type, Payment-Signature,
+Authorization` request headers are allowed on this route, so a browser-side agent
+can send a signed payment too.
+
+Four fields carry the weight:
+
+- **`amount`** is micro-USDC — `"2000"` is $0.002 at six decimals. There is no
+  currency string to parse.
+- **`network`** is a CAIP-2 chain id (`eip155:8453` is Base) and **`asset`** is the
+  USDC contract on it, so the client never guesses which USDC.
+- **`extra.name` / `extra.version`** are the EIP-712 domain of the token contract:
+  `"USD Coin"` v2. Signing against `"USDC"` produces a signature that fails
+  verification — the domain is part of the digest.
+- **`payTo`** is the only address a permit should ever be signed for. A payload
+  pointing anywhere else is rejected before any signature is checked.
+
+## What the server checks before the facilitator is called
+
+A wrong shape costs nothing — it answers `400 invalid_payment_payload`:
+
+- `x402Version` is exactly `2`.
+- `accepted` repeats the terms verbatim: `scheme`, `network`, `asset`, `amount`,
+  `payTo`.
+- `payload.signature` is `0x` + 130 hex characters (65-byte packed `r‖s‖v`).
+- `payload.authorization.value` equals `amount` exactly.
+- `payload.authorization.nonce` is `0x` + 64 hex characters, and single-use
+  on-chain — which is what makes "retry the same payload" safe rather than hopeful.
+- `validAfter` is in the past and `validBefore` in the future.
+
+## Retry policy, as error codes
+
+| `error_code` | What to do |
+|---|---|
+| `insufficient_usdc` | Fund the wallet and sign a **fresh** envelope. |
+| `invalid_payment_payload`, `invalid_payment` | The shape or signature is wrong. Fix it; retrying unchanged cannot succeed. |
+| `permit_expired`, `permit_not_yet_valid` | Sign a fresh permit. |
+| `settlement_failed` | Ambiguous settle. Retry with the **same** envelope — it is idempotent. |
+| `screening_declined` | Compliance screening declined. Do not retry. |
+| `location_blocked` | A jurisdiction the facilitator does not serve. |
+| `self_send_not_allowed` | Payer and recipient are the same address. |
+| `content_insufficient` | The page rendered but yielded almost no text (JS shell, login wall). **Not charged.** |
+| `domain_blocked` | The host repeatedly returned nothing parseable. **Not charged.** Do not retry. |
+
+There is no refund path because nothing is charged up front: settlement runs after
+a successful read, so a failed render simply never settles.
+
+## Check the recipient before you sign
+
+`/.well-known/x402` publishes the address the endpoint claims, and the 402 repeats
+it. Compare them before signing anything:
+
+```js
+const accept = terms; // accepts[0] from the 402
+const disc = await (await fetch("https://nanoparse.app/.well-known/x402")).json();
+if (!disc.ownershipProofs.map((a) => a.toLowerCase()).includes(accept.payTo.toLowerCase()))
+  throw new Error("recipient not published by the endpoint");
+```
+
+That buys consistency, not identity — both documents come from the same origin —
+but it is one GET and it catches a swapped recipient.
+
+## What was verified
+
+- The client under **Option B** was run verbatim against the live endpoint on
+  2026-10-06 with a fresh, unfunded throwaway wallet: free tier exhausted → `402`
+  → signed envelope → retry → `insufficient_usdc: Payer's USDC balance is too low
+  for this call (needs 2000 micro-USDC on Base)`. The shape and signature were
+  accepted; nothing was charged.
+- The **Option A** MCP loop was verified the same way: `tools/call` returned
+  `isError: true` with `structuredContent` = the PaymentRequired object, and the
+  retry carrying `payment_signature` answered
+  `-32000 / insufficient_usdc` for the unfunded payer.
+- The settle leg — USDC actually moving to the treasury on Base — is exercised
+  end to end by our own labeled canary through this same paid path.
+
+## Docs
+
+- Quick start: <https://nanoparse.app/quickstart>
+- Machine spec: <https://nanoparse.app/openapi.json>
+- Agent-facing description: <https://nanoparse.app/llms.txt>
+- x402 discovery: <https://nanoparse.app/.well-known/x402>
+
+MIT licensed.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nanoparse-mcp",
-  "version": "2.0.0",
-  "description": "NanoParse MCP — hosted Model Context Protocol server for AI agents. Any URL becomes clean Markdown with attribution signals. $0.005 per page via x402, no account or API key.",
+  "version": "2.0.1",
+  "description": "NanoParse MCP \u2014 hosted Model Context Protocol server for AI agents. Any URL becomes clean Markdown with attribution signals. $0.002 per page via x402, no account or API key.",
   "keywords": [
     "mcp",
     "model-context-protocol",