@weiseer/mcp-doctor 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @weiseer/mcp-doctor
+
+> Install-time trust gate for MCP servers. PASS / WARN / BLOCK + cited evidence.
+
+Part of [weiseer](https://github.com/weiseer). Probe **P-010**.
+
+## What it does
+
+Scans MCP server packages (or your entire `claude_desktop_config.json` / `cline_config.json`) and tells you which ones to trust before you install or connect to them.
+
+Verdict is one of:
+- **PASS** — no significant supply-chain or vulnerability signals
+- **WARN** — material concerns; review before installing
+- **BLOCK** — critical issue (known CVE, typosquat, hardcoded credentials, etc.)
+
+All scoring is **open-source and rule-based** — see [rubric.yaml](./rubric.yaml). You can argue with our methodology; we'd rather you do that than trust a black-box ML model.
+
+## Install
+
+```bash
+npm install -g @weiseer/mcp-doctor
+```
+
+Or run on-demand:
+
+```bash
+npx @weiseer/mcp-doctor @modelcontextprotocol/server-github
+```
+
+## Common uses
+
+**1. Check a single package before installing:**
+
+```bash
+npx @weiseer/mcp-doctor @some/mcp-server
+```
+
+**2. Audit your existing MCP config:**
+
+```bash
+npx @weiseer/mcp-doctor --config ~/Library/Application\ Support/Claude/claude_desktop_config.json
+```
+
+**3. CI integration (block bad MCPs in PR):**
+
+```yaml
+- uses: weiseer/mcp-doctor-action@v1
+  with:
+    packages: '@x/server-foo @y/server-bar'
+```
+
+**4. README trust badge:**
+
+```md
+![MCP Trust](https://weiseer.com/badge/@x/server-foo)
+```
+
+## What gets scored
+
+- **Supply chain hygiene** — postinstall scripts, unpinned deps, missing provenance, repo URL integrity
+- **Maintainer health** — release cadence, archive status, bus factor, GitHub last-push age
+- **Known vulnerabilities** — direct + transitive CVE via OSV.dev
+- **MCP-specific risk** — typosquat against official servers, hardcoded credentials, capability misdeclaration
+
+Full rubric: [rubric.yaml](./rubric.yaml). Open-source by design.
+
+## Why this exists
+
+The MCP ecosystem has a security crisis. MCPwn (CVE-2026-33032, CVSS 9.8) exposed 2,600+ instances. The Shai-Hulud npm worm stole MCP auth tokens from 172 packages. MCPSafe found high-severity bugs in *official* MCP servers from Atlassian, GitHub, Cloudflare, Microsoft. Bumblebee shipped from Perplexity in May 2026 specifically because supply-chain scanning was missing for MCP.
+
+We agree the problem is real and decided to ship a developer-friendly install gate that fits the existing MCP workflow rather than reinventing it.
+
+## License
+
+Apache-2.0.
+
+## Related
+
+- Open-source rubric: [rubric.yaml](./rubric.yaml)
+- 9 other weiseer MCP services: [github.com/weiseer](https://github.com/weiseer)

package/bin/mcp-doctor.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * @weiseer/mcp-doctor — install-time trust gate CLI for MCP servers.
+ * v0.1.0 — Day 3 ship.
+ *
+ * Usage:
+ *   npx @weiseer/mcp-doctor <package1> [<package2> ...]
+ *   npx @weiseer/mcp-doctor --config /path/to/claude_desktop_config.json
+ *   npx @weiseer/mcp-doctor --json
+ *
+ * Exits non-zero on any BLOCK — useful for CI integration.
+ * License: Apache-2.0. P-010.
+ */
+import { scanPackages } from "../lib/scan.js";
+import { readFileSync } from "node:fs";
+import { argv, exit, stderr } from "node:process";
+
+function parseArgs(args) {
+  const out = { packages: [], json: false, configPath: null, registry: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--json") out.json = true;
+    else if (a === "--config") { out.configPath = args[++i]; }
+    else if (a === "--registry") { out.registry = args[++i]; }
+    else if (a === "--help" || a === "-h") {
+      printHelp();
+      exit(0);
+    } else if (a.startsWith("--")) {
+      stderr.write(`unknown flag: ${a}\n`);
+      exit(2);
+    } else {
+      out.packages.push(a);
+    }
+  }
+  return out;
+}
+
+function printHelp() {
+  const txt = `mcp-doctor — install-time trust gate for MCP servers.
+
+USAGE
+  mcp-doctor <package1> [<package2> ...]
+  mcp-doctor --config <path-to-claude_desktop_config.json>
+  mcp-doctor --json
+
+Open-source rubric: https://github.com/weiseer/mcp-doctor/blob/main/rubric.yaml
+
+EXIT CODES
+  0 = all PASS or WARN
+  1 = at least one BLOCK
+  2 = invalid usage
+`;
+  process.stdout.write(txt);
+}
+
+function packagesFromConfig(configPath) {
+  const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+  const mcpServers = raw.mcpServers || {};
+  const pkgs = new Set();
+  for (const [, srv] of Object.entries(mcpServers)) {
+    // Detect npx -y <pkg> args
+    if (srv.command === "npx") {
+      const args = srv.args || [];
+      // skip -y flags, pick first non-flag arg
+      for (const a of args) {
+        if (a.startsWith("-")) continue;
+        pkgs.add(a);
+        break;
+      }
+    }
+  }
+  return [...pkgs];
+}
+
+function emoji(v) {
+  return ({ PASS: "✓", WARN: "⚠", BLOCK: "✗", ERROR: "?" })[v] || "?";
+}
+
+function renderHuman(r) {
+  const head = `${emoji(r.verdict)} ${r.verdict}: ${r.package}@${r.version || "?"}  (score ${r.score}/100)${r.self_disclosure ? " [self-disclosed]" : ""}`;
+  if (r.error) return head + `\n  ERROR: ${r.error}`;
+  const sigs = (r.triggered_signals || []).map(s => `    -${s.deduct}${s.hard_block ? " HARD" : ""} ${s.signal_id}: ${s.evidence}`);
+  const m = r.metadata || {};
+  const tail = `  m=${m.maintainer_count} dsr=${m.days_since_release} gh_dsp=${m.github_days_since_push} stars=${m.github_stars} deps=${m.dep_count} osv=${m.osv_vuln_count} lic=${m.license}`;
+  return [head, ...sigs, tail].join("\n");
+}
+
+async function main() {
+  const args = parseArgs(argv.slice(2));
+  let packages = args.packages.slice();
+
+  if (args.configPath) {
+    try {
+      packages = packages.concat(packagesFromConfig(args.configPath));
+    } catch (e) {
+      stderr.write(`config parse failed: ${e.message}\n`);
+      exit(2);
+    }
+  }
+
+  if (packages.length === 0) {
+    printHelp();
+    exit(2);
+  }
+
+  // Day 3 strategy: scanner is the Python engine. For v0.1 ship, the Node CLI
+  // either (a) executes a hosted endpoint or (b) wraps a bundled scanning core.
+  // Day 3 takes the simplest correct path: call the public scoring endpoint.
+  //
+  // For users who want fully-offline: --registry file:///path/to/bundled-db.json
+  // will land in Day 5.
+  const results = await scanPackages(packages, { registry: args.registry });
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(results, null, 2) + "\n");
+  } else {
+    for (const r of results) {
+      process.stdout.write(renderHuman(r) + "\n\n");
+    }
+    const counts = results.reduce((acc, r) => { acc[r.verdict] = (acc[r.verdict] || 0) + 1; return acc; }, {});
+    process.stdout.write(`summary: ${JSON.stringify(counts)}\n`);
+  }
+
+  if (results.some(r => r.verdict === "BLOCK")) exit(1);
+}
+
+main().catch(err => {
+  stderr.write(`mcp-doctor: fatal: ${err.message}\n`);
+  exit(2);
+});

