@vantageos/mcp-doctor 0.1.0

package/LICENSE

@@ -0,0 +1,110 @@
+Functional Source License, Version 1.1, Apache 2.0 Future License
+
+Abbreviation
+
+FSL-1.1-Apache-2.0
+
+Notice
+
+Copyright 2026 VantageOS (ElPi Corp)
+
+Terms and Conditions
+
+Licensor:             VantageOS (ElPi Corp)
+
+Licensed Work:        VantagePeers
+                      The Licensed Work is (c) 2026 VantageOS (ElPi Corp)
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided Your use does not include offering the Licensed
+                      Work to third parties as a hosted or managed service
+                      where the service provides users with access to any
+                      substantial set of the features or functionality of the
+                      Licensed Work.
+
+Change Date:          2028-04-03 (two years from publication)
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: contact@vantageos.com
+
+License text below is provided for informational purposes only.
+
+---
+
+Functional Source License, Version 1.1, Apache 2.0 Future License
+
+1. Purpose
+
+This license gives you broad permission to use, modify, and share this
+software, with one important condition: you may not use it to compete with us.
+
+2. Acceptance
+
+To use the software, you must agree to these terms. If you do not agree, you
+may not use the software.
+
+3. Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-
+sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+4. Limitations
+
+You may not make the functionality of the software available to third parties
+as a service, or otherwise use the software to provide a service to third
+parties that competes with the licensor.
+
+5. Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license or becomes able to license, to make, have made, use, sell, offer for
+sale, import, and have imported the software, in each case subject to the
+limitations and conditions in this license.
+
+6. Fair Use
+
+This license is not intended to limit any rights you may have under applicable
+fair use or other laws.
+
+7. No Other Rights
+
+These terms do not grant any other rights. The licensor reserves all rights not
+expressly granted.
+
+8. Termination
+
+Your license is automatically terminated if you violate the terms. However, if
+you cure the violation within 30 days of discovering it, your license is
+reinstated retroactively.
+
+9. Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED.
+
+10. Limitation of Liability
+
+TO THE EXTENT PERMITTED BY LAW, THE LICENSOR IS NOT LIABLE FOR ANY DAMAGES
+ARISING FROM THE USE OF THE SOFTWARE.
+
+11. Change Date and License
+
+After the Change Date, the licensor grants you the rights under the Change
+License.
+
+12. Definitions
+
+"Compete" means providing a product or service that is substantially similar
+to, or a replacement for, all or a significant portion of the Licensed Work.
+
+---
+
+Apache License, Version 2.0
+
+After the Change Date (2028-04-03), this software will be available under the
+Apache License, Version 2.0. See https://www.apache.org/licenses/LICENSE-2.0
+for full text.

package/README.md

