@url2md-io/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 url2md
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,392 @@
+# @url2md-io/mcp
+
+> **The official package is `@url2md-io/mcp` — with the `@url2md-io` scope.** The unscoped name
+> `url2md-mcp` on npm is **someone else's package**, published by an unrelated person in May 2026.
+> It is not ours, we have no control over it, and we cannot see what it does with what it is given.
+> Running `npx url2md-mcp` runs their code — and this tool is set up by handing it a wallet private
+> key. Give the key only to `@url2md-io/mcp`. If the name you are about to install has no scope in
+> front of it, it is the wrong one.
+
+An MCP server that gives your agent one tool: **turn any URL into clean Markdown**.
+
+It handles ordinary pages, JavaScript-rendered pages (a headless browser is used only when the page
+needs one) and PDFs. There is no account, no sign-up and no API key. Each call is paid for on-chain,
+from a wallet you control, at **$0.005** — half a cent — in USDC on Base. The settlement receipt
+comes back with the Markdown.
+
+---
+
+## What you need before you start
+
+1. **Node 22.18 or newer.** Check with `node --version`. Nothing else: `npx` fetches the package
+   and the published files are plain JavaScript, so there is nothing for you to build.
+2. **A wallet private key, holding USDC on Base.** This is the part that is different from a normal
+   MCP server, so it is worth being precise:
+   - It must be a raw private key: `0x` followed by 64 hex characters. Not a seed phrase.
+   - The wallet needs **USDC only — no ETH**. The payment facilitator submits the transfer and pays
+     the gas. A wallet with $2 of USDC and nothing else works.
+   - **Use a fresh wallet with a small balance.** Anything with this key can spend the USDC in it.
+     Do not use a wallet you keep anything else in.
+   - Get USDC on Base by bridging, or by buying on an exchange that withdraws to Base directly
+     (Coinbase does). The USDC contract on Base is `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
+
+If you would rather try it without spending real money, see [Trying it on
+testnet](#trying-it-on-testnet) below — the test network's USDC is free.
+
+---
+
+## Install
+
+Nothing to install. Every example below runs the server with `npx`, which fetches it on first use
+and caches it:
+
+```bash
+npx @url2md-io/mcp
+```
+
+Mind the scope — `@url2md-io/mcp`, never the unscoped `url2md-mcp`, which is someone else's
+package. Run it once by hand like that and it will refuse to start, with `CONFIG_MISSING_KEY`.
+That is the answer you want: the package is there and the only thing missing is the key, which the
+next step sets up.
+
+To pin a version, or to keep it off the network at start-up, install it instead:
+
+```bash
+npm install -g @url2md-io/mcp    # then the command is: url2md
+```
+
+### Put the key in a file, not in a config
+
+You can pass the key in `URL2MD_PRIVATE_KEY`, and the examples below show both ways. Prefer the
+file:
+
+```bash
+umask 077
+printf '0xYOUR_PRIVATE_KEY' > ~/.url2md-key    # no trailing newline needed; one is fine
+chmod 600 ~/.url2md-key
+```
+
+Then set **`URL2MD_PRIVATE_KEY_FILE=/Users/you/.url2md-key`** instead of the key itself. A path is
+not a secret. The key itself, put anywhere else, ends up somewhere you did not intend:
+
+- `claude mcp add … --env URL2MD_PRIVATE_KEY=0x…` puts it in your shell history, and then in
+  `~/.claude.json` in plaintext.
+- Any `-e URL2MD_PRIVATE_KEY=0x…` on a command line is visible to every process on the machine
+  through `ps aux` for as long as it runs.
+
+`URL2MD_PRIVATE_KEY_FILE` wins if both are set.
+
+## Add it to your MCP client
+
+### Claude Code
+
+```bash
+claude mcp add url2md \
+  --env URL2MD_PRIVATE_KEY_FILE=/Users/you/.url2md-key \
+  --env URL2MD_BASE_URL=https://url2md.io \
+  -- npx -y @url2md-io/mcp
+```
+
+### Claude Desktop, Cursor, Windsurf, and anything else that reads a JSON config
+
+Add this to the `mcpServers` object of your client's config file (Claude Desktop:
+`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
+`%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "url2md": {
+      "command": "npx",
+      "args": ["-y", "@url2md-io/mcp"],
+      "env": {
+        "URL2MD_PRIVATE_KEY_FILE": "/Users/you/.url2md-key",
+        "URL2MD_BASE_URL": "https://url2md.io"
+      }
+    }
+  }
+}
+```
+
+If the server never appears, the cause is almost always `PATH`. Desktop clients on macOS are
+launched by the window manager with a minimal `PATH` that usually does not include a
+version-managed Node, so a bare `"npx"` resolves to nothing. Use an absolute path for `command` —
+`which npx` prints it — and keep `args` as they are. Restart the client after editing the file.
+
+### Check it before you wire it up
+
+You can talk to the server yourself with the reference MCP inspector, which needs nothing installed:
+
+```bash
+npx @modelcontextprotocol/inspector --cli npx -y @url2md-io/mcp \
+  -e URL2MD_PRIVATE_KEY_FILE=/Users/you/.url2md-key \
+  --method tools/list
+```
+
+The server prints one line to stderr when it starts, naming the deployment, **the network and
+whether it is real money**, the wallet address it will pay from, and the per-call limit:
+
+```
+@url2md-io/mcp 0.1.0 → https://url2md.io; eip155:8453 (real money); paying from 0x0972…7a36, at most $0.10 per call and $1.00 in total
+```
+
+Your private key is never printed, logged, or sent anywhere except as the signature on a payment.
+
+---
+
+## The tool
+
+### `fetch_markdown`
+
+| Parameter | Required | Default | What it does |
+|---|---|---|---|
+| `url` | yes | — | The absolute `http(s)` URL to convert. |
+| `render` | no | `auto` | `auto`: use a headless browser only if the page looks client-rendered. `static`: never render, take the HTML as served. `browser`: always render. |
+
+`render=browser` costs the same but is slower, and can fail on pages a plain fetch would have
+handled. `auto` is right almost always.
+
+**What comes back** — the Markdown as the tool's text, and this as structured content:
+
+```json
+{
+  "markdown": "# Example Domain\n\nThis domain is for use in documentation examples…",
+  "url": "https://example.com/",
+  "finalUrl": "https://example.com/",
+  "title": "Example Domain",
+  "source": "static",
+  "words": 24,
+  "tokensEstimate": 42,
+  "warnings": [],
+  "payment": {
+    "amountUsd": "0.005",
+    "amountAtomic": "5000",
+    "network": "eip155:8453",
+    "payTo": "0xa09aE66Ec8664475697FfC0eb45aa3Fe52Aa6030",
+    "settled": true,
+    "payer": "0x…your wallet",
+    "transaction": "0x3bd94a…",
+    "explorerUrl": "https://basescan.org/tx/0x3bd94a…",
+    "ledgerId": "e17a62c0-0801-4043-a58a-da135c1343ae"
+  },
+  "paymentRounds": 1,
+  "committedUsd": "0.005",
+  "signed": [
+    {
+      "amountUsd": "0.005",
+      "amountAtomic": "5000",
+      "network": "eip155:8453",
+      "payTo": "0xa09aE66Ec8664475697FfC0eb45aa3Fe52Aa6030",
+      "payer": "0x…your wallet",
+      "nonce": "0xdccc5af7…",
+      "validBefore": "2026-09-07T05:17:26.000Z"
+    }
+  ]
+}
+```
+
+`source` says how the Markdown was produced: `static`, `browser`, `pdf`, `origin-markdown` or
+`text`. Fields that do not apply are left out rather than set to `null`.
+
+**`payment` is there whenever you were charged**, even if the service answered without confirming
+the settlement. The `amountUsd`, `network`, `payTo` and `payer` are always **what this client
+signed** — never what the service's receipt claims. If the receipt disagrees with any of them,
+`warnings` names both figures and the signed one stands. `settled: false` means no usable
+settlement came back at all; `transaction` is then absent and `warnings` tells you to check the
+wallet on-chain.
+
+`committedUsd` is everything the call authorized, and `signed` lists each authorization with the
+nonce that identifies it on-chain. On an ordinary call `committedUsd` equals `payment.amountUsd`.
+On a **tolled** call it is higher: the first authorization is replaced by the quote, only the quote
+is settled, and the service still holds the first one — `warnings` says so, with both numbers.
+
+Read `warnings`. It carries the service's own notes too — a browser render that failed and fell
+back to the static result, for instance. Anything you must not miss is also written **above the
+Markdown in the tool's text**, because many MCP clients show a model only the text and drop the
+structured content: an unconfirmed payment appears there as a `PAYMENT NOT CONFIRMED` line, and
+every warning as a `NOTE:` line. A clean, settled call has no preamble at all.
+
+---
+
+## What a call costs
+
+**$0.005** per call, whatever the page. The wallet is debited once, when the call succeeds — or, for
+a page that needs a browser, just before the browser starts.
+
+**Which failures are free, exactly.** A bad URL, an unsupported scheme and a blocked host are
+refused on the *unpaid* request: nothing is signed and `details` is empty. Everything else —
+`ROBOTS_DISALLOWED`, `ROBOTS_UNREACHABLE` (which is where a mistyped domain lands), a page that
+times out, a render that fails — is discovered **after** the payment gate, so a signed
+authorization has already left this process. url2md does not settle a payment for a call it
+answered with an error, and the ledger row would say `needs_refund` if it did; but this client
+cannot see the chain and does not claim the money is safe. Every such failure therefore comes back
+with `details.committedUsd`, and `details.signed[]` carrying each authorization's amount,
+recipient, EIP-3009 nonce and expiry — that nonce is what USDC emits as `AuthorizationUsed` when a
+payment is actually redeemed, so you can check for yourself. An agent that retries a mistyped
+domain in a loop signs $0.005 each time until `URL2MD_MAX_SPEND_USD` stops it.
+
+**Pages that charge their own toll.** Some pages are themselves behind an x402 paywall. url2md can
+pay them for you: it quotes you the base price plus the page's toll plus 25 %, you pay that, and it
+pays the origin from its own wallet. Those calls come back with `toll` filled in and
+`paymentRounds: 2`. Tolls above $0.05 are refused rather than passed on.
+
+**Two ceilings.** One call will not commit more than **$0.10** in total, however many rounds it
+takes — comfortably above the most a legitimate call can cost (base + the $0.05 toll cap + margin
+≈ $0.068), and low enough that a surprising price is refused instead of paid. And the whole process
+will not commit more than **$1.00** for as long as it runs, which is what bounds an agent stuck in a
+retry loop; restarting the server resets it. Raise either with `URL2MD_MAX_PRICE_USD` and
+`URL2MD_MAX_SPEND_USD`. Neither check can be turned off, though setting the numbers absurdly high
+has the same effect, so the server says so on startup if you do.
+
+**What is checked before anything is signed.** A `402` is written by whoever answers your request,
+so the terms in it are not evidence of anything on their own. Before signing, this client fetches
+the service's own published terms from `GET /` (free, unpaid) and refuses the payment unless the
+402 matches them:
+
+| Check | Refused with |
+|---|---|
+| The service publishes a `payTo`, an asset and a network at all | `UNPUBLISHED_TERMS` |
+| The recipient is the `payTo` the service publishes | `PAYTO_MISMATCH` |
+| The token is the asset the service publishes | `UNSUPPORTED_PAYMENT_TERMS` |
+| The network is the one the service publishes | `UNSUPPORTED_PAYMENT_TERMS` |
+| The scheme is `exact` | `UNSUPPORTED_PAYMENT_TERMS` |
+| The authorization is redeemable for at most an hour | `UNSUPPORTED_PAYMENT_TERMS` |
+| The **whole call** stays at or under your per-call ceiling | `PRICE_ABOVE_LIMIT` |
+| This process has not spent its session budget | `SPEND_LIMIT_REACHED` |
+
+These **fail closed**: a service that publishes no receiving address gets no signature, rather than
+an unchecked one. The amount is not compared with the published price for the *toll* round, because
+a quote is legitimately higher than the base price — but a **first** 402 above the published price
+is reported in `warnings` even when it is inside your ceiling, since that is a service charging
+something other than what it advertises.
+
+**`URL2MD_BASE_URL` is the whole trust anchor.** Every check above compares the 402 with what *that
+URL* published moments earlier. It stops a service contradicting itself; it cannot stop a service
+that lies consistently, because an impostor writes both halves. So: point it at a deployment you
+trust, and nothing else. It must be `https://` (only a loopback address may be plain `http`), and
+the paid request is pinned to that origin — a redirect to another host is refused
+(`REDIRECT_REFUSED`) rather than followed, because following it would hand your signed
+authorization to whoever the redirect names.
+
+The ceiling bounds the whole call, so a two-round tolled call cannot commit twice the number you
+set — and what a call committed in total is always reported, as `committedUsd` on success and
+`details.committedUsd` on failure.
+
+**If a call fails after a payment was signed**, the error carries `details.signedButUnconfirmed`,
+`details.committedUsd`, and `details.signed` — one entry per authorization, with the amount, the
+recipient, the network, the EIP-3009 nonce and when it stops being redeemable. A signature that has
+left this process is money you have committed whether or not the service ever redeems it, so it is
+never omitted from a failure.
+
+---
+
+## Configuration
+
+| Variable | Required | Default | What it is |
+|---|---|---|---|
+| `URL2MD_PRIVATE_KEY_FILE` | one of these two | — | Path to a file containing the key. **Preferred** — a path is not a secret. Wins if both are set. |
+| `URL2MD_PRIVATE_KEY` | one of these two | — | The key itself: `0x` + 64 hex characters. |
+| `URL2MD_MAX_PRICE_USD` | no | `0.10` | Most this server will commit for **one call**, in USD, across every round of it. |
+| `URL2MD_MAX_SPEND_USD` | no | `1.00` | Most this server will commit **in total**, for as long as the process runs. Restarting resets it. |
+| `URL2MD_BASE_URL` | no | `https://url2md.io` | The url2md deployment to call. |
+| `URL2MD_TIMEOUT_MS` | no | `90000` | How long to wait for one conversion. |
+
+---
+
+## When something goes wrong
+
+Failures come back as MCP error results (`isError: true`) whose text is a JSON object, so an agent
+can branch on the code rather than read prose:
+
+```json
+{ "error": { "code": "BLOCKED_HOST", "message": "localhost is not a public host", "retryable": false, "httpStatus": 400 } }
+```
+
+| Code | What happened | What to do |
+|---|---|---|
+| `CONFIG_MISSING_KEY`, `CONFIG_BAD_KEY`, `CONFIG_BAD_KEY_FILE` | No key, not a private key, or a key file that could not be read. The server refuses to start (exit 2). | Set `URL2MD_PRIVATE_KEY_FILE` to a readable file holding `0x` + 64 hex characters. |
+| `CONFIG_BAD_LIMIT`, `CONFIG_BAD_BASE_URL`, `CONFIG_BAD_TIMEOUT` | A setting the server will not guess at — including a `URL2MD_BASE_URL` that is not `https://`. It refuses to start. | Fix the value named in the message. |
+| `INVALID_URL`, `UNSUPPORTED_SCHEME` | The URL is not an absolute `http(s)` URL. | Fix the URL. |
+| `BLOCKED_HOST` | Private, loopback, link-local or internal host. | Public URLs only — this is deliberate. |
+| `ROBOTS_DISALLOWED` | The origin's robots.txt forbids it. Checked after the payment gate, so an authorization was signed — read `details.committedUsd`. | Nothing; url2md obeys robots.txt. |
+| `PRICE_ABOVE_LIMIT` | The call, in total, would cost more than `URL2MD_MAX_PRICE_USD`. | Read `details.totalUsd`; raise the limit if it is reasonable. |
+| `SPEND_LIMIT_REACHED` | This server has committed its whole `URL2MD_MAX_SPEND_USD` session budget. **Nothing was signed.** | Raise it and restart, or look at why the agent is spending. |
+| `UNPUBLISHED_TERMS` | The service asks for payment but publishes no receiving address, asset or network to check its 402 against. **Nothing was signed.** | Check `URL2MD_BASE_URL`. A real url2md deployment publishes all three at `GET /`. |
+| `PAYTO_MISMATCH` | The 402 asked you to pay an address the service does not publish. **Nothing was signed.** | Do not raise any limit. Check you are pointed at the right `URL2MD_BASE_URL`; if you are, stop and investigate. |
+| `UNSUPPORTED_PAYMENT_TERMS` | The 402's network, asset or scheme is not the one the service publishes, or this client cannot pay it. Nothing was signed. | As above. |
+| `PAYMENT_NOT_SIGNED` | The payment could not be signed — usually the x402 client's own spend controls refusing an unrecognised token. | Read the message; nothing was sent. |
+| `ROBOTS_UNREACHABLE` | The origin's robots.txt could not be fetched. RFC 9309 requires treating that as disallow. Checked after the payment gate, so an authorization was signed — read `details.committedUsd`. | Retryable, but each retry signs another payment: a nonexistent domain lands here too, so check the URL before looping. |
+| `SERVICE_UNREACHABLE`, `TIMEOUT` | url2md itself did not answer, or not in time. | Retryable. Check `URL2MD_BASE_URL`. |
+| `BAD_RESPONSE`, `PAYMENT_NOT_ACCEPTED` | url2md answered something this client could not use, or kept asking for payment after two rounds. | Nothing further was signed. Report it. |
+| `REDIRECT_REFUSED` | The service tried to redirect the request to another host. The request — and the signed authorization it carried — was not followed there. | Check `URL2MD_BASE_URL`. If it is right, stop and investigate: an honest deployment does not do this. |
+| `TOO_MANY_REDIRECTS` | More than three redirects inside the service's own origin. | Check `URL2MD_BASE_URL`. |
+| `UPSTREAM_PAYMENT_REQUIRED`, `UPSTREAM_PAYMENT_FAILED` | The page charges its own toll and url2md could not pass it through, or the origin refused url2md's payment. | If `details.callerCharged` is true you were charged; quote `details.ledgerId`. |
+| `INTERNAL` | An unexpected failure inside this server. | Report it. |
+| `UPSTREAM_TOLL_TOO_HIGH` | The page charges a toll above url2md's $0.05 cap. | Nothing; that page is not available through url2md. |
+| `PAYMENT_REJECTED` | The service refused the payment when it tried to settle it. Usually an empty wallet. | Check the wallet has USDC on the network the startup line names. |
+| `PAYMENT_REQUIRED` | The service asked for payment but does not publish x402 pricing, so this client will not guess at terms. | Check `URL2MD_BASE_URL`. |
+| `RENDER_FAILED`, `UPSTREAM_STATUS`, `UPSTREAM_TIMEOUT` | The page itself failed. | `retryable` says whether trying again is worth it. |
+| `RATE_LIMITED` | 60 calls a minute, 6 browser renders a minute. | Wait. |
+
+url2md's own error codes are documented in full in the service's
+[`FEATURES.md`](https://github.com/glassyeah/url2md/blob/main/FEATURES.md) and `openapi.json`; any
+of them can appear here unchanged.
+
+**If you were charged and got nothing**, the error carries `details.callerCharged: true` and
+`details.ledgerId`. url2md keeps a row for every settled payment and reconciles it against the chain;
+quote the ledger id to <hello@url2md.io>.
+
+---
+
+## Trying it on testnet
+
+Base Sepolia USDC is free, so you can exercise the whole thing without spending anything. Note that
+this changes the **payment network** to Base Sepolia (`eip155:84532`): a wallet funded with USDC on
+Base mainnet cannot pay the testnet deployment, and vice versa. The startup line names the network
+it will pay on, so you can check before you spend.
+
+```bash
+npx @modelcontextprotocol/inspector --cli npx -y @url2md-io/mcp \
+  -e URL2MD_PRIVATE_KEY_FILE=/Users/you/.url2md-testnet-key \
+  -e URL2MD_BASE_URL=https://url2md-testnet.url2md.workers.dev \
+  --method tools/call --tool-name fetch_markdown --tool-arg url=https://example.com
+```
+
+Fund a throwaway wallet from the [Coinbase Base Sepolia faucet](https://portal.cdp.coinbase.com/products/faucet).
+The testnet deployment is the same code as production, on the test network. Set the same
+`URL2MD_BASE_URL` in your client config to point it at testnet permanently.
+
+---
+
+## Why this is a local server and not a hosted one
+
+Because a hosted server would have no wallet of yours to pay with. It would pay from its own and
+then have to bill you some other way — an account, an API key, an invoice — which is the exact thing
+x402 removes. Running it beside your client keeps the key on your machine and the payment yours.
+
+The key is read once at startup and used for one thing: signing
+[EIP-3009](https://eips.ethereum.org/EIPS/eip-3009) USDC transfer authorizations for the exact
+amount the 402 asks for. It is never written to stdout (which is the MCP wire), to stderr, to an
+error message, or into a tool result. The only thing derived from it that ever leaves the process is
+the public address.
+
+---
+
+## Working on it
+
+The source is the `mcp/` directory of the service repository. There is no build step — Node runs the
+TypeScript directly, which is why `engines.node` is `>=22.18`.
+
+```bash
+npm install          # in mcp/
+npm run typecheck    # tsc
+npm test             # vitest
+```
+
+## About url2md
+
+<https://url2md.io> — the service itself, with the same facts as JSON (`GET /`), Markdown
+(`/llms.txt`) and OpenAPI (`/openapi.json`). Source: <https://github.com/glassyeah/url2md>.
+Questions: <hello@url2md.io>.
+
+MIT.