protocolprobe-discover 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 ProtocolProbe
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# ProtocolProbe discovery (feature #17)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lists the MCP servers configured on **this machine**, and which ones Claude Desktop has started. Zero dependencies
+(Node 18+; tests also pass on Node 18.20.8), reads config files only, **sends nothing anywhere**.
+
+```
+npx protocolprobe-discover                      # once published; from a checkout: node discover.mjs
+npx protocolprobe-discover --dir ../app --dir . # project configs in these directories too
+npx protocolprobe-discover --json               # same fields, machine-readable
+npx protocolprobe-discover --help | --version
+```
+
+In a repository checkout only (not in the published package):
+
+```
+node --test discover.test.mjs registry-match.test.mjs package.test.mjs   # tests (20)
+node build-index.mjs --registry <registry dump.ndjson> --snapshot YYYY-MM-DD   # rebuild the registry snapshot (each registry refresh)
+```
+
+## Publishing (owner's steps; nothing here has been published)
+
+`"private": true` was removed on 2026-10-20 for the first publish (owner decision). The name
+`protocolprobe-discover` was free on npm on 2026-10-14 and again on 2026-10-20 (not a reservation). Before publishing: run the tests and
+`npm pack --dry-run` (the package test checks that exactly 7 files ship: the three sources, the snapshot, README, LICENSE,
+plus package.json), rebuild the snapshot if it is over 60 days old, confirm the licence (ISC, copyright line "ProtocolProbe")
+and the name, then `npm publish --access public` from this folder with 2FA. After the first publish set `SITE_DISCOVER=true` on
+the site so `/docs/discover` goes live (it is off by default because it would describe a command that does not exist yet).
+
+## Match against the official MCP registry (offline)
+
+For every package a known runner starts (npm, PyPI, OCI image) and every remote URL, it looks the server up in
+`registry-index.json.gz`, a snapshot of the official registry (latest version of each server) built by
+`build-index.mjs`. The lookup is local: **no network call is made**. The output says `registry: listed as <name> →
+https://protocolprobe.com/mcp/servers/<name>` (that page shows what we checked and what we did not), `shared by N
+registry entries` when a key belongs to several (never guessed), or `not found in the snapshot` (the server may be
+newer, unpublished or not a registry server; this says nothing about its safety). A local script or an unrecognised
+command is not matched. The snapshot date is printed in the output; the file is regenerated on each registry refresh.
+
+Measured on the 2026-10-23 snapshot (48,551 servers): 17,144 package keys, 97.3% belong to exactly one server; 31,819
+remote host+path keys, 99.8% belong to exactly one. **Not everything people run is in it:** the reference servers
+`@modelcontextprotocol/server-filesystem`, `-server-memory` and `mcp-server-sqlite-npx` are not registry packages, so they
+show `not found`. Only latest versions count: a package whose only registry row is an old version is not listed.
+
+## What it never shows
+
+Config files hold API keys in env values, header values, command arguments, URL queries and sometimes URL paths.
+The rule is: **if a value is not known to be safe, it is not shown, only counted.**
+
+- Never shown: env and header values; a remote host that the registry does not list is shortened to its last two
+  labels (`*.supabase.co`), and a label of 12+ letters-and-digits is replaced; env variable names that are not in the
+  conventional upper-case shape (they are counted); a server name with a single word of 25+ characters; command arguments; URL userinfo, query and fragment; a URL built from
+  variables (`${…}`); every URL path segment except generic endpoint words (`mcp`, `sse`, `api`, `v1`, …, see
+  `PATH_WORDS` in lib.mjs), shown as `*`, unless the registry lists that exact URL (then the public path is shown); package
+  names that are not "plain names" (short lower-case words joined by `.` `_` `-` `~`, optional leading `@`; mixed
+  case, hex, many digits or long words fail); a command string that carries its own arguments (`"npx -y pkg --token=…"`); a package name when an
+  unknown flag comes before it (its value could be next); server and log names that look like a credential (`ghp_`,
+  `sk-`, `AKIA`, JWTs, long letter-and-digit runs, hex, mixed case with digits), replaced by
+  "(name not shown: looks like a credential)".
+- Shown: server name, client and scope, transport (one of stdio/http/streamable-http/sse/ws, else "other"), the
+  command's base name, a package name from a known runner (`npx`, `bunx`, `pnpm dlx`, `uvx`, `pipx run`,
+  `docker run`) when every flag before it is known, a remote URL's origin and plain path, counts of arguments, env
+  variables and headers, and env variable **names**. Paths under your home folder are shown as `~`. Control
+  characters in names from a config file are escaped, so a config cannot rewrite the terminal output.
+- Tested with config files full of fake secrets in every place an independent review found (2026-10-10): none appears
+  in the text or JSON output. Re-checked 2026-10-14 with 13 more planted secrets (arguments, env, headers, URL
+  userinfo/query/fragment, docker `-e`, uv index URL, `mcp-remote --header`, names): none appears, and the two paths
+  that did pass (a letters-only per-account host, a lower-case env name) are closed and have tests. 15 tests;
+  19 of 21 code mutations of the 2026-10-14 code are caught; the two not caught change no output (a guard that cannot be
+  reached because package keys always carry an `npm:`/`pypi:`/`oci:` prefix, and a URL check that a second check repeats). Run on Windows only; macOS and Linux
+  paths are asserted, not run.
+
+## Where it looks (from each vendor's documentation, read 2026-10-10)
+
+| client | files | key |
+|---|---|---|
+| Claude Desktop | macOS `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows `%APPDATA%\Claude\claude_desktop_config.json`; logs `~/Library/Logs/Claude`, `%APPDATA%\Claude\logs` (`mcp-server-NAME.log`) | `mcpServers` |
+| Claude Code | `~/.claude.json` (user scope, and `projects[path]` local scope), `<project>/.mcp.json` (also read by VS Code) | `mcpServers` |
+| Cursor | `~/.cursor/mcp.json`, `<project>/.cursor/mcp.json` | `mcpServers` |
+| VS Code | `<project>/.vscode/mcp.json`; user `mcp.json` in the profile folder (`%APPDATA%\Code\User`, `~/Library/Application Support/Code/User`, `~/.config/Code/User`, plus `profiles/<id>/`; also `Code - Insiders`); `~/.copilot/mcp-config.json` | `servers` (`mcpServers` for the Copilot file) |
+
+Sources: code.claude.com/docs/en/mcp · cursor.com/docs/context/mcp ·
+code.visualstudio.com/docs/copilot/customization/mcp-servers · code.visualstudio.com/docs/configure/profiles.
+The Claude Desktop paths come from the project's research log (real probe, 2026-10-03).
+
+## Limits (stated, not hidden)
+
+- Only these clients and locations. Not seen: other clients, enterprise-managed files (`managed-mcp.json`), Claude
+  Code plugin servers and its approve/disable lists in `.claude/settings.json` (so a `.mcp.json` server is listed
+  even if it was rejected), `CLAUDE_CONFIG_DIR` and `$COPILOT_HOME` relocations, VS Code devcontainer and remote
+  configs, VS Code's discovery of Claude Desktop servers, and servers started outside a config file. Claude Desktop
+  extensions and the Store build's storage were not checked.
+- Project configs are found only in the directories you pass (default: the current one); it does not search the disk.
+- "Started" evidence exists only for Claude Desktop, and log files persist: a server listed there was started at some
+  point, not necessarily now.
+- The VS Code default-profile location (`…/Code/User/mcp.json`) is inferred from VS Code's profile-folder docs; the
+  user-level file is documented as "in your user profile folder".
+- The secret heuristics are conservative but not perfect. What can still pass: a credential used as the whole
+  registrable domain with fewer than 12 characters; a server name a person picked that is shorter than 25 characters per word (names
+  like `Context7` or `Neo4jMemory` stay visible); a project folder name inside a `local (~project)` scope. Hosts and
+  env names were tightened on 2026-10-14 after a letters-only per-account host and a lower-case env name passed.
+- `npx mcp-remote <url>` is read as a remote: the URL that follows the package is shortened and matched by the same rules
+  as a `url` entry (never shown as written, headers ignored). Other programs' arguments are never read.
+- The registry snapshot ages. After 60 days the output warns that newer servers show as "not found"; rebuild it with
+  `build-index.mjs` on each registry refresh (docs/FUTURE-TASKS.md section 6).
+- Over-redaction (safe side, nothing leaks): upper-case path segments (`/MCP` → `/*`), mixed-case package names
+  (`Flask-MCP`), `==` version pins (`mcp-proxy==0.8.2`) and images from a registry with a port
+  (`localhost:5000/my-mcp`) are not shown as packages or path words.
+- Speed: a plain-JSON file of 44.5 MB parses in about 0.24 s; a JSON-with-comments file (VS Code) of the same size
+  would take about 12.5 s (measured). Real VS Code files are small.
+- Tested on Windows against fixture files in every layout (and macOS/Linux paths by assertion); on this machine only
+  `~/.claude.json` existed (0 servers).

package/discover.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// ProtocolProbe shadow-MCP discovery (feature #17): lists the MCP servers configured on THIS machine, and which ones
+// Claude Desktop has started (its per-server log files). Runs locally, reads config files only, sends nothing
+// anywhere, needs no install.
+//
+//   node discover.mjs                      user-level configs + the current directory's project configs
+//   node discover.mjs --dir ../a --dir b   project configs in these directories too
+//   node discover.mjs --json               machine-readable output (same fields)
+//
+// Never printed (see lib.mjs): env and header values, command arguments, URL userinfo/query/fragment, URL path
+// segments that are not plain words, anything that looks like a credential. Home paths are shown as "~".
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+import { fileURLToPath } from "node:url";
+import { claudeDesktopLogDir, describe, entriesOf, looksSecret, projectLocations, ranFromLogNames, stripJsonc, userLocations, vscodeProfilesDir } from "./lib.mjs";
+import { validIndex } from "./registry-index.mjs";
+
+/** A server or log name that looks like a credential is replaced, in both text and JSON output. */
+// a name a person picked ("Context7") stays visible; one that looks like a credential, or has a single word of 25+
+// characters (a token used as a label), is replaced
+const safeName = (n) => (looksSecret(n, { name: true }) || String(n).split(/[-_. ]/).some((w) => w.length > 24) ? "(name not shown: looks like a credential)" : String(n));
+const STALE_DAYS = 60; // the registry is refreshed monthly; two months old is worth a warning
+const INDEX_FILE =path.join(path.dirname(fileURLToPath(import.meta.url)), "registry-index.json.gz");
+
+/** The offline registry snapshot, or null (with the reason) when it is missing or not the shape this code reads. */
+export function loadIndex(file = INDEX_FILE) {
+  try {
+    const x = JSON.parse(zlib.gunzipSync(fs.readFileSync(file)).toString("utf8"));
+    if (!validIndex(x)) return { index: null, why: "registry snapshot file is not in the expected format" };
+    return { index: { ...x, hostSet: new Set(x.hosts) } };
+  } catch (e) { return { index: null, why: e.code === "ENOENT" ? "registry snapshot file not found" : "registry snapshot file could not be read" }; }
+}
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+
+export function scan({ platform = process.platform, home = os.homedir(), appData = process.env.APPDATA, dirs = [process.cwd()], index: given, now = new Date() } = {}) {
+  const loaded = given === undefined ? loadIndex() : { index: given };
+  const index = loaded.index;
+  // a registry snapshot ages: servers published after it show as "not found". Say so once it is old.
+  const ageDays = index ? Math.floor((now - new Date(`${index.snapshot}T00:00:00Z`)) / 86400000) : null;
+  const tilde = (p) => {
+    const h = path.resolve(home);
+    const same = platform === "win32" ? p.toLowerCase().startsWith(h.toLowerCase()) : p.startsWith(h);
+    return same && (p.length === h.length || /[\\/]/.test(p[h.length])) ? "~" + p.slice(h.length) : p;
+  };
+  const locations = [...userLocations({ platform, home, appData })];
+  for (const l of [...locations]) {
+    if (l.key === "servers" && l.scope === "user") {
+      const pdir = vscodeProfilesDir(l.file);
+      let subs = [];
+      try { subs = fs.readdirSync(pdir).filter((n) => isDir(path.join(pdir, n))); } catch {}
+      for (const s of subs) locations.push({ ...l, scope: `user (profile ${s})`, file: path.join(pdir, s, "mcp.json") });
+    }
+  }
+  const warnings = loaded.why ? [`${loaded.why}: servers are not matched against the registry and remote hosts are shortened`] : [];
+  if (ageDays !== null && ageDays > STALE_DAYS) warnings.push(`the registry snapshot is ${ageDays} days old (${index.snapshot}): servers published since then show as "not found"`);
+  for (const d of dirs) {
+    const abs = path.resolve(d);
+    if (!isDir(abs)) { warnings.push(`--dir ${tilde(abs)} is not a directory; skipped`); continue; }
+    locations.push(...projectLocations(abs));
+  }
+  // the same file can be reached twice (e.g. --dir ~ finds ~/.cursor/mcp.json again): read it once
+  const seen = new Set();
+  const unique = locations.filter((l) => { const k = path.resolve(l.file).toLowerCase(); if (seen.has(k)) return false; seen.add(k); return true; });
+
+  const files = [], servers = [];
+  for (const l of unique) {
+    const shown = { ...l, file: tilde(l.file) };
+    let text;
+    try { text = fs.readFileSync(l.file, "utf8"); } catch (e) { files.push({ ...shown, status: e.code === "ENOENT" || e.code === "ENOTDIR" ? "absent" : "unreadable" }); continue; }
+    let json;
+    try { json = JSON.parse(stripJsonc(text)); } catch { files.push({ ...shown, status: "not valid JSON" }); continue; }
+    const entries = entriesOf(json, l.key);
+    files.push({ ...shown, status: "read", servers: entries.length });
+    for (const e of entries) servers.push({ client: l.client, scope: e.project ? `local (${tilde(platform === "win32" ? String(e.project).replace(/\//g, "\\") : String(e.project))})` : l.scope, file: shown.file, name: safeName(e.name), ...describe(e.def, index) });
+  }
+
+  let ran = null;
+  const logDir = claudeDesktopLogDir({ platform, home, appData });
+  if (logDir) {
+    try { ran = { dir: tilde(logDir), servers: ranFromLogNames(fs.readdirSync(logDir)).map(safeName) }; } catch { ran = { dir: tilde(logDir), servers: null }; }
+  }
+  return { scannedAt: new Date().toISOString(), platform, registrySnapshot: index ? { snapshot: index.snapshot, servers: index.servers } : null, warnings, files, servers, claudeDesktopStarted: ran };
+}
+
+/**
+ * Control characters in names from a config file are shown escaped, never raw: terminal escapes, newlines, line
+ * separators, and text-direction controls (a right-to-left override can visually reverse a line).
+ */
+const CTRL = new RegExp("[\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029\\u200e\\u200f\\u202a-\\u202e\\u2066-\\u2069]", "g");
+const clean = (v) => String(v).replace(CTRL, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+
+/** One line about the registry match; "not listed" is a statement about the snapshot, not about the server. */
+function registryLine(m) {
+  if (m.state === "listed") return `registry: listed as ${m.name} → ${m.url}`;
+  if (m.state === "several") return `registry: shared by ${m.count} registry entries (not guessed which)`;
+  return "registry: not found in the snapshot (it may be newer, unpublished, or not a registry server; this says nothing about its safety)";
+}
+
+export function render(r) {
+  const lines = [];
+  lines.push(`MCP servers configured on this machine (${r.platform}, ${r.scannedAt})`);
+  lines.push("Nothing was sent anywhere. Not shown: env and header values, command arguments, URL queries, path segments that");
+  lines.push("are not plain words, and anything that looks like a credential. Remote hosts are shortened unless the registry lists them.");
+  if (r.registrySnapshot) lines.push(`Matched offline (no network) against the official MCP registry as of ${clean(r.registrySnapshot.snapshot)} (${r.registrySnapshot.servers} servers).`);
+  for (const w of r.warnings ?? []) lines.push(`warning: ${clean(w)}`);
+  lines.push("");
+  lines.push(`Config files checked: ${r.files.length} (read ${r.files.filter((f) => f.status === "read").length}, absent ${r.files.filter((f) => f.status === "absent").length}, problem ${r.files.filter((f) => !["read", "absent"].includes(f.status)).length})`);
+  for (const f of r.files.filter((f) => f.status !== "absent")) lines.push(`  ${f.status === "read" ? `${f.servers} server(s)` : f.status.toUpperCase()}  ${clean(f.client)} · ${clean(f.scope)} · ${clean(f.file)}`);
+  lines.push("");
+  lines.push(`Servers: ${r.servers.length}`);
+  for (const s of r.servers) {
+    const what = s.remote && s.package ? `${s.package.runner} ${s.package.name} → remote ${s.remote}` : s.remote ? `remote ${s.remote}` : s.package ? `${s.package.runner} ${s.package.name}` : s.command ? `command "${s.command}" (${s.args} argument${s.args === 1 ? "" : "s"})` : "command or URL not shown";
+    const extra = [s.transport, s.envVars ? `env vars: ${s.envNames.join(", ") || s.envVars}${s.envNames.length && s.envNames.length < s.envVars ? ` (+${s.envVars - s.envNames.length} not shown)` : ""}` : null, s.headers ? `${s.headers} header(s)` : null, s.disabled ? "disabled" : null].filter(Boolean).join(" · ");
+    lines.push(`  ${clean(s.name)}  —  ${clean(what)}`);
+    lines.push(`      ${clean(s.client)} · ${clean(s.scope)} · ${clean(extra)}`);
+    if (s.registry) lines.push(`      ${clean(registryLine(s.registry))}`);
+  }
+  const st = r.claudeDesktopStarted;
+  if (st) {
+    lines.push("");
+    lines.push(st.servers ? `Claude Desktop has started (a log file exists): ${st.servers.length ? st.servers.map(clean).join(", ") : "none"}` : `Claude Desktop logs: not found (${clean(st.dir)})`);
+  }
+  lines.push("");
+  lines.push("A listed server's page shows what ProtocolProbe checked and what it did not: https://protocolprobe.com/mcp/servers/");
+  return lines.join("\n");
+}
+
+export const USAGE = "usage: protocolprobe-discover [--dir <project>]... [--json] | --help | --version";
+
+/** The package's own version (package.json ships next to this file), or null if it cannot be read. */
+export function version() {
+  try { return JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "package.json"), "utf8")).version ?? null; } catch { return null; }
+}
+
+export function parseArgs(argv) {
+  const dirs = [];
+  let json = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") return { help: true };
+    if (a === "--version" || a === "-v") return { version: true };
+    if (a === "--json") json = true;
+    else if (a === "--dir") {
+      const v = argv[i + 1];
+      if (v === undefined || v.startsWith("--")) return { error: "--dir needs a directory" };
+      dirs.push(v); i++;
+    } else return { error: `unknown argument: ${a}` };
+  }
+  return { dirs, json };
+}
+
+/**
+ * True when this file is the program being run. Compared by real path: an installed command (npm's bin link) reaches this
+ * file through a symlink, and comparing the raw argv[1] with the module URL would then print nothing at all.
+ */
+export function isMain(argv1 = process.argv[1], url = import.meta.url) {
+  try { return !!argv1 && fs.realpathSync(argv1) === fs.realpathSync(fileURLToPath(url)); } catch { return false; }
+}
+
+if (isMain()) {
+  const a = parseArgs(process.argv.slice(2));
+  if (a.error) { console.error(`${a.error}\n${USAGE}`); process.exit(2); }
+  if (a.help) {
+    console.log(`${USAGE}\n\nLists the MCP servers configured on this machine (Claude Desktop, Claude Code, Cursor, VS Code) and, offline, which are in the\nofficial MCP registry. Reads config files only; sends nothing anywhere; never prints env/header values or arguments.\n  --dir <project>  also read that project's .mcp.json, .cursor/mcp.json and .vscode/mcp.json (default: the current directory)\n  --json           machine-readable output`);
+  } else if (a.version) {
+    console.log(version() ?? "unknown");
+  } else {
+    const r = scan({ dirs: a.dirs.length ? a.dirs : [process.cwd()] });
+    console.log(a.json ? JSON.stringify(r, null, 2) : render(r));
+  }
+}

