mcp-medic 1.0.0

package/dist/orchestrator.js

@@ -0,0 +1,60 @@
+async function connectStub(config) {
+    return {
+        server: config,
+        status: 'failed',
+        error: {
+            stage: 'spawn',
+            message: 'protocol layer not yet implemented (src/protocol/) — see .agent-room/STATUS.md',
+        },
+    };
+}
+let connectImpl = (config, _timeoutMs) => connectStub(config);
+/** Allows the protocol layer to register its real implementation without
+ * this file needing to import it directly (keeps orchestrator decoupled
+ * from protocol internals per CONTRACT.md module boundaries). */
+export function registerConnectImpl(impl) {
+    connectImpl = impl;
+}
+export async function runChecks(config, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5000;
+    const checks = options.checks ?? [];
+    const connections = [];
+    const diagnostics = [];
+    for (const server of config.servers) {
+        const connection = await connectImpl(server, timeoutMs, options);
+        connections.push(connection);
+        if (connection.status !== 'connected') {
+            continue; // checks require a live connection; connection failure is its own signal in the report
+        }
+        for (const check of checks) {
+            try {
+                const results = await check.run(connection);
+                diagnostics.push(...results);
+            }
+            catch (err) {
+                // Non-negotiable per CONTRACT.md: a throwing check must not crash
+                // the run. This catch is a safety net on top of each check's own
+                // required internal handling.
+                diagnostics.push({
+                    checkId: check.id,
+                    severity: 'error',
+                    message: `check threw unexpectedly: ${err instanceof Error ? err.message : String(err)}`,
+                    serverName: connection.server.name,
+                });
+            }
+        }
+    }
+    const summary = {
+        servers: config.servers.length,
+        connected: connections.filter((c) => c.status === 'connected').length,
+        failed: connections.filter((c) => c.status !== 'connected').length,
+        errors: diagnostics.filter((d) => d.severity === 'error').length,
+        warnings: diagnostics.filter((d) => d.severity === 'warning').length,
+    };
+    return {
+        configSource: config.sourcePath,
+        connections,
+        diagnostics,
+        summary,
+    };
+}

package/dist/policy.d.ts

@@ -0,0 +1,16 @@
+import type { Check, TransportType } from './types.js';
+export interface MCPDoctorPolicy {
+    bannedTransports?: TransportType[];
+    allowedDomains?: string[];
+    minDescriptionLength?: number;
+    requireToolDescriptions?: boolean;
+}
+/**
+ * Loads a policy from a file path, or auto-discovers .mcp-doctor-policy.json in cwd.
+ */
+export declare function loadPolicy(policyPath?: string, cwd?: string): MCPDoctorPolicy | undefined;
+/**
+ * Creates composable Check instances from an organization policy.
+ * Policy checks seamlessly integrate with the standard Check interface.
+ */
+export declare function createPolicyChecks(policy: MCPDoctorPolicy): Check[];

package/dist/policy.js

