@eidonze/mcpdoctor 0.1.1

package/README.md

@@ -0,0 +1,81 @@
+# 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.
+
+Zero dependencies. Runs anywhere Node ≥ 18 runs. Never touches your keys.
+
+```bash
+npx @eidonze/mcpdoctor inspect https://your-endpoint/v1/paid --method=POST
+```
+
+## Why
+
+Shipping an x402 service ourselves ([ReceiptRail](https://github.com/xka0085-byte/agenttoll)),
+we 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** (`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.
+
+Each check in mcpdoctor maps to a failure mode we actually hit in production.
+
+## 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 |
+
+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 |
+
+## Verified, not vibes
+
+- **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.
+
+```bash
+npm test
+```
+
+## Safety boundary
+
+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.
+
+## Roadmap
+
+- `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
+
+## License
+
+MIT

package/bin/mcpdoctor.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+
+const MAX_BODY = 1024 * 1024;
+const TIMEOUT = 10_000;
+const VERSION = '0.1.0';
+
+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

@@ -0,0 +1,15 @@
+{
+  "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.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "mcpdoctor": "bin/mcpdoctor.mjs" },
+  "main": "bin/mcpdoctor.mjs",
+  "engines": { "node": ">=18" },
+  "scripts": { "test": "node test/smoke.mjs" },
+  "keywords": ["mcp", "x402", "model-context-protocol", "developer-tools", "diagnostics", "web3", "solana", "usdc", "agent-payments", "linter"],
+  "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"
+}

package/test/smoke.mjs

@@ -0,0 +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();
+}