mcp-wtf 0.1.0

package/dist/discover.js

@@ -0,0 +1,135 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Every place the well-known hosts keep their MCP configuration. Two shapes
+ * exist in the wild: `mcpServers` (Claude Desktop, Claude Code, Cursor,
+ * Windsurf) and `servers` (VS Code).
+ */
+export function knownConfigPaths(platform = process.platform, home = homedir(), cwd = process.cwd()) {
+    const paths = [];
+    const push = (path, host) => paths.push({ path, host });
+    if (platform === 'win32') {
+        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');
+    }
+    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');
+    }
+    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, '.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(cwd, '.vscode', 'mcp.json'), 'VS Code (workspace)');
+    return paths;
+}
+function toSpec(name, raw, source) {
+    if (raw.disabled === true)
+        return null;
+    const sources = [source];
+    const url = typeof raw.url === 'string' ? raw.url : typeof raw.serverUrl === 'string' ? raw.serverUrl : null;
+    if (url) {
+        return { name, kind: 'http', url, headers: raw.headers ?? {}, sources };
+    }
+    if (typeof raw.command !== 'string' || !raw.command)
+        return null;
+    const args = Array.isArray(raw.args) ? raw.args.filter((a) => typeof a === 'string') : [];
+    const spec = {
+        name,
+        kind: 'stdio',
+        command: raw.command,
+        args,
+        env: raw.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(' ');
+    if (joined.includes('${input:')) {
+        spec.unlaunchable = 'uses ${input:...} placeholders that need interactive values';
+    }
+    return spec;
+}
+/** Pull every server out of one config file. Returns [] when unreadable. */
+export function readConfigFile(path, host) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const source = `${host} (${path})`;
+    const collect = (block) => {
+        if (!block || typeof block !== 'object' || Array.isArray(block))
+            return;
+        for (const [name, entry] of Object.entries(block)) {
+            const spec = toSpec(name, entry ?? {}, source);
+            if (spec)
+                out.push(spec);
+        }
+    };
+    collect(parsed['mcpServers']);
+    collect(parsed['servers']);
+    // Claude Code also nests per-project servers under `projects`.
+    const projects = parsed['projects'];
+    if (projects && typeof projects === 'object' && !Array.isArray(projects)) {
+        for (const proj of Object.values(projects)) {
+            collect(proj?.['mcpServers']);
+        }
+    }
+    return out;
+}
+/**
+ * Search every known location, merge duplicates (the same server configured
+ * in several hosts is one server with several sources), and report which
+ * config files were actually found -- and which exist but cannot be parsed,
+ * because a malformed config is the diagnosis, not a thing to skip.
+ */
+export function discover(explicitConfig) {
+    const candidates = explicitConfig
+        ? [{ path: explicitConfig, host: 'config' }]
+        : knownConfigPaths();
+    const configsSearched = [];
+    const configErrors = [];
+    const byIdentity = new Map();
+    for (const { path, host } of candidates) {
+        if (!existsSync(path))
+            continue;
+        configsSearched.push(path);
+        try {
+            JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch (e) {
+            configErrors.push({ path, error: e.message });
+            continue;
+        }
+        for (const spec of readConfigFile(path, host)) {
+            // Identity is what would actually run, not the display name -- two hosts
+            // pointing at the same command are one server. The environment is part
+            // of what runs: the same command with a different env (one with a real
+            // 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 identity = spec.kind === 'http'
+                ? `http|${spec.url}`
+                : `stdio|${spec.command}|${(spec.args ?? []).join(' ')}|${envKey}|${spec.cwd ?? ''}`;
+            const existing = byIdentity.get(identity);
+            if (existing)
+                existing.sources.push(...spec.sources);
+            else
+                byIdentity.set(identity, spec);
+        }
+    }
+    return { specs: [...byIdentity.values()], configsSearched, configErrors };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { discover, readConfigFile, knownConfigPaths } from './discover.js';
+export { diagnoseServer, diagnoseAll, staticChecks, resolveCommand } from './diagnose.js';
+export { renderTerminal } from './report/terminal.js';
+export { McpClient, StdioTransport, HttpTransport } from './client/index.js';
+export type { Diagnosis, Finding, ServerSpec, Verdict, WtfOptions, WtfReport } from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { discover, readConfigFile, knownConfigPaths } from './discover.js';
+export { diagnoseServer, diagnoseAll, staticChecks, resolveCommand } from './diagnose.js';
+export { renderTerminal } from './report/terminal.js';
+export { McpClient, StdioTransport, HttpTransport } from './client/index.js';

package/dist/report/terminal.d.ts

@@ -0,0 +1,2 @@
+import type { WtfReport } from '../types.js';
+export declare function renderTerminal(report: WtfReport): string;

package/dist/report/terminal.js

@@ -0,0 +1,92 @@
+const useColor = !process.env['NO_COLOR'] && (process.env['FORCE_COLOR'] === '1' || process.stdout.isTTY === true);
+const c = {
+    reset: useColor ? '\x1b[0m' : '',
+    bold: useColor ? '\x1b[1m' : '',
+    red: useColor ? '\x1b[31m' : '',
+    green: useColor ? '\x1b[32m' : '',
+    yellow: useColor ? '\x1b[33m' : '',
+    gray: useColor ? '\x1b[90m' : '',
+};
+const BADGE = {
+    healthy: `${c.green} OK ${c.reset}`,
+    warning: `${c.yellow}WARN${c.reset}`,
+    broken: `${c.red}DEAD${c.reset}`,
+};
+function hostsOf(d) {
+    return [...new Set(d.spec.sources.map((s) => s.split(' (')[0] ?? s))].join(', ');
+}
+export function renderTerminal(report) {
+    const lines = [];
+    const { diagnoses } = report;
+    lines.push('');
+    const dead = report.broken;
+    const headline = dead === 0
+        ? `all ${diagnoses.length} MCP server${diagnoses.length === 1 ? '' : 's'} are alive`
+        : `${dead} of ${diagnoses.length} MCP server${diagnoses.length === 1 ? '' : 's'} ${dead === 1 ? 'is' : 'are'} broken -- here is exactly why`;
+    lines.push(`  ${c.bold}mcp-wtf${c.reset}  ${headline}`);
+    lines.push(`  ${c.gray}${report.configsSearched.length} config${report.configsSearched.length === 1 ? '' : 's'} searched${report.configErrors.length ? `, ${report.configErrors.length} unreadable` : ''}${c.reset}`);
+    lines.push('');
+    for (const err of report.configErrors) {
+        lines.push(`  ${c.red}DEAD${c.reset}  ${c.bold}${err.path}${c.reset}`);
+        lines.push(`        ${c.red}The config file itself is not valid JSON:${c.reset} ${err.error}`);
+        lines.push(`        ${c.gray}Every server in this file is invisible to its host until this is fixed.${c.reset}`);
+        lines.push('');
+    }
+    // Broken first -- they are what the user came for.
+    const order = ['broken', 'warning', 'healthy'];
+    for (const verdict of order) {
+        for (const d of diagnoses.filter((x) => x.verdict === verdict)) {
+            const title = d.serverInfo?.name && d.serverInfo.name !== d.spec.name
+                ? `${d.spec.name} ${c.gray}(${d.serverInfo.name}${d.serverInfo.version ? ` v${d.serverInfo.version}` : ''})${c.reset}`
+                : d.spec.name;
+            const meta = [hostsOf(d)];
+            if (d.toolCount !== undefined)
+                meta.push(`${d.toolCount} tools`);
+            if (d.connectMs !== undefined)
+                meta.push(`${d.connectMs}ms`);
+            lines.push(`  ${BADGE[d.verdict]}  ${c.bold}${title}${c.reset}  ${c.gray}${meta.join(', ')}${c.reset}`);
+            for (const f of d.findings) {
+                const mark = f.severity === 'fatal' ? `${c.red}x${c.reset}` : f.severity === 'warn' ? `${c.yellow}!${c.reset}` : `${c.gray}i${c.reset}`;
+                lines.push(`        ${mark} ${f.message}`);
+                if (f.fix) {
+                    wrap(f.fix, 90).forEach((fl, i) => {
+                        lines.push(i === 0 ? `          ${c.green}fix:${c.reset} ${fl}` : `               ${fl}`);
+                    });
+                }
+                if (f.detail) {
+                    for (const dl of f.detail.split('\n').slice(0, 8))
+                        lines.push(`          ${c.gray}${dl}${c.reset}`);
+                }
+            }
+            lines.push('');
+        }
+    }
+    const parts = [];
+    if (report.broken)
+        parts.push(`${c.red}${report.broken} broken${c.reset}`);
+    if (report.warnings)
+        parts.push(`${c.yellow}${report.warnings} with warnings${c.reset}`);
+    if (report.healthy)
+        parts.push(`${c.green}${report.healthy} healthy${c.reset}`);
+    lines.push(`  ${c.gray}${'-'.repeat(64)}${c.reset}`);
+    lines.push(`  ${parts.join(`${c.gray}  |  ${c.reset}`)}   ${c.gray}${(report.durationMs / 1000).toFixed(1)}s${c.reset}`);
+    lines.push('');
+    return lines.join('\n');
+}
+function wrap(text, width) {
+    const words = text.split(' ');
+    const out = [];
+    let line = '';
+    for (const w of words) {
+        if (line && line.length + w.length + 1 > width) {
+            out.push(line);
+            line = w;
+        }
+        else {
+            line = line ? `${line} ${w}` : w;
+        }
+    }
+    if (line)
+        out.push(line);
+    return out;
+}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+export interface ToolDef {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+}
+export interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    [k: string]: unknown;
+}
+/** One MCP server as found in a host config file (or given on the CLI). */
+export interface ServerSpec {
+    name: string;
+    kind: 'stdio' | 'http';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    sources: string[];
+    unlaunchable?: string;
+}
+export type Verdict = 'healthy' | 'broken' | 'warning';
+export interface Finding {
+    /** Stable dotted id, e.g. `cmd.not_found`. */
+    code: string;
+    severity: 'fatal' | 'warn' | 'info';
+    /** What is wrong, in one plain-language sentence. */
+    message: string;
+    /** What to do about it, concretely, naming the file to edit when known. */
+    fix?: string;
+    /** Raw evidence: the stderr tail, the offending line, the resolved path. */
+    detail?: string;
+}
+export interface Diagnosis {
+    spec: ServerSpec;
+    verdict: Verdict;
+    findings: Finding[];
+    /** Populated when the handshake succeeded. */
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    } | null;
+    toolCount?: number;
+    connectMs?: number;
+}
+export interface WtfOptions {
+    timeoutMs: number;
+    concurrency: number;
+}
+export interface WtfReport {
+    diagnoses: Diagnosis[];
+    configsSearched: string[];
+    /** Config files that exist but could not be parsed, with the parse error. */
+    configErrors: Array<{
+        path: string;
+        error: string;
+    }>;
+    healthy: number;
+    broken: number;
+    warnings: number;
+    durationMs: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "mcp-wtf",
+  "version": "0.1.0",
+  "description": "Your MCP server won't connect. Find out why in 10 seconds. Diagnoses every server in your Claude Desktop, Claude Code, Cursor and VS Code configs: missing commands, placeholder API keys, stdout pollution, silent crashes - with the exact fix for each. Zero dependencies.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "troubleshooting",
+    "doctor",
+    "diagnostics",
+    "failed-to-connect",
+    "disconnected",
+    "debug",
+    "claude",
+    "claude-desktop",
+    "claude-code",
+    "cursor",
+    "cli",
+    "fix"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "mcp-wtf": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Beeeeen/mcp-wtf.git"
+  },
+  "homepage": "https://github.com/Beeeeen/mcp-wtf#readme",
+  "bugs": {
+    "url": "https://github.com/Beeeeen/mcp-wtf/issues"
+  },
+  "author": "Ben Yang <ben@yangjiawei.com>"
+}