@@ -0,0 +1,143 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Loads a policy from a file path, or auto-discovers .mcp-doctor-policy.json in cwd.
+ */
+export function loadPolicy(policyPath, cwd = process.cwd()) {
+    const targetPath = policyPath ? resolve(policyPath) : resolve(cwd, '.mcp-doctor-policy.json');
+    if (!existsSync(targetPath)) {
+        return undefined;
+    }
+    try {
+        const raw = readFileSync(targetPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch (err) {
+        throw new Error(`Failed to parse policy file at ${targetPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Creates composable Check instances from an organization policy.
+ * Policy checks seamlessly integrate with the standard Check interface.
+ */
+export function createPolicyChecks(policy) {
+    const checks = [];
+    // 1. Banned transport check
+    if (policy.bannedTransports && policy.bannedTransports.length > 0) {
+        const banned = new Set(policy.bannedTransports);
+        checks.push({
+            id: 'policy.banned-transport',
+            description: 'Enforces organizational policies on allowed connection transports.',
+            run(connection) {
+                const results = [];
+                try {
+                    if (banned.has(connection.server.transport)) {
+                        results.push({
+                            checkId: 'policy.banned-transport',
+                            severity: 'error',
+                            message: `Transport "${connection.server.transport}" is banned by organizational policy.`,
+                            serverName: connection.server.name,
+                            details: {
+                                transport: connection.server.transport,
+                                bannedTransports: Array.from(banned),
+                            },
+                            suggestedFix: {
+                                description: `Migrate server "${connection.server.name}" to an allowed transport.`,
+                            },
+                        });
+                    }
+                }
+                catch (err) {
+                    results.push({
+                        checkId: 'policy.banned-transport',
+                        severity: 'error',
+                        message: `policy check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                        serverName: connection.server.name,
+                    });
+                }
+                return results;
+            },
+        });
+    }
+    // 2. Allowed domain allowlist check
+    if (policy.allowedDomains && policy.allowedDomains.length > 0) {
+        const allowed = policy.allowedDomains.map((d) => d.toLowerCase());
+        checks.push({
+            id: 'policy.domain-allowlist',
+            description: 'Ensures remote SSE/HTTP servers connect only to approved domains.',
+            run(connection) {
+                const results = [];
+                try {
+                    if (connection.server.url) {
+                        const parsedUrl = new URL(connection.server.url);
+                        const hostname = parsedUrl.hostname.toLowerCase();
+                        const isAllowed = allowed.some((dom) => hostname === dom || hostname.endsWith(`.${dom}`));
+                        if (!isAllowed) {
+                            results.push({
+                                checkId: 'policy.domain-allowlist',
+                                severity: 'error',
+                                message: `Server URL domain "${hostname}" is not in organizational allowlist [${allowed.join(', ')}].`,
+                                serverName: connection.server.name,
+                                details: { hostname, allowedDomains: allowed, url: connection.server.url },
+                                suggestedFix: {
+                                    description: `Configure server "${connection.server.name}" to use an approved domain or update .mcp-doctor-policy.json.`,
+                                },
+                            });
+                        }
+                    }
+                }
+                catch (err) {
+                    results.push({
+                        checkId: 'policy.domain-allowlist',
+                        severity: 'error',
+                        message: `policy check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                        serverName: connection.server.name,
+                    });
+                }
+                return results;
+            },
+        });
+    }
+    // 3. Minimum description length check
+    if (typeof policy.minDescriptionLength === 'number' && policy.minDescriptionLength > 0) {
+        const minLen = policy.minDescriptionLength;
+        checks.push({
+            id: 'policy.description-length',
+            description: `Enforces minimum tool description length of ${minLen} characters.`,
+            run(connection) {
+                const results = [];
+                try {
+                    if (!connection.tools)
+                        return results;
+                    for (const tool of connection.tools) {
+                        const desc = tool.description?.trim() || '';
+                        if (desc.length < minLen) {
+                            results.push({
+                                checkId: 'policy.description-length',
+                                severity: 'warning',
+                                message: `Tool "${tool.name}" description is too brief (${desc.length} chars, policy requires minimum ${minLen}).`,
+                                serverName: connection.server.name,
+                                toolName: tool.name,
+                                details: { currentLength: desc.length, requiredLength: minLen },
+                                suggestedFix: {
+                                    description: `Expand tool "${tool.name}" description to at least ${minLen} characters to assist model tool selection.`,
+                                },
+                            });
+                        }
+                    }
+                }
+                catch (err) {
+                    results.push({
+                        checkId: 'policy.description-length',
+                        severity: 'error',
+                        message: `policy check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                        serverName: connection.server.name,
+                    });
+                }
+                return results;
+            },
+        });
+    }
+    return checks;
+}

package/dist/protocol/connect.d.ts

@@ -0,0 +1,2 @@
+import type { MCPConnection, MCPServerConfig, RunOptions } from '../types.js';
+export declare function connect(config: MCPServerConfig, timeoutMs: number, options?: RunOptions): Promise<MCPConnection>;

package/dist/protocol/connect.js

