@eidonze/mcpdoctor 0.1.2 → 0.1.3

package/README.md

@@ -1,108 +1,110 @@
-# mcpdoctor
-
-**mcpdoctor is a read-only CLI for inspecting MCP and x402 endpoints.**
-
-Point it at a URL, get one `PASS / FAIL / UNKNOWN` report:
-
-- the **HTTP 402 payment document** — parsed from the known locations
-  (`Payment-Required` / `X-Payment-Required` / `WWW-Authenticate` headers or
-  the response body), in both x402 v1 (`accepts[]`) and v2 (`x402.accepts`)
-  shapes, with every `scheme / network / asset / amount / payTo` field checked;
-- the **discovery manifests** — whether `/.well-known/mcp/server.json` and
-  `/.well-known/x402` are reachable, with a SHA-256 of each;
-- a **SHA-256 digest** of the response body, plus latency and size.
-
-mcpdoctor is **not an MCP server** and does not implement the MCP protocol.
-It is the endpoint inspector you run *before* pointing an MCP client or an
-x402 buyer at an endpoint — a preflight/debugging tool for AI-agent payment
-infrastructure. Zero dependencies. Node ≥ 18. Never touches keys, never pays.
-
-## Install
-
-```bash
-npm install -g @eidonze/mcpdoctor    # or run without installing:
-npx @eidonze/mcpdoctor inspect <url>
-```
-
-## Usage
-
-```bash
-mcpdoctor inspect <url> [--method=GET|POST] [--format=json|markdown]
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `--method` | `GET` | HTTP verb for the probe (`POST` sends `{}`) |
-| `--format` | `markdown` | `json` for CI / machine-readable reports |
-| `--json` | — | shorthand for `--format=json` |
-
-Exit codes: `0` PASS · `1` FAIL · `2` UNKNOWN (network/timeout) · `3` usage error.
-
-## Real examples (captured 2026-09-29, against live endpoints)
-
-Inspecting an MCP endpoint that is free (no payment gate) — the tool reports
-the 200 instead of a 402, and still verifies the discovery manifests:
-
-```json
-{
-  "endpoint": "https://agenttoll-receipts.app.workbuddy.host/mcp",
-  "method": "POST",
-  "finalStatus": "FAIL",
-  "http": { "status": 200, "elapsedMs": 2830, "bodyBytes": 82,
-            "bodySha256": "598dc097dcca1e573c742100863899c00724a021b421a5bb49952d49fec6b4f4" },
-  "findings": [
-    { "status": "FAIL", "code": "NO_402", "message": "Expected HTTP 402, received 200" }
-  ],
-  "metadata": [
-    { "path": "/.well-known/mcp/server.json", "status": 200, "reachable": true }
-  ]
-}
-```
-
-Inspecting the official x402 demo endpoint — it does return 402, but ships a
-payment document mcpdoctor cannot parse, which is exactly the class of silent
-breakage this CLI exists to catch:
-
-```json
-{
-  "endpoint": "https://x402.org/protected",
-  "finalStatus": "FAIL",
-  "http": { "status": 402 },
-  "headers": { "paymentRequired": true },
-  "findings": [
-    { "status": "FAIL", "code": "NO_ACCEPTS",
-      "message": "No recognizable payment requirement found" }
-  ]
-}
-```
-
-## What it does NOT do
-
-- No MCP protocol session: no `initialize`, no `tools/list` — mcpdoctor
-  checks what an endpoint *advertises* (402 documents, discovery manifests),
-  not a full MCP handshake.
-- No wallet, signing, settlement, or retries. Read-only preflight only.
-- `PASS` means the observed 402 document had recognizable, complete fields —
-  it is not a security or payment-success certification.
-
-## Why
-
-We ship an x402 service ourselves ([ReceiptRail](https://github.com/xka0085-byte/agenttoll))
-and hit every way a paid endpoint can silently break:
-
-- an endpoint that validates the request body **before** returning the 402
-  challenge is invisible to every x402 client — they only react to `402`;
-- payment documents arrive in **four different places** and **two different
-  shapes**; parsers that only look at one place report false failures;
-- vendor hint headers without `accepts[]` can shadow the real payment document.
-
-Each check in mcpdoctor maps to a failure mode we actually hit in production.
-
-## Part of the Agent / Chain Evidence Tools suite
-
-Read-only diagnostics for AI agents on Web3 —
-[hub & docs](https://xka0085-byte.github.io/evidence-tools/) ·
-[ReceiptRail (live MCP service)](https://github.com/xka0085-byte/agenttoll) ·
-[npm: @eidonze/mcpdoctor](https://www.npmjs.com/package/@eidonze/mcpdoctor)
-
-MIT licensed. Known limitations are documented, not hidden.
+# mcpdoctor
+
+> ⚠️ **Official package notice**: this is the official `mcpdoctor`, published by npm user [`eidonze`](https://www.npmjs.com/~eidonze), repo [`xka0085-byte/mcp-doctor`](https://github.com/xka0085-byte/mcp-doctor). We are **NOT affiliated** with **mcpdoctor.dev** — that is a *different* product (an MCP **server-auditing** tool). This `mcpdoctor` is an independent, read-only **402/x402 payment-endpoint inspector CLI**. Same name, different tool. Verify the package by its scope: `@eidonze/mcpdoctor`.
+
+**mcpdoctor is a read-only CLI for inspecting MCP and x402 endpoints.**
+
+Point it at a URL, get one `PASS / FAIL / UNKNOWN` report:
+
+- the **HTTP 402 payment document** — parsed from the known locations
+  (`Payment-Required` / `X-Payment-Required` / `WWW-Authenticate` headers or
+  the response body), in both x402 v1 (`accepts[]`) and v2 (`x402.accepts`)
+  shapes, with every `scheme / network / asset / amount / payTo` field checked;
+- the **discovery manifests** — whether `/.well-known/mcp/server.json` and
+  `/.well-known/x402` are reachable, with a SHA-256 of each;
+- a **SHA-256 digest** of the response body, plus latency and size.
+
+mcpdoctor is **not an MCP server** and does not implement the MCP protocol.
+It is the endpoint inspector you run *before* pointing an MCP client or an
+x402 buyer at an endpoint — a preflight/debugging tool for AI-agent payment
+infrastructure. Zero dependencies. Node ≥ 18. Never touches keys, never pays.
+
+## Install
+
+```bash
+npm install -g @eidonze/mcpdoctor    # or run without installing:
+npx @eidonze/mcpdoctor inspect <url>
+```
+
+## Usage
+
+```bash
+mcpdoctor inspect <url> [--method=GET|POST] [--format=json|markdown]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--method` | `GET` | HTTP verb for the probe (`POST` sends `{}`) |
+| `--format` | `markdown` | `json` for CI / machine-readable reports |
+| `--json` | — | shorthand for `--format=json` |
+
+Exit codes: `0` PASS · `1` FAIL · `2` UNKNOWN (network/timeout) · `3` usage error.
+
+## Real examples (captured 2026-09-29, against live endpoints)
+
+Inspecting an MCP endpoint that is free (no payment gate) — the tool reports
+the 200 instead of a 402, and still verifies the discovery manifests:
+
+```json
+{
+  "endpoint": "https://agenttoll-receipts.app.workbuddy.host/mcp",
+  "method": "POST",
+  "finalStatus": "FAIL",
+  "http": { "status": 200, "elapsedMs": 2830, "bodyBytes": 82,
+            "bodySha256": "598dc097dcca1e573c742100863899c00724a021b421a5bb49952d49fec6b4f4" },
+  "findings": [
+    { "status": "FAIL", "code": "NO_402", "message": "Expected HTTP 402, received 200" }
+  ],
+  "metadata": [
+    { "path": "/.well-known/mcp/server.json", "status": 200, "reachable": true }
+  ]
+}
+```
+
+Inspecting the official x402 demo endpoint — it does return 402, but ships a
+payment document mcpdoctor cannot parse, which is exactly the class of silent
+breakage this CLI exists to catch:
+
+```json
+{
+  "endpoint": "https://x402.org/protected",
+  "finalStatus": "FAIL",
+  "http": { "status": 402 },
+  "headers": { "paymentRequired": true },
+  "findings": [
+    { "status": "FAIL", "code": "NO_ACCEPTS",
+      "message": "No recognizable payment requirement found" }
+  ]
+}
+```
+
+## What it does NOT do
+
+- No MCP protocol session: no `initialize`, no `tools/list` — mcpdoctor
+  checks what an endpoint *advertises* (402 documents, discovery manifests),
+  not a full MCP handshake.
+- No wallet, signing, settlement, or retries. Read-only preflight only.
+- `PASS` means the observed 402 document had recognizable, complete fields —
+  it is not a security or payment-success certification.
+
+## Why
+
+We ship an x402 service ourselves ([ReceiptRail](https://github.com/xka0085-byte/agenttoll))
+and hit every way a paid endpoint can silently break:
+
+- an endpoint that validates the request body **before** returning the 402
+  challenge is invisible to every x402 client — they only react to `402`;
+- payment documents arrive in **four different places** and **two different
+  shapes**; parsers that only look at one place report false failures;
+- vendor hint headers without `accepts[]` can shadow the real payment document.
+
+Each check in mcpdoctor maps to a failure mode we actually hit in production.
+
+## Part of the Agent / Chain Evidence Tools suite
+
+Read-only diagnostics for AI agents on Web3 —
+[hub & docs](https://xka0085-byte.github.io/evidence-tools/) ·
+[ReceiptRail (live MCP service)](https://github.com/xka0085-byte/agenttoll) ·
+[npm: @eidonze/mcpdoctor](https://www.npmjs.com/package/@eidonze/mcpdoctor)
+
+MIT licensed. Known limitations are documented, not hidden.

package/bin/mcpdoctor.mjs

@@ -1,155 +1,155 @@
-#!/usr/bin/env node
-import { createHash } from 'node:crypto';
-
-const MAX_BODY = 1024 * 1024;
-const TIMEOUT = 10_000;
-const VERSION = '0.1.2';
-
-const help = `mcpdoctor ${VERSION}
-
-Read-only MCP/x402 endpoint diagnostics.
-
-Usage:
-  mcpdoctor inspect <url> [--method=GET|POST] [--format=json|markdown]
-  mcpdoctor --help
-
-This MVP never signs, pays, retries payment, or accepts a private key.`;
-
-function die(message, code = 3) {
-  console.error(`Error: ${message}\n\n${help}`);
-  process.exitCode = code;
-}
-
-function redact(value) {
-  return typeof value === 'string'
-    ? value.replace(/(authorization|signature|token|api[_-]?key)\s*[:=]\s*[^,\s}]+/gi, '$1: [REDACTED]').replace(/Bearer\s+[^\s]+/gi, 'Bearer [REDACTED]')
-    : value;
-}
-
-async function readBody(response) {
-  const reader = response.body?.getReader();
-  if (!reader) return '';
-  const chunks = [];
-  let size = 0;
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    size += value.byteLength;
-    if (size > MAX_BODY) { await reader.cancel(); throw new Error(`response body exceeds ${MAX_BODY} bytes`); }
-    chunks.push(value);
-  }
-  return Buffer.concat(chunks).toString('utf8');
-}
-
-function headersOf(headers) {
-  return Object.fromEntries([...headers].map(([key, value]) => [key.toLowerCase(), redact(value)]));
-}
-
-function json(text) { try { return JSON.parse(text); } catch { return null; } }
-
-function findPaymentDocument(headers, body) {
-  const candidates = [headers['payment-required'], headers['x-payment-required'], headers['www-authenticate'], body].filter(Boolean);
-  const parsed = [];
-  for (const candidate of candidates) {
-    const direct = json(candidate);
-    if (direct && typeof direct === 'object') { parsed.push(direct); continue; }
-    const start = candidate.indexOf('{');
-    const end = candidate.lastIndexOf('}');
-    if (start >= 0 && end > start) {
-      const nested = json(candidate.slice(start, end + 1));
-      if (nested) parsed.push(nested);
-    }
-  }
-  if (!parsed.length) return null;
-  // headers like x-payment-required may carry vendor hints without accepts[] —
-  // prefer the candidate that actually contains payment requirements
-  return parsed.find((d) => requirements(d).length > 0) ?? parsed[0];
-}
-
-function requirements(document) {
-  if (!document || typeof document !== 'object') return [];
-  // x402 v2 canonical shape: { x402: { version: 2, accepts: [...] } }
-  if (document.x402 && Array.isArray(document.x402.accepts)) return document.x402.accepts;
-  if (Array.isArray(document.accepts)) return document.accepts;
-  if (Array.isArray(document.paymentRequirements?.accepts)) return document.paymentRequirements.accepts;
-  if (document.paymentRequirements && typeof document.paymentRequirements === 'object') return [document.paymentRequirements];
-  if (document.challenge && typeof document.challenge === 'object') return [document.challenge];
-  return [];
-}
-
-function normalize(item) {
-  return {
-    scheme: item.scheme ?? null,
-    network: item.network ?? item.chain ?? null,
-    asset: item.asset ?? item.mint ?? null,
-    amount: item.amount ?? item.maxAmountRequired ?? null,
-    payTo: item.payTo ?? item.vendor ?? item.recipient ?? null,
-    maxTimeoutSeconds: item.maxTimeoutSeconds ?? null,
-  };
-}
-
-async function probe(url, method = 'GET') {
-  const started = Date.now();
-  const init = { method, redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT), headers: { accept: 'application/json, application/problem+json, text/plain' } };
-  if (method === 'POST') { init.headers['content-type'] = 'application/json'; init.body = '{}'; }
-  const response = await fetch(url, init);
-  const body = await readBody(response);
-  const headers = headersOf(response.headers);
-  return { response, body, headers, elapsedMs: Date.now() - started };
-}
-
-async function metadata(base, path) {
-  try {
-    const result = await probe(new URL(path, base).toString(), 'GET');
-    return { path, status: result.response.status, reachable: result.response.ok, bodySha256: createHash('sha256').update(result.body).digest('hex'), bodyBytes: Buffer.byteLength(result.body) };
-  } catch (error) { return { path, status: null, reachable: false, error: redact(error.message) }; }
-}
-
-function makeReport(url, method, result) {
-  const { response, body, headers, elapsedMs } = result;
-  const document = findPaymentDocument(headers, body);
-  const accepts = requirements(document).map(normalize);
-  const findings = [];
-  if (response.status !== 402) findings.push({ status: 'FAIL', code: 'NO_402', message: `Expected HTTP 402, received ${response.status}` });
-  if (!document) findings.push({ status: 'FAIL', code: 'NO_PAYMENT_DOCUMENT', message: 'No parseable payment document in known headers or body' });
-  if (document && !accepts.length) findings.push({ status: 'FAIL', code: 'NO_ACCEPTS', message: 'No recognizable payment requirement found' });
-  for (const [index, item] of accepts.entries()) for (const field of ['scheme', 'network', 'asset', 'amount', 'payTo']) if (!item[field]) findings.push({ status: 'FAIL', code: `MISSING_${field.toUpperCase()}`, message: `accepts[${index}] is missing ${field}` });
-  const digest = createHash('sha256').update(body).digest('hex');
-  return { reportVersion: 1, inspectorVersion: VERSION, mode: 'read-only', checkedAt: new Date().toISOString(), endpoint: url, method, finalStatus: response.status === 402 && document && accepts.length && !findings.length ? 'PASS' : 'FAIL', http: { status: response.status, elapsedMs, contentType: headers['content-type'] ?? null, bodyBytes: Buffer.byteLength(body), bodySha256: digest }, headers: { paymentRequired: Boolean(headers['payment-required'] || headers['x-payment-required']), wwwAuthenticate: Boolean(headers['www-authenticate']) }, x402: { version: document?.x402Version ?? null, resource: document?.resource ?? null, accepts }, findings, limitations: ['Read-only preflight only; no wallet, signing, settlement, or post-payment delivery was attempted.', 'PASS means the observed 402 document had recognizable fields; it is not a security, payment-success, or content-quality certification.'] };
-}
-
-function markdown(report) {
-  const lines = [`# mcpdoctor report`, '', `- Status: **${report.finalStatus}**`, `- Endpoint: ${report.endpoint}`, `- HTTP: ${report.http.status}`, `- Response: ${report.http.elapsedMs} ms / ${report.http.bodyBytes} bytes`, `- Body SHA-256: \`${report.http.bodySha256}\``, '', '## Payment requirements', ''];
-  if (!report.x402.accepts.length) lines.push('- None parsed', '');
-  report.x402.accepts.forEach((item, i) => lines.push(`### accepts[${i}]`, '', ...Object.entries(item).map(([key, value]) => `- ${key}: ${value ?? 'missing'}`), ''));
-  lines.push('## Findings', '', ...(report.findings.length ? report.findings.map((item) => `- **${item.status}** \`${item.code}\`: ${item.message}`) : ['- None']), '', '## Limitations', '', ...report.limitations.map((item) => `- ${item}`), '');
-  return lines.join('\n');
-}
-
-const args = process.argv.slice(2);
-if (args.includes('--help') || args.length === 0) { console.log(help); process.exitCode = args.length ? 0 : 3; }
-else if (args[0] !== 'inspect') die('only the inspect command is available in this MVP');
-else {
-  const rawUrl = args[1];
-  const method = (args.find((arg) => arg.startsWith('--method='))?.split('=')[1] ?? 'GET').toUpperCase();
-  const format = args.find((arg) => arg.startsWith('--format='))?.split('=')[1] ?? (args.includes('--json') ? 'json' : 'markdown');
-  if (!rawUrl) die('URL is required');
-  else if (!['GET', 'POST'].includes(method)) die('--method must be GET or POST');
-  else if (!['json', 'markdown'].includes(format)) die('--format must be json or markdown');
-  else {
-    let url;
-    try { url = new URL(rawUrl); if (!['http:', 'https:'].includes(url.protocol)) throw new Error('only http(s) URLs are supported'); }
-    catch (error) { die(error.message); }
-    if (url) try {
-      const result = await probe(url, method);
-      const report = makeReport(url.toString(), method, result);
-      report.metadata = await Promise.all(['/.well-known/mcp/server.json', '/.well-known/x402'].map((path) => metadata(url, path)));
-      process.stdout.write(format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : markdown(report));
-      process.exitCode = report.finalStatus === 'PASS' ? 0 : 1;
-    } catch (error) {
-      const report = { reportVersion: 1, inspectorVersion: VERSION, mode: 'read-only', checkedAt: new Date().toISOString(), endpoint: url.toString(), finalStatus: 'UNKNOWN', findings: [{ status: 'UNKNOWN', code: 'REQUEST_FAILED', message: redact(error.message) }], limitations: ['The endpoint could not be observed within the timeout/body limit. No payment was attempted.'] };
-      process.stdout.write(format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : markdown(report));
-      process.exitCode = 2;
-    }
-  }
-}
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+
+const MAX_BODY = 1024 * 1024;
+const TIMEOUT = 10_000;
+const VERSION = '0.1.3';
+
+const help = `mcpdoctor ${VERSION}
+
+Read-only MCP/x402 endpoint diagnostics.
+
+Usage:
+  mcpdoctor inspect <url> [--method=GET|POST] [--format=json|markdown]
+  mcpdoctor --help
+
+This MVP never signs, pays, retries payment, or accepts a private key.`;
+
+function die(message, code = 3) {
+  console.error(`Error: ${message}\n\n${help}`);
+  process.exitCode = code;
+}
+
+function redact(value) {
+  return typeof value === 'string'
+    ? value.replace(/(authorization|signature|token|api[_-]?key)\s*[:=]\s*[^,\s}]+/gi, '$1: [REDACTED]').replace(/Bearer\s+[^\s]+/gi, 'Bearer [REDACTED]')
+    : value;
+}
+
+async function readBody(response) {
+  const reader = response.body?.getReader();
+  if (!reader) return '';
+  const chunks = [];
+  let size = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > MAX_BODY) { await reader.cancel(); throw new Error(`response body exceeds ${MAX_BODY} bytes`); }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function headersOf(headers) {
+  return Object.fromEntries([...headers].map(([key, value]) => [key.toLowerCase(), redact(value)]));
+}
+
+function json(text) { try { return JSON.parse(text); } catch { return null; } }
+
+function findPaymentDocument(headers, body) {
+  const candidates = [headers['payment-required'], headers['x-payment-required'], headers['www-authenticate'], body].filter(Boolean);
+  const parsed = [];
+  for (const candidate of candidates) {
+    const direct = json(candidate);
+    if (direct && typeof direct === 'object') { parsed.push(direct); continue; }
+    const start = candidate.indexOf('{');
+    const end = candidate.lastIndexOf('}');
+    if (start >= 0 && end > start) {
+      const nested = json(candidate.slice(start, end + 1));
+      if (nested) parsed.push(nested);
+    }
+  }
+  if (!parsed.length) return null;
+  // headers like x-payment-required may carry vendor hints without accepts[] —
+  // prefer the candidate that actually contains payment requirements
+  return parsed.find((d) => requirements(d).length > 0) ?? parsed[0];
+}
+
+function requirements(document) {
+  if (!document || typeof document !== 'object') return [];
+  // x402 v2 canonical shape: { x402: { version: 2, accepts: [...] } }
+  if (document.x402 && Array.isArray(document.x402.accepts)) return document.x402.accepts;
+  if (Array.isArray(document.accepts)) return document.accepts;
+  if (Array.isArray(document.paymentRequirements?.accepts)) return document.paymentRequirements.accepts;
+  if (document.paymentRequirements && typeof document.paymentRequirements === 'object') return [document.paymentRequirements];
+  if (document.challenge && typeof document.challenge === 'object') return [document.challenge];
+  return [];
+}
+
+function normalize(item) {
+  return {
+    scheme: item.scheme ?? null,
+    network: item.network ?? item.chain ?? null,
+    asset: item.asset ?? item.mint ?? null,
+    amount: item.amount ?? item.maxAmountRequired ?? null,
+    payTo: item.payTo ?? item.vendor ?? item.recipient ?? null,
+    maxTimeoutSeconds: item.maxTimeoutSeconds ?? null,
+  };
+}
+
+async function probe(url, method = 'GET') {
+  const started = Date.now();
+  const init = { method, redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT), headers: { accept: 'application/json, application/problem+json, text/plain' } };
+  if (method === 'POST') { init.headers['content-type'] = 'application/json'; init.body = '{}'; }
+  const response = await fetch(url, init);
+  const body = await readBody(response);
+  const headers = headersOf(response.headers);
+  return { response, body, headers, elapsedMs: Date.now() - started };
+}
+
+async function metadata(base, path) {
+  try {
+    const result = await probe(new URL(path, base).toString(), 'GET');
+    return { path, status: result.response.status, reachable: result.response.ok, bodySha256: createHash('sha256').update(result.body).digest('hex'), bodyBytes: Buffer.byteLength(result.body) };
+  } catch (error) { return { path, status: null, reachable: false, error: redact(error.message) }; }
+}
+
+function makeReport(url, method, result) {
+  const { response, body, headers, elapsedMs } = result;
+  const document = findPaymentDocument(headers, body);
+  const accepts = requirements(document).map(normalize);
+  const findings = [];
+  if (response.status !== 402) findings.push({ status: 'FAIL', code: 'NO_402', message: `Expected HTTP 402, received ${response.status}` });
+  if (!document) findings.push({ status: 'FAIL', code: 'NO_PAYMENT_DOCUMENT', message: 'No parseable payment document in known headers or body' });
+  if (document && !accepts.length) findings.push({ status: 'FAIL', code: 'NO_ACCEPTS', message: 'No recognizable payment requirement found' });
+  for (const [index, item] of accepts.entries()) for (const field of ['scheme', 'network', 'asset', 'amount', 'payTo']) if (!item[field]) findings.push({ status: 'FAIL', code: `MISSING_${field.toUpperCase()}`, message: `accepts[${index}] is missing ${field}` });
+  const digest = createHash('sha256').update(body).digest('hex');
+  return { reportVersion: 1, inspectorVersion: VERSION, mode: 'read-only', checkedAt: new Date().toISOString(), endpoint: url, method, finalStatus: response.status === 402 && document && accepts.length && !findings.length ? 'PASS' : 'FAIL', http: { status: response.status, elapsedMs, contentType: headers['content-type'] ?? null, bodyBytes: Buffer.byteLength(body), bodySha256: digest }, headers: { paymentRequired: Boolean(headers['payment-required'] || headers['x-payment-required']), wwwAuthenticate: Boolean(headers['www-authenticate']) }, x402: { version: document?.x402Version ?? null, resource: document?.resource ?? null, accepts }, findings, limitations: ['Read-only preflight only; no wallet, signing, settlement, or post-payment delivery was attempted.', 'PASS means the observed 402 document had recognizable fields; it is not a security, payment-success, or content-quality certification.'] };
+}
+
+function markdown(report) {
+  const lines = [`# mcpdoctor report`, '', `- Status: **${report.finalStatus}**`, `- Endpoint: ${report.endpoint}`, `- HTTP: ${report.http.status}`, `- Response: ${report.http.elapsedMs} ms / ${report.http.bodyBytes} bytes`, `- Body SHA-256: \`${report.http.bodySha256}\``, '', '## Payment requirements', ''];
+  if (!report.x402.accepts.length) lines.push('- None parsed', '');
+  report.x402.accepts.forEach((item, i) => lines.push(`### accepts[${i}]`, '', ...Object.entries(item).map(([key, value]) => `- ${key}: ${value ?? 'missing'}`), ''));
+  lines.push('## Findings', '', ...(report.findings.length ? report.findings.map((item) => `- **${item.status}** \`${item.code}\`: ${item.message}`) : ['- None']), '', '## Limitations', '', ...report.limitations.map((item) => `- ${item}`), '');
+  return lines.join('\n');
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.length === 0) { console.log(help); process.exitCode = args.length ? 0 : 3; }
+else if (args[0] !== 'inspect') die('only the inspect command is available in this MVP');
+else {
+  const rawUrl = args[1];
+  const method = (args.find((arg) => arg.startsWith('--method='))?.split('=')[1] ?? 'GET').toUpperCase();
+  const format = args.find((arg) => arg.startsWith('--format='))?.split('=')[1] ?? (args.includes('--json') ? 'json' : 'markdown');
+  if (!rawUrl) die('URL is required');
+  else if (!['GET', 'POST'].includes(method)) die('--method must be GET or POST');
+  else if (!['json', 'markdown'].includes(format)) die('--format must be json or markdown');
+  else {
+    let url;
+    try { url = new URL(rawUrl); if (!['http:', 'https:'].includes(url.protocol)) throw new Error('only http(s) URLs are supported'); }
+    catch (error) { die(error.message); }
+    if (url) try {
+      const result = await probe(url, method);
+      const report = makeReport(url.toString(), method, result);
+      report.metadata = await Promise.all(['/.well-known/mcp/server.json', '/.well-known/x402'].map((path) => metadata(url, path)));
+      process.stdout.write(format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : markdown(report));
+      process.exitCode = report.finalStatus === 'PASS' ? 0 : 1;
+    } catch (error) {
+      const report = { reportVersion: 1, inspectorVersion: VERSION, mode: 'read-only', checkedAt: new Date().toISOString(), endpoint: url.toString(), finalStatus: 'UNKNOWN', findings: [{ status: 'UNKNOWN', code: 'REQUEST_FAILED', message: redact(error.message) }], limitations: ['The endpoint could not be observed within the timeout/body limit. No payment was attempted.'] };
+      process.stdout.write(format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : markdown(report));
+      process.exitCode = 2;
+    }
+  }
+}

