@eidonze/mcpdoctor 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +117 -100
  2. package/bin/mcpdoctor.mjs +13 -3
  3. package/package.json +41 -8
  4. package/test/smoke.mjs +17 -0
package/README.md CHANGED
@@ -1,100 +1,117 @@
1
- # mcpdoctor
2
-
3
- Read-only checks for MCP tool schemas and x402 payment endpoints. Use it before an agent client or buyer depends on an endpoint.
4
-
5
- [![npm](https://img.shields.io/npm/v/@eidonze/mcpdoctor?logo=npm)](https://www.npmjs.com/package/@eidonze/mcpdoctor)
6
- [![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)
7
- [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8
-
9
- ## Find the right guide
10
-
11
- - [Public documentation site](https://xka0085-byte.github.io/mcp-doctor/)
12
- - [MCP schema checker](docs/mcp-schema-checker.md)
13
- - [x402 endpoint inspector](docs/x402-endpoint-inspector.md)
14
- - [MCP security CI](docs/mcp-security-ci.md)
15
- - [Troubleshooting](docs/troubleshooting.md)
16
- - [OAuth scope and current limits](docs/mcp-oauth-diagnostics.md)
17
-
18
- ## Run it now
19
-
20
- Check an MCP server without calling any tools:
21
-
22
- ```bash
23
- npx @eidonze/mcpdoctor@0.1.5 schema https://your-mcp-server.example/mcp --json
24
- ```
25
-
26
- Check an x402 endpoint without paying:
27
-
28
- ```bash
29
- npx @eidonze/mcpdoctor@0.1.5 inspect https://your-api.example/paid --method=POST --json
30
- ```
31
-
32
- Requires Node.js 18+. No API key or wallet is needed.
33
-
34
- ## Which command?
35
-
36
- | Command | Checks | Does not do |
37
- |---|---|---|
38
- | `schema` | MCP `initialize`, `tools/list`, tool names, descriptions, and JSON schemas | Does not call tools or prove runtime behavior |
39
- | `inspect` | HTTP 402, x402 v1/v2 payment document, `accepts[]`, discovery manifests, latency and response digest | Does not sign, pay, settle, retry, or verify delivery |
40
-
41
- Exit codes are stable for automation: `0` PASS, `1` FAIL, `2` UNKNOWN/network error, `3` usage error.
42
-
43
- ## GitHub Actions
44
-
45
- Add a read-only check to pull requests:
46
-
47
- ```yaml
48
- name: MCP Trust Check
49
- on: [pull_request]
50
-
51
- jobs:
52
- mcp-trust:
53
- runs-on: ubuntu-latest
54
- steps:
55
- - uses: xka0085-byte/mcp-doctor@v1
56
- with:
57
- endpoint: https://your-mcp-server.example/mcp
58
- mode: schema
59
- format: markdown
60
- ```
61
-
62
- Use `mode: inspect` for an x402 preflight. The action fails on `FAIL` or `UNKNOWN` by default; set `fail-on: false` for an informational check.
63
-
64
- ## Starter template
65
-
66
- Start a new MCP project with this check already wired in:
67
-
68
- - [Secure MCP Server Starter](examples/secure-mcp-server-starter/)
69
-
70
- The check is read-only and should target a public test endpoint. Do not place private keys or credentials in workflow inputs.
71
-
72
- ## What the report means
73
-
74
- `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.
75
-
76
- Example schema failure:
77
-
78
- ```text
79
- FAIL REQUIRED_PROPERTY_UNDEFINED tools[0] requires undeclared property query
80
- ```
81
-
82
- Example x402 failure:
83
-
84
- ```text
85
- FAIL NO_402 Expected HTTP 402, received 400
86
- ```
87
-
88
- ## Why it exists
89
-
90
- 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.
91
-
92
- 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`.
93
-
94
- ## Feedback
95
-
96
- 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.
97
-
98
- ## License
99
-
100
- MIT
1
+ # mcpdoctor
2
+
3
+ Read-only checks for MCP tool schemas and x402 payment endpoints. Use it before an agent client or buyer depends on an endpoint.
4
+
5
+ [![npm](https://img.shields.io/npm/v/@eidonze/mcpdoctor?logo=npm)](https://www.npmjs.com/package/@eidonze/mcpdoctor)
6
+ [![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)
7
+ [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8
+
9
+ ## Find the right guide
10
+
11
+ - [Public documentation site](https://xka0085-byte.github.io/mcp-doctor/)
12
+ - [MCP schema checker](docs/mcp-schema-checker.md)
13
+ - [x402 endpoint inspector](docs/x402-endpoint-inspector.md)
14
+ - [MCP security CI](docs/mcp-security-ci.md)
15
+ - [Troubleshooting](docs/troubleshooting.md)
16
+ - [OAuth scope and current limits](docs/mcp-oauth-diagnostics.md)
17
+
18
+ ## Run it now
19
+
20
+ Check an MCP server without calling any tools:
21
+
22
+ ```bash
23
+ npx @eidonze/mcpdoctor@0.1.5 schema https://your-mcp-server.example/mcp --json
24
+ ```
25
+
26
+ Check an x402 endpoint without paying:
27
+
28
+ ```bash
29
+ npx @eidonze/mcpdoctor@0.1.5 inspect https://your-api.example/paid --method=POST --json
30
+ ```
31
+
32
+ Requires Node.js 18+. No API key or wallet is needed.
33
+
34
+ Example schema run against a live endpoint:
35
+
36
+ ```text
37
+ $ npx @eidonze/mcpdoctor schema https://your-mcp-server.example/mcp
38
+
39
+ MCP Tool Schema Report
40
+ - Status: FAIL
41
+ - Endpoint: https://your-mcp-server.example/mcp
42
+ - Protocol: 2025-06-18
43
+ - Tools: 12
44
+
45
+ - FAIL REQUIRED_PROPERTY_UNDEFINED: tools[3] requires undeclared property query
46
+ - WARN PROPERTY_DESCRIPTION_MISSING: tools[7].limit has no description
47
+ ```
48
+
49
+ The exact same run against a healthy server prints `Status: PASS` and exits 0, so CI can gate on it.
50
+
51
+ ## Which command?
52
+
53
+ | Command | Checks | Does not do |
54
+ |---|---|---|
55
+ | `schema` | MCP `initialize`, `tools/list`, tool names, descriptions, and JSON schemas | Does not call tools or prove runtime behavior |
56
+ | `inspect` | HTTP 402, x402 v1/v2 payment document, `accepts[]`, discovery manifests, latency and response digest | Does not sign, pay, settle, retry, or verify delivery |
57
+
58
+ Exit codes are stable for automation: `0` PASS, `1` FAIL, `2` UNKNOWN/network error, `3` usage error.
59
+
60
+ ## GitHub Actions
61
+
62
+ Add a read-only check to pull requests:
63
+
64
+ ```yaml
65
+ name: MCP Trust Check
66
+ on: [pull_request]
67
+
68
+ jobs:
69
+ mcp-trust:
70
+ runs-on: ubuntu-latest
71
+ steps:
72
+ - uses: xka0085-byte/mcp-doctor@v1
73
+ with:
74
+ endpoint: https://your-mcp-server.example/mcp
75
+ mode: schema
76
+ format: markdown
77
+ ```
78
+
79
+ Use `mode: inspect` for an x402 preflight. The action fails on `FAIL` or `UNKNOWN` by default; set `fail-on: false` for an informational check.
80
+
81
+ ## Starter template
82
+
83
+ Start a new MCP project with this check already wired in:
84
+
85
+ - [Secure MCP Server Starter](examples/secure-mcp-server-starter/)
86
+
87
+ The check is read-only and should target a public test endpoint. Do not place private keys or credentials in workflow inputs.
88
+
89
+ ## What the report means
90
+
91
+ `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.
92
+
93
+ Example schema failure:
94
+
95
+ ```text
96
+ FAIL REQUIRED_PROPERTY_UNDEFINED tools[0] requires undeclared property query
97
+ ```
98
+
99
+ Example x402 failure:
100
+
101
+ ```text
102
+ FAIL NO_402 Expected HTTP 402, received 400
103
+ ```
104
+
105
+ ## Why it exists
106
+
107
+ 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.
108
+
109
+ 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`.
110
+
111
+ ## Feedback
112
+
113
+ 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.
114
+
115
+ ## License
116
+
117
+ MIT
package/bin/mcpdoctor.mjs CHANGED
@@ -3,7 +3,7 @@ import { createHash } from 'node:crypto';
3
3
 
4
4
  const MAX_BODY = 1024 * 1024;
5
5
  const TIMEOUT = 10_000;
6
- const VERSION = '0.1.4';
6
+ const VERSION = '0.1.5';
7
7
 
8
8
  const help = `mcpdoctor ${VERSION}
9
9
 
@@ -47,6 +47,16 @@ function headersOf(headers) {
47
47
  }
48
48
 
49
49
  function json(text) { try { return JSON.parse(text); } catch { return null; } }
50
+ function jsonrpc(text) {
51
+ const direct = json(text);
52
+ if (direct && (direct.result !== undefined || direct.error !== undefined)) return direct;
53
+ for (const line of String(text).split(/\r?\n/)) {
54
+ if (!line.startsWith('data:')) continue;
55
+ const obj = json(line.slice(5).trim());
56
+ if (obj && (obj.result !== undefined || obj.error !== undefined)) return obj;
57
+ }
58
+ return direct;
59
+ }
50
60
 
51
61
  function findPaymentDocument(headers, body) {
52
62
  const candidates = [headers['payment-required'], headers['x-payment-required'], headers['www-authenticate'], body].filter(Boolean);
@@ -133,13 +143,13 @@ async function schemaCommand(url, format) {
133
143
  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 } } }) });
134
144
  const initText = await readBody(response);
135
145
  if (!response.ok) throw new Error(`MCP initialize returned HTTP ${response.status}`);
136
- const init = json(initText);
146
+ const init = jsonrpc(initText);
137
147
  if (!init?.result?.protocolVersion) add('INITIALIZE_RESPONSE_INVALID', 'FAIL', 'Initialize response did not include result.protocolVersion');
138
148
  const headers = { 'content-type': 'application/json', accept: 'application/json, text/event-stream', 'MCP-Protocol-Version': init?.result?.protocolVersion ?? '2025-03-26' };
139
149
  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: {} }) });
140
150
  const listText = await readBody(list);
141
151
  if (!list.ok) throw new Error(`tools/list returned HTTP ${list.status}`);
142
- const parsed = json(listText);
152
+ const parsed = jsonrpc(listText);
143
153
  const tools = parsed?.result?.tools;
144
154
  if (!Array.isArray(tools)) add('TOOLS_LIST_INVALID', 'FAIL', 'tools/list response did not contain result.tools[]');
145
155
  else if (!tools.length) add('NO_TOOLS', 'WARN', 'Server exposes an empty tool list');
package/package.json CHANGED
@@ -1,17 +1,50 @@
1
1
  {
2
2
  "name": "@eidonze/mcpdoctor",
3
- "version": "0.1.5",
3
+ "version": "0.1.6",
4
4
  "mcpName": "io.github.xka0085-byte/mcpdoctor",
5
5
  "description": "Read-only MCP and x402 endpoint preflight checks: 402 challenge shape, payment document parsing, accepts[] conformance, discovery manifests, response digest. Zero dependencies.",
6
6
  "license": "MIT",
7
7
  "type": "module",
8
- "bin": { "mcpdoctor": "bin/mcpdoctor.mjs" },
8
+ "bin": {
9
+ "mcpdoctor": "bin/mcpdoctor.mjs"
10
+ },
9
11
  "main": "bin/mcpdoctor.mjs",
10
- "files": ["bin", "test", "README.md", "LICENSE"],
11
- "engines": { "node": ">=18" },
12
- "scripts": { "test": "node test/smoke.mjs" },
13
- "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"],
14
- "repository": { "type": "git", "url": "git+https://github.com/xka0085-byte/mcp-doctor.git" },
15
- "bugs": { "url": "https://github.com/xka0085-byte/mcp-doctor/issues" },
12
+ "files": [
13
+ "bin",
14
+ "test",
15
+ "README.md",
16
+ "LICENSE"
17
+ ],
18
+ "engines": {
19
+ "node": ">=18"
20
+ },
21
+ "scripts": {
22
+ "test": "node test/smoke.mjs"
23
+ },
24
+ "keywords": [
25
+ "mcp",
26
+ "model-context-protocol",
27
+ "mcp-security",
28
+ "mcp-scanner",
29
+ "mcp-schema",
30
+ "mcp-oauth",
31
+ "agent-security",
32
+ "tool-schema",
33
+ "x402-inspector",
34
+ "http-402",
35
+ "mcp-cli",
36
+ "mcp-debugging",
37
+ "developer-tools",
38
+ "diagnostics",
39
+ "x402",
40
+ "cli"
41
+ ],
42
+ "repository": {
43
+ "type": "git",
44
+ "url": "git+https://github.com/xka0085-byte/mcp-doctor.git"
45
+ },
46
+ "bugs": {
47
+ "url": "https://github.com/xka0085-byte/mcp-doctor/issues"
48
+ },
16
49
  "homepage": "https://xka0085-byte.github.io/evidence-tools/"
17
50
  }
package/test/smoke.mjs CHANGED
@@ -29,6 +29,18 @@ const server = createServer(async (request, response) => {
29
29
  }
30
30
  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;
31
31
  }
32
+ // regression (found against production DeepWiki): servers may answer POST with
33
+ // an SSE stream (text/event-stream) even for plain JSON-RPC calls
34
+ if (request.url === '/mcp-sse') {
35
+ let incoming = ''; for await (const chunk of request) incoming += chunk;
36
+ const rpc = JSON.parse(incoming || '{}');
37
+ const payload = rpc.method === 'initialize'
38
+ ? { jsonrpc: '2.0', id: rpc.id, result: { protocolVersion: '2025-06-18', serverInfo: { name: 'sse-fixture', version: '1' }, capabilities: {} } }
39
+ : { 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'] } }] } };
40
+ response.writeHead(200, { 'content-type': 'text/event-stream' });
41
+ response.end(`event: message\ndata: ${JSON.stringify(payload)}\n\n`);
42
+ return;
43
+ }
32
44
  // regression (our original production bug): body validation must not shadow the 402
33
45
  if (request.url === '/bad-400') {
34
46
  response.writeHead(400, { 'content-type': 'application/json' });
@@ -83,6 +95,11 @@ try {
83
95
  const schemaReport = JSON.parse(schema.stdout);
84
96
  assert.equal(schemaReport.finalStatus, 'PASS', JSON.stringify(schemaReport.findings));
85
97
  assert.equal(schemaReport.mcp.toolCount, 1);
98
+ const sse = await runSchema(`http://127.0.0.1:${port}/mcp-sse`);
99
+ assert.equal(sse.code, 0, sse.stderr);
100
+ const sseReport = JSON.parse(sse.stdout);
101
+ assert.equal(sseReport.finalStatus, 'PASS', JSON.stringify(sseReport.findings));
102
+ assert.equal(sseReport.mcp.toolCount, 1, 'SSE-wrapped JSON-RPC must be parsed');
86
103
  const help = await new Promise((resolve) => {
87
104
  const child = spawn(process.execPath, [cli, '--help'], { stdio: ['ignore', 'pipe', 'pipe'] });
88
105
  let stdout = ''; child.stdout.on('data', (chunk) => { stdout += chunk; }); child.on('close', (code) => resolve({ code, stdout }));