@@ -0,0 +1,76 @@
+# @vantageos/mcp-doctor
+
+Static **MCP conformance checker**. Point it at an MCP server source tree and it emits a
+**conformance-diff table** against the MCP **2026-07-28** standard — one row per checked item:
+
+```
+item | file:line | present | absent | non-conforming | verdict
+```
+
+No narrative, no LLM, no network: a deterministic static scan you can wire into CI. It reproduces,
+unaided, the manual conformance audits the fleet ran by hand on its own MCP servers.
+
+## Usage
+
+```bash
+npx @vantageos/mcp-doctor <path-to-mcp-server-source>
+```
+
+Example:
+
+```bash
+npx @vantageos/mcp-doctor ./mcp-server
+```
+
+```
+surface: ./mcp-server
+item                     | file:line          | state           | verdict
+-----------------------------------------------------------------------------
+D2 stateless             | -                  | present         | stateless (no mcp-session-id session-keying)
+D3 resultType            | server.ts:589      | absent          | list/read builder returns {content} without resultType -> add via protocol-kit
+D4 CacheableResult       | server.ts:579,595  | absent          | list/read builders lack ttlMs/cacheScope -> add CacheableResult
+D5 server/discover       | -                  | absent          | no server/discover handler -> add via protocol-kit
+D6 mcp-apps ui-key       | -                  | absent          | no MCP Apps UI key (no _meta ui)
+D7 protocol-kit          | package.json       | absent          | hand-rolled builders, protocol-kit not a dependency
+```
+
+The path is the root of the MCP server sources (the folder holding `server.ts` / `transport/` /
+`package.json`). `node_modules`, `dist`, `build`, `.git` and test folders are skipped automatically.
+
+## Programmatic use
+
+```ts
+import { runDoctor, renderTable } from "@vantageos/mcp-doctor";
+
+const results = runDoctor("./mcp-server");
+console.log(renderTable("./mcp-server", results));
+```
+
+## What it checks — the 6 Tier-A detectors (MCP 2026-07-28)
+
+Each detector maps one standard item and is proven **bipolar** on real material: a genuine defect
+(MUST_FLAG) and a genuine conformant site (MUST_PASS).
+
+| ID | Standard item | Verdict shape |
+|----|---------------|---------------|
+| **D2** stateless | `sessionIdGenerator: undefined`, no `Mcp-Session-Id` session-keying, no hand-rolled `initialize` gate | conforming (stateless) / non-conforming (session-keyed) |
+| **D3** resultType | `resultType` present on list/read result builders | present / absent |
+| **D4** CacheableResult | `ttlMs` / `cacheScope` on the list/read result types | present / absent |
+| **D5** server/discover | a `server/discover` handler is registered (absence-based, with a positive control) | present / absent |
+| **D6** mcp-apps ui-key | MCP Apps UI key is the GA nested `_meta.ui.resourceUri` — not flat `ui/resourceUri`, not community `io.modelcontextprotocol/ui` | GA-nested / flat-deprecated / community-nonGA / none |
+| **D7** protocol-kit | `@vantageos/mcp-protocol-kit` listed in `package.json` **and actually called** (builder invoked, not merely declared) | listed+called / listed-not-called / hand-rolled |
+
+## Positioning
+
+`mcp-doctor` is both an **internal fleet upgrade tool** — it drives MCP servers toward the current
+standard by naming the exact `file:line` to fix — and a **vendable product** for any team shipping
+MCP servers who needs a reproducible conformance gate. It is deterministic: the same tree yields the
+same diff on any machine, so it belongs in CI, not in a review checklist.
+
+## License
+
+FSL-1.1-Apache-2.0 (Functional Source License, Apache 2.0 future license). See [LICENSE](./LICENSE).
+
+---
+
+Orchestrator: Gamma — VantageOS Team | 2026-08-03

package/dist/doctor.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+type State = "present" | "absent" | "non-conforming";
+interface DetectorResult {
+    id: string;
+    /** display anchor(s) file:line — the site the verdict is about. */
+    anchor: string;
+    state: State;
+    verdict: string;
+}
+
+declare function runDoctor(target: string): DetectorResult[];
+declare function renderTable(surface: string, results: DetectorResult[]): string;
+
+export { renderTable, runDoctor };

