@eidonze/mcpdoctor 0.1.2 → 0.1.4

package/LICENSE

@@ -1,21 +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.
+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,5 +1,7 @@
 # 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:
@@ -24,6 +26,46 @@ npm install -g @eidonze/mcpdoctor    # or run without installing:
 npx @eidonze/mcpdoctor inspect <url>
 ```
 
+Current release: `0.1.4`. The CLI is read-only: it does not sign, pay, retry payment, invoke MCP tools, or accept private keys.
+
+## GitHub Actions
+
+Run the check in pull requests without installing a package or storing a key:
+
+```yaml
+name: MCP Trust Check
+on: [pull_request]
+
+jobs:
+  mcp-trust:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: xka0085-byte/mcpdoctor@v1
+        with:
+          endpoint: https://your-mcp-server.example/mcp
+          mode: schema
+          format: markdown
+```
+
+`schema` performs read-only `initialize` and `tools/list` checks. Use `mode: inspect`
+for a read-only x402 HTTP 402 preflight. A non-zero exit means the observed result
+was `FAIL` or `UNKNOWN`; this is a CI gate, not a security certification.
+
+## 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
@@ -38,8 +80,19 @@ mcpdoctor inspect <url> [--method=GET|POST] [--format=json|markdown]
 
 Exit codes: `0` PASS · `1` FAIL · `2` UNKNOWN (network/timeout) · `3` usage error.
 
+## Tool schema checks
+
+Inspect MCP initialization and `tools/list` without calling tools:
+
+```bash
+node mcpdoctor/bin/mcpdoctor.mjs schema https://your-mcp-server.example/mcp --json
+```
+
+This is deterministic static lint, not a prediction of model tool selection or a cross-client certification. See [`SCHEMA-MVP.md`](./SCHEMA-MVP.md).
+
 ## 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:
 

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.2';
+const VERSION = '0.1.4';
 
 const help = `mcpdoctor ${VERSION}
 
@@ -11,6 +11,7 @@ Read-only MCP/x402 endpoint diagnostics.
 
 Usage:
   mcpdoctor inspect <url> [--method=GET|POST] [--format=json|markdown]
+  mcpdoctor schema <url> [--format=json|markdown]
   mcpdoctor --help
 
 This MVP never signs, pays, retries payment, or accepts a private key.`;
@@ -126,9 +127,47 @@ function markdown(report) {
   return lines.join('\n');
 }
 
+async function schemaCommand(url, format) {
+  const findings = [];
+  const add = (code, severity, message) => findings.push({ code, severity, message });
+  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);
+  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 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');
+  else for (const [i, tool] of tools.entries()) {
+    const at = `tools[${i}]`;
+    if (typeof tool.name !== 'string' || !tool.name.trim()) add('TOOL_NAME_MISSING', 'FAIL', `${at} has no name`);
+    if (typeof tool.description !== 'string' || !tool.description.trim()) add('TOOL_DESCRIPTION_MISSING', 'WARN', `${at} has no description`);
+    const schema = tool.inputSchema;
+    if (!schema || schema.type !== 'object') add('INPUT_SCHEMA_NOT_OBJECT', 'FAIL', `${at}.inputSchema must declare type: object`);
+    const props = schema?.properties;
+    if (props !== undefined && (!props || typeof props !== 'object' || Array.isArray(props))) add('PROPERTIES_INVALID', 'FAIL', `${at}.inputSchema.properties must be an object`);
+    for (const req of schema?.required ?? []) if (!props?.[req]) add('REQUIRED_PROPERTY_UNDEFINED', 'FAIL', `${at} requires undeclared property ${req}`);
+    for (const [key, property] of Object.entries(props ?? {})) if (typeof property?.description !== 'string' || !property.description.trim()) add('PROPERTY_DESCRIPTION_MISSING', 'WARN', `${at}.${key} has no description`);
+  }
+  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')}`);
+  process.exitCode = report.finalStatus === 'PASS' ? 0 : 1;
+}
+
 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 if (args[0] === 'schema') {
+  let url; try { url = new URL(args[1]); if (!['http:', 'https:'].includes(url.protocol)) throw new Error('only http(s) URLs are supported'); } catch (error) { die(error.message); }
+  const format = args.includes('--json') || args.includes('--format=json') ? 'json' : 'markdown';
+  if (url) schemaCommand(url, format).catch((error) => { console.error(`UNKNOWN: ${redact(error.message)}`); process.exitCode = 2; });
+}
+else if (args[0] !== 'inspect') die('only inspect and schema commands are available in this MVP');
 else {
   const rawUrl = args[1];
   const method = (args.find((arg) => arg.startsWith('--method='))?.split('=')[1] ?? 'GET').toUpperCase();

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@eidonze/mcpdoctor",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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.",
+  "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" },

package/test/smoke.mjs

@@ -8,7 +8,7 @@ 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) => {
+const server = createServer(async (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' }] }));
@@ -21,6 +21,14 @@ const server = createServer((request, response) => {
     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;
   }
+  if (request.url === '/mcp') {
+    let incoming = ''; for await (const chunk of request) incoming += chunk;
+    const rpc = JSON.parse(incoming || '{}');
+    if (rpc.method === 'initialize') {
+      response.writeHead(200, { 'content-type': 'application/json' }); response.end(JSON.stringify({ jsonrpc: '2.0', id: rpc.id, result: { protocolVersion: '2025-06-18', serverInfo: { name: 'fixture', version: '1' }, capabilities: {} } })); return;
+    }
+    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 (our original production bug): body validation must not shadow the 402
   if (request.url === '/bad-400') {
     response.writeHead(400, { 'content-type': 'application/json' });
@@ -43,6 +51,15 @@ function run(url, ...args) {
     child.on('close', (code) => resolve({ code, stdout, stderr }));
   });
 }
+function runSchema(url) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [cli, 'schema', url, '--format=json'], { 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`);
@@ -61,6 +78,11 @@ try {
   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 schema = await runSchema(`http://127.0.0.1:${port}/mcp`);
+  assert.equal(schema.code, 0, schema.stderr);
+  const schemaReport = JSON.parse(schema.stdout);
+  assert.equal(schemaReport.finalStatus, 'PASS', JSON.stringify(schemaReport.findings));
+  assert.equal(schemaReport.mcp.toolCount, 1);
   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 }));