@eidonze/mcpdoctor 0.1.5 → 0.1.7

package/README.md

@@ -1,100 +1,129 @@
-# mcpdoctor
-
-Read-only checks for MCP tool schemas and x402 payment endpoints. Use it before an agent client or buyer depends on an endpoint.
-
-[![npm](https://img.shields.io/npm/v/@eidonze/mcpdoctor?logo=npm)](https://www.npmjs.com/package/@eidonze/mcpdoctor)
-[![CI](https://github.com/xka0085-byte/mcp-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/xka0085-byte/mcp-doctor/actions/workflows/ci.yml)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-
-## Find the right guide
-
-- [Public documentation site](https://xka0085-byte.github.io/mcp-doctor/)
-- [MCP schema checker](docs/mcp-schema-checker.md)
-- [x402 endpoint inspector](docs/x402-endpoint-inspector.md)
-- [MCP security CI](docs/mcp-security-ci.md)
-- [Troubleshooting](docs/troubleshooting.md)
-- [OAuth scope and current limits](docs/mcp-oauth-diagnostics.md)
-
-## Run it now
-
-Check an MCP server without calling any tools:
-
-```bash
-npx @eidonze/mcpdoctor@0.1.5 schema https://your-mcp-server.example/mcp --json
-```
-
-Check an x402 endpoint without paying:
-
-```bash
-npx @eidonze/mcpdoctor@0.1.5 inspect https://your-api.example/paid --method=POST --json
-```
-
-Requires Node.js 18+. No API key or wallet is needed.
-
-## Which command?
-
-| Command | Checks | Does not do |
-|---|---|---|
-| `schema` | MCP `initialize`, `tools/list`, tool names, descriptions, and JSON schemas | Does not call tools or prove runtime behavior |
-| `inspect` | HTTP 402, x402 v1/v2 payment document, `accepts[]`, discovery manifests, latency and response digest | Does not sign, pay, settle, retry, or verify delivery |
-
-Exit codes are stable for automation: `0` PASS, `1` FAIL, `2` UNKNOWN/network error, `3` usage error.
-
-## GitHub Actions
-
-Add a read-only check to pull requests:
-
-```yaml
-name: MCP Trust Check
-on: [pull_request]
-
-jobs:
-  mcp-trust:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: xka0085-byte/mcp-doctor@v1
-        with:
-          endpoint: https://your-mcp-server.example/mcp
-          mode: schema
-          format: markdown
-```
-
-Use `mode: inspect` for an x402 preflight. The action fails on `FAIL` or `UNKNOWN` by default; set `fail-on: false` for an informational check.
-
-## Starter template
-
-Start a new MCP project with this check already wired in:
-
-- [Secure MCP Server Starter](examples/secure-mcp-server-starter/)
-
-The check is read-only and should target a public test endpoint. Do not place private keys or credentials in workflow inputs.
-
-## What the report means
-
-`PASS` means the observed response matched the checks in this version. It is not a security audit, protocol certification, payment-success guarantee, or proof that an endpoint is safe. `UNKNOWN` means the endpoint could not be observed within the timeout or response-size limits.
-
-Example schema failure:
-
-```text
-FAIL REQUIRED_PROPERTY_UNDEFINED tools[0] requires undeclared property query
-```
-
-Example x402 failure:
-
-```text
-FAIL NO_402 Expected HTTP 402, received 400
-```
-
-## Why it exists
-
-The checks come from failure modes observed while building ReceiptRail: body validation that prevents an x402 challenge, payment documents in multiple headers/body shapes, and vendor hint headers that can hide the real `accepts[]` document.
-
-mcpdoctor is not an MCP server. It is an independent, read-only endpoint inspector. It is not affiliated with mcpdoctor.dev; verify the npm scope is `@eidonze/mcpdoctor`.
-
-## Feedback
-
-Found a false positive or a protocol shape we should support? [Open an issue](https://github.com/xka0085-byte/mcp-doctor/issues). Include the command, redacted output, Node version, and whether the endpoint is MCP or x402. Never include tokens, payment signatures, or private URLs.
-
-## License
-
-MIT
+# mcpdoctor
+
+Read-only checks for MCP tool schemas and x402 payment endpoints. Use it before an agent client or buyer depends on an endpoint.
+
+[![npm](https://img.shields.io/npm/v/@eidonze/mcpdoctor?logo=npm)](https://www.npmjs.com/package/@eidonze/mcpdoctor)
+[![CI](https://github.com/xka0085-byte/mcp-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/xka0085-byte/mcp-doctor/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## Find the right guide
+
+- [Public documentation site](https://xka0085-byte.github.io/mcp-doctor/)
+- [MCP schema checker](docs/mcp-schema-checker.md)
+- [x402 endpoint inspector](docs/x402-endpoint-inspector.md)
+- [MCP security CI](docs/mcp-security-ci.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [OAuth scope and current limits](docs/mcp-oauth-diagnostics.md)
+
+## Run it now
+
+Check an MCP server without calling any tools:
+
+```bash
+npx @eidonze/mcpdoctor@0.1.6 schema https://your-mcp-server.example/mcp --json
+```
+
+Check an x402 endpoint without paying:
+
+```bash
+npx @eidonze/mcpdoctor@0.1.6 inspect https://your-api.example/paid --method=POST --json
+```
+
+Requires Node.js 18+. No API key or wallet is needed.
+
+Example schema run against a live endpoint:
+
+```text
+$ npx @eidonze/mcpdoctor schema https://your-mcp-server.example/mcp
+
+MCP Tool Schema Report
+- Status: FAIL
+- Endpoint: https://your-mcp-server.example/mcp
+- Protocol: 2025-06-18
+- Tools: 12
+
+- FAIL REQUIRED_PROPERTY_UNDEFINED: tools[3] requires undeclared property query
+- WARN PROPERTY_DESCRIPTION_MISSING: tools[7].limit has no description
+```
+
+The exact same run against a healthy server prints `Status: PASS` and exits 0, so CI can gate on it.
+
+## Which command?
+
+| Command | Checks | Does not do |
+|---|---|---|
+| `schema` | MCP `initialize`, `tools/list`, tool names, descriptions, and JSON schemas | Does not call tools or prove runtime behavior |
+| `inspect` | HTTP 402, x402 v1/v2 payment document, `accepts[]`, discovery manifests, latency and response digest | Does not sign, pay, settle, retry, or verify delivery |
+
+Exit codes are stable for automation: `0` PASS, `1` FAIL, `2` UNKNOWN/network error, `3` usage error.
+
+## What it does NOT check
+
+mcpdoctor is a protocol- and schema-level preflight, not a security audit. It does not:
+
+- Detect malicious code, prompt injection, or supply-chain risk in the server's implementation
+- Call tools, so it cannot prove runtime behavior, data handling, or permission scope
+- Bypass, test, or evaluate authentication and authorization
+- Verify payment settlement or delivery for x402 endpoints
+- Certify compliance with any spec beyond the response shapes it inspects
+
+A `PASS` means the observed handshake and schemas were well-formed at scan time. Nothing more.
+
+## GitHub Actions
+
+Add a read-only check to pull requests:
+
+```yaml
+name: MCP Trust Check
+on: [pull_request]
+
+jobs:
+  mcp-trust:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: xka0085-byte/mcp-doctor@v1
+        with:
+          endpoint: https://your-mcp-server.example/mcp
+          mode: schema
+          format: markdown
+```
+
+Use `mode: inspect` for an x402 preflight. The action fails on `FAIL` or `UNKNOWN` by default; set `fail-on: false` for an informational check.
+
+## Starter template
+
+Start a new MCP project with this check already wired in:
+
+- [Secure MCP Server Starter](examples/secure-mcp-server-starter/)
+
+The check is read-only and should target a public test endpoint. Do not place private keys or credentials in workflow inputs.
+
+## What the report means
+
+`PASS` means the observed response matched the checks in this version. It is not a security audit, protocol certification, payment-success guarantee, or proof that an endpoint is safe. `UNKNOWN` means the endpoint could not be observed within the timeout or response-size limits.
+
+Example schema failure:
+
+```text
+FAIL REQUIRED_PROPERTY_UNDEFINED tools[0] requires undeclared property query
+```
+
+Example x402 failure:
+
+```text
+FAIL NO_402 Expected HTTP 402, received 400
+```
+
+## Why it exists
+
+The checks come from failure modes observed while building ReceiptRail: body validation that prevents an x402 challenge, payment documents in multiple headers/body shapes, and vendor hint headers that can hide the real `accepts[]` document.
+
+mcpdoctor is not an MCP server. It is an independent, read-only endpoint inspector. It is not affiliated with mcpdoctor.dev; verify the npm scope is `@eidonze/mcpdoctor`.
+
+## Feedback
+
+Found a false positive or a protocol shape we should support? [Open an issue](https://github.com/xka0085-byte/mcp-doctor/issues). Include the command, redacted output, Node version, and whether the endpoint is MCP or x402. Never include tokens, payment signatures, or private URLs.
+
+## License
+
+MIT

package/bin/mcpdoctor-mcp.mjs

@@ -0,0 +1,105 @@
+// mcpdoctor-mcp: run mcpdoctor as an MCP server (stdio, zero dependencies).
+// Exposes two tools so AI clients can check endpoints without leaving chat:
+//   schema_check(url)  - read-only MCP handshake + tools/list validation
+//   x402_inspect(url)  - read-only 402 challenge validation, never pays
+// Protocol: newline-delimited JSON-RPC 2.0 per the MCP stdio transport spec.
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import url from 'node:url';
+import readline from 'node:readline';
+
+const cliPath = path.join(path.dirname(url.fileURLToPath(import.meta.url)), 'mcpdoctor.mjs');
+
+const TOOLS = [
+  {
+    name: 'schema_check',
+    description: 'Run a read-only MCP preflight check against a server URL: initialize handshake, tools/list, and tool JSON schema validation. Never calls tools or reads data. Returns PASS/FAIL/UNKNOWN with detailed findings.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'MCP server endpoint URL, e.g. https://example.com/mcp' },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'x402_inspect',
+    description: 'Inspect an x402 payment endpoint without paying: reads the HTTP 402 challenge, validates the payment document shape, accepts[] entries and discovery manifests. Never signs or settles.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'x402 resource URL, e.g. https://api.example/paid' },
+        method: { type: 'string', enum: ['GET', 'POST'], description: 'HTTP method to probe with, default GET' },
+      },
+      required: ['url'],
+    },
+  },
+];
+
+function runCli(args) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [cliPath, ...args, '--json'], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '', err = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    const t = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, 45000);
+    child.on('close', (code) => {
+      clearTimeout(t);
+      resolve({ code, out: out.trim(), err: err.trim() });
+    });
+  });
+}
+
+async function callTool(name, args) {
+  if (name === 'schema_check') {
+    const r = await runCli(['schema', String(args.url)]);
+    const text = r.out || r.err || `exit ${r.code}`;
+    return { content: [{ type: 'text', text }], isError: r.code === 1 ? false : r.code >= 2 };
+  }
+  if (name === 'x402_inspect') {
+    const m = ['GET', 'POST'].includes(String(args.method ?? '').toUpperCase()) ? `--method=${String(args.method).toUpperCase()}` : '';
+    const r = await runCli(['inspect', String(args.url), m].filter(Boolean));
+    const text = r.out || r.err || `exit ${r.code}`;
+    return { content: [{ type: 'text', text }], isError: r.code === 1 ? false : r.code >= 2 };
+  }
+  throw new Error(`unknown tool: ${name}`);
+}
+
+const serverInfo = { name: 'mcpdoctor', version: '0.1.7' };
+const write = (msg) => process.stdout.write(JSON.stringify(msg) + '\n');
+
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+rl.on('line', async (line) => {
+  if (!line.trim()) return;
+  let msg;
+  try { msg = JSON.parse(line); } catch { return; }
+  const { id, method, params } = msg;
+  const respond = (result) => id !== undefined && write({ jsonrpc: '2.0', id, result });
+  const fail = (code, message) => id !== undefined && write({ jsonrpc: '2.0', id, error: { code, message } });
+
+  switch (method) {
+    case 'initialize':
+      respond({ protocolVersion: params?.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo });
+      break;
+    case 'notifications/initialized':
+    case 'notifications/cancelled':
+      break;
+    case 'ping':
+      respond({});
+      break;
+    case 'tools/list':
+      respond({ tools: TOOLS });
+      break;
+    case 'tools/call': {
+      try {
+        const result = await callTool(String(params?.name), params?.arguments ?? {});
+        respond(result);
+      } catch (e) {
+        fail(-32000, String(e.message ?? e));
+      }
+      break;
+    }
+    default:
+      fail(-32601, `method not found: ${method}`);
+  }
+});

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.4';
+const VERSION = '0.1.5';
 
 const help = `mcpdoctor ${VERSION}
 
@@ -47,6 +47,16 @@ function headersOf(headers) {
 }
 
 function json(text) { try { return JSON.parse(text); } catch { return null; } }
+function jsonrpc(text) {
+  const direct = json(text);
+  if (direct && (direct.result !== undefined || direct.error !== undefined)) return direct;
+  for (const line of String(text).split(/\r?\n/)) {
+    if (!line.startsWith('data:')) continue;
+    const obj = json(line.slice(5).trim());
+    if (obj && (obj.result !== undefined || obj.error !== undefined)) return obj;
+  }
+  return direct;
+}
 
 function findPaymentDocument(headers, body) {
   const candidates = [headers['payment-required'], headers['x-payment-required'], headers['www-authenticate'], body].filter(Boolean);
@@ -133,13 +143,13 @@ async function schemaCommand(url, format) {
   const response = await fetch(url, { method: 'POST', redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT), headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', 'MCP-Protocol-Version': '2025-03-26' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'mcpdoctor', version: VERSION } } }) });
   const initText = await readBody(response);
   if (!response.ok) throw new Error(`MCP initialize returned HTTP ${response.status}`);
-  const init = json(initText);
+  const init = jsonrpc(initText);
   if (!init?.result?.protocolVersion) add('INITIALIZE_RESPONSE_INVALID', 'FAIL', 'Initialize response did not include result.protocolVersion');
   const headers = { 'content-type': 'application/json', accept: 'application/json, text/event-stream', 'MCP-Protocol-Version': init?.result?.protocolVersion ?? '2025-03-26' };
   const list = await fetch(url, { method: 'POST', redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT), headers, body: JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }) });
   const listText = await readBody(list);
   if (!list.ok) throw new Error(`tools/list returned HTTP ${list.status}`);
-  const parsed = json(listText);
+  const parsed = jsonrpc(listText);
   const tools = parsed?.result?.tools;
   if (!Array.isArray(tools)) add('TOOLS_LIST_INVALID', 'FAIL', 'tools/list response did not contain result.tools[]');
   else if (!tools.length) add('NO_TOOLS', 'WARN', 'Server exposes an empty tool list');

package/package.json

@@ -1,17 +1,51 @@
 {
   "name": "@eidonze/mcpdoctor",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "mcpName": "io.github.xka0085-byte/mcpdoctor",
   "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" },
+  "bin": {
+    "mcpdoctor": "bin/mcpdoctor.mjs",
+    "mcpdoctor-mcp": "bin/mcpdoctor-mcp.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-security", "mcp-scanner", "mcp-schema", "mcp-oauth", "agent-security", "tool-schema", "x402-inspector", "http-402", "mcp-cli", "mcp-debugging", "developer-tools", "diagnostics", "x402", "cli"],
-  "repository": { "type": "git", "url": "git+https://github.com/xka0085-byte/mcp-doctor.git" },
-  "bugs": { "url": "https://github.com/xka0085-byte/mcp-doctor/issues" },
+  "files": [
+    "bin",
+    "test",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-security",
+    "mcp-scanner",
+    "mcp-schema",
+    "mcp-oauth",
+    "agent-security",
+    "tool-schema",
+    "x402-inspector",
+    "http-402",
+    "mcp-cli",
+    "mcp-debugging",
+    "developer-tools",
+    "diagnostics",
+    "x402",
+    "cli"
+  ],
+  "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/"
 }

package/test/smoke.mjs

@@ -29,6 +29,18 @@ const server = createServer(async (request, response) => {
     }
     response.writeHead(200, { 'content-type': 'application/json' }); response.end(JSON.stringify({ jsonrpc: '2.0', id: rpc.id, result: { tools: [{ name: 'hello', description: 'Returns a greeting.', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Name.' } }, required: ['name'] } }] } })); return;
   }
+  // regression (found against production DeepWiki): servers may answer POST with
+  // an SSE stream (text/event-stream) even for plain JSON-RPC calls
+  if (request.url === '/mcp-sse') {
+    let incoming = ''; for await (const chunk of request) incoming += chunk;
+    const rpc = JSON.parse(incoming || '{}');
+    const payload = rpc.method === 'initialize'
+      ? { jsonrpc: '2.0', id: rpc.id, result: { protocolVersion: '2025-06-18', serverInfo: { name: 'sse-fixture', version: '1' }, capabilities: {} } }
+      : { jsonrpc: '2.0', id: rpc.id, result: { tools: [{ name: 'hello', description: 'Returns a greeting.', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Name.' } }, required: ['name'] } }] } };
+    response.writeHead(200, { 'content-type': 'text/event-stream' });
+    response.end(`event: message\ndata: ${JSON.stringify(payload)}\n\n`);
+    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' });
@@ -83,6 +95,11 @@ try {
   const schemaReport = JSON.parse(schema.stdout);
   assert.equal(schemaReport.finalStatus, 'PASS', JSON.stringify(schemaReport.findings));
   assert.equal(schemaReport.mcp.toolCount, 1);
+  const sse = await runSchema(`http://127.0.0.1:${port}/mcp-sse`);
+  assert.equal(sse.code, 0, sse.stderr);
+  const sseReport = JSON.parse(sse.stdout);
+  assert.equal(sseReport.finalStatus, 'PASS', JSON.stringify(sseReport.findings));
+  assert.equal(sseReport.mcp.toolCount, 1, 'SSE-wrapped JSON-RPC must be parsed');
   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 }));