@eidonze/mcpdoctor 0.1.4 → 0.1.5

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 (2) hide show
  1. package/README.md +100 -161
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,161 +1,100 @@
1
- # mcpdoctor
2
-
3
- > ⚠️ **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`.
4
-
5
- **mcpdoctor is a read-only CLI for inspecting MCP and x402 endpoints.**
6
-
7
- Point it at a URL, get one `PASS / FAIL / UNKNOWN` report:
8
-
9
- - the **HTTP 402 payment document** — parsed from the known locations
10
- (`Payment-Required` / `X-Payment-Required` / `WWW-Authenticate` headers or
11
- the response body), in both x402 v1 (`accepts[]`) and v2 (`x402.accepts`)
12
- shapes, with every `scheme / network / asset / amount / payTo` field checked;
13
- - the **discovery manifests** — whether `/.well-known/mcp/server.json` and
14
- `/.well-known/x402` are reachable, with a SHA-256 of each;
15
- - a **SHA-256 digest** of the response body, plus latency and size.
16
-
17
- mcpdoctor is **not an MCP server** and does not implement the MCP protocol.
18
- It is the endpoint inspector you run *before* pointing an MCP client or an
19
- x402 buyer at an endpoint — a preflight/debugging tool for AI-agent payment
20
- infrastructure. Zero dependencies. Node ≥ 18. Never touches keys, never pays.
21
-
22
- ## Install
23
-
24
- ```bash
25
- npm install -g @eidonze/mcpdoctor # or run without installing:
26
- npx @eidonze/mcpdoctor inspect <url>
27
- ```
28
-
29
- Current release: `0.1.4`. The CLI is read-only: it does not sign, pay, retry payment, invoke MCP tools, or accept private keys.
30
-
31
- ## GitHub Actions
32
-
33
- Run the check in pull requests without installing a package or storing a key:
34
-
35
- ```yaml
36
- name: MCP Trust Check
37
- on: [pull_request]
38
-
39
- jobs:
40
- mcp-trust:
41
- runs-on: ubuntu-latest
42
- steps:
43
- - uses: xka0085-byte/mcpdoctor@v1
44
- with:
45
- endpoint: https://your-mcp-server.example/mcp
46
- mode: schema
47
- format: markdown
48
- ```
49
-
50
- `schema` performs read-only `initialize` and `tools/list` checks. Use `mode: inspect`
51
- for a read-only x402 HTTP 402 preflight. A non-zero exit means the observed result
52
- was `FAIL` or `UNKNOWN`; this is a CI gate, not a security certification.
53
-
54
- ## Why
55
-
56
- Shipping an x402 service ourselves ([ReceiptRail](https://github.com/xka0085-byte/agenttoll)),
57
- we hit every way a paid endpoint can silently break:
58
-
59
- - an endpoint that validates the request body **before** returning the 402
60
- challenge is invisible to every x402 client — they only react to `402`;
61
- - payment documents arrive in **four different places** (`Payment-Required` /
62
- `X-Payment-Required` / `WWW-Authenticate` headers, or the response body) and
63
- in **two different shapes** (v1 top-level `accepts[]`, v2 nested `x402.accepts`);
64
- parsers that only look at one place report false failures;
65
- - vendor hint headers without `accepts[]` can shadow the real payment document.
66
-
67
- Each check in mcpdoctor maps to a failure mode we actually hit in production.
68
-
69
- ## Usage
70
-
71
- ```bash
72
- mcpdoctor inspect <url> [--method=GET|POST] [--format=json|markdown]
73
- ```
74
-
75
- | Option | Default | Description |
76
- |---|---|---|
77
- | `--method` | `GET` | HTTP verb for the probe (`POST` sends `{}`) |
78
- | `--format` | `markdown` | `json` for CI / machine-readable reports |
79
- | `--json` | — | shorthand for `--format=json` |
80
-
81
- Exit codes: `0` PASS · `1` FAIL · `2` UNKNOWN (network/timeout) · `3` usage error.
82
-
83
- ## Tool schema checks
84
-
85
- Inspect MCP initialization and `tools/list` without calling tools:
86
-
87
- ```bash
88
- node mcpdoctor/bin/mcpdoctor.mjs schema https://your-mcp-server.example/mcp --json
89
- ```
90
-
91
- This is deterministic static lint, not a prediction of model tool selection or a cross-client certification. See [`SCHEMA-MVP.md`](./SCHEMA-MVP.md).
92
-
93
- ## Real examples (captured 2026-09-29, against live endpoints)
94
-
95
-
96
- Inspecting an MCP endpoint that is free (no payment gate) — the tool reports
97
- the 200 instead of a 402, and still verifies the discovery manifests:
98
-
99
- ```json
100
- {
101
- "endpoint": "https://agenttoll-receipts.app.workbuddy.host/mcp",
102
- "method": "POST",
103
- "finalStatus": "FAIL",
104
- "http": { "status": 200, "elapsedMs": 2830, "bodyBytes": 82,
105
- "bodySha256": "598dc097dcca1e573c742100863899c00724a021b421a5bb49952d49fec6b4f4" },
106
- "findings": [
107
- { "status": "FAIL", "code": "NO_402", "message": "Expected HTTP 402, received 200" }
108
- ],
109
- "metadata": [
110
- { "path": "/.well-known/mcp/server.json", "status": 200, "reachable": true }
111
- ]
112
- }
113
- ```
114
-
115
- Inspecting the official x402 demo endpoint — it does return 402, but ships a
116
- payment document mcpdoctor cannot parse, which is exactly the class of silent
117
- breakage this CLI exists to catch:
118
-
119
- ```json
120
- {
121
- "endpoint": "https://x402.org/protected",
122
- "finalStatus": "FAIL",
123
- "http": { "status": 402 },
124
- "headers": { "paymentRequired": true },
125
- "findings": [
126
- { "status": "FAIL", "code": "NO_ACCEPTS",
127
- "message": "No recognizable payment requirement found" }
128
- ]
129
- }
130
- ```
131
-
132
- ## What it does NOT do
133
-
134
- - No MCP protocol session: no `initialize`, no `tools/list` — mcpdoctor
135
- checks what an endpoint *advertises* (402 documents, discovery manifests),
136
- not a full MCP handshake.
137
- - No wallet, signing, settlement, or retries. Read-only preflight only.
138
- - `PASS` means the observed 402 document had recognizable, complete fields —
139
- it is not a security or payment-success certification.
140
-
141
- ## Why
142
-
143
- We ship an x402 service ourselves ([ReceiptRail](https://github.com/xka0085-byte/agenttoll))
144
- and hit every way a paid endpoint can silently break:
145
-
146
- - an endpoint that validates the request body **before** returning the 402
147
- challenge is invisible to every x402 client — they only react to `402`;
148
- - payment documents arrive in **four different places** and **two different
149
- shapes**; parsers that only look at one place report false failures;
150
- - vendor hint headers without `accepts[]` can shadow the real payment document.
151
-
152
- Each check in mcpdoctor maps to a failure mode we actually hit in production.
153
-
154
- ## Part of the Agent / Chain Evidence Tools suite
155
-
156
- Read-only diagnostics for AI agents on Web3 —
157
- [hub & docs](https://xka0085-byte.github.io/evidence-tools/) ·
158
- [ReceiptRail (live MCP service)](https://github.com/xka0085-byte/agenttoll) ·
159
- [npm: @eidonze/mcpdoctor](https://www.npmjs.com/package/@eidonze/mcpdoctor)
160
-
161
- MIT licensed. Known limitations are documented, not hidden.
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@eidonze/mcpdoctor",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
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",
@@ -10,7 +10,7 @@
10
10
  "files": ["bin", "test", "README.md", "LICENSE"],
11
11
  "engines": { "node": ">=18" },
12
12
  "scripts": { "test": "node test/smoke.mjs" },
13
- "keywords": ["mcp", "model-context-protocol", "mcp-cli", "mcp-inspector", "mcp-endpoint-inspector", "mcp-debugging", "x402", "cli", "developer-tools", "diagnostics"],
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
14
  "repository": { "type": "git", "url": "git+https://github.com/xka0085-byte/mcp-doctor.git" },
15
15
  "bugs": { "url": "https://github.com/xka0085-byte/mcp-doctor/issues" },
16
16
  "homepage": "https://xka0085-byte.github.io/evidence-tools/"