@url2md-io/mcp 0.1.0 → 0.1.2

package/README.md

@@ -127,7 +127,7 @@ The server prints one line to stderr when it starts, naming the deployment, **th
 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
+@url2md-io/mcp 0.1.2 → 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.
@@ -138,10 +138,10 @@ Your private key is never printed, logged, or sent anywhere except as the signat
 
 ### `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. |
+| Parameter | What it does |
+|---|---|
+| `url` | **Required.** The absolute `http(s)` URL to convert. |
+| `render` | Optional, default `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.
@@ -213,8 +213,12 @@ every warning as a `NOTE:` line. A clean, settled call has no preamble at all.
 **$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 —
+**Which failures are free, exactly.** A malformed URL, an unsupported scheme and a blocked host are
+refused on the *unpaid* request: nothing is signed and `details` is empty. A **missing** URL is the
+one exception, and it costs nothing either: the bare path answers a payment challenge like every
+other x402 endpoint, so this client signs a payment and is then told `INVALID_URL` — the service
+settles nothing for a call it answered with an error, so the authorization is wasted, not spent.
+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
@@ -282,14 +286,43 @@ 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. |
+One of the two key variables is required. Everything else has a default.
+
+#### `URL2MD_PRIVATE_KEY_FILE`
+
+Path to a file containing the key. **Preferred** — a path is not a secret, and a key on a command
+line is visible to every process on the machine. Wins if both key variables are set.
+
+#### `URL2MD_PRIVATE_KEY`
+
+The key itself: `0x` followed by 64 hex characters. Use the file instead where you can.
+
+#### `URL2MD_MAX_PRICE_USD` — default `0.10`
+
+The most this server will commit for **one call**, in USD, across every round of that call. A
+tolled page takes two rounds; this ceiling covers both.
+
+#### `URL2MD_MAX_SPEND_USD` — default `1.00`
+
+The most this server will commit **in total**, for as long as the process runs. Restarting resets
+it.
+
+#### `URL2MD_BASE_URL` — default `https://url2md.io`
+
+The url2md deployment to call. Must be `https://` (only a loopback address may be plain `http`),
+because this is the origin every 402 is checked against.
+
+#### `URL2MD_TIMEOUT_MS` — default `90000`
+
+How long to wait for one conversion, in milliseconds. 90 s is the default because that is what the
+service's own bounds add up to: 20 s for the fetch (robots.txt, every redirect hop and the body run
+on one deadline) and, when the page needs a headless browser, 55 s more for the render (30 s of
+navigation plus 25 s of action and slack) — 75 s in the worst case, plus room for the network and
+the payment round trips.
+
+Do not set it to 30 s because you read that a render gets 30 s: that is the navigation timeout
+*inside* the browser, not the wall clock. Giving up early does not cancel the call, and on a page
+that needed a browser your payment has already settled by the time the render starts.
 
 ---
 
@@ -302,35 +335,35 @@ can branch on the code rather than read prose:
 { "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.
+| Code | What it means, and 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 missing, or 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, and url2md obeys robots.txt — so there is nothing to retry. Checked after the payment gate, so an authorization was signed: read `details.committedUsd`. |
+| `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, so it is not available through url2md. Nothing to do. |
+| `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`. |
+| `UPSTREAM_STATUS` | The origin answered a status url2md cannot convert. `details.status` is the origin's own: `404` or `5xx` means the page is broken or gone, but `403` usually means the origin refused **url2md** — a bot wall, not a page failure — and retrying changes nothing. On a `429` the origin is asking for a slower pace: `details.retryAfter` carries its `Retry-After` when it sent one, and that is the one case where waiting and trying again is worth a second payment. |
+| `RENDER_FAILED`, `UPSTREAM_TIMEOUT` | The page itself failed to load or render in time. `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 OpenAPI document,
+<https://url2md.io/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;
@@ -372,21 +405,23 @@ the public address.
 
 ---
 
-## Working on it
+## Checking what you are about to run
 
-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`.
+The service's repository is private, so this README and the published tarball are the whole public
+record — which is the reason the README documents every check, every error code and everything the
+key is used for, rather than pointing at code you cannot open. The tarball is small and readable,
+and you can have it without installing anything:
 
 ```bash
-npm install          # in mcp/
-npm run typecheck    # tsc
-npm test             # vitest
+npm pack @url2md-io/mcp     # downloads the tarball; tar -xzf it and read dist/
 ```
 
+`dist/` is plain JavaScript compiled from TypeScript, a few hundred lines. `dist/client.js` is
+where the key is used and where every 402 is checked against what the service publishes.
+
 ## 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>.
+(`/llms.txt`) and OpenAPI (`/openapi.json`). Questions: <hello@url2md.io>.
 
 MIT.

package/dist/client.js

@@ -120,6 +120,9 @@ export function readConfig(env, readFile = defaultReadFile) {
         throw new Url2mdToolError("CONFIG_BAD_BASE_URL", `URL2MD_BASE_URL must be https:// (got ${JSON.stringify(baseUrl)}). This URL is what every 402 is checked against, so anyone who can rewrite the traffic can rewrite the terms this client verifies. Only a loopback address may be plain http.`);
     }
     const timeoutRaw = (env["URL2MD_TIMEOUT_MS"] ?? "").trim();
+    // 90 s: the service's own worst case (20 s fetch + 55 s browser wall clock = 75 s, its `LIMITS.worstCaseMs`)
+    // plus slack for the network and the payment round trips. It is the same number as the service's
+    // `CLIENT_TIMEOUT_MS`, kept in step by a drift guard because this package cannot import from that one.
     const timeoutMs = timeoutRaw ? Number(timeoutRaw) : 90_000;
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         throw new Url2mdToolError("CONFIG_BAD_TIMEOUT", `URL2MD_TIMEOUT_MS must be a positive number of milliseconds; got ${JSON.stringify(timeoutRaw)}.`);

package/dist/index.js

@@ -18,7 +18,7 @@ import { Budget, ceilingLooksWrong, CEILING_WORTH_MENTIONING_USD, convert, disco
  * message or into a tool result.
  */
 export const SERVER_NAME = "url2md";
-export const SERVER_VERSION = "0.1.0";
+export const SERVER_VERSION = "0.1.2";
 export const TOOL_NAME = "fetch_markdown";
 export const inputSchema = z.object({
     url: z.string().describe("The absolute http(s) URL to convert. Public hosts only: private, loopback and link-local addresses are refused, and the origin's robots.txt is obeyed."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@url2md-io/mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for url2md — any URL in, clean Markdown out. Pays per call over x402 from your own wallet.",
   "keywords": [
     "mcp",
@@ -11,13 +11,8 @@
     "url-to-markdown"
   ],
   "homepage": "https://url2md.io",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/glassyeah/url2md.git",
-    "directory": "mcp"
-  },
   "bugs": {
-    "url": "https://url2md.io"
+    "email": "hello@url2md.io"
   },
   "license": "MIT",
   "type": "module",
@@ -25,7 +20,7 @@
     "node": ">=22.18"
   },
   "bin": {
-    "url2md": "./dist/index.js"
+    "url2md": "dist/index.js"
   },
   "files": [
     "dist",