package/package.json

@@ -1,17 +1,17 @@
-{
-  "name": "@eidonze/mcpdoctor",
-  "version": "0.1.2",
-  "mcpName": "io.github.xka0085-byte/mcpdoctor",
-  "description": "CLI for inspecting MCP and x402 endpoints: parses the HTTP 402 payment document (v1/v2 accepts[]), checks /.well-known/mcp and /.well-known/x402 discovery manifests, returns a response SHA-256 digest. Read-only endpoint inspector and preflight debugging tool for AI-agent payment endpoints. Not an MCP server. Zero dependencies.",
-  "license": "MIT",
-  "type": "module",
-  "bin": { "mcpdoctor": "bin/mcpdoctor.mjs" },
-  "main": "bin/mcpdoctor.mjs",
-  "files": ["bin", "test", "README.md", "LICENSE"],
-  "engines": { "node": ">=18" },
-  "scripts": { "test": "node test/smoke.mjs" },
-  "keywords": ["mcp", "model-context-protocol", "mcp-cli", "mcp-inspector", "mcp-endpoint-inspector", "mcp-debugging", "x402", "cli", "developer-tools", "diagnostics"],
-  "repository": { "type": "git", "url": "git+https://github.com/xka0085-byte/mcp-doctor.git" },
-  "bugs": { "url": "https://github.com/xka0085-byte/mcp-doctor/issues" },
-  "homepage": "https://xka0085-byte.github.io/evidence-tools/"
-}
+{
+  "name": "@eidonze/mcpdoctor",
+  "version": "0.1.3",
+  "mcpName": "io.github.xka0085-byte/mcpdoctor",
+  "description": "CLI for inspecting MCP and x402 endpoints: parses the HTTP 402 payment document (v1/v2 accepts[]), checks /.well-known/mcp and /.well-known/x402 discovery manifests, returns a response SHA-256 digest. Read-only endpoint inspector and preflight debugging tool for AI-agent payment endpoints. Not an MCP server. Zero dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "mcpdoctor": "bin/mcpdoctor.mjs" },
+  "main": "bin/mcpdoctor.mjs",
+  "files": ["bin", "test", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "scripts": { "test": "node test/smoke.mjs" },
+  "keywords": ["mcp", "model-context-protocol", "mcp-cli", "mcp-inspector", "mcp-endpoint-inspector", "mcp-debugging", "x402", "cli", "developer-tools", "diagnostics"],
+  "repository": { "type": "git", "url": "git+https://github.com/xka0085-byte/mcp-doctor.git" },
+  "bugs": { "url": "https://github.com/xka0085-byte/mcp-doctor/issues" },
+  "homepage": "https://xka0085-byte.github.io/evidence-tools/"
+}