mcp-wtf 0.1.0 → 0.2.0

package/dist/discover.js

@@ -1,10 +1,19 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+/** VS Code's per-user directory -- the root the extensions hang their state off. */
+function vscodeUserDir(platform, home) {
+    if (platform === 'win32')
+        return join(process.env['APPDATA'] ?? join(home, 'AppData', 'Roaming'), 'Code', 'User');
+    if (platform === 'darwin')
+        return join(home, 'Library', 'Application Support', 'Code', 'User');
+    return join(home, '.config', 'Code', 'User');
+}
 /**
- * Every place the well-known hosts keep their MCP configuration. Two shapes
+ * Every place the well-known hosts keep their MCP configuration. Three shapes
  * exist in the wild: `mcpServers` (Claude Desktop, Claude Code, Cursor,
- * Windsurf) and `servers` (VS Code).
+ * Windsurf, Gemini CLI, Cline, Roo Code), `servers` (VS Code) and
+ * `context_servers` (Zed).
  */
 export function knownConfigPaths(platform = process.platform, home = homedir(), cwd = process.cwd()) {
     const paths = [];
@@ -13,47 +22,144 @@ export function knownConfigPaths(platform = process.platform, home = homedir(),
         const appdata = process.env['APPDATA'] ?? join(home, 'AppData', 'Roaming');
         push(join(appdata, 'Claude', 'claude_desktop_config.json'), 'Claude Desktop');
         push(join(appdata, 'Code', 'User', 'mcp.json'), 'VS Code');
+        push(join(appdata, 'Zed', 'settings.json'), 'Zed');
     }
     else if (platform === 'darwin') {
         push(join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'), 'Claude Desktop');
         push(join(home, 'Library', 'Application Support', 'Code', 'User', 'mcp.json'), 'VS Code');
+        push(join(home, '.config', 'zed', 'settings.json'), 'Zed');
     }
     else {
         push(join(home, '.config', 'Claude', 'claude_desktop_config.json'), 'Claude Desktop');
         push(join(home, '.config', 'Code', 'User', 'mcp.json'), 'VS Code');
+        push(join(home, '.config', 'zed', 'settings.json'), 'Zed');
     }
+    // The VS Code extensions keep their servers in globalStorage, not in the
+    // editor's own config -- which is why "I configured it in Cline and nothing
+    // else can see it" is not a bug.
+    const vscode = vscodeUserDir(platform, home);
+    push(join(vscode, 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json'), 'Cline');
+    push(join(vscode, 'globalStorage', 'rooveterinaryinc.roo-cline', 'settings', 'mcp_settings.json'), 'Roo Code');
     push(join(home, '.claude.json'), 'Claude Code');
     push(join(cwd, '.mcp.json'), 'Claude Code (project)');
     push(join(home, '.cursor', 'mcp.json'), 'Cursor');
     push(join(cwd, '.cursor', 'mcp.json'), 'Cursor (project)');
     push(join(home, '.codeium', 'windsurf', 'mcp_config.json'), 'Windsurf');
+    push(join(home, '.gemini', 'settings.json'), 'Gemini CLI');
+    push(join(cwd, '.gemini', 'settings.json'), 'Gemini CLI (project)');
     push(join(cwd, '.vscode', 'mcp.json'), 'VS Code (workspace)');
     return paths;
 }
+/**
+ * JSON.parse, but tolerant of what these files actually contain. VS Code's
+ * mcp.json and Zed's settings.json are JSONC -- Zed ships a default settings
+ * file that is nothing but comments -- and calling those "not valid JSON"
+ * would be a confident, wrong diagnosis. Comments and trailing commas are
+ * stripped; anything still broken is genuinely broken.
+ */
+export function parseJsonc(text) {
+    const out = [];
+    let inString = false;
+    let escaped = false;
+    // Only ever drop a comma that a closing bracket makes illegal, and only
+    // outside a string -- a blind regex would corrupt values like "a, }b".
+    const dropTrailingComma = () => {
+        let i = out.length - 1;
+        while (i >= 0 && /\s/.test(out[i]))
+            i--;
+        if (i >= 0 && out[i] === ',')
+            out.splice(i, 1);
+    };
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            out.push(ch);
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out.push(ch);
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i++;
+            out.push('\n');
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '*') {
+            const end = text.indexOf('*/', i + 2);
+            i = end === -1 ? text.length : end + 1;
+            continue;
+        }
+        if (ch === '}' || ch === ']')
+            dropTrailingComma();
+        out.push(ch);
+    }
+    return JSON.parse(out.join(''));
+}
+/**
+ * Zed nests the launch under `command`: {"path": "npx", "args": [], "env": {}}.
+ * Everyone else puts a bare string there. Both mean the same thing.
+ */
+function flatten(raw) {
+    if (raw.command && typeof raw.command === 'object' && !Array.isArray(raw.command)) {
+        const nested = raw.command;
+        return {
+            command: typeof nested.path === 'string' ? nested.path : null,
+            args: nested.args ?? raw.args,
+            env: nested.env ?? raw.env,
+        };
+    }
+    return { command: typeof raw.command === 'string' ? raw.command : null, args: raw.args, env: raw.env };
+}
 function toSpec(name, raw, source) {
-    if (raw.disabled === true)
+    if (raw.disabled === true || raw.enabled === false)
         return null;
     const sources = [source];
-    const url = typeof raw.url === 'string' ? raw.url : typeof raw.serverUrl === 'string' ? raw.serverUrl : null;
+    const url = typeof raw.url === 'string'
+        ? raw.url
+        : typeof raw.serverUrl === 'string'
+            ? raw.serverUrl
+            : typeof raw.httpUrl === 'string' // Gemini CLI's name for streamable HTTP
+                ? raw.httpUrl
+                : null;
     if (url) {
         return { name, kind: 'http', url, headers: raw.headers ?? {}, sources };
     }
-    if (typeof raw.command !== 'string' || !raw.command)
+    const flat = flatten(raw);
+    if (!flat.command)
         return null;
-    const args = Array.isArray(raw.args) ? raw.args.filter((a) => typeof a === 'string') : [];
+    const args = Array.isArray(flat.args) ? flat.args.filter((a) => typeof a === 'string') : [];
+    // Hand-edited configs contain numbers and booleans where the launcher only
+    // ever passes strings; keeping them would make later checks throw on a file
+    // that is merely odd.
+    const env = {};
+    if (flat.env && typeof flat.env === 'object' && !Array.isArray(flat.env)) {
+        for (const [key, value] of Object.entries(flat.env)) {
+            if (typeof value === 'string')
+                env[key] = value;
+        }
+    }
     const spec = {
         name,
         kind: 'stdio',
-        command: raw.command,
+        command: flat.command,
         args,
-        env: raw.env ?? {},
+        env,
         cwd: typeof raw.cwd === 'string' ? raw.cwd : undefined,
         sources,
     };
     // VS Code configs can reference interactive inputs (${input:apiKey}); those
     // servers cannot be launched non-interactively, but they should still show
     // up in the report rather than silently vanish.
-    const joined = [raw.command, ...args, JSON.stringify(spec.env)].join(' ');
+    const joined = [flat.command, ...args, JSON.stringify(spec.env)].join(' ');
     if (joined.includes('${input:')) {
         spec.unlaunchable = 'uses ${input:...} placeholders that need interactive values';
     }
@@ -63,7 +169,7 @@ function toSpec(name, raw, source) {
 export function readConfigFile(path, host) {
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(path, 'utf8'));
+        parsed = parseJsonc(readFileSync(path, 'utf8'));
     }
     catch {
         return [];
@@ -81,6 +187,7 @@ export function readConfigFile(path, host) {
     };
     collect(parsed['mcpServers']);
     collect(parsed['servers']);
+    collect(parsed['context_servers']); // Zed
     // Claude Code also nests per-project servers under `projects`.
     const projects = parsed['projects'];
     if (projects && typeof projects === 'object' && !Array.isArray(projects)) {
@@ -108,7 +215,7 @@ export function discover(explicitConfig) {
             continue;
         configsSearched.push(path);
         try {
-            JSON.parse(readFileSync(path, 'utf8'));
+            parseJsonc(readFileSync(path, 'utf8'));
         }
         catch (e) {
             configErrors.push({ path, error: e.message });
@@ -121,8 +228,9 @@ export function discover(explicitConfig) {
             // token, one with a placeholder) is a different server, and merging
             // them would silently drop one from the report.
             const envKey = JSON.stringify(Object.entries(spec.env ?? {}).sort());
+            const headerKey = JSON.stringify(Object.entries(spec.headers ?? {}).sort());
             const identity = spec.kind === 'http'
-                ? `http|${spec.url}`
+                ? `http|${spec.url}|${headerKey}`
                 : `stdio|${spec.command}|${(spec.args ?? []).join(' ')}|${envKey}|${spec.cwd ?? ''}`;
             const existing = byIdentity.get(identity);
             if (existing)

package/dist/index.d.ts

@@ -1,5 +1,10 @@
-export { discover, readConfigFile, knownConfigPaths } from './discover.js';
-export { diagnoseServer, diagnoseAll, staticChecks, resolveCommand } from './diagnose.js';
+export { discover, readConfigFile, knownConfigPaths, parseJsonc } from './discover.js';
+export { diagnoseServer, diagnoseAll, staticChecks, resolveCommand, classifyStderr } from './diagnose.js';
+export { probeRemote, classifyHttpProbe, classifyNetworkError, oauthMetadataUrl, readRpcBody } from './remote.js';
+export type { HttpProbe, RemoteResult } from './remote.js';
+export { diagnoseLogs, analyzeLogFile, analyzeLogText, classifyLogLine, discoverLogFiles, knownLogDirs, findLogFiles, serverNameFromLogPath, tail, } from './logs.js';
+export { redactSecrets, quoteLine, redactSpecSecrets } from './redact.js';
 export { renderTerminal } from './report/terminal.js';
 export { McpClient, StdioTransport, HttpTransport } from './client/index.js';
+export { VERSION } from './version.js';
 export type { Diagnosis, Finding, ServerSpec, Verdict, WtfOptions, WtfReport } from './types.js';

package/dist/index.js

@@ -1,4 +1,8 @@
-export { discover, readConfigFile, knownConfigPaths } from './discover.js';
-export { diagnoseServer, diagnoseAll, staticChecks, resolveCommand } from './diagnose.js';
+export { discover, readConfigFile, knownConfigPaths, parseJsonc } from './discover.js';
+export { diagnoseServer, diagnoseAll, staticChecks, resolveCommand, classifyStderr } from './diagnose.js';
+export { probeRemote, classifyHttpProbe, classifyNetworkError, oauthMetadataUrl, readRpcBody } from './remote.js';
+export { diagnoseLogs, analyzeLogFile, analyzeLogText, classifyLogLine, discoverLogFiles, knownLogDirs, findLogFiles, serverNameFromLogPath, tail, } from './logs.js';
+export { redactSecrets, quoteLine, redactSpecSecrets } from './redact.js';
 export { renderTerminal } from './report/terminal.js';
 export { McpClient, StdioTransport, HttpTransport } from './client/index.js';
+export { VERSION } from './version.js';

package/dist/logs.d.ts

@@ -0,0 +1,63 @@
+import type { Diagnosis, Finding } from './types.js';
+/**
+ * Log-file mode.
+ *
+ * Relaunching a server answers "why won't it connect" for the server that is
+ * broken now. It cannot answer "why did it drop out at 4pm yesterday", and it
+ * cannot help at all when the failure only happens inside the host -- a
+ * different PATH, a different working directory, a token the GUI has and the
+ * terminal does not. The host wrote all of that down and then never showed it
+ * to anyone. This reads those files and runs the same classifier over them.
+ */
+/** How much of each file is recent enough to be worth reading. */
+export declare const TAIL_LINES = 200;
+/** Where the hosts keep MCP logs, per OS. */
+export declare function knownLogDirs(platform?: NodeJS.Platform, home?: string): Array<{
+    dir: string;
+    host: string;
+}>;
+/**
+ * `mcp-server-github.log` -> `github`; the shared `mcp.log` has no one server.
+ * Rotated files (`mcp-server-github1.log`, `mcp.log.2`) belong to the same
+ * server as the file they were rotated out of.
+ */
+export declare function serverNameFromLogPath(path: string): string;
+/** Every MCP log in a directory, newest first. Missing directories are silent. */
+export declare function findLogFiles(dir: string): string[];
+export declare function discoverLogFiles(platform?: NodeJS.Platform, home?: string): Array<{
+    path: string;
+    host: string;
+}>;
+export declare function tail(text: string, lines?: number): string[];
+export declare function readTail(path: string, maxBytes?: number): string;
+/**
+ * Classify one line. Log-specific signatures first, then the same stderr
+ * signatures the live checks use -- a server's stderr is copied into these
+ * files verbatim, so everything mcp-wtf already knows how to read applies.
+ */
+export declare function classifyLogLine(line: string): Finding | null;
+/**
+ * Which server a line is about. Hosts bracket the server name into every line
+ * they write -- `[github] [info] ...` in a per-server file, `[info] [github]
+ * ...` in the shared one -- which is what makes the shared mcp.log usable.
+ */
+export declare function serverTagOf(line: string): string | null;
+/** Findings for one log file's recent tail, grouped by the server they name. */
+export declare function scanLogText(text: string, lines?: number, max?: number): Map<string | null, Finding[]>;
+/** The flat form: every finding in a file, in the order they were logged. */
+export declare function analyzeLogText(text: string, lines?: number, max?: number): Finding[];
+/**
+ * One diagnosis per server named in the file. Usually that is one server --
+ * but the shared mcp.log carries every server interleaved, and attributing its
+ * lines is the difference between a useful report and a pile of log excerpts.
+ */
+export declare function analyzeLogFile(path: string, host: string, lines?: number): Diagnosis[];
+/**
+ * Diagnose a set of log files: explicit paths, or every one we can find. One
+ * server can own several files (rotation) and appear in the shared log too, so
+ * the results are merged back into one entry per server.
+ */
+export declare function diagnoseLogs(explicit?: string[], lines?: number): {
+    diagnoses: Diagnosis[];
+    scanned: string[];
+};

package/dist/logs.js

@@ -0,0 +1,315 @@
+import { closeSync, existsSync, fstatSync, openSync, readSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, win32 } from 'node:path';
+import { classifyStderr } from './diagnose.js';
+import { quoteLine } from './redact.js';
+/**
+ * Log-file mode.
+ *
+ * Relaunching a server answers "why won't it connect" for the server that is
+ * broken now. It cannot answer "why did it drop out at 4pm yesterday", and it
+ * cannot help at all when the failure only happens inside the host -- a
+ * different PATH, a different working directory, a token the GUI has and the
+ * terminal does not. The host wrote all of that down and then never showed it
+ * to anyone. This reads those files and runs the same classifier over them.
+ */
+/** How much of each file is recent enough to be worth reading. */
+export const TAIL_LINES = 200;
+/** Where the hosts keep MCP logs, per OS. */
+export function knownLogDirs(platform = process.platform, home = homedir()) {
+    if (platform === 'win32') {
+        const appdata = process.env['APPDATA'] ?? join(home, 'AppData', 'Roaming');
+        return [{ dir: join(appdata, 'Claude', 'logs'), host: 'Claude Desktop log' }];
+    }
+    if (platform === 'darwin') {
+        return [{ dir: join(home, 'Library', 'Logs', 'Claude'), host: 'Claude Desktop log' }];
+    }
+    return [{ dir: join(home, '.config', 'Claude', 'logs'), host: 'Claude Desktop log' }];
+}
+/**
+ * `mcp-server-github.log` -> `github`; the shared `mcp.log` has no one server.
+ * Rotated files (`mcp-server-github1.log`, `mcp.log.2`) belong to the same
+ * server as the file they were rotated out of.
+ */
+export function serverNameFromLogPath(path) {
+    // win32.basename splits on both separators, so a Windows path pasted into a
+    // report parses the same on every OS; posix basename would keep `C:\...`.
+    const file = win32.basename(path);
+    const named = file.match(/^mcp-server-(.+?)\d*\.log(?:\.\d+)?$/i);
+    if (named?.[1])
+        return named[1];
+    return /^mcp\d*\.log/i.test(file) ? '(host log)' : file.replace(/\.log(\.\d+)?$/i, '');
+}
+/** Every MCP log in a directory, newest first. Missing directories are silent. */
+export function findLogFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((f) => /^mcp(-server-.+?)?\d*\.log(\.\d+)?$/i.test(f))
+        .map((f) => join(dir, f))
+        .filter((p) => {
+        try {
+            return statSync(p).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+}
+export function discoverLogFiles(platform = process.platform, home = homedir()) {
+    const out = [];
+    for (const { dir, host } of knownLogDirs(platform, home)) {
+        if (!existsSync(dir))
+            continue;
+        for (const path of findLogFiles(dir))
+            out.push({ path, host });
+    }
+    return out;
+}
+export function tail(text, lines = TAIL_LINES) {
+    const all = text.split(/\r?\n/).filter((l) => l.trim());
+    return all.slice(-lines);
+}
+/**
+ * Enough of the end of a file to hold TAIL_LINES lines. These files reach tens
+ * of megabytes -- a host that has been running for months writes every
+ * JSON-RPC message it sees into them -- and reading all of that to look at the
+ * last two hundred lines would make a tool that promises ten seconds slow.
+ */
+const TAIL_BYTES = 256 * 1024;
+export function readTail(path, maxBytes = TAIL_BYTES) {
+    const fd = openSync(path, 'r');
+    try {
+        const size = fstatSync(fd).size;
+        const start = Math.max(0, size - maxBytes);
+        const buffer = Buffer.allocUnsafe(size - start);
+        if (buffer.length > 0)
+            readSync(fd, buffer, 0, buffer.length, start);
+        const text = buffer.toString('utf8');
+        // A byte offset lands mid-line, and mid-character; that first fragment is
+        // not a line and must not be classified as one.
+        return start > 0 ? text.slice(text.indexOf('\n') + 1) : text;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+// ---------------------------------------------------------------------------
+// Signatures that only ever appear in a host's log, never in a server's own
+// stderr. They run first, because the host's phrasing for a failure is not the
+// server's -- "Unexpected token ... is not valid JSON" in a host log is the
+// host choking on polluted stdout, not the server throwing a SyntaxError.
+// ---------------------------------------------------------------------------
+const LOG_SIGNATURES = [
+    [
+        /docker: error during connect|Cannot connect to the Docker daemon|Is the docker daemon running/i,
+        () => ({
+            code: 'docker.not_running',
+            severity: 'fatal',
+            message: 'The server is launched through Docker, and the Docker daemon was not running.',
+            fix: 'Start Docker Desktop before the host, or the server dies on every launch. A host that starts with the machine will always lose this race -- consider a non-Docker build of the server.',
+        }),
+    ],
+    [
+        /spawn (\S+) ENOENT/i,
+        (m) => ({
+            code: 'cmd.not_found',
+            severity: 'fatal',
+            message: `The host could not start "${m[1]}" -- it is not on the PATH the host runs with.`,
+            fix: 'Classic GUI-versus-terminal PATH split: it works in your shell and does not exist as far as the host is concerned. Put the absolute path to the binary in the config (`which npx` / `where npx`).',
+        }),
+    ],
+    [
+        /(?:Unexpected token .{0,40}is not valid JSON|Unexpected non-whitespace character after JSON|Expected property name or '\}' in JSON|Unexpected end of JSON input)/i,
+        () => ({
+            code: 'stdio.pollution',
+            severity: 'fatal',
+            message: 'The host failed to parse what the server sent on stdout -- the server is printing non-JSON onto the protocol channel.',
+            fix: 'Something in the server logs to stdout. On stdio transport stdout IS the protocol, so those bytes corrupt the stream and the host disconnects. Logs belong on stderr; look for a LOG_LEVEL or QUIET env var if it is not your server.',
+        }),
+    ],
+    [
+        /Server (?:process )?exited with code (\d+)/i,
+        (m) => ({
+            code: 'crash.on_start',
+            severity: 'fatal',
+            message: `The host recorded the server exiting with code ${m[1]} instead of staying up.`,
+            fix: 'Run the exact command from the config in a terminal and watch what it prints. Whatever kills it there is what killed it here.',
+        }),
+    ],
+    [
+        /MCP error -32000|transport closed unexpectedly|process exiting early/i,
+        () => ({
+            code: 'transport.closed_unexpectedly',
+            severity: 'fatal',
+            message: 'The server process went away without shutting down -- the host logged the transport closing unexpectedly.',
+            fix: 'Something killed it: a crash, an out-of-memory kill, or stdout pollution that corrupted the stream. The lines just above this one in the same file are where the reason is, if the server printed one at all.',
+        }),
+    ],
+    [
+        /Server disconnected|Server transport closed|Client transport closed/i,
+        () => ({
+            code: 'transport.closed',
+            severity: 'warn',
+            message: 'The host recorded this server disconnecting.',
+            fix: 'On its own this proves nothing: the same line is written every time you quit the app. It only matters when it lands seconds after startup -- check the timestamp against when you last used the host.',
+        }),
+    ],
+    [
+        /MCP error -32001|Request timed out|initialization timed out|Timed out waiting for/i,
+        () => ({
+            code: 'handshake.timeout',
+            severity: 'fatal',
+            message: 'The host gave up waiting for the server to answer.',
+            fix: 'The process starts but never completes the handshake. Usual causes: it is an HTTP server being launched as a stdio one, the entrypoint is the wrong file, or a cold `npx` download outruns the host\'s startup timeout.',
+        }),
+    ],
+];
+/**
+ * Hosts mirror every JSON-RPC message into the log. Those lines carry tool
+ * arguments and tool results -- arbitrary text that will happily contain the
+ * word "unauthorized" or someone's `Cannot find module` stack trace. Reading
+ * them as evidence is how a diagnostic tool starts inventing failures.
+ */
+const MIRRORED_TRAFFIC = /Message from (?:client|server): *[{[]/i;
+/**
+ * Classify one line. Log-specific signatures first, then the same stderr
+ * signatures the live checks use -- a server's stderr is copied into these
+ * files verbatim, so everything mcp-wtf already knows how to read applies.
+ */
+export function classifyLogLine(line) {
+    if (MIRRORED_TRAFFIC.test(line))
+        return null;
+    for (const [pattern, build] of LOG_SIGNATURES) {
+        const m = line.match(pattern);
+        if (m)
+            return build(m);
+    }
+    return classifyStderr([line], 'your MCP config file', '');
+}
+/**
+ * Symptoms rather than causes. Every failure ends with the transport closing,
+ * so reporting that next to the reason it closed is noise -- and reporting it
+ * alone is close to useless, which is why it is only a warning.
+ */
+const SYMPTOM_ONLY = new Set(['transport.closed', 'transport.closed_unexpectedly']);
+const LOG_LEVEL = /^(info|error|warn|warning|debug|trace)$/i;
+/**
+ * Which server a line is about. Hosts bracket the server name into every line
+ * they write -- `[github] [info] ...` in a per-server file, `[info] [github]
+ * ...` in the shared one -- which is what makes the shared mcp.log usable.
+ */
+export function serverTagOf(line) {
+    for (const m of line.matchAll(/\[([^\]]{1,64})\]/g)) {
+        const tag = m[1].trim();
+        if (tag && !LOG_LEVEL.test(tag))
+            return tag;
+    }
+    return null;
+}
+/** Findings for one log file's recent tail, grouped by the server they name. */
+export function scanLogText(text, lines = TAIL_LINES, max = 6) {
+    const byServer = new Map();
+    for (const line of tail(text, lines)) {
+        const finding = classifyLogLine(line);
+        if (!finding)
+            continue;
+        const server = serverTagOf(line);
+        let seen = byServer.get(server);
+        if (!seen)
+            byServer.set(server, (seen = new Map()));
+        // The same failure is logged on every reconnect attempt; one is enough,
+        // and the first occurrence is the one with the useful context around it.
+        const key = `${finding.code}|${finding.message}`;
+        if (seen.has(key) || seen.size >= max)
+            continue;
+        seen.set(key, { ...finding, detail: `> ${quoteLine(line)}` });
+    }
+    const out = new Map();
+    for (const [server, seen] of byServer)
+        out.set(server, preferCauses([...seen.values()]));
+    return out;
+}
+/** Drop "and then it disconnected" once something explains why it disconnected. */
+function preferCauses(findings) {
+    const causes = findings.filter((f) => !SYMPTOM_ONLY.has(f.code));
+    return causes.length > 0 ? causes : findings;
+}
+/** The flat form: every finding in a file, in the order they were logged. */
+export function analyzeLogText(text, lines = TAIL_LINES, max = 6) {
+    return [...scanLogText(text, lines, max).values()].flat();
+}
+function verdictOf(findings) {
+    if (findings.some((f) => f.severity === 'fatal'))
+        return 'broken';
+    return findings.some((f) => f.severity === 'warn') ? 'warning' : 'healthy';
+}
+/**
+ * One diagnosis per server named in the file. Usually that is one server --
+ * but the shared mcp.log carries every server interleaved, and attributing its
+ * lines is the difference between a useful report and a pile of log excerpts.
+ */
+export function analyzeLogFile(path, host, lines = TAIL_LINES) {
+    const source = `${host} (${path})`;
+    const fileServer = serverNameFromLogPath(path);
+    const shared = fileServer === '(host log)';
+    let text;
+    try {
+        text = readTail(path);
+    }
+    catch (e) {
+        const finding = { code: 'log.unreadable', severity: 'warn', message: `Could not read ${path}: ${e.message}` };
+        return [{ spec: { name: fileServer, kind: 'log', sources: [source] }, verdict: 'warning', findings: [finding] }];
+    }
+    const grouped = new Map();
+    for (const [tag, findings] of scanLogText(text, lines)) {
+        // Only the shared log gets to rename its findings; a per-server file is
+        // authoritative about whose it is, whatever the lines inside claim.
+        const name = shared ? (tag ?? fileServer) : fileServer;
+        grouped.set(name, [...(grouped.get(name) ?? []), ...findings]);
+    }
+    if (grouped.size === 0)
+        grouped.set(fileServer, []);
+    return [...grouped].map(([name, findings]) => ({
+        spec: { name, kind: 'log', sources: [source] },
+        verdict: verdictOf(findings),
+        findings,
+    }));
+}
+/**
+ * Diagnose a set of log files: explicit paths, or every one we can find. One
+ * server can own several files (rotation) and appear in the shared log too, so
+ * the results are merged back into one entry per server.
+ */
+export function diagnoseLogs(explicit = [], lines = TAIL_LINES) {
+    const files = explicit.length > 0 ? explicit.map((path) => ({ path, host: 'log file' })) : discoverLogFiles();
+    const byName = new Map();
+    for (const { path, host } of files) {
+        for (const found of analyzeLogFile(path, host, lines)) {
+            const existing = byName.get(found.spec.name);
+            if (!existing) {
+                byName.set(found.spec.name, found);
+                continue;
+            }
+            existing.spec.sources.push(...found.spec.sources);
+            for (const finding of found.findings) {
+                const duplicate = existing.findings.some((f) => f.code === finding.code && f.message === finding.message);
+                if (!duplicate)
+                    existing.findings.push(finding);
+            }
+        }
+    }
+    // One file's symptom can be another file's explained failure, so the causes
+    // only win once everything about a server is in one place.
+    for (const diagnosis of byName.values()) {
+        diagnosis.findings = preferCauses(diagnosis.findings);
+        diagnosis.verdict = verdictOf(diagnosis.findings);
+    }
+    return { diagnoses: [...byName.values()], scanned: files.map((f) => f.path) };
+}

package/dist/redact.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Everything quoted back from a log file or an HTTP response passes through
+ * here first.
+ *
+ * Config env values are easy: mcp-wtf names the key and never the value. Logs
+ * and HTTP responses are not, because they were written by someone else --
+ * hosts cheerfully log `Authorization: Bearer ...`, and a 401 body often
+ * echoes the token that failed. The promise is that a report can be pasted
+ * into a GitHub issue without reading it first, so this is applied to every
+ * borrowed string, not only the ones that look risky.
+ */
+export declare function redactSecrets(text: string): string;
+/** Redact, collapse whitespace and clip -- the form used for quoted evidence. */
+export declare function quoteLine(line: string, max?: number): string;
+export declare function redactSpecSecrets<T extends {
+    spec: {
+        env?: Record<string, string>;
+        headers?: Record<string, string>;
+    };
+}>(diagnosis: T): T;