@url2md-io/mcp 0.1.1 → 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.1 → 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.
@@ -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
@@ -335,7 +339,7 @@ can branch on the code rather than read prose:
 |---|---|
 | `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. |
+| `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. |
@@ -354,7 +358,8 @@ can branch on the code rather than read prose:
 | `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`. |
-| `RENDER_FAILED`, `UPSTREAM_STATUS`, `UPSTREAM_TIMEOUT` | The page itself failed. `retryable` says whether trying again is worth it. |
+| `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,

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.1";
+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.1",
+  "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",
@@ -20,7 +20,7 @@
     "node": ">=22.18"
   },
   "bin": {
-    "url2md": "./dist/index.js"
+    "url2md": "dist/index.js"
   },
   "files": [
     "dist",