mcp-medic 1.0.0

package/dist/registry.js

@@ -0,0 +1,87 @@
+/**
+ * Resolves a published MCP server descriptor or registry identifier into an MCPServerConfig.
+ *
+ * Supported formats:
+ * - Direct HTTP/SSE URL: "https://mcp.example.com/sse" -> sse/http config
+ * - NPM/Npx package: "npm:@modelcontextprotocol/server-memory" or "@modelcontextprotocol/server-memory" -> stdio npx
+ * - PyPI/Uvx package: "pypi:mcp-server-git" or "uvx:mcp-server-git" -> stdio uvx
+ * - Registry URL returning JSON server config: "https://registry.example.com/servers/my-tool.json"
+ * - Smithery / Glama server ID: "smithery:username/server-name"
+ */
+export async function resolveRegistryServer(registryId, options = {}) {
+    const trimmed = registryId.trim();
+    const fetchImpl = options.fetchFn ?? fetch;
+    if (!trimmed) {
+        throw new Error('Registry server identifier cannot be empty');
+    }
+    // 1. Direct URL (HTTP / SSE / JSON manifest)
+    if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+        const url = new URL(trimmed);
+        // If URL points to a JSON manifest
+        if (url.pathname.endsWith('.json')) {
+            const res = await fetchImpl(trimmed, {
+                headers: { Accept: 'application/json' },
+                signal: AbortSignal.timeout(options.timeoutMs ?? 5000),
+            });
+            if (!res.ok) {
+                throw new Error(`Failed to fetch registry descriptor from ${trimmed}: HTTP ${res.status}`);
+            }
+            const data = (await res.json());
+            if (typeof data.command === 'string' || typeof data.url === 'string') {
+                return {
+                    name: (typeof data.name === 'string' && data.name) || url.pathname.split('/').pop()?.replace('.json', '') || 'registry-server',
+                    transport: data.transport || (data.url ? (data.url.toString().includes('sse') ? 'sse' : 'http') : 'stdio'),
+                    command: typeof data.command === 'string' ? data.command : undefined,
+                    args: Array.isArray(data.args) ? data.args : undefined,
+                    env: data.env || undefined,
+                    url: typeof data.url === 'string' ? data.url : undefined,
+                    headers: data.headers || undefined,
+                };
+            }
+        }
+        // Default URL endpoint transport (SSE if contains 'sse', otherwise HTTP)
+        const isSse = url.pathname.includes('sse') || url.searchParams.has('sse');
+        return {
+            name: url.hostname + url.pathname.replace(/\/$/, ''),
+            transport: isSse ? 'sse' : 'http',
+            url: trimmed,
+        };
+    }
+    // 2. PyPI / uvx package prefix
+    if (trimmed.startsWith('pypi:') || trimmed.startsWith('uvx:')) {
+        const pkg = trimmed.replace(/^(pypi:|uvx:)/, '');
+        return {
+            name: pkg,
+            transport: 'stdio',
+            command: 'uvx',
+            args: [pkg],
+        };
+    }
+    // 3. NPM package prefix
+    if (trimmed.startsWith('npm:')) {
+        const pkg = trimmed.slice(4);
+        return {
+            name: pkg,
+            transport: 'stdio',
+            command: 'npx',
+            args: ['-y', pkg],
+        };
+    }
+    // 4. Smithery / Glama community identifier
+    if (trimmed.startsWith('smithery:')) {
+        const serverName = trimmed.slice(9);
+        return {
+            name: `smithery/${serverName}`,
+            transport: 'stdio',
+            command: 'npx',
+            args: ['-y', `@smithery/cli@latest`, 'run', serverName],
+        };
+    }
+    // 5. Default scoped or standard npm package identifier (e.g. "@modelcontextprotocol/server-filesystem")
+    return {
+        name: trimmed,
+        transport: 'stdio',
+        command: 'npx',
+        args: ['-y', trimmed],
+    };
+}

package/dist/report.d.ts

@@ -0,0 +1,7 @@
+import type { RunReport } from './types.js';
+export interface FormatReportOptions {
+    showFixes?: boolean;
+}
+/** Human-readable plain text report formatter. */
+export declare function formatReportHuman(report: RunReport, options?: FormatReportOptions): string;
+export declare function formatReportJSON(report: RunReport): string;

package/dist/report.js