@@ -0,0 +1,417 @@
+import { spawn } from 'node:child_process';
+const PROTOCOL_VERSION = '2024-11-05';
+const CLIENT_INFO = { name: 'mcp-doctor', version: '0.0.1' };
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function logVerbose(options, message) {
+    if (options?.onLog) {
+        options.onLog(message);
+    }
+    else if (options?.verbose) {
+        console.error(`[debug] ${message}`);
+    }
+}
+function failed(config, status, stage, message, raw) {
+    return { server: config, status, error: { stage, message, ...(raw === undefined ? {} : { raw }) } };
+}
+function withTimeout(promise, timeoutMs, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+function validateResponse(response, expectedId) {
+    if (!response || response.jsonrpc !== '2.0' || response.id !== expectedId) {
+        throw new Error('invalid JSON-RPC response');
+    }
+    if (response.error) {
+        throw new Error(`MCP request failed (${response.error.code}): ${response.error.message}`);
+    }
+    if (!response.result || typeof response.result !== 'object') {
+        throw new Error('JSON-RPC response has no result');
+    }
+    return response.result;
+}
+function normalizeTools(result) {
+    if (!Array.isArray(result.tools))
+        throw new Error('tools/list response has no tools array');
+    return result.tools.map((tool, index) => {
+        if (!tool || typeof tool !== 'object' || typeof tool.name !== 'string') {
+            throw new Error(`tools/list returned an invalid tool at index ${index}`);
+        }
+        const value = tool;
+        return {
+            name: value.name,
+            ...(typeof value.description === 'string' ? { description: value.description } : {}),
+            inputSchema: value.inputSchema,
+        };
+    });
+}
+async function refreshTokenIfNeeded(config, options) {
+    const headers = { ...(config.headers ?? {}) };
+    if (!config.tokenRefreshUrl) {
+        return headers;
+    }
+    try {
+        logVerbose(options, `Refreshing OAuth token from ${config.tokenRefreshUrl}...`);
+        const res = await fetch(config.tokenRefreshUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...(config.headers ?? {}) },
+            body: JSON.stringify(config.tokenRefreshBody ?? {}),
+        });
+        if (!res.ok) {
+            throw new Error(`Token refresh failed with status ${res.status}`);
+        }
+        const data = (await res.json());
+        const token = (typeof data.access_token === 'string' && data.access_token) ||
+            (typeof data.token === 'string' && data.token);
+        if (token) {
+            headers['Authorization'] = `Bearer ${token}`;
+            logVerbose(options, 'Token refreshed successfully');
+        }
+    }
+    catch (err) {
+        logVerbose(options, `Token refresh warning: ${messageOf(err)}`);
+    }
+    return headers;
+}
+class StdioTransport {
+    options;
+    process;
+    nextId = 1;
+    pending = new Map();
+    buffer = '';
+    closed = false;
+    exitError;
+    constructor(config, options) {
+        this.options = options;
+        if (!config.command)
+            throw new Error('stdio transport requires command');
+        this.process = spawn(config.command, config.args ?? [], {
+            env: { ...process.env, ...(config.env ?? {}) },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.exitError = new Promise((_, reject) => {
+            this.process.once('error', (error) => reject(new Error(`failed to start MCP server: ${error.message}`)));
+            this.process.once('exit', (code, signal) => {
+                if (!this.closed)
+                    reject(new Error(`MCP server exited before responding (code=${code ?? 'unknown'}, signal=${signal ?? 'none'})`));
+            });
+        });
+        this.process.stdout.setEncoding('utf8');
+        this.process.stdout.on('data', (chunk) => this.consume(chunk));
+    }
+    consume(chunk) {
+        this.buffer += chunk;
+        let newline = this.buffer.indexOf('\n');
+        while (newline >= 0) {
+            const line = this.buffer.slice(0, newline).trim();
+            this.buffer = this.buffer.slice(newline + 1);
+            newline = this.buffer.indexOf('\n');
+            if (!line)
+                continue;
+            try {
+                logVerbose(this.options, `<-- stdio: ${line}`);
+                const parsed = JSON.parse(line);
+                if (typeof parsed.id === 'number') {
+                    const waiter = this.pending.get(parsed.id);
+                    if (waiter) {
+                        this.pending.delete(parsed.id);
+                        waiter.resolve(parsed);
+                    }
+                }
+            }
+            catch {
+                // Ignore server log noise or malformed notifications; the request timeout reports the failure.
+            }
+        }
+    }
+    request(method, params) {
+        const id = this.nextId++;
+        const payload = JSON.stringify({ jsonrpc: '2.0', id, method, ...(params === undefined ? {} : { params }) }) +
+            '\n';
+        logVerbose(this.options, `--> stdio: ${payload.trim()}`);
+        return Promise.race([
+            new Promise((resolve, reject) => {
+                this.pending.set(id, { resolve, reject });
+                this.process.stdin.write(payload, (error) => {
+                    if (error) {
+                        this.pending.delete(id);
+                        reject(error);
+                    }
+                });
+            }),
+            this.exitError,
+        ]);
+    }
+    notify(method, params) {
+        return new Promise((resolve, reject) => {
+            const payload = JSON.stringify({ jsonrpc: '2.0', method, ...(params === undefined ? {} : { params }) }) +
+                '\n';
+            logVerbose(this.options, `--> stdio (notify): ${payload.trim()}`);
+            this.process.stdin.write(payload, (error) => (error ? reject(error) : resolve()));
+        });
+    }
+    async close() {
+        this.closed = true;
+        for (const waiter of this.pending.values())
+            waiter.reject(new Error('MCP server connection closed'));
+        this.pending.clear();
+        if (!this.process.killed) {
+            this.process.kill();
+            await new Promise((resolve) => this.process.once('close', () => resolve()));
+        }
+    }
+}
+async function httpJson(url, headers, body, options) {
+    const bodyText = JSON.stringify(body);
+    logVerbose(options, `--> HTTP POST ${url}: ${bodyText}`);
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            Accept: 'application/json, text/event-stream',
+            'Content-Type': 'application/json',
+            ...headers,
+        },
+        body: bodyText,
+    });
+    if (!response.ok)
+        throw new Error(`MCP HTTP request failed with status ${response.status}`);
+    const text = await response.text();
+    logVerbose(options, `<-- HTTP ${response.status}: ${text}`);
+    const data = text.trim().startsWith('data:')
+        ? text
+            .split(/\r?\n/)
+            .find((line) => line.startsWith('data:'))
+            ?.slice(5)
+            .trim()
+        : text;
+    if (!data)
+        throw new Error('MCP HTTP response was empty');
+    return JSON.parse(data);
+}
+class HttpTransport {
+    config;
+    options;
+    nextId = 1;
+    headers = {};
+    constructor(config, options) {
+        this.config = config;
+        this.options = options;
+        if (!config.url)
+            throw new Error(`${config.transport} transport requires url`);
+    }
+    async getHeaders() {
+        if (Object.keys(this.headers).length === 0) {
+            this.headers = await refreshTokenIfNeeded(this.config, this.options);
+        }
+        return this.headers;
+    }
+    async request(method, params) {
+        const id = this.nextId++;
+        const headers = await this.getHeaders();
+        return httpJson(this.config.url, headers, { jsonrpc: '2.0', id, method, ...(params === undefined ? {} : { params }) }, this.options);
+    }
+    async notify(method, params) {
+        const headers = await this.getHeaders();
+        const bodyText = JSON.stringify({
+            jsonrpc: '2.0',
+            method,
+            ...(params === undefined ? {} : { params }),
+        });
+        logVerbose(this.options, `--> HTTP POST (notify) ${this.config.url}: ${bodyText}`);
+        const response = await fetch(this.config.url, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json, text/event-stream',
+                'Content-Type': 'application/json',
+                ...headers,
+            },
+            body: bodyText,
+        });
+        if (!response.ok)
+            throw new Error(`MCP HTTP notification failed with status ${response.status}`);
+    }
+    async close() { }
+}
+class SseTransport {
+    config;
+    options;
+    nextId = 1;
+    endpointPromise;
+    headers = {};
+    constructor(config, options) {
+        this.config = config;
+        this.options = options;
+        if (!config.url)
+            throw new Error('sse transport requires url');
+    }
+    async getHeaders() {
+        if (Object.keys(this.headers).length === 0) {
+            this.headers = await refreshTokenIfNeeded(this.config, this.options);
+        }
+        return this.headers;
+    }
+    async endpointWithRetry(maxRetries = 2) {
+        let lastError;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                return await this.fetchEndpoint();
+            }
+            catch (err) {
+                lastError = err;
+                logVerbose(this.options, `SSE connection attempt ${attempt} failed: ${messageOf(err)}`);
+                if (attempt < maxRetries) {
+                    await new Promise((r) => setTimeout(r, 100 * attempt));
+                }
+            }
+        }
+        throw lastError instanceof Error ? lastError : new Error(String(lastError));
+    }
+    async fetchEndpoint() {
+        const headers = await this.getHeaders();
+        logVerbose(this.options, `--> SSE connecting to ${this.config.url}...`);
+        const response = await fetch(this.config.url, {
+            headers: { Accept: 'text/event-stream', ...headers },
+        });
+        if (!response.ok || !response.body)
+            throw new Error(`MCP SSE connection failed with status ${response.status}`);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                buffer += decoder.decode(chunk.value, { stream: true });
+                logVerbose(this.options, `<-- SSE stream chunk: ${buffer}`);
+                const event = buffer.match(/(?:^|\r?\n)\r?\n([\s\S]*?)(?:\r?\n\r?\n|$)/);
+                if (!event)
+                    continue;
+                buffer = buffer.slice((event.index ?? 0) + event[0].length);
+                const data = event[1]
+                    .split(/\r?\n/)
+                    .filter((line) => line.startsWith('data:'))
+                    .map((line) => line.slice(5).trim())
+                    .join('\n');
+                if (data) {
+                    const endpointUrl = new URL(data, this.config.url).toString();
+                    logVerbose(this.options, `SSE discovered endpoint: ${endpointUrl}`);
+                    return endpointUrl;
+                }
+            }
+        }
+        finally {
+            await reader.cancel();
+        }
+        throw new Error('MCP SSE stream ended before endpoint event');
+    }
+    async endpoint() {
+        if (!this.endpointPromise) {
+            this.endpointPromise = this.endpointWithRetry();
+        }
+        return this.endpointPromise;
+    }
+    async request(method, params) {
+        const id = this.nextId++;
+        const headers = await this.getHeaders();
+        const targetEndpoint = await this.endpoint();
+        return httpJson(targetEndpoint, headers, { jsonrpc: '2.0', id, method, ...(params === undefined ? {} : { params }) }, this.options);
+    }
+    async notify(method, params) {
+        const headers = await this.getHeaders();
+        const endpoint = await this.endpoint();
+        const bodyText = JSON.stringify({
+            jsonrpc: '2.0',
+            method,
+            ...(params === undefined ? {} : { params }),
+        });
+        logVerbose(this.options, `--> SSE POST (notify) ${endpoint}: ${bodyText}`);
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...headers },
+            body: bodyText,
+        });
+        if (!response.ok)
+            throw new Error(`MCP SSE notification failed with status ${response.status}`);
+    }
+    async close() { }
+}
+export async function connect(config, timeoutMs, options) {
+    const started = Date.now();
+    let transport;
+    try {
+        if (config.transport === 'stdio') {
+            try {
+                transport = new StdioTransport(config, options);
+            }
+            catch (error) {
+                return failed(config, 'failed', 'spawn', messageOf(error), error);
+            }
+        }
+        else if (config.transport === 'sse' || config.transport === 'http') {
+            try {
+                transport =
+                    config.transport === 'sse'
+                        ? new SseTransport(config, options)
+                        : new HttpTransport(config, options);
+            }
+            catch (error) {
+                return failed(config, 'failed', 'spawn', messageOf(error), error);
+            }
+        }
+        else {
+            return failed(config, 'failed', 'spawn', `unsupported transport: ${String(config.transport)}`);
+        }
+        let initialize;
+        try {
+            const response = await withTimeout(transport.request('initialize', {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: CLIENT_INFO,
+            }), timeoutMs, 'initialize handshake');
+            initialize = validateResponse(response, 1);
+            if (!initialize.capabilities || typeof initialize.capabilities !== 'object') {
+                throw new Error('initialize response has no capabilities object');
+            }
+        }
+        catch (error) {
+            const timedOut = messageOf(error).includes('timed out');
+            const message = messageOf(error);
+            return failed(config, timedOut ? 'timeout' : 'failed', message.startsWith('failed to start') ? 'spawn' : 'handshake', message, error);
+        }
+        try {
+            await withTimeout(transport.notify('notifications/initialized'), timeoutMs, 'initialized notification');
+        }
+        catch (error) {
+            return failed(config, messageOf(error).includes('timed out') ? 'timeout' : 'failed', 'capability-negotiation', messageOf(error), error);
+        }
+        try {
+            const tools = normalizeTools(validateResponse(await withTimeout(transport.request('tools/list'), timeoutMs, 'tools/list'), 2));
+            return {
+                server: config,
+                status: 'connected',
+                capabilities: initialize.capabilities,
+                tools,
+                latencyMs: Date.now() - started,
+            };
+        }
+        catch (error) {
+            return failed(config, messageOf(error).includes('timed out') ? 'timeout' : 'failed', 'list-tools', messageOf(error), error);
+        }
+    }
+    catch (error) {
+        return failed(config, 'failed', 'handshake', messageOf(error), error);
+    }
+    finally {
+        await transport?.close().catch(() => undefined);
+    }
+}

package/dist/protocol/index.d.ts

@@ -0,0 +1,3 @@
+import { connect } from './connect.js';
+export declare function registerProtocol(): void;
+export { connect };

package/dist/protocol/index.js

@@ -0,0 +1,6 @@
+import { registerConnectImpl } from '../orchestrator.js';
+import { connect } from './connect.js';
+export function registerProtocol() {
+    registerConnectImpl(connect);
+}
+export { connect };

package/dist/registry.d.ts

@@ -0,0 +1,16 @@
+import type { MCPServerConfig } from './types.js';
+export interface RegistryResolveOptions {
+    timeoutMs?: number;
+    fetchFn?: typeof fetch;
+}
+/**
+ * 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 declare function resolveRegistryServer(registryId: string, options?: RegistryResolveOptions): Promise<MCPServerConfig>;