@eidonze/mcpdoctor 0.1.6 → 0.1.8

package/README.md

@@ -20,13 +20,13 @@ Read-only checks for MCP tool schemas and x402 payment endpoints. Use it before
 Check an MCP server without calling any tools:
 
 ```bash
-npx @eidonze/mcpdoctor@0.1.5 schema https://your-mcp-server.example/mcp --json
+npx @eidonze/mcpdoctor 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
+npx @eidonze/mcpdoctor inspect https://your-api.example/paid --method=POST --json
 ```
 
 Requires Node.js 18+. No API key or wallet is needed.
@@ -57,6 +57,18 @@ The exact same run against a healthy server prints `Status: PASS` and exits 0, s
 
 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:
@@ -76,7 +88,7 @@ jobs:
           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.
+Use `mode: inspect` for an x402 preflight. The action fails on `FAIL` or `UNKNOWN` by default; set `fail-on: false` for an informational check. Looking for it in the Marketplace? Search "MCP Trust Check" or "mcp server test", or browse the [mcp-trust-check listing](https://github.com/marketplace/actions/mcp-trust-check).
 
 ## Starter template
 

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.8' };
+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.5';
+const VERSION = '0.1.8';
 
 const help = `mcpdoctor ${VERSION}
 
@@ -133,7 +133,8 @@ 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}`), '');
+  lines.push('## Findings', '', ...(report.findings.length ? report.findings.map((item) => `- **${item.status}** \`${item.code}\`: ${item.message}`) : ['- None']), '', '## Limitations', '', ...report.limitations.map((item) => `- ${item}`));
+  if (report.finalStatus === 'PASS') lines.push('', '## Next steps', '', 'Gate CI on this exact check (paste into .github/workflows/x402.yml):', '', '```yaml', '- uses: xka0085-byte/mcp-doctor@v1', '  with:', `    endpoint: ${report.endpoint}`, '    mode: inspect', '```', '', 'Weekly re-scan and docs: https://xka0085-byte.github.io/mcp-doctor/x402-endpoint-inspector.html');
   return lines.join('\n');
 }
 
@@ -166,7 +167,12 @@ async function schemaCommand(url, format) {
   }
   if (!findings.length) add('STATIC_SCHEMA_CHECKS_PASSED', 'INFO', `${tools.length} tools passed deterministic schema checks`);
   const report = { reportVersion: 1, inspectorVersion: VERSION, mode: 'read-only MCP initialize + tools/list', checkedAt: new Date().toISOString(), endpoint: url.toString(), finalStatus: findings.some(x => x.severity === 'FAIL') ? 'FAIL' : 'PASS', mcp: { protocolVersion: init?.result?.protocolVersion ?? null, serverInfo: init?.result?.serverInfo ?? null, toolCount: Array.isArray(tools) ? tools.length : null }, findings, limitations: ['Static schema checks do not predict model tool selection or prove behavior across all clients.', 'No tool was called; side effects, authorization, data quality and security were not tested.'] };
-  console.log(format === 'json' ? JSON.stringify(report, null, 2) : `# MCP Tool Schema Report\n\n- Status: **${report.finalStatus}**\n- Endpoint: ${report.endpoint}\n- Protocol: ${report.mcp.protocolVersion ?? 'unknown'}\n- Tools: ${report.mcp.toolCount ?? 'unknown'}\n\n${findings.map(x => `- **${x.severity}** \`${x.code}\`: ${x.message}`).join('\n')}\n\n${report.limitations.map(x => `- ${x}`).join('\n')}`);
+  if (format === 'json') { console.log(JSON.stringify(report, null, 2)); }
+  else {
+    let text = `# MCP Tool Schema Report\n\n- Status: **${report.finalStatus}**\n- Endpoint: ${report.endpoint}\n- Protocol: ${report.mcp.protocolVersion ?? 'unknown'}\n- Tools: ${report.mcp.toolCount ?? 'unknown'}\n\n${findings.map(x => `- **${x.severity}** \`${x.code}\`: ${x.message}`).join('\n')}\n\n${report.limitations.map(x => `- ${x}`).join('\n')}`;
+    if (report.finalStatus === 'PASS') text += `\n\nNext steps\n- Gate CI on this exact check (paste into .github/workflows/mcp.yml):\n\n    - uses: xka0085-byte/mcp-doctor@v1\n      with:\n        endpoint: ${report.endpoint}\n        mode: schema\n\n- Weekly re-scan and a README status badge: https://xka0085-byte.github.io/mcp-doctor/trust/\n`;
+    console.log(text);
+  }
   process.exitCode = report.finalStatus === 'PASS' ? 0 : 1;
 }
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@eidonze/mcpdoctor",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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"
+    "mcpdoctor": "bin/mcpdoctor.mjs",
+    "mcpdoctor-mcp": "bin/mcpdoctor-mcp.mjs"
   },
   "main": "bin/mcpdoctor.mjs",
   "files": [