@eidonze/mcpdoctor 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xka0085-byte (Eidon)
+
+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

@@ -1,29 +1,30 @@
 # mcpdoctor
 
-Read-only preflight checks for **x402 payment endpoints** and **MCP servers**.
-One command tells you whether your paid endpoint answers the way agent clients
-actually expect — before a real buyer (human or AI) hits it.
+> ⚠️ **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`.
 
-Zero dependencies. Runs anywhere Node ≥ 18 runs. Never touches your keys.
+**mcpdoctor is a read-only CLI for inspecting MCP and x402 endpoints.**
 
-```bash
-npx @eidonze/mcpdoctor inspect https://your-endpoint/v1/paid --method=POST
-```
+Point it at a URL, get one `PASS / FAIL / UNKNOWN` report:
 
-## Why
+- 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.
 
-Shipping an x402 service ourselves ([ReceiptRail](https://github.com/xka0085-byte/agenttoll)),
-we hit every way a paid endpoint can silently break:
+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.
 
-- 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** (`Payment-Required` /
-  `X-Payment-Required` / `WWW-Authenticate` headers, or the response body) and
-  in **two different shapes** (v1 top-level `accepts[]`, v2 nested `x402.accepts`);
-  parsers that only look at one place report false failures;
-- vendor hint headers without `accepts[]` can shadow the real payment document.
+## Install
 
-Each check in mcpdoctor maps to a failure mode we actually hit in production.
+```bash
+npm install -g @eidonze/mcpdoctor    # or run without installing:
+npx @eidonze/mcpdoctor inspect <url>
+```
 
 ## Usage
 
@@ -35,47 +36,75 @@ mcpdoctor inspect <url> [--method=GET|POST] [--format=json|markdown]
 |---|---|---|
 | `--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 }
+  ]
+}
+```
 
-The report includes the observed HTTP status, the parsed payment requirements
-(`accepts[]` with scheme / network / asset / amount / payTo / timeout), response
-latency, size, a SHA-256 digest of the response bytes (tamper-evident record),
-and reachability of `/.well-known/mcp/server.json` and `/.well-known/x402`.
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| `0` | PASS — parseable 402 payment document with required fields |
-| `1` | FAIL — endpoint responded but is not 402 / document incomplete |
-| `2` | UNKNOWN — endpoint could not be observed within limits |
-| `3` | invalid command |
+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" }
+  ]
+}
+```
 
-## Verified, not vibes
+## What it does NOT do
 
-- **Positive control**: passes against a production x402 service that itself
-  survived x402scan's auditor (ReceiptRail, dual-network settlement).
-- **Negative control**: the test suite spins up a server that returns `400`
-  instead of `402` — the exact production bug that inspired this tool — and
-  asserts mcpdoctor flags it (`NO_402`), plus a header-hint-shadowing case.
+- 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.
 
-```bash
-npm test
-```
+## Why
 