package/lib.mjs

@@ -0,0 +1,280 @@
+// Feature #17, shadow-MCP discovery: which MCP servers are configured (and, for Claude Desktop, which actually ran) on
+// THIS machine. Pure functions here (unit-tested); file access is in discover.mjs.
+//
+// Privacy rules (CLAUDE.md, "Org-wide shadow-MCP discovery"): nothing is sent anywhere; secrets never leave the config
+// file. Never output env values, header values, raw arguments, URL query strings or URL userinfo: config files hold
+// API keys in all of those places. Only names, counts, the command's base name, a package name recognised from a
+// known runner pattern, and a remote URL's origin + path are reported.
+//
+// Locations and formats, each read from the vendor's own documentation on 2026-10-10 (Claude Desktop from the
+// project's research log, verified with a real probe on 2026-10-03):
+//   Claude Desktop  macOS ~/Library/Application Support/Claude/claude_desktop_config.json,
+//                   Windows %APPDATA%\Claude\claude_desktop_config.json; logs ~/Library/Logs/Claude, %APPDATA%\Claude\logs
+//                   (one mcp-server-NAME.log per server that was started)                  key "mcpServers"
+//   Claude Code     ~/.claude.json: "mcpServers" (user scope) and "projects"[path]."mcpServers" (local scope);
+//                   <project>/.mcp.json (project scope)                                     code.claude.com/docs/en/mcp
+//   Cursor          ~/.cursor/mcp.json, <project>/.cursor/mcp.json                          cursor.com/docs/context/mcp
+//   VS Code         <project>/.vscode/mcp.json (key "servers"); user mcp.json in the user profile folder
+//                   (%APPDATA%\Code\User, ~/Library/Application Support/Code/User, ~/.config/Code/User, and
+//                   profiles/<id>/ under each); ~/.copilot/mcp-config.json (key "mcpServers")
+//                                                       code.visualstudio.com/docs/copilot/customization/mcp-servers
+
+import path from "node:path";
+import { matchPackage, matchRemote, normPackage, remoteKey } from "./registry-index.mjs";
+
+/** Every user-level file to look at, for one platform and home directory (paths only; nothing is read here). */
+export function userLocations({ platform, home, appData }) {
+  const L = [];
+  const add = (client, scope, file, key) => L.push({ client, scope, file, key });
+  if (platform === "darwin") add("Claude Desktop", "user", path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json"), "mcpServers");
+  if (platform === "win32" && appData) add("Claude Desktop", "user", path.join(appData, "Claude", "claude_desktop_config.json"), "mcpServers");
+  add("Claude Code", "user + local", path.join(home, ".claude.json"), "claude.json");
+  add("Cursor", "user", path.join(home, ".cursor", "mcp.json"), "mcpServers");
+  add("VS Code / Copilot", "user", path.join(home, ".copilot", "mcp-config.json"), "mcpServers");
+  for (const product of ["Code", "Code - Insiders"]) {
+    const userDir = platform === "win32" ? (appData ? path.join(appData, product, "User") : null)
+      : platform === "darwin" ? path.join(home, "Library", "Application Support", product, "User")
+      : path.join(home, ".config", product, "User");
+    if (userDir) add(product === "Code" ? "VS Code" : "VS Code Insiders", "user", path.join(userDir, "mcp.json"), "servers");
+  }
+  return L;
+}
+
+/** VS Code profile folders hold their own mcp.json (scanned by the caller when the folder exists). */
+export function vscodeProfilesDir(userMcpFile) {
+  return path.join(path.dirname(userMcpFile), "profiles");
+}
+
+/** Claude Desktop's log folder (servers that were actually started leave mcp-server-NAME.log). */
+export function claudeDesktopLogDir({ platform, home, appData }) {
+  if (platform === "darwin") return path.join(home, "Library", "Logs", "Claude");
+  if (platform === "win32" && appData) return path.join(appData, "Claude", "logs");
+  return null;
+}
+
+/** Project-level files inside one project directory. */
+export function projectLocations(dir) {
+  return [
+    // .mcp.json is read by Claude Code and, per its docs, by VS Code too
+    { client: "Claude Code / VS Code", scope: "project", file: path.join(dir, ".mcp.json"), key: "mcpServers" },
+    { client: "Cursor", scope: "project", file: path.join(dir, ".cursor", "mcp.json"), key: "mcpServers" },
+    { client: "VS Code", scope: "project", file: path.join(dir, ".vscode", "mcp.json"), key: "servers" },
+  ];
+}
+
+/** Server entries from a parsed config file: [{ name, def, project? }]. ~/.claude.json has two places. */
+export function entriesOf(json, key) {
+  const out = [];
+  const take = (obj, project) => {
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) return;
+    for (const [name, def] of Object.entries(obj)) if (def && typeof def === "object") out.push({ name, def, ...(project ? { project } : {}) });
+  };
+  if (key === "claude.json") {
+    take(json?.mcpServers);
+    if (json?.projects && typeof json.projects === "object") for (const [p, v] of Object.entries(json.projects)) take(v?.mcpServers, p);
+  } else take(json?.[key]);
+  return out;
+}
+
+// Known runners: which flags take NO value and which take ONE value. If any other flag appears before the first
+// positional argument, we cannot know whether that positional is the package or a flag's value, so nothing is
+// reported (independent review, 2026-10-10: unlisted flags such as `uvx --refresh-package X` or
+// `docker run --hostname X` otherwise turned their value into the "package").
+const RUNNERS = {
+  npx: { sub: null, bare: ["-y", "--yes", "--no", "-q", "--quiet", "--no-install", "--ignore-existing", "--prefer-online", "--prefer-offline"], valued: ["-p", "--package", "-c", "--call"] },
+  bunx: { sub: null, bare: ["--bun"], valued: [] },
+  pnpm: { sub: "dlx", bare: ["-s", "--silent"], valued: ["--package"] },
+  uvx: { sub: null, bare: ["-q", "--quiet", "--offline", "--refresh", "--isolated", "--no-cache", "-v", "--verbose"], valued: ["--from", "--with", "--python", "-p", "--index", "--index-url", "--extra-index-url", "--refresh-package", "--with-requirements", "--with-editable", "--env-file"] },
+  pipx: { sub: "run", bare: ["--no-cache", "--verbose", "-q", "--quiet"], valued: ["--spec", "--python", "--index-url", "--pip-args"] },
+  docker: { sub: "run", bare: ["-i", "-t", "-it", "-ti", "--rm", "-d", "--init", "--privileged", "--interactive", "--tty", "--detach", "--read-only"],
+    valued: ["-e", "--env", "--env-file", "-v", "--volume", "--name", "-p", "--publish", "--network", "--net", "-w", "--workdir", "-u", "--user", "--mount",
+      "--entrypoint", "--platform", "-l", "--label", "--label-file", "--add-host", "-h", "--hostname", "--dns", "--cap-add", "--cap-drop", "-m", "--memory",
+      "--cpus", "--log-opt", "--log-driver", "--device", "--security-opt", "--tmpfs", "--ulimit", "--restart", "--pull", "--gpus", "--ipc", "--pid", "--shm-size"] },
+};
+function firstPositional(a, { bare, valued }) {
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    if (!x.startsWith("-")) return x;
+    if (x.includes("=") && valued.some((f) => x.startsWith(f + "="))) continue; // --flag=value: value stays inside, not printed
+    if (valued.includes(x)) { i++; continue; }
+    if (bare.includes(x)) continue;
+    return null; // a flag we do not know: the next argument may be its value
+  }
+  return null;
+}
+// a package or image name: letters, digits and @ / . _ - : (version tags allowed); anything else is not reported
+const PKG_RE = /^@?[a-z0-9][a-z0-9._-]*(\/[a-z0-9][a-z0-9._-]*)*(@[a-z0-9._^~<>=-]+)?(:[a-z0-9._-]+)?$/i;
+/**
+ * Strings that look like credentials are never reported, even where a name is expected. For names a person picked
+ * (server, command and env names: "Context7", "Neo4jMemory") the mixed-case rule needs 16+ characters; URL path
+ * segments and package names go through plainName(), which is stricter.
+ */
+export function looksSecret(x, { name = false } = {}) {
+  const s = String(x);
+  if (/^(ghp_|gho_|ghu_|ghs_|github_pat_|sk-|sk_|pk_|rk_|xox[abprs]-|AIza|AKIA|ASIA|eyJ)/i.test(s)) return true;
+  if (/(ghp_|gho_|github_pat_|xox[abprs]-|AIza|AKIA)[A-Za-z0-9_-]{8,}/.test(s)) return true; // a known prefix inside
+  return s.split(/[\/@:._~-]/).some((part) =>
+    (part.length >= 20 && /[a-z]/i.test(part) && /\d/.test(part)) ||                         // long letter-and-digit run
+    /^[0-9a-f]{12,}$/i.test(part) ||                                                         // hex string
+    (part.length >= (name ? 16 : 8) && /[a-z]/.test(part) && /[A-Z]/.test(part) && /\d/.test(part))); // mixed case + digit
+}
+
+/**
+ * A "plain name": short lower-case words joined by . _ - ~ (an optional leading @), as real package names and URL
+ * path words look. Random tokens fail it (mixed case, a word over 16 characters, many digits, hex).
+ */
+export function plainName(x) {
+  const s = String(x);
+  if (!/^@?[a-z0-9]+([._~-][a-z0-9]+)*$/.test(s) || looksSecret(s)) return false;
+  // words up to 16 characters; longer ones (e.g. "modelcontextprotocol") only up to 24 and letters only
+  return s.replace(/^@/, "").split(/[._~-]/).every((w) => w.length <= 16 || (w.length <= 24 && /^[a-z]+$/.test(w)))
+    && (s.match(/\d/g) ?? []).length <= 8;
+}
+
+/**
+ * The command's base name, only when the command is a plain program or a path to one. A command string that also
+ * carries arguments ("npx -y pkg --token=…", "node C:\srv\server.js --key=…") is never printed.
+ */
+export function commandName(cmd) {
+  if (typeof cmd !== "string") return null;
+  const c = cmd.trim();
+  const cut = Math.max(c.lastIndexOf("/"), c.lastIndexOf("\\"));
+  const dir = cut >= 0 ? c.slice(0, cut) : "", base = (cut >= 0 ? c.slice(cut + 1) : c).replace(/\.(exe|cmd|bat|ps1|sh)$/i, "");
+  if (/\s-|\s--/.test(dir) || /\s/.test(base)) return null; // arguments in the string
+  return /^[\w.+-]{1,64}$/.test(base) && !looksSecret(base, { name: true }) ? base : null;
+}
+
+/** The package a known runner starts, or null. Never returns an argument that does not look like a package name. */
+export function packageOf(def) {
+  const cmd = commandName(def.command)?.toLowerCase();
+  const r = cmd ? RUNNERS[cmd] : null;
+  if (!r || !Array.isArray(def.args)) return null;
+  let args = def.args.map(String);
+  if (r.sub) { if (args[0] !== r.sub) return null; args = args.slice(1); }
+  const pick = firstPositional(args, r);
+  if (!pick || !PKG_RE.test(pick) || pick.length > 214 || looksSecret(pick)) return null;
+  const nameOnly = pick.replace(/^(@?[^@]+)@.*$/, "$1").replace(/:[^/]*$/, ""); // without @version or :tag
+  return nameOnly.split("/").every((part) => plainName(part)) ? { runner: cmd, name: pick } : null;
+}
+
+const TRANSPORTS = ["stdio", "http", "streamable-http", "sse", "ws"];
+
+/**
+ * A remote URL reduced to its origin and a path in which every segment that is not a plain word is replaced by "*"
+ * (tokens are sometimes put in the path). No userinfo, query or fragment. A URL built from variables (`${…}`) is
+ * not shown at all. null when it is not a valid http(s)/ws(s) URL.
+ */
+export function safeRemote(url, hosts = null, listed = null) {
+  const raw = String(url);
+  if (raw.includes("${")) return "(URL built from variables)";
+  try {
+    const u = new URL(raw);
+    if (!["http:", "https:", "ws:", "wss:"].includes(u.protocol)) return null;
+    // a URL the registry itself lists is public: its path is shown as written. Any other path keeps only the generic
+    // endpoint words below; every other segment is "*" (a lower-case token cannot be told apart from a word)
+    const key = remoteKey(raw);
+    const isListed = !!listed && key !== null && Object.hasOwn(listed, key);
+    const segs = u.pathname.split("/").map((seg) => (seg === "" || isListed || PATH_WORDS.has(seg) ? seg : "*"));
+    return `${u.protocol}//${shownHost(u, hosts)}${segs.join("/")}`;
+  } catch { return null; }
+}
+
+// generic endpoint words that carry no account or secret; anything else in an unlisted URL's path is shown as "*"
+const PATH_WORDS = new Set(["mcp", "sse", "api", "v1", "v2", "v3", "http", "stream", "streamable", "streamable-http", "message", "messages", "rpc", "server", "servers", "tools", "public", "beta", "events", "ws", "socket", "jsonrpc"]);
+
+/**
+ * The URL `mcp-remote` is started with (npx mcp-remote https://… --header …). It is an argument, so it is never shown
+ * as written: only its shortened form and its registry match are reported, through the same rules as a "url" entry.
+ * null for any other program, or when no URL follows the package.
+ */
+export function remoteArgOf(def) {
+  const pkg = packageOf(def);
+  if (!pkg || normPackage("npm", pkg.name) !== "mcp-remote" || !Array.isArray(def.args)) return null;
+  const args = def.args.map(String), i = args.indexOf(pkg.name);
+  const url = i < 0 ? undefined : args.slice(i + 1).find((a) => /^(https?|wss?):\/\//i.test(a));
+  return url ?? null;
+}
+
+/**
+ * A host is shown whole only when it is a public host the registry itself lists, an IP address, a single-label name
+ * (localhost) or a bare two-label domain. Any other host keeps only its last two labels ("*.supabase.co"): per-account
+ * hosts are sometimes the credential (project references, tunnel ids), and a letters-only token cannot be told apart
+ * from a word. A label that itself looks like a credential is replaced by "*" even in a two-label domain.
+ */
+export function shownHost(u, hosts) {
+  const name = u.hostname.toLowerCase(), port = u.port ? `:${u.port}` : "";
+  if (u.hostname.startsWith("[") || /^\d{1,3}(\.\d{1,3}){3}$/.test(name) || !name.includes(".")) return u.host;
+  if (hosts?.has(name)) return u.host;
+  const labels = name.split(".");
+  const tail = labels.slice(-2).map((l) => (looksSecret(l) || (l.length >= 12 && /\d/.test(l) && /[a-z]/.test(l)) ? "*" : l)); // the URL parser lower-cases hosts, so the mixed-case rule cannot see a token: 12+ characters of letters and digits is hidden
+  return (labels.length > 2 ? "*." : "") + tail.join(".") + port;
+}
+
+/**
+ * An environment variable name is shown only in the conventional shape: upper case, digits and underscores, every
+ * word short (GITHUB_PERSONAL_ACCESS_TOKEN). A lower-case or long single-word name could be a credential used as a
+ * key, so it is only counted.
+ */
+export function conventionalEnvName(k) {
+  const s = String(k);
+  return /^[A-Z][A-Z0-9_]{0,63}$/.test(s) && !looksSecret(s, { name: true }) && s.split("_").every((w) => w.length <= 14);
+}
+
+/** One reportable server: names, counts and recognised identifiers only. */
+export function describe(def, index = null) {
+  const url = def.url ?? def.serverUrl;
+  const declared = typeof def.type === "string" ? def.type.toLowerCase() : null;
+  const isWs = typeof url === "string" && /^wss?:/i.test(url);
+  const transport = declared ? (TRANSPORTS.includes(declared) ? declared : "other") : url ? (isWs ? "ws" : "http") : def.command ? "stdio" : "unknown";
+  const plainObj = (o) => o && typeof o === "object" && !Array.isArray(o);
+  const viaRemote = url ? null : remoteArgOf(def);              // `npx mcp-remote <url>`: the package AND the remote it points at
+  const target = url ?? viaRemote;
+  return {
+    transport,
+    command: url ? null : commandName(def.command),
+    package: url ? null : packageOf(def),
+    remote: target ? safeRemote(target, index ? index.hostSet : null, index ? index.remotes : null) : null,
+    // an offline lookup against the registry snapshot (public data only: it matches, it never prints the config's value)
+    registry: target ? matchRemote(target, index) : matchPackage(packageOf(def), index),
+    args: Array.isArray(def.args) ? def.args.length : typeof def.args === "string" ? 1 : 0,
+    envVars: plainObj(def.env) ? Object.keys(def.env).length : 0,
+    envNames: plainObj(def.env) ? Object.keys(def.env).filter(conventionalEnvName) : [],
+    headers: plainObj(def.headers) ? Object.keys(def.headers).length : 0,
+    disabled: def.disabled === true,
+  };
+}
+
+/** Server names Claude Desktop started at some point: a log file mcp-server-NAME.log exists (logs persist). */
+export function ranFromLogNames(names) {
+  return [...new Set(names.map((n) => /^mcp-server-(.+)\.log$/.exec(n)?.[1]).filter(Boolean))].sort();
+}
+
+/** JSON with comments and trailing commas (VS Code writes JSONC) → plain JSON text. Strings are left untouched. */
+export function stripJsonc(text) {
+  text = String(text).replace(/^/, "");
+  try { JSON.parse(text); return text; } catch {} // plain JSON: no character-by-character pass (large ~/.claude.json)
+  let out = "", i = 0, inStr = false;
+  while (i < text.length) {
+    const c = text[i], n = text[i + 1];
+    if (inStr) {
+      out += c;
+      if (c === "\\") { out += n ?? ""; i += 2; continue; }
+      if (c === '"') inStr = false;
+      i++; continue;
+    }
+    if (c === '"') { inStr = true; out += c; i++; continue; }
+    if (c === "/" && n === "/") { while (i < text.length && text[i] !== "\n") i++; continue; }
+    if (c === "/" && n === "*") { i += 2; while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++; i += 2; continue; }
+    out += c; i++;
+  }
+  // trailing commas before } or ] (outside strings: strings were copied verbatim, so re-scan with the same state machine)
+  let res = "", s = false;
+  for (let j = 0; j < out.length; j++) {
+    const c = out[j];
+    if (s) { res += c; if (c === "\\") { res += out[++j] ?? ""; } else if (c === '"') s = false; continue; }
+    if (c === '"') { s = true; res += c; continue; }
+    if (c === ",") { let k = j + 1; while (k < out.length && /\s/.test(out[k])) k++; if (out[k] === "}" || out[k] === "]") continue; }
+    res += c;
+  }
+  return res.replace(/^/, "");
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "protocolprobe-discover",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Lists the MCP servers configured on this machine and, offline, which are in the official MCP registry. Reads config files only; sends nothing anywhere; never prints secrets.",
+  "type": "module",
+  "license": "ISC",
+  "author": "ProtocolProbe <hello@protocolprobe.com>",
+  "homepage": "https://protocolprobe.com/docs/discover",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "security",
+    "inventory",
+    "shadow-it"
+  ],
+  "bin": {
+    "protocolprobe-discover": "discover.mjs"
+  },
+  "main": "discover.mjs",
+  "files": [
+    "discover.mjs",
+    "lib.mjs",
+    "registry-index.mjs",
+    "registry-index.json.gz",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test discover.test.mjs registry-match.test.mjs package.test.mjs"
+  }
+}

