mcp-triage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NeufAgents (neufagents.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# MCP Triage
+
+[![CI](https://github.com/neufagents/mcp-triage/actions/workflows/ci.yml/badge.svg)](https://github.com/neufagents/mcp-triage/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/mcp-triage.svg)](https://www.npmjs.com/package/mcp-triage) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+**Triage broken MCP setups across agent clients.** A [NeufAgents](https://neufagents.com) tool. One command scans the MCP configuration of every agent client on your machine, finds what is broken or fragile, explains it in plain English, and — where it is safe — repairs it.
+
+Why *triage*: a triage assesses severity fast and routes the case — a free check-and-fix pass for the mechanical problems, and a precise hint (plus a human path) for setups that need surgery.
+
+## What it does
+
+- **Scans** (8 clients): Claude Desktop · Claude Code · Codex · Cursor · VS Code · Windsurf · OpenClaw · dsh
+- **Checks** (v0.1): JSON syntax (including the classic trailing comma), Codex-style TOML tables (basic), command resolvable on PATH, missing `${VAR}` / `process.env.VAR` references, relative-path arguments, plain `http://` remote URLs, transport/entry consistency (stdio needs a command, HTTP transports need a url, `serverName` required for dsh entries), cross-client drift for same-named servers
+- **Fixes** (opt-in `--fix`): mechanical repairs, only for files that fail to parse — strips JSON comments and trailing commas, re-verifies the result, keeps a `.mcp-triage.bak` backup. Everything else is escalated with a hint, never guessed at.
+- **JSON5-aware**: OpenClaw's `openclaw.json` is JSON5 (comments + trailing commas legal) and is parsed as such — no false syntax errors
+- **CLI-first**: runs even when your client cannot start — that is exactly when you need it
+- **Zero runtime dependencies**
+
+## Usage
+
+```bash
+npx mcp-triage            # scan standard locations (all clients) + project configs in cwd
+npx mcp-triage --json     # machine-readable output
+npx mcp-triage --file ./my-config.json
+npx mcp-triage --fix              # repair files that fail to parse (comments / trailing commas)
+npx mcp-triage --fix --dry-run    # show what --fix would do; write nothing
+```
+
+Exit codes: `0` = no error findings, `1` = at least one error finding (post-fix when `--fix` is used).
+
+### `--fix` semantics (v0.1)
+
+- Only files that **fail to parse** are fix candidates; healthy files are never rewritten.
+- Repairs are mechanical deletions only (comments, trailing commas). A repaired copy must parse as JSON or **nothing is written**.
+- Before the first write the original is saved as `<file>.mcp-triage.bak` (an existing backup is kept, never overwritten — so the pristine version survives repeated runs).
+
+## Example output
+
+A demo machine with three clients — one broken JSON, one unrunnable command, one healthy config:
+
+```
+$ npx mcp-triage scan
+
+MCP Triage v0.1.0 — scanned 3 config file(s)
+
+  ✗ Claude Desktop — ~/AppData/Roaming/Claude/claude_desktop_config.json — 0 server(s)
+  ✓ Codex — ~/.codex/config.toml — 2 server(s)  (toml-minimal)
+  ✓ Cursor — ~/.cursor/mcp.json — 1 server(s)
+
+Findings (4):
+  [ERROR] config.syntax — Claude Desktop: Trailing comma breaks JSON parsing
+           line 5: "args": ["-y", "@modelcontextprotocol/server-memory"],
+           → Remove the comma before the closing bracket/brace, then restart the client.
+  [ERROR] server.command-unresolvable — Codex · "notes-mcp": command "my-notes-mcp" not found on PATH
+           → This is the #1 cause of "server silently missing" bugs. Common causes: nvm-managed node (the client does not load your shell profile), missing pnpm/uv, or a typo. Use an absolute path or install the runtime the client can see.
+  [WARN ] server.relative-path-arg — Codex · "notes-mcp": Relative path argument "./notes" may resolve from the wrong directory
+           → Clients spawn servers from their own working directory. Use an absolute path to make this stable.
+  [INFO ] config.cross-client-drift — Codex · "filesystem": Server "filesystem" is configured differently across 2 clients
+           codex → ~/.codex/config.toml
+           cursor → ~/.cursor/mcp.json
+           → Drift is not always wrong — but when one client works and another does not, this is where to look.
+
+Summary: 2 error(s), 1 warning(s), 1 info — 3 server(s) across 3 file(s).
+```
+
+`--fix` takes care of the mechanical class — and nothing else:
+
+```
+$ npx mcp-triage --fix
+
+Fix results:
+  [FIXED] Claude Desktop — ~/AppData/Roaming/Claude/claude_desktop_config.json: removed 1 trailing comma
+           → backup: ~/AppData/Roaming/Claude/claude_desktop_config.json.mcp-triage.bak
+
+Summary: 1 error(s), 1 warning(s), 1 info — 4 server(s) across 3 file(s).
+```
+
+*Sample output from a demo machine; home paths shortened for readability. `--fix --dry-run` prints the same report with `[DRY]` instead of `[FIXED]`, and writes nothing.*
+
+## Coverage notes & known limitations (v0.1)
+
+- All 8 client paths are verified against official docs and/or a real machine (verification log: `docs/verification-log.md` in the repo). OpenClaw paths additionally honor `OPENCLAW_CONFIG_PATH`; VS Code includes the remote/WSL user config (`~/.vscode-server/data/User/mcp.json`).
+- JSON clients: full parsing (OpenClaw: JSON5-light — comments and trailing commas; exotic JSON5 beyond that still fails). TOML (Codex): **basic** — `[mcp_servers.*]` tables only. YAML (dsh cordis profiles): **light** — per-entry extraction of `@deepseek-ai/dsh-mcp-client` patch entries (serverName, transport, command, args, env, cwd; `!!js` expressions kept as text for reference checks).
+- Claude Code project-scoped `mcpServers` inside `~/.claude.json` (`projects.*.mcpServers`) are **not yet scanned** (v0.1.1).
+- `--file` on a file we cannot attribute to a client: if it only parses as JSON5, you get an **info** saying so (not an error) — strict-JSON clients would reject such a file.
+
+## When `--fix` is not enough
+
+`--fix` covers the mechanical class — for free. For everything else (a client that still refuses to start after a clean scan, a setup you want hardened before it breaks, a migration across machines), [NeufAgents](https://neufagents.com) offers a paid fix service: send your triage report to `hi@neufagents.com` and you get a written scope before any work starts. Fully async, no calls.
+
+## Development
+
+```bash
+npm install
+npm test          # node:test, 45 specs — dev/test scripts need Node 22.18+ (native type stripping)
+npm run build     # tsc → dist/
+node src/cli.ts scan
+node src/cli.ts scan --fix --dry-run
+```
+
+The dev and test scripts import `.ts` files directly, so they need Node 22.18+. The published package
+itself supports Node 20+ (`engines`) and its `scan` / `--fix` flows are smoke-tested on Node 20.19.
+
+CI runs the full spec suite on Node 22 and a build + `--version` smoke on Node 20 on every push and pull request.
+
+The package is ESM with zero runtime dependencies; `src/index.ts` is the library entry
+(`import { discoverFiles, parseConfigFile, runChecks, applyFixes } from 'mcp-triage'`),
+`src/cli.ts` is the `mcp-triage` binary. `prepack` builds `dist/`; `prepublishOnly` runs the specs.
+
+## License
+
+MIT © NeufAgents (neufagents.com)

package/dist/checks.d.ts

@@ -0,0 +1,12 @@
+import type { Diagnostic, ParsedConfig } from './types.ts';
+export interface CheckContext {
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+}
+export declare const DEFAULT_CHECK_CONTEXT: CheckContext;
+/** Resolve a bare command name on PATH (or verify an absolute one). Returns resolved path or null. */
+export declare function resolveCommandOnPath(cmd: string, ctx: CheckContext): string | null;
+export declare function findEnvRefs(s: string): string[];
+export declare function runChecks(parsed: ParsedConfig[], ctx?: CheckContext): Diagnostic[];
+/** Cross-file drift: same server name present in multiple clients but with different launch shape. */
+export declare function checkCrossClientDrift(parsed: ParsedConfig[]): Diagnostic[];

package/dist/checks.js

@@ -0,0 +1,211 @@
+// Checks engine: takes parsed configs, returns diagnostics.
+// v0.1 built-ins: command presence, command resolvability on PATH, ${VAR} env refs, relative-path args, insecure http url.
+import fs from 'node:fs';
+import path from 'node:path';
+export const DEFAULT_CHECK_CONTEXT = { env: process.env, platform: process.platform };
+function isFileExecutable(p) {
+    try {
+        const st = fs.statSync(p);
+        if (!st.isFile())
+            return false;
+        if (process.platform !== 'win32') {
+            // any execute bit
+            return (st.mode & 0o111) !== 0;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve a bare command name on PATH (or verify an absolute one). Returns resolved path or null. */
+export function resolveCommandOnPath(cmd, ctx) {
+    const hasSep = cmd.includes('/') || cmd.includes('\\');
+    if (hasSep)
+        return isFileExecutable(cmd) ? cmd : null;
+    const pathVar = ctx.env.PATH ?? ctx.env.Path ?? '';
+    const dirs = pathVar.split(path.delimiter).filter(Boolean);
+    const exts = ctx.platform === 'win32'
+        ? (ctx.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean).map((e) => e.toLowerCase())
+        : [''];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const cand = path.join(dir, cmd + ext);
+            if (isFileExecutable(cand))
+                return cand;
+        }
+        // Windows: command may already carry its extension
+        const direct = path.join(dir, cmd);
+        if (isFileExecutable(direct))
+            return direct;
+    }
+    return null;
+}
+const ENV_REF_RE = /\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)\}|process\.env\.([A-Za-z_][A-Za-z0-9_]*)/g;
+export function findEnvRefs(s) {
+    const out = [];
+    for (const m of s.matchAll(ENV_REF_RE))
+        out.push((m[1] ?? m[2]));
+    return out;
+}
+function stringy(s) {
+    const parts = [];
+    if (s.command)
+        parts.push(s.command);
+    if (s.args)
+        parts.push(...s.args);
+    if (s.url)
+        parts.push(s.url);
+    if (s.env)
+        for (const v of Object.values(s.env))
+            if (v)
+                parts.push(v);
+    if (s.cwd)
+        parts.push(s.cwd);
+    return parts;
+}
+function checkServer(clientId, file, s, ctx) {
+    const diags = [];
+    const base = { clientId, file, serverName: s.name };
+    if (s.enabled === false) {
+        diags.push({
+            checkId: 'server.disabled',
+            severity: 'info',
+            title: 'Server is disabled (enabled: false) — runtime checks skipped',
+            ...base,
+            hint: 'OpenClaw keeps disabled definitions without connecting them. Remove `enabled: false` to activate.',
+        });
+        return diags;
+    }
+    if (!s.command && !s.url) {
+        diags.push({
+            checkId: 'server.command-missing',
+            severity: 'error',
+            title: 'Server has neither "command" nor "url" — it cannot start',
+            ...base,
+            hint: 'Add a command (stdio) or a url (remote). This entry is inert as written.',
+        });
+        return diags;
+    }
+    const KNOWN_TRANSPORTS = ['stdio', 'streamable-http', 'sse', 'http'];
+    const t = s.transport?.toLowerCase();
+    if (t && !KNOWN_TRANSPORTS.includes(t)) {
+        diags.push({
+            checkId: 'server.transport-unknown',
+            severity: 'warning',
+            title: `Unknown transport "${s.transport}"`,
+            ...base,
+            hint: 'Expected one of: stdio, streamable-http, sse, http. The client may reject the entry or fall back to a default.',
+        });
+    }
+    if (t === 'stdio' && s.command === undefined) {
+        diags.push({
+            checkId: 'server.stdio-command-missing',
+            severity: 'error',
+            title: 'transport is "stdio" but no command is set',
+            ...base,
+            hint: 'stdio servers must name the executable to spawn (e.g. command: npx). Add it, or switch to an http transport with a url.',
+        });
+    }
+    if (t && ['streamable-http', 'sse', 'http'].includes(t) && s.url === undefined) {
+        diags.push({
+            checkId: 'server.http-url-missing',
+            severity: 'error',
+            title: `transport is "${s.transport}" but no url is set`,
+            ...base,
+            hint: 'HTTP transports must point at an endpoint (url: https://.../mcp). Add it, or use a stdio command instead.',
+        });
+    }
+    if (s.command) {
+        const resolved = resolveCommandOnPath(s.command, ctx);
+        if (!resolved) {
+            diags.push({
+                checkId: 'server.command-unresolvable',
+                severity: 'error',
+                title: `command "${s.command}" not found on PATH`,
+                ...base,
+                hint: 'This is the #1 cause of "server silently missing" bugs. Common causes: nvm-managed node (the client does not load your shell profile), missing pnpm/uv, or a typo. Use an absolute path or install the runtime the client can see.',
+            });
+        }
+    }
+    if (s.url && /^http:\/\//i.test(s.url)) {
+        diags.push({
+            checkId: 'server.url-insecure',
+            severity: 'warning',
+            title: 'Remote server uses plain http://',
+            ...base,
+            detail: s.url,
+            hint: 'Prefer https:// unless this is a deliberate localhost setup.',
+        });
+    }
+    if (s.args) {
+        for (const a of s.args) {
+            if (a.startsWith('./') || a.startsWith('../')) {
+                diags.push({
+                    checkId: 'server.relative-path-arg',
+                    severity: 'warning',
+                    title: `Relative path argument "${a}" may resolve from the wrong directory`,
+                    ...base,
+                    hint: 'Clients spawn servers from their own working directory. Use an absolute path to make this stable.',
+                });
+                break;
+            }
+        }
+    }
+    const missing = new Set();
+    for (const part of stringy(s)) {
+        for (const ref of findEnvRefs(part)) {
+            if (!ctx.env[ref])
+                missing.add(ref);
+        }
+    }
+    if (missing.size > 0) {
+        diags.push({
+            checkId: 'server.env-ref-missing',
+            severity: 'warning',
+            title: `Referenced env var${missing.size > 1 ? 's' : ''} not set: ${[...missing].join(', ')}`,
+            ...base,
+            hint: 'Set it in your shell AND make sure the client process can see it (GUI apps often do not inherit shell env).',
+        });
+    }
+    return diags;
+}
+export function runChecks(parsed, ctx = DEFAULT_CHECK_CONTEXT) {
+    const out = [];
+    for (const p of parsed) {
+        for (const s of p.servers)
+            out.push(...checkServer(p.clientId, p.file, s, ctx));
+    }
+    return out;
+}
+/** Cross-file drift: same server name present in multiple clients but with different launch shape. */
+export function checkCrossClientDrift(parsed) {
+    const byName = new Map();
+    for (const p of parsed) {
+        for (const s of p.servers) {
+            const shape = JSON.stringify([s.command ?? s.url ?? '', s.args ?? []]);
+            const list = byName.get(s.name) ?? [];
+            list.push({ file: p.file, clientId: p.clientId, shape });
+            byName.set(s.name, list);
+        }
+    }
+    const out = [];
+    for (const [name, list] of byName) {
+        if (list.length < 2)
+            continue;
+        const shapes = new Set(list.map((l) => l.shape));
+        if (shapes.size > 1) {
+            out.push({
+                checkId: 'config.cross-client-drift',
+                severity: 'info',
+                title: `Server "${name}" is configured differently across ${list.length} clients`,
+                detail: list.map((l) => `${l.clientId} → ${l.file}`).join('\n'),
+                hint: 'Drift is not always wrong — but when one client works and another does not, this is where to look.',
+                clientId: list[0].clientId,
+                file: list[0].file,
+                serverName: name,
+            });
+        }
+    }
+    return out;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// mcp-triage CLI — v0.1
+// Usage: mcp-triage [scan] [--file <path>] [--cwd <dir>] [--json] [--fix [--dry-run]] [--version] [--help]
+import path from 'node:path';
+import { discoverFiles } from "./discover.js";
+import { parseConfigFile } from "./parse.js";
+import { runChecks, checkCrossClientDrift, DEFAULT_CHECK_CONTEXT } from "./checks.js";
+import { applyFixes } from "./fix.js";
+import { renderHuman, renderJson } from "./report.js";
+import { VERSION } from "./version.js";
+function help() {
+    return `mcp-triage v${VERSION} — triage broken MCP setups across agent clients
+
+Usage:
+  mcp-triage [scan]              Scan standard config locations (all clients) + current dir project configs
+  mcp-triage scan --file <path>  Scan a single config file
+  mcp-triage scan --cwd <dir>    Also check project-level configs relative to <dir>
+  mcp-triage scan --json         Machine-readable output
+
+Fix mode (opt-in):
+  mcp-triage scan --fix            Repair config files that fail to parse (mechanical repairs only:
+                                   JSON comments / trailing commas). A .mcp-triage.bak backup is
+                                   written before any change, and nothing is written unless the
+                                   repaired copy parses cleanly.
+  mcp-triage scan --fix --dry-run  Show what --fix would do; write nothing.
+
+Exit codes: 0 = no error findings, 1 = at least one error finding (post-fix when --fix is used).
+`;
+}
+function guessFormat(file) {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === '.toml')
+        return 'toml';
+    if (ext === '.yml' || ext === '.yaml')
+        return 'yaml';
+    return 'json';
+}
+function collectDiagnostics(parsed) {
+    return [
+        ...parsed.flatMap((p) => p.diagnostics),
+        ...runChecks(parsed, DEFAULT_CHECK_CONTEXT),
+        ...checkCrossClientDrift(parsed),
+    ];
+}
+const argv = process.argv.slice(2);
+if (argv.includes('--version') || argv.includes('-V')) {
+    console.log(VERSION);
+    process.exit(0);
+}
+if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(help());
+    process.exit(0);
+}
+const json = argv.includes('--json');
+const fix = argv.includes('--fix');
+const dryRun = argv.includes('--dry-run');
+let cwd = process.cwd();
+const cwdIdx = argv.indexOf('--cwd');
+if (cwdIdx >= 0 && argv[cwdIdx + 1])
+    cwd = path.resolve(argv[cwdIdx + 1]);
+const fileIdx = argv.indexOf('--file');
+let files;
+if (fileIdx >= 0 && argv[fileIdx + 1]) {
+    const f = path.resolve(argv[fileIdx + 1]);
+    files = [{ clientId: 'custom', file: f, format: guessFormat(f), scope: 'project', json5Fallback: true }];
+}
+else {
+    files = discoverFiles(cwd);
+}
+let parsed = files.map(parseConfigFile);
+let diagnostics = collectDiagnostics(parsed);
+let fixes;
+if (fix) {
+    fixes = applyFixes(files, parsed, { dryRun });
+    if (fixes.some((r) => r.status === 'fixed')) {
+        parsed = files.map(parseConfigFile); // re-read what is now on disk
+        diagnostics = collectDiagnostics(parsed);
+    }
+}
+const input = { files, parsed, diagnostics };
+console.log(json ? renderJson(input, VERSION, fixes) : renderHuman(input, VERSION, fixes));
+if (diagnostics.some((d) => d.severity === 'error'))
+    process.exitCode = 1;

package/dist/clients.d.ts

@@ -0,0 +1,13 @@
+import type { ClientSpec } from './types.ts';
+export declare const CLIENTS: ClientSpec[];
+export interface PathContext {
+    platform: NodeJS.Platform;
+    home: string;
+    appdata: string;
+    configDir: string;
+    /** Process env (used for path overrides like OPENCLAW_CONFIG_PATH). Optional for tests. */
+    env?: NodeJS.ProcessEnv;
+}
+export declare function defaultPathContext(): PathContext;
+export declare function expandPlaceholders(p: string, ctx: PathContext): string;
+export declare function clientPathsForPlatform(spec: ClientSpec, ctx: PathContext): string[];

package/dist/clients.js

@@ -0,0 +1,116 @@
+// Client registry: 8 clients x config locations.
+// Path verification round (2026-09-19, night cycle): all 8 verified against official docs
+// and/or this machine. Sources per entry. `verify: true` marks entries NOT yet verified.
+//
+// Sources:
+// - VS Code: code.visualstudio.com/docs/agents/reference/mcp-configuration (mcp.json; user profile via
+//   "MCP: Open User Configuration"; workspace .vscode/mcp.json; servers key). Remote/WSL path
+//   ~/.vscode-server/data/User/mcp.json confirmed via StackOverflow 79706687 + microsoft/vscode#256546.
+// - OpenClaw: docs.openclaw.ai/gateway/configuration (JSON5 config at ~/.openclaw/openclaw.json,
+//   path overridable via OPENCLAW_CONFIG_PATH) + docs.openclaw.ai/tools/mcp (mcp.servers map).
+// - dsh: machine-verified 2026-09-19 (~/.dsh/profiles/{headless,web}/cordis{,.patch}.yml exist locally)
+//   + @deepseek-ai/dsh-mcp-client@0.1.5-rc.2 README (patch entry: name + config.{serverName,transport,...}).
+import os from 'node:os';
+import path from 'node:path';
+export const CLIENTS = [
+    {
+        id: 'claude-desktop',
+        name: 'Claude Desktop',
+        format: 'json',
+        paths: {
+            win32: ['<appdata>/Claude/claude_desktop_config.json'],
+            darwin: ['<home>/Library/Application Support/Claude/claude_desktop_config.json'],
+            linux: ['<config>/Claude/claude_desktop_config.json'],
+        },
+        serversHint: 'mcpServers',
+    },
+    {
+        id: 'claude-code',
+        name: 'Claude Code',
+        format: 'json',
+        paths: {
+            any: ['<home>/.claude.json'],
+        },
+        projectPaths: ['.mcp.json'],
+        serversHint: 'mcpServers (global in ~/.claude.json; project in .mcp.json)',
+    },
+    {
+        id: 'codex',
+        name: 'Codex',
+        format: 'toml',
+        paths: {
+            any: ['<home>/.codex/config.toml'],
+        },
+        serversHint: '[mcp_servers.<name>] tables',
+    },
+    {
+        id: 'cursor',
+        name: 'Cursor',
+        format: 'json',
+        paths: {
+            any: ['<home>/.cursor/mcp.json'],
+        },
+        projectPaths: ['.cursor/mcp.json'],
+        serversHint: 'mcpServers',
+    },
+    {
+        id: 'vscode',
+        name: 'VS Code',
+        format: 'json',
+        paths: {
+            win32: ['<appdata>/Code/User/mcp.json'],
+            // Remote/WSL sessions keep the user config on the server side (~/.vscode-server/data/User/).
+            darwin: ['<home>/Library/Application Support/Code/User/mcp.json', '<home>/.vscode-server/data/User/mcp.json'],
+            linux: ['<config>/Code/User/mcp.json', '<home>/.vscode-server/data/User/mcp.json'],
+        },
+        projectPaths: ['.vscode/mcp.json'],
+        serversHint: 'servers',
+    },
+    {
+        id: 'windsurf',
+        name: 'Windsurf',
+        format: 'json',
+        paths: {
+            any: ['<home>/.codeium/windsurf/mcp_config.json'],
+        },
+        serversHint: 'mcpServers',
+    },
+    {
+        id: 'openclaw',
+        name: 'OpenClaw',
+        format: 'json',
+        json5: true,
+        envOverride: 'OPENCLAW_CONFIG_PATH',
+        paths: {
+            any: ['<home>/.openclaw/openclaw.json', '<config>/openclaw/config.json'],
+        },
+        serversHint: 'mcp.servers (older guides may show mcpServers)',
+    },
+    {
+        id: 'dsh',
+        name: 'dsh (DeepSeek Harness)',
+        format: 'yaml',
+        paths: {
+            any: ['<home>/.dsh/profiles/*/cordis.patch.yml', '<home>/.dsh/profiles/*/cordis.yml'],
+        },
+        serversHint: '@deepseek-ai/dsh-mcp-client patch entries (config.serverName/transport/command/args/env)',
+    },
+];
+export function defaultPathContext() {
+    const home = os.homedir();
+    return {
+        platform: process.platform,
+        home,
+        appdata: process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming'),
+        configDir: path.join(home, '.config'),
+        env: process.env,
+    };
+}
+export function expandPlaceholders(p, ctx) {
+    return p.replace(/<home>/g, ctx.home).replace(/<appdata>/g, ctx.appdata).replace(/<config>/g, ctx.configDir);
+}
+export function clientPathsForPlatform(spec, ctx) {
+    const plat = spec.paths[ctx.platform] ?? [];
+    const any = spec.paths.any ?? [];
+    return [...plat, ...any].map((p) => expandPlaceholders(p, ctx));
+}

package/dist/discover.d.ts

@@ -0,0 +1,5 @@
+import { type PathContext } from './clients.ts';
+import type { DiscoveredFile } from './types.ts';
+/** Expand a pattern containing at most one '*' path segment. Returns [] when nothing exists. */
+export declare function expandGlob(pattern: string): string[];
+export declare function discoverFiles(cwd: string, ctx?: PathContext): DiscoveredFile[];

package/dist/discover.js

@@ -0,0 +1,70 @@
+// Discovery: expand client paths (placeholders + one '*' segment), keep files that exist.
+import fs from 'node:fs';
+import path from 'node:path';
+import { CLIENTS, clientPathsForPlatform, defaultPathContext } from "./clients.js";
+function isFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Expand a pattern containing at most one '*' path segment. Returns [] when nothing exists. */
+export function expandGlob(pattern) {
+    if (!pattern.includes('*'))
+        return [pattern];
+    const norm = pattern.split('/');
+    const starIdx = norm.findIndex((seg) => seg.includes('*'));
+    if (starIdx === -1)
+        return [pattern];
+    const seg = norm[starIdx];
+    if (seg !== '*')
+        return [pattern]; // only plain single-star segments supported in v0.1
+    const parent = norm.slice(0, starIdx).join('/');
+    const rest = norm.slice(starIdx + 1);
+    let entries = [];
+    try {
+        entries = fs.readdirSync(parent);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries) {
+        const candidate = [parent, e, ...rest].join('/');
+        if (isFile(candidate))
+            out.push(candidate);
+    }
+    return out;
+}
+export function discoverFiles(cwd, ctx = defaultPathContext()) {
+    const seen = new Set();
+    const out = [];
+    const push = (f) => {
+        const key = f.file.toLowerCase();
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push(f);
+    };
+    for (const spec of CLIENTS) {
+        for (const p of clientPathsForPlatform(spec, ctx)) {
+            for (const f of expandGlob(p)) {
+                if (isFile(f))
+                    push({ clientId: spec.id, file: f, format: spec.format, scope: 'global', json5: spec.json5 });
+            }
+        }
+        if (spec.envOverride && ctx.env?.[spec.envOverride]) {
+            const f = path.resolve(ctx.env[spec.envOverride]);
+            if (isFile(f))
+                push({ clientId: spec.id, file: f, format: spec.format, scope: 'global', json5: spec.json5 });
+        }
+        for (const rel of spec.projectPaths ?? []) {
+            const f = path.join(cwd, rel);
+            if (isFile(f))
+                push({ clientId: spec.id, file: f, format: spec.format, scope: 'project', json5: spec.json5 });
+        }
+    }
+    return out;
+}