-## Safety boundary
+We ship an x402 service ourselves ([ReceiptRail](https://github.com/xka0085-byte/agenttoll))
+and hit every way a paid endpoint can silently break:
 
-Read-only. mcpdoctor never signs, pays, retries payment, calls a facilitator,
-or accepts a private key. A `PASS` is not a security audit, payment-success
-certificate, or compliance decision — it means the observed 402 document had
-recognizable, well-formed fields.
+- 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.
 
-## Roadmap
+Each check in mcpdoctor maps to a failure mode we actually hit in production.
 
-- `extensions.bazaar` schema conformance (x402 Bazaar discovery listings)
-- `x-payment-info.protocols` object-array check
-- MCP streamable-HTTP `initialize` handshake check
-- `/.well-known/mcp/server-card.json` (Smithery SEP-1649) validation
+## Part of the Agent / Chain Evidence Tools suite
 
-## License
+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
+MIT licensed. Known limitations are documented, not hidden.

package/bin/mcpdoctor.mjs

@@ -3,7 +3,7 @@ import { createHash } from 'node:crypto';
 
 const MAX_BODY = 1024 * 1024;
 const TIMEOUT = 10_000;
-const VERSION = '0.1.0';
+const VERSION = '0.1.3';
 
 const help = `mcpdoctor ${VERSION}
 

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@eidonze/mcpdoctor",
-  "version": "0.1.1",
-  "description": "Read-only MCP and x402 endpoint preflight checks: 402 challenge shape, payment document parsing, accepts[] conformance, discovery manifests, response digest. Zero dependencies.",
+  "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", "x402", "model-context-protocol", "developer-tools", "diagnostics", "web3", "solana", "usdc", "agent-payments", "linter"],
+  "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://github.com/xka0085-byte/mcp-doctor#readme"
+  "homepage": "https://xka0085-byte.github.io/evidence-tools/"
 }

package/test/smoke.mjs

@@ -1,73 +1,73 @@
-#!/usr/bin/env node
-import assert from 'node:assert/strict';
-import { createServer } from 'node:http';
-import { spawn } from 'node:child_process';
-import { once } from 'node:events';
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
-
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const cli = path.join(root, 'bin', 'mcpdoctor.mjs');
-const server = createServer((request, response) => {
-  if (request.url === '/good') {
-    response.writeHead(402, { 'content-type': 'application/json', 'payment-required': JSON.stringify({ x402Version: 2, accepts: [{ scheme: 'exact', network: 'eip155:8453', asset: 'USDC', amount: '10000', payTo: '0x1234567890123456789012345678901234567890' }] }) });
-    response.end(JSON.stringify({ x402Version: 2, accepts: [{ scheme: 'exact', network: 'eip155:8453', asset: 'USDC', amount: '10000', payTo: '0x1234567890123456789012345678901234567890' }] }));
-    return;
-  }
-  // regression (found against production ReceiptRail): a hint header WITHOUT accepts[]
-  // must not shadow the real payment document in the body
-  if (request.url === '/header-hint') {
-    response.writeHead(402, { 'content-type': 'application/json', 'x-payment-required': JSON.stringify({ vendor: 'VendorHintNoAccepts', amount: '1000', decimals: 6 }) });
-    response.end(JSON.stringify({ x402Version: 2, resource: { url: 'x', description: 'd', mimeType: 'application/json' }, accepts: [{ scheme: 'exact', network: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1', amount: '1000', asset: 'MINT', payTo: 'PayToAddr' }] }));
-    return;
-  }
-  // regression (our original production bug): body validation must not shadow the 402
-  if (request.url === '/bad-400') {
-    response.writeHead(400, { 'content-type': 'application/json' });
-    response.end(JSON.stringify({ error: 'missing body param' }));
-    return;
-  }
-  response.writeHead(404, { 'content-type': 'application/json' });
-  response.end(JSON.stringify({ error: 'not found' }));
-});
-server.listen(0, '127.0.0.1');
-await once(server, 'listening');
-const port = server.address().port;
-
-function run(url, ...args) {
-  return new Promise((resolve) => {
-    const child = spawn(process.execPath, [cli, 'inspect', url, '--format=json', ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = ''; let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.on('close', (code) => resolve({ code, stdout, stderr }));
-  });
-}
-
-try {
-  const good = await run(`http://127.0.0.1:${port}/good`);
-  assert.equal(good.code, 0, good.stderr);
-  assert.equal(JSON.parse(good.stdout).finalStatus, 'PASS');
-  const bad = await run(`http://127.0.0.1:${port}/missing`);
-  assert.equal(bad.code, 1, bad.stderr);
-  assert.equal(JSON.parse(bad.stdout).finalStatus, 'FAIL');
-  const hint = await run(`http://127.0.0.1:${port}/header-hint`, '--method=POST');
-  assert.equal(hint.code, 0, hint.stderr);
-  const hintReport = JSON.parse(hint.stdout);
-  assert.equal(hintReport.finalStatus, 'PASS', JSON.stringify(hintReport.findings));
-  assert.equal(hintReport.x402.accepts.length, 1, 'body accepts[] must win over accept-less header hints');
-  const bad400 = await run(`http://127.0.0.1:${port}/bad-400`, '--method=POST');
-  assert.equal(bad400.code, 1, bad400.stderr);
-  const bad400Report = JSON.parse(bad400.stdout);
-  assert.equal(bad400Report.finalStatus, 'FAIL');
-  assert.ok(bad400Report.findings.some((f) => f.code === 'NO_402'), 'must flag 400-instead-of-402');
-  const help = await new Promise((resolve) => {
-    const child = spawn(process.execPath, [cli, '--help'], { stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = ''; child.stdout.on('data', (chunk) => { stdout += chunk; }); child.on('close', (code) => resolve({ code, stdout }));
-  });
-  assert.equal(help.code, 0);
-  assert.match(help.stdout, /mcpdoctor/);
-  console.log('mcpdoctor smoke tests passed');
-} finally {
-  server.close();
-}
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const cli = path.join(root, 'bin', 'mcpdoctor.mjs');
+const server = createServer((request, response) => {
+  if (request.url === '/good') {
+    response.writeHead(402, { 'content-type': 'application/json', 'payment-required': JSON.stringify({ x402Version: 2, accepts: [{ scheme: 'exact', network: 'eip155:8453', asset: 'USDC', amount: '10000', payTo: '0x1234567890123456789012345678901234567890' }] }) });
+    response.end(JSON.stringify({ x402Version: 2, accepts: [{ scheme: 'exact', network: 'eip155:8453', asset: 'USDC', amount: '10000', payTo: '0x1234567890123456789012345678901234567890' }] }));
+    return;
+  }
+  // regression (found against production ReceiptRail): a hint header WITHOUT accepts[]
+  // must not shadow the real payment document in the body
+  if (request.url === '/header-hint') {
+    response.writeHead(402, { 'content-type': 'application/json', 'x-payment-required': JSON.stringify({ vendor: 'VendorHintNoAccepts', amount: '1000', decimals: 6 }) });
+    response.end(JSON.stringify({ x402Version: 2, resource: { url: 'x', description: 'd', mimeType: 'application/json' }, accepts: [{ scheme: 'exact', network: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1', amount: '1000', asset: 'MINT', payTo: 'PayToAddr' }] }));
+    return;
+  }
+  // regression (our original production bug): body validation must not shadow the 402
+  if (request.url === '/bad-400') {
+    response.writeHead(400, { 'content-type': 'application/json' });
+    response.end(JSON.stringify({ error: 'missing body param' }));
+    return;
+  }
+  response.writeHead(404, { 'content-type': 'application/json' });
+  response.end(JSON.stringify({ error: 'not found' }));
+});
+server.listen(0, '127.0.0.1');
+await once(server, 'listening');
+const port = server.address().port;
+
+function run(url, ...args) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [cli, 'inspect', url, '--format=json', ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = ''; let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('close', (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+try {
+  const good = await run(`http://127.0.0.1:${port}/good`);
+  assert.equal(good.code, 0, good.stderr);
+  assert.equal(JSON.parse(good.stdout).finalStatus, 'PASS');
+  const bad = await run(`http://127.0.0.1:${port}/missing`);
+  assert.equal(bad.code, 1, bad.stderr);
+  assert.equal(JSON.parse(bad.stdout).finalStatus, 'FAIL');
+  const hint = await run(`http://127.0.0.1:${port}/header-hint`, '--method=POST');
+  assert.equal(hint.code, 0, hint.stderr);
+  const hintReport = JSON.parse(hint.stdout);
+  assert.equal(hintReport.finalStatus, 'PASS', JSON.stringify(hintReport.findings));
+  assert.equal(hintReport.x402.accepts.length, 1, 'body accepts[] must win over accept-less header hints');
+  const bad400 = await run(`http://127.0.0.1:${port}/bad-400`, '--method=POST');
+  assert.equal(bad400.code, 1, bad400.stderr);
+  const bad400Report = JSON.parse(bad400.stdout);
+  assert.equal(bad400Report.finalStatus, 'FAIL');
+  assert.ok(bad400Report.findings.some((f) => f.code === 'NO_402'), 'must flag 400-instead-of-402');
+  const help = await new Promise((resolve) => {
+    const child = spawn(process.execPath, [cli, '--help'], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = ''; child.stdout.on('data', (chunk) => { stdout += chunk; }); child.on('close', (code) => resolve({ code, stdout }));
+  });
+  assert.equal(help.code, 0);
+  assert.match(help.stdout, /mcpdoctor/);
+  console.log('mcpdoctor smoke tests passed');
+} finally {
+  server.close();
+}