package/registry-index.mjs

@@ -0,0 +1,87 @@
+// Offline match of what is configured on a machine against the official MCP registry (feature #17).
+// The index is a snapshot built from the registry data we already hold (build-index.mjs); matching never touches the
+// network, so using it cannot send anything anywhere. Pure functions here (unit-tested); the file is read in discover.mjs.
+//
+// What is matched: a package a known runner starts (npm / PyPI / OCI image) and a remote URL's host + path. A key that
+// belongs to exactly one registry server maps to its name; a key shared by several is stored as their count and shown
+// as "several", never guessed.
+
+export const INDEX_FORMAT = 1;
+// registry server names look like "io.github.owner/name"; anything else is not stored or shown
+const SERVER_NAME_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+/** The runner → package ecosystem a recognised package belongs to. */
+export const ECOSYSTEM = { npx: "npm", bunx: "npm", pnpm: "npm", uvx: "pypi", pipx: "pypi", docker: "oci" };
+
+/** Package name without version or tag, in the form the registry spells it. null when there is nothing to match. */
+export function normPackage(ecosystem, name) {
+  let s = String(name).trim();
+  if (!s) return null;
+  if (ecosystem === "npm") return s.replace(/^(@?[^@]+)@.*$/, "$1").toLowerCase();
+  if (ecosystem === "pypi") return s.replace(/@.*$/, "").toLowerCase().replace(/[-_.]+/g, "-");
+  if (ecosystem === "oci") {
+    s = s.replace(/@sha256:[0-9a-f]+$/i, "").replace(/:[^/]*$/, "").toLowerCase();
+    return s.replace(/^(index\.)?docker\.io\//, "").replace(/^library\//, "");
+  }
+  return null;
+}
+
+/** host + path of a remote URL, lower-case host, no query or fragment, no trailing slash. null if not a valid URL. */
+export function remoteKey(url) {
+  try {
+    const u = new URL(String(url));
+    if (!["http:", "https:", "ws:", "wss:"].includes(u.protocol)) return null;
+    return u.host.toLowerCase() + u.pathname.replace(/\/+$/, "");
+  } catch { return null; }
+}
+
+/** Build the index from registry rows ({server, _meta}); only the latest version of each server counts. */
+export function buildIndex(rows, snapshot) {
+  const packages = new Map(), remotes = new Map(), hosts = new Set();
+  let servers = 0;
+  const add = (map, key, name) => { if (!key) return; (map.get(key) ?? map.set(key, new Set()).get(key)).add(name); };
+  for (const r of rows) {
+    const s = r?.server;
+    if (!s || typeof s.name !== "string" || !SERVER_NAME_RE.test(s.name)) continue;
+    if (r._meta?.["io.modelcontextprotocol.registry/official"]?.isLatest === false) continue;
+    servers++;
+    for (const p of s.packages ?? []) {
+      const eco = p.registryType;
+      if (!["npm", "pypi", "oci"].includes(eco) || typeof p.identifier !== "string") continue;
+      const n = normPackage(eco, p.identifier);
+      if (n) add(packages, `${eco}:${n}`, s.name);
+    }
+    for (const x of s.remotes ?? []) {
+      const k = remoteKey(x?.url);
+      if (!k) continue;
+      add(remotes, k, s.name);
+      hosts.add(k.split("/")[0].replace(/:\d+$/, ""));
+    }
+  }
+  const flat = (m) => Object.fromEntries([...m].sort(([a], [b]) => (a < b ? -1 : 1)).map(([k, v]) => [k, v.size === 1 ? [...v][0] : v.size]));
+  return { format: INDEX_FORMAT, snapshot, source: "official MCP registry, latest version of each server", servers, packages: flat(packages), remotes: flat(remotes), hosts: [...hosts].sort() };
+}
+
+/** True for an index object of the shape this code reads (a corrupt or foreign file must not be trusted). */
+export function validIndex(x) {
+  const plain = (o) => o && typeof o === "object" && !Array.isArray(o);
+  return plain(x) && x.format === INDEX_FORMAT && typeof x.snapshot === "string" && Number.isInteger(x.servers) && plain(x.packages) && plain(x.remotes) && Array.isArray(x.hosts);
+}
+
+const result = (v) => (typeof v === "string" ? { state: "listed", name: v, url: `https://protocolprobe.com/mcp/servers/${v}` } : { state: "several", count: v });
+
+/** Registry match for a recognised package ({runner, name}) or a remote URL; null when there is nothing to match. */
+export function matchPackage(pkg, index) {
+  if (!index || !pkg) return null;
+  const eco = ECOSYSTEM[pkg.runner], n = eco ? normPackage(eco, pkg.name) : null;
+  if (!n) return null;
+  const v = Object.hasOwn(index.packages, `${eco}:${n}`) ? index.packages[`${eco}:${n}`] : undefined;
+  return v === undefined ? { state: "not-listed" } : result(v);
+}
+export function matchRemote(url, index) {
+  if (!index) return null;
+  const k = remoteKey(url);
+  if (!k) return null;
+  const v = Object.hasOwn(index.remotes, k) ? index.remotes[k] : undefined;
+  return v === undefined ? { state: "not-listed" } : result(v);
+}