mcp-triage 0.1.0

package/dist/report.js

@@ -0,0 +1,99 @@
+// Report rendering: human-readable (default) and --json.
+import os from 'node:os';
+import { CLIENTS } from "./clients.js";
+const ORDER = ['error', 'warning', 'info'];
+const LABEL = { error: 'ERROR', warning: 'WARN ', info: 'INFO ' };
+const FIX_LABEL = {
+    fixed: 'FIXED',
+    'would-fix': 'DRY  ',
+    'not-fixable': 'NOFIX',
+    skipped: 'SKIP ',
+};
+export function tilde(p) {
+    const home = os.homedir();
+    return p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+function clientName(id) {
+    return CLIENTS.find((c) => c.id === id)?.name ?? id;
+}
+export function renderHuman(input, version, fixes) {
+    const lines = [];
+    lines.push(`MCP Triage v${version} — scanned ${input.files.length} config file(s)`);
+    lines.push('');
+    if (input.files.length === 0) {
+        lines.push('No MCP config files found in the standard locations for: ' + CLIENTS.map((c) => c.name).join(', '));
+        lines.push('If you expected one, pass a path explicitly: mcp-triage scan --file <path>');
+        return lines.join('\n');
+    }
+    for (const p of input.parsed) {
+        const flag = p.ok ? '✓' : '✗';
+        const n = p.servers.length;
+        const caveat = p.caveat ? `  (${p.caveat})` : '';
+        lines.push(`  ${flag} ${clientName(p.clientId)} — ${tilde(p.file)} — ${n} server(s)${caveat}`);
+    }
+    lines.push('');
+    const sorted = [...input.diagnostics].sort((a, b) => ORDER.indexOf(a.severity) - ORDER.indexOf(b.severity));
+    if (sorted.length === 0) {
+        lines.push('All clear — no findings.');
+    }
+    else {
+        lines.push(`Findings (${sorted.length}):`);
+        for (const d of sorted) {
+            const where = [clientName(d.clientId ?? ''), d.serverName ? `"${d.serverName}"` : ''].filter(Boolean).join(' · ');
+            lines.push(`  [${LABEL[d.severity]}] ${d.checkId} — ${where ? where + ': ' : ''}${d.title}`);
+            if (d.detail)
+                for (const l of d.detail.split('\n'))
+                    lines.push(`           ${l}`);
+            if (d.hint)
+                lines.push(`           → ${d.hint}`);
+        }
+    }
+    if (fixes !== undefined) {
+        lines.push('');
+        if (fixes.length === 0) {
+            lines.push('Fix results: no repair candidates — no scanned file failed to parse.');
+        }
+        else {
+            const dry = fixes.some((f) => f.status === 'would-fix');
+            lines.push(dry ? 'Fix results (dry run — nothing written):' : 'Fix results:');
+            for (const f of fixes) {
+                const what = f.changes.length > 0 ? `: ${f.changes.join(', ')}` : '';
+                lines.push(`  [${FIX_LABEL[f.status]}] ${clientName(f.clientId)} — ${tilde(f.file)}${what}`);
+                if (f.reason)
+                    lines.push(`           → ${f.reason}`);
+                if (f.backupPath) {
+                    lines.push(`           → backup: ${tilde(f.backupPath)}${f.backupKept ? ' (existing backup kept)' : ''}`);
+                }
+            }
+        }
+    }
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const d of input.diagnostics)
+        counts[d.severity]++;
+    const servers = input.parsed.reduce((a, p) => a + p.servers.length, 0);
+    lines.push('');
+    lines.push(`Summary: ${counts.error} error(s), ${counts.warning} warning(s), ${counts.info} info — ${servers} server(s) across ${input.files.length} file(s).`);
+    return lines.join('\n');
+}
+export function renderJson(input, version, fixes) {
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const d of input.diagnostics)
+        counts[d.severity]++;
+    return JSON.stringify({
+        tool: 'mcp-triage',
+        version,
+        generatedAt: new Date().toISOString(),
+        files: input.parsed.map((p) => ({
+            clientId: p.clientId,
+            clientName: clientName(p.clientId),
+            file: p.file,
+            format: p.format,
+            ok: p.ok,
+            caveat: p.caveat,
+            servers: p.servers.map((s) => ({ name: s.name, command: s.command, url: s.url, transport: s.transport })),
+        })),
+        diagnostics: input.diagnostics,
+        ...(fixes !== undefined ? { fixes } : {}),
+        summary: { counts, servers: input.parsed.reduce((a, p) => a + p.servers.length, 0), files: input.files.length },
+    }, null, 2);
+}

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+export type Severity = 'error' | 'warning' | 'info';
+export type Format = 'json' | 'toml' | 'yaml';
+export interface Diagnostic {
+    /** Stable id, e.g. 'config.syntax', 'server.command-resolvable' */
+    checkId: string;
+    severity: Severity;
+    /** One-line, plain English */
+    title: string;
+    detail?: string;
+    hint?: string;
+    clientId?: string;
+    file?: string;
+    serverName?: string;
+    /** Whether `--fix` can address this in a future/current version */
+    fixable?: boolean;
+}
+export interface ServerEntry {
+    name: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string | undefined>;
+    url?: string;
+    transport?: string;
+    cwd?: string;
+    /** Explicitly disabled entries (OpenClaw `enabled: false`) — kept but not connected; runtime checks are skipped. */
+    enabled?: boolean;
+}
+export interface ParsedConfig {
+    clientId: string;
+    file: string;
+    format: Format;
+    ok: boolean;
+    /** Set when parsing is intentionally partial, e.g. 'toml-minimal', 'yaml-light' */
+    caveat?: string;
+    servers: ServerEntry[];
+    diagnostics: Diagnostic[];
+}
+export interface ClientSpec {
+    id: string;
+    name: string;
+    format: Format;
+    /**
+     * Config paths per platform. Placeholders: <home> <appdata> <config>.
+     * A single '*' segment is allowed for profile-style dirs (e.g. dsh profiles).
+     */
+    paths: Partial<Record<'win32' | 'darwin' | 'linux' | 'any', string[]>>;
+    /** Project-level (relative to cwd) config paths */
+    projectPaths?: string[];
+    /** Where server entries live in the file (informational) */
+    serversHint: string;
+    /** File format is JSON5 (comments + trailing commas are legal) — parse leniently. */
+    json5?: boolean;
+    /** Env var that overrides the config path (e.g. OPENCLAW_CONFIG_PATH); scanned in addition when set. */
+    envOverride?: string;
+    /** True when the path/format is not yet verified against official docs (pre-release). */
+    verify?: boolean;
+}
+export interface DiscoveredFile {
+    clientId: string;
+    file: string;
+    format: Format;
+    scope: 'global' | 'project';
+    /** Inherited from the client spec (JSON5-tolerant parsing). */
+    json5?: boolean;
+    /** Unknown client (e.g. explicit --file): try a JSON5 fallback and report it as info when it applies. */
+    json5Fallback?: boolean;
+}
+export interface ScanResult {
+    files: DiscoveredFile[];
+    parsed: ParsedConfig[];
+    diagnostics: Diagnostic[];
+}
+export type FixStatus = 'fixed' | 'would-fix' | 'not-fixable' | 'skipped';
+export interface FixOutcome {
+    file: string;
+    clientId: string;
+    status: FixStatus;
+    /** Human-readable list of repairs applied (or that would be applied). */
+    changes: string[];
+    /** Path of the backup written before the fix (absent for dry runs and non-writes). */
+    backupPath?: string;
+    /** True when an earlier backup existed and was kept (the file had been backed up before). */
+    backupKept?: boolean;
+    /** Why nothing was written (for not-fixable / skipped). */
+    reason?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Core types for mcp-triage v0.1
+export {};

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.1.0';

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "mcp-triage",
+  "version": "0.1.0",
+  "description": "Triage broken MCP setups across 8 agent clients — find what is wrong, fix what is fixable, escalate the rest. Zero runtime dependencies.",
+  "type": "module",
+  "bin": {
+    "mcp-triage": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test tests/*.spec.ts",
+    "dev": "node src/cli.ts scan",
+    "prepare": "npm run build",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "author": "NeufAgents (neufagents.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neufagents/mcp-triage.git"
+  },
+  "homepage": "https://github.com/neufagents/mcp-triage#readme",
+  "bugs": {
+    "url": "https://github.com/neufagents/mcp-triage/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "triage",
+    "doctor",
+    "diagnostics",
+    "cli",
+    "agent",
+    "claude",
+    "cursor",
+    "codex",
+    "windsurf",
+    "openclaw"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.6.1",
+    "typescript": "^5.7.0"
+  }
+}