@@ -0,0 +1,30 @@
+/** Human-readable plain text report formatter. */
+export function formatReportHuman(report, options = {}) {
+    const lines = [];
+    lines.push(`mcp-doctor report${report.configSource ? ` — ${report.configSource}` : ''}`);
+    lines.push(`${report.summary.connected}/${report.summary.servers} servers connected, ` +
+        `${report.summary.errors} error(s), ${report.summary.warnings} warning(s)`);
+    lines.push('');
+    for (const conn of report.connections) {
+        const status = conn.status === 'connected' ? 'OK' : conn.status.toUpperCase();
+        lines.push(`[${status}] ${conn.server.name} (${conn.server.transport})`);
+        if (conn.error) {
+            lines.push(`  ${conn.error.stage}: ${conn.error.message}`);
+        }
+    }
+    if (report.diagnostics.length > 0) {
+        lines.push('');
+        lines.push('Diagnostics:');
+        for (const d of report.diagnostics) {
+            const scope = d.toolName ? `${d.serverName}/${d.toolName}` : d.serverName;
+            lines.push(`  [${d.severity}] ${scope} — ${d.message} (${d.checkId})`);
+            if (options.showFixes && d.suggestedFix?.description) {
+                lines.push(`    Suggested fix: ${d.suggestedFix.description}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+export function formatReportJSON(report) {
+    return JSON.stringify(report, null, 2);
+}

package/dist/types.d.ts

@@ -0,0 +1,70 @@
+export type TransportType = 'stdio' | 'sse' | 'http';
+export interface MCPServerConfig {
+    name: string;
+    transport: TransportType;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    tokenRefreshUrl?: string;
+    tokenRefreshBody?: Record<string, unknown>;
+}
+export interface MCPConfig {
+    servers: MCPServerConfig[];
+    sourcePath?: string;
+}
+export interface MCPToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema: unknown;
+}
+export interface MCPConnection {
+    server: MCPServerConfig;
+    status: 'connected' | 'failed' | 'timeout';
+    capabilities?: Record<string, unknown>;
+    tools?: MCPToolDefinition[];
+    error?: {
+        stage: 'spawn' | 'handshake' | 'capability-negotiation' | 'list-tools';
+        message: string;
+        raw?: unknown;
+    };
+    latencyMs?: number;
+}
+export type Severity = 'error' | 'warning' | 'info';
+export interface SuggestedFix {
+    description: string;
+    patch?: unknown;
+}
+export interface DiagnosticResult {
+    checkId: string;
+    severity: Severity;
+    message: string;
+    serverName: string;
+    toolName?: string;
+    details?: unknown;
+    suggestedFix?: SuggestedFix;
+}
+export interface Check {
+    id: string;
+    description: string;
+    run(connection: MCPConnection): Promise<DiagnosticResult[]> | DiagnosticResult[];
+}
+export interface RunOptions {
+    timeoutMs?: number;
+    checks?: Check[];
+    verbose?: boolean;
+    onLog?: (message: string) => void;
+}
+export interface RunReport {
+    configSource?: string;
+    connections: MCPConnection[];
+    diagnostics: DiagnosticResult[];
+    summary: {
+        servers: number;
+        connected: number;
+        failed: number;
+        errors: number;
+        warnings: number;
+    };
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Mirrors .agent-room/CONTRACT.md exactly. If these ever diverge,
+// CONTRACT.md is the source of truth — update both in the same commit
+// and log the change in .agent-room/DECISIONS.md.
+export {};

package/dist/watch.d.ts

@@ -0,0 +1,12 @@
+export interface WatchOptions {
+    debounceMs?: number;
+    onTrigger: () => Promise<void> | void;
+    onError?: (err: Error) => void;
+}
+export interface WatcherHandle {
+    close: () => void;
+}
+/**
+ * Watches a file with debouncing on rapid file system events.
+ */
+export declare function watchFileDebounced(filePath: string, options: WatchOptions): WatcherHandle;

package/dist/watch.js

@@ -0,0 +1,85 @@
+import { watch, watchFile, unwatchFile, existsSync } from 'node:fs';
+import { resolve, dirname, basename } from 'node:path';
+/**
+ * Watches a file with debouncing on rapid file system events.
+ */
+export function watchFileDebounced(filePath, options) {
+    const debounceMs = options.debounceMs ?? 200;
+    const absPath = resolve(filePath);
+    const dirPath = dirname(absPath);
+    const targetBase = basename(absPath);
+    let timer;
+    let isClosed = false;
+    const run = () => {
+        if (isClosed)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(async () => {
+            try {
+                await options.onTrigger();
+            }
+            catch (err) {
+                if (options.onError) {
+                    options.onError(err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+        }, debounceMs);
+    };
+    // Watch directory to catch atomic file replaces as well as direct writes
+    let dirWatcher;
+    try {
+        if (existsSync(dirPath)) {
+            dirWatcher = watch(dirPath, (_eventType, filename) => {
+                if (!filename || filename === targetBase) {
+                    run();
+                }
+            });
+        }
+    }
+    catch {
+        // fallback if dir watch fails
+    }
+    // Also watch file directly
+    let fileWatcher;
+    try {
+        if (existsSync(absPath)) {
+            fileWatcher = watch(absPath, () => {
+                run();
+            });
+        }
+    }
+    catch {
+        // fallback
+    }
+    // watchFile as polling backup
+    try {
+        if (existsSync(absPath)) {
+            watchFile(absPath, { interval: 50 }, () => {
+                run();
+            });
+        }
+    }
+    catch {
+        // fallback
+    }
+    return {
+        close() {
+            isClosed = true;
+            if (timer)
+                clearTimeout(timer);
+            try {
+                dirWatcher?.close();
+            }
+            catch { }
+            try {
+                fileWatcher?.close();
+            }
+            catch { }
+            try {
+                unwatchFile(absPath);
+            }
+            catch { }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "mcp-medic",
+  "version": "1.0.0",
+  "description": "Diagnose broken MCP (Model Context Protocol) server configs before they break your agent silently.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-medic": "dist/cli.js",
+    "mcpmedic": "dist/cli.js",
+    "mcp-doctor": "dist/cli.js",
+    "mcpdoctor": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "action.yml"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "developer-tools",
+    "diagnostics",
+    "claude",
+    "claude-desktop",
+    "vscode",
+    "json-schema",
+    "linter",
+    "llm",
+    "agents"
+  ],
+  "author": "Shivam Dixit",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shivam039/mcp-doctor.git"
+  },
+  "homepage": "https://github.com/shivam039/mcp-doctor#readme",
+  "bugs": {
+    "url": "https://github.com/shivam039/mcp-doctor/issues"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}