package/dist/doctor.js

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+
+// src/scan.ts
+import { readFileSync, readdirSync, statSync, existsSync } from "fs";
+import { join, dirname, relative } from "path";
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", ".git", "tests", "__tests__", "coverage"]);
+function isCommentLine(raw) {
+  const t = raw.trim();
+  if (t === "") return false;
+  return t.startsWith("*") || t.startsWith("//") || t.startsWith("/*") || t.startsWith("*/");
+}
+function walk(dir, out) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    const full = join(dir, name);
+    let st;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      if (SKIP_DIRS.has(name)) continue;
+      walk(full, out);
+    } else if (name.endsWith(".ts") || name.endsWith(".tsx")) {
+      if (name.endsWith(".d.ts") || name.endsWith(".test.ts")) continue;
+      out.push(full);
+    }
+  }
+}
+function loadFile(path, root) {
+  const raw = readFileSync(path, "utf8");
+  const lines = raw.split("\n").map((r, i) => ({ n: i + 1, raw: r, comment: isCommentLine(r) }));
+  return { path, rel: relative(root, path) || path, lines };
+}
+function findPackageJson(startDir) {
+  let dir = startDir;
+  for (let depth = 0; depth < 8; depth++) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        return { path: candidate, json: JSON.parse(readFileSync(candidate, "utf8")) };
+      } catch {
+        return { path: candidate, json: {} };
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function loadTree(root) {
+  const st = statSync(root);
+  const baseDir = st.isDirectory() ? root : dirname(root);
+  const filePaths = [];
+  if (st.isDirectory()) walk(root, filePaths);
+  else if (root.endsWith(".ts") || root.endsWith(".tsx")) filePaths.push(root);
+  const files = filePaths.map((p) => loadFile(p, baseDir));
+  return { root, files, packageJson: findPackageJson(baseDir) };
+}
+
+// src/detectors/d2.ts
+var SESSION_RE = /mcp-session-id/i;
+var d2 = {
+  id: "D2 stateless",
+  run(tree) {
+    const hits = [];
+    for (const file of tree.files) {
+      for (const line of file.lines) {
+        if (line.comment) continue;
+        if (SESSION_RE.test(line.raw)) hits.push({ file: file.rel, line: line.n });
+      }
+    }
+    if (hits.length > 0) {
+      const anchor = `${hits[0].file}:${hits.map((h) => h.line).join(",")}`;
+      return {
+        id: this.id,
+        anchor,
+        state: "non-conforming",
+        verdict: "session-keyed (mcp-session-id header) -> migrate to stateless"
+      };
+    }
+    return {
+      id: this.id,
+      anchor: "-",
+      state: "present",
+      verdict: "stateless (no mcp-session-id session-keying)"
+    };
+  }
+};
+
+// src/detectors/toolContext.ts
+var LIST_READ_RE = /^(list|read|get|search)/;
+var INLINE_NAME_RE = /\b(?:s\.tool|\.tool|registerTool)\s*\(\s*["'`]([a-z][a-z0-9_]*)["'`]/;
+var OPENER_RE = /\b(?:s\.tool|\.tool|registerTool)\s*\(\s*$/;
+var BARE_NAME_RE = /^\s*["'`]([a-z][a-z0-9_]*)["'`]\s*,?/;
+var DESCRIPTOR_NAME_RE = /\bname:\s*["'`]([a-z][a-z0-9_]*)["'`]/;
+var CONTENT_RE = /content:\s*\[/;
+function findListReadBuilders(tree) {
+  const out = [];
+  for (const file of tree.files) {
+    let currentTool = null;
+    let currentToolLine = 0;
+    let awaitingName = false;
+    for (const line of file.lines) {
+      if (line.comment) continue;
+      const raw = line.raw;
+      const inline = raw.match(INLINE_NAME_RE);
+      if (inline) {
+        currentTool = inline[1];
+        currentToolLine = line.n;
+        awaitingName = false;
+      } else if (OPENER_RE.test(raw)) {
+        awaitingName = true;
+      } else if (awaitingName) {
+        const bare = raw.match(BARE_NAME_RE);
+        if (bare) {
+          currentTool = bare[1];
+          currentToolLine = line.n;
+        }
+        awaitingName = false;
+      }
+      const desc = raw.match(DESCRIPTOR_NAME_RE);
+      if (desc) {
+        currentTool = desc[1];
+        currentToolLine = line.n;
+      }
+      if (CONTENT_RE.test(raw) && currentTool && LIST_READ_RE.test(currentTool)) {
+        out.push({
+          file,
+          toolName: currentTool,
+          toolNameLine: currentToolLine,
+          contentLine: line.n
+        });
+      }
+    }
+  }
+  return out;
+}
+function countKeywordInCode(tree, re) {
+  let count = 0;
+  let firstFile;
+  let firstLine;
+  for (const file of tree.files) {
+    for (const line of file.lines) {
+      if (line.comment) continue;
+      if (re.test(line.raw)) {
+        count += 1;
+        if (firstFile === void 0) {
+          firstFile = file;
+          firstLine = line.n;
+        }
+      }
+    }
+  }
+  return { count, firstFile, firstLine };
+}
+
+// src/detectors/d3.ts
+var RESULT_TYPE_RE = /\bresultType\b/;
+var KIT_RESULT_CALL_RE = /\b(buildToolsListResult|buildListResult|buildToolCallResult)\s*\(/;
+var d3 = {
+  id: "D3 resultType",
+  run(tree) {
+    const builders = findListReadBuilders(tree);
+    const rt = countKeywordInCode(tree, RESULT_TYPE_RE);
+    const kit = countKeywordInCode(tree, KIT_RESULT_CALL_RE);
+    if (rt.count > 0 || kit.count > 0) {
+      const src = rt.count > 0 ? rt : kit;
+      return {
+        id: this.id,
+        anchor: src.firstFile ? `${src.firstFile.rel}:${src.firstLine}` : "-",
+        state: "present",
+        verdict: rt.count > 0 ? "resultType present" : "resultType via kit result-builder call"
+      };
+    }
+    if (builders.length === 0) {
+      return { id: this.id, anchor: "-", state: "absent", verdict: "no list/read builders found; resultType absent" };
+    }
+    const b = builders[0];
+    return {
+      id: this.id,
+      anchor: `${b.file.rel}:${b.contentLine}`,
+      state: "absent",
+      verdict: `list/read builder returns {content} without resultType (grep resultType=0) -> add via protocol-kit`
+    };
+  }
+};
+
+// src/detectors/d4.ts
+var CACHEABLE_RE = /\b(ttlMs|cacheScope)\b/;
+var d4 = {
+  id: "D4 CacheableResult",
+  run(tree) {
+    const builders = findListReadBuilders(tree);
+    const cache = countKeywordInCode(tree, CACHEABLE_RE);
+    if (cache.count > 0) {
+      return {
+        id: this.id,
+        anchor: cache.firstFile ? `${cache.firstFile.rel}:${cache.firstLine}` : "-",
+        state: "present",
+        verdict: "CacheableResult present (ttlMs/cacheScope)"
+      };
+    }
+    if (builders.length === 0) {
+      return { id: this.id, anchor: "-", state: "absent", verdict: "no list/read builders found; CacheableResult absent" };
+    }
+    const anchorLines = builders.slice(0, 2).map((b) => b.toolNameLine);
+    return {
+      id: this.id,
+      anchor: `${builders[0].file.rel}:${anchorLines.join(",")}`,
+      state: "absent",
+      verdict: "list/read builders lack ttlMs/cacheScope (grep=0) -> add CacheableResult"
+    };
+  }
+};
+
+// src/detectors/d5.ts
+var DISCOVER_RE = /server\/discover/;
+var POSITIVE_CONTROL = 'method: zv4.literal("server/discover"),';
+function d5PositiveControl() {
+  return { pattern: DISCOVER_RE.source, sample: POSITIVE_CONTROL, matched: DISCOVER_RE.test(POSITIVE_CONTROL) };
+}
+var d5 = {
+  id: "D5 server/discover",
+  run(tree) {
+    const control = d5PositiveControl();
+    if (!control.matched) {
+      throw new Error(
+        `D5 positive control FAILED: pattern /${control.pattern}/ did not match sample \`${control.sample}\` \u2014 matcher broken, absence verdict untrustworthy`
+      );
+    }
+    for (const file of tree.files) {
+      for (const line of file.lines) {
+        if (DISCOVER_RE.test(line.raw)) {
+          return {
+            id: this.id,
+            anchor: `${file.rel}:${line.n}`,
+            state: "present",
+            verdict: "server/discover handler present"
+          };
+        }
+      }
+    }
+    return {
+      id: this.id,
+      anchor: "-",
+      state: "absent",
+      verdict: "no server/discover handler (grep=0, positive-control OK) -> add via protocol-kit"
+    };
+  }
+};
+
+// src/detectors/d6.ts
+var COMMUNITY_RE = /["'`]io\.modelcontextprotocol\/ui["'`]\s*:|_meta\s*\[\s*["'`]io\.modelcontextprotocol\/ui["'`]\s*\]/;
+var FLAT_RE = /["'`]ui\/resourceUri["'`]\s*:|_meta\s*\[\s*["'`]ui\/resourceUri["'`]\s*\]/;
+var NESTED_UI_RE = /_meta\s*:\s*\{\s*ui\b/;
+var RESOURCE_URI_RE = /\bresourceUri\b/;
+var d6 = {
+  id: "D6 mcp-apps ui-key",
+  run(tree) {
+    let community = null;
+    let flat = null;
+    let nested = null;
+    let sawResourceUri = false;
+    for (const file of tree.files) {
+      for (const line of file.lines) {
+        if (line.comment) continue;
+        if (!community && COMMUNITY_RE.test(line.raw)) community = { file: file.rel, line: line.n };
+        if (!flat && FLAT_RE.test(line.raw)) flat = { file: file.rel, line: line.n };
+        if (!nested && NESTED_UI_RE.test(line.raw)) nested = { file: file.rel, line: line.n };
+        if (RESOURCE_URI_RE.test(line.raw)) sawResourceUri = true;
+      }
+    }
+    if (community) {
+      return {
+        id: this.id,
+        anchor: `${community.file}:${community.line}`,
+        state: "non-conforming",
+        verdict: "community io.modelcontextprotocol/ui key (non-GA) -> _meta.ui.resourceUri"
+      };
+    }
+    if (flat) {
+      return {
+        id: this.id,
+        anchor: `${flat.file}:${flat.line}`,
+        state: "non-conforming",
+        verdict: "flat ui/resourceUri key (deprecated) -> _meta.ui.resourceUri"
+      };
+    }
+    if (nested && sawResourceUri) {
+      return {
+        id: this.id,
+        anchor: `${nested.file}:${nested.line}`,
+        state: "present",
+        verdict: "GA nested _meta.ui.resourceUri"
+      };
+    }
+    return { id: this.id, anchor: "-", state: "absent", verdict: "no MCP Apps UI key (no _meta ui)" };
+  }
+};
+
+// src/detectors/d7.ts
+var KIT_PKG = "@vantageos/mcp-protocol-kit";
+var KIT_CALL_RE = /\b(buildToolsListResult|buildListResult|buildToolCallResult|handleServerDiscover)\s*\(/;
+var KIT_IMPORT_RE = /from\s+["'`]@vantageos\/mcp-protocol-kit["'`]/;
+function depListed(pkgJson) {
+  if (!pkgJson) return false;
+  for (const key of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+    const deps = pkgJson[key];
+    if (deps && typeof deps === "object" && KIT_PKG in deps) return true;
+  }
+  return false;
+}
+var d7 = {
+  id: "D7 protocol-kit",
+  run(tree) {
+    const listed = depListed(tree.packageJson?.json);
+    let importLine = null;
+    let callLine = null;
+    for (const file of tree.files) {
+      for (const line of file.lines) {
+        if (line.comment) continue;
+        if (!importLine && KIT_IMPORT_RE.test(line.raw)) importLine = { file: file.rel, line: line.n };
+        if (!callLine && KIT_CALL_RE.test(line.raw)) callLine = { file: file.rel, line: line.n };
+      }
+    }
+    const called = importLine !== null && callLine !== null;
+    if (listed && called) {
+      return {
+        id: this.id,
+        anchor: `${callLine.file}:${callLine.line}`,
+        state: "present",
+        verdict: "protocol-kit listed + builder called"
+      };
+    }
+    if (listed && !called) {
+      return {
+        id: this.id,
+        anchor: tree.packageJson ? tree.packageJson.path.split("/").slice(-2).join("/") : "-",
+        state: "non-conforming",
+        verdict: "protocol-kit listed but no builder called -> wire buildToolsListResult/handleServerDiscover"
+      };
+    }
+    return {
+      id: this.id,
+      anchor: tree.packageJson ? tree.packageJson.path.split("/").slice(-2).join("/") : "-",
+      state: "absent",
+      verdict: "hand-rolled builders, protocol-kit not a dependency -> add @vantageos/mcp-protocol-kit"
+    };
+  }
+};
+
+// src/detectors/index.ts
+var detectors = [d2, d3, d4, d5, d6, d7];
+
+// src/doctor.ts
+function pad(s, w) {
+  return s.length >= w ? s : s + " ".repeat(w - s.length);
+}
+function runDoctor(target) {
+  const tree = loadTree(target);
+  return detectors.map((d) => d.run(tree));
+}
+function renderTable(surface, results) {
+  const cols = { item: 24, anchor: 26, state: 15 };
+  const header = `${pad("item", cols.item)} | ${pad("file:line", cols.anchor)} | ${pad("state", cols.state)} | verdict`;
+  const sep = "-".repeat(header.length);
+  const rows = results.map(
+    (r) => `${pad(r.id, cols.item)} | ${pad(r.anchor, cols.anchor)} | ${pad(r.state, cols.state)} | ${r.verdict}`
+  );
+  return [`surface: ${surface}`, header, sep, ...rows].join("\n");
+}
+function main() {
+  const target = process.argv[2];
+  if (!target) {
+    console.error("usage: tsx src/doctor.ts <source-tree-path>");
+    process.exit(1);
+  }
+  const results = runDoctor(target);
+  console.log(renderTable(target, results));
+}
+if (import.meta.url === `file://${process.argv[1]}`) main();
+export {
+  renderTable,
+  runDoctor
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@vantageos/mcp-doctor",
+  "version": "0.1.0",
+  "description": "Static MCP conformance checker: audits an MCP server source tree against the MCP 2026-07-28 standard and emits a conformance-diff table (file:line | present | absent | non-conforming | verdict).",
+  "type": "module",
+  "main": "./dist/doctor.js",
+  "types": "./dist/doctor.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/doctor.d.ts",
+      "import": "./dist/doctor.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "mcp-doctor": "./dist/doctor.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elpiarthera/mcp-doctor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/elpiarthera/mcp-doctor/issues"
+  },
+  "homepage": "https://github.com/elpiarthera/mcp-doctor#readme",
+  "author": "ElPi Corp / Laurent Perello",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "conformance",
+    "audit",
+    "linter",
+    "static-analysis"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "doctor": "tsx src/doctor.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src tests",
+    "lint:fix": "biome check --write src tests",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "@types/node": "^26.1.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}