package/lib/scan.js

@@ -0,0 +1,47 @@
+/**
+ * Scan dispatcher for mcp-doctor CLI.
+ *
+ * v0.1 (Day 3): calls the public scoring endpoint at weiseer-mcp-doctor backend.
+ * v0.2+ (Day 5): bundles trust DB + rubric for fully-offline scan.
+ *
+ * The hosted endpoint runs the same open-source rubric (rubric.yaml in this repo).
+ * The endpoint is rate-limited free / no auth required, capped at 1000 calls/day/IP.
+ */
+const ENDPOINT = process.env.MCP_DOCTOR_ENDPOINT || "https://oracle.weiseer.com/mcp-doctor/scan";
+const LOCAL_FALLBACK = process.env.MCP_DOCTOR_LOCAL_FALLBACK === "1";
+
+async function scanOnePackage(pkg) {
+  const url = new URL(ENDPOINT);
+  url.searchParams.set("pkg", pkg);
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 15000);
+    const res = await fetch(url, { signal: ctrl.signal, headers: { "User-Agent": "weiseer-mcp-doctor-cli/0.1.0" } });
+    clearTimeout(t);
+    if (!res.ok) {
+      return {
+        package: pkg, version: "", verdict: "ERROR", score: 0,
+        error: `endpoint http ${res.status}`,
+        triggered_signals: [], metadata: {},
+        scanned_at: new Date().toISOString(),
+      };
+    }
+    return await res.json();
+  } catch (e) {
+    return {
+      package: pkg, version: "", verdict: "ERROR", score: 0,
+      error: `endpoint unreachable: ${e.message}`,
+      triggered_signals: [], metadata: {},
+      scanned_at: new Date().toISOString(),
+    };
+  }
+}
+
+export async function scanPackages(packages, opts = {}) {
+  const results = [];
+  // Sequential for now; the rate-limit per IP is generous but we are polite.
+  for (const pkg of packages) {
+    results.push(await scanOnePackage(pkg));
+  }
+  return results;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@weiseer/mcp-doctor",
+  "version": "0.1.0",
+  "mcpName": "io.github.weiseer/mcp-doctor",
+  "description": "Install-time trust gate for MCP servers — PASS/WARN/BLOCK + cited evidence + GitHub Action support.",
+  "type": "module",
+  "bin": {
+    "mcp-doctor": "./bin/mcp-doctor.js"
+  },
+  "main": "./lib/index.js",
+  "files": [
+    "bin/",
+    "lib/",
+    "rubric.yaml",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/mcp-doctor.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "security",
+    "trust",
+    "supply-chain",
+    "vulnerability",
+    "audit",
+    "ai-agent",
+    "weiseer"
+  ],
+  "author": "weiseer <wei@weiseer.com>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/weiseer/mcp-doctor.git"
+  },
+  "homepage": "https://github.com/weiseer/mcp-doctor#readme",
+  "bugs": {
+    "url": "https://github.com/weiseer/mcp-doctor/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}