@kryptosai/mcp-observatory 1.28.2 → 1.28.3

package/dist/src/server.js

@@ -1,657 +1,41 @@
 #!/usr/bin/env node
-import { readdir } from "node:fs/promises";
-import path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { defaultCassettesDirectory, loadCassette, saveCassette } from "./cassette.js";
-import { diffArtifacts } from "./diff.js";
-import { scanForTargets } from "./discovery.js";
-import { detectEnvironment } from "./environment.js";
-import { renderMarkdown } from "./reporters/markdown.js";
-import { errorMessage } from "./utils/errors.js";
-import { runTarget, runTargetRecording } from "./runner.js";
-import { defaultRunsDirectory, readArtifact, writeRunArtifact } from "./storage.js";
-import { compareResponses } from "./verify.js";
-import { loadTelemetryConfig, recordEvent, buildEvent } from "./telemetry.js";
 import { TOOL_VERSION } from "./version.js";
-import { readLockFile, verifyAgainstLock } from "./lockfile.js";
-import { readHistory, getTrend, renderTrendLabel } from "./history.js";
-import { buildCiReport } from "./commands/ci-report.js";
-// ── Security: Command Allowlist ────────────────────────────────────────────
-// MCP server mode is invoked by an LLM, not an operator. Arbitrary command
-// execution would let a prompt-injection attack run anything on the host.
-// Only commands whose base executable appears in this set are permitted.
-const ALLOWED_COMMANDS = new Set([
-    "npx",
-    "node",
-    "python",
-    "python3",
-    "uvx",
-    "docker",
-    "deno",
-    "bun",
-]);
-// ── Security: Argument Validation ──────────────────────────────────────────
-// Reject args containing shell metacharacters that could enable injection.
-const DANGEROUS_ARG_PATTERN = /[;|`]|\$\(|&&|\|\|/;
-export function validateArgs(args) {
-    for (const arg of args) {
-        if (DANGEROUS_ARG_PATTERN.test(arg)) {
-            throw new Error(`Argument "${arg}" contains shell metacharacters and was rejected. ` +
-                `Remove characters like ; | && || $() or backticks.`);
-        }
-    }
-}
-export function validateCommand(command) {
-    const base = path.basename(command.split(/\s+/)[0] ?? "");
-    if (!ALLOWED_COMMANDS.has(base)) {
-        throw new Error(`Command "${base}" is not in the MCP server allowlist. ` +
-            `Allowed executables: ${[...ALLOWED_COMMANDS].join(", ")}. ` +
-            `Use the CLI for arbitrary commands.`);
-    }
-}
-// ── Security: Path Validation ──────────────────────────────────────────────
-// File-reading tools must not traverse outside expected directories.
-export function validatePath(filePath, allowedRoot) {
-    const resolved = path.resolve(filePath);
-    const root = path.resolve(allowedRoot);
-    if (!resolved.startsWith(root + path.sep) && resolved !== root) {
-        throw new Error(`Path "${filePath}" resolves outside allowed directory "${allowedRoot}".`);
-    }
-    return resolved;
-}
-// ── Observability ──────────────────────────────────────────────────────────
-function logRequest(tool, startMs, error, enrichment) {
-    const durationMs = Date.now() - startMs;
-    const status = error ? "ERROR" : "OK";
-    process.stderr.write(`[observatory] ${tool} ${status} ${durationMs}ms\n`);
-    recordEvent(buildEvent("tool_call", tool, "mcp", { executionMs: durationMs, ...enrichment }));
-}
-function formatRun(artifact) {
-    const lines = [];
-    lines.push(`Target: ${artifact.target.targetId}`);
-    lines.push(`Gate: ${artifact.gate}`);
-    lines.push(`Created: ${artifact.createdAt}`);
-    if (artifact.target.serverName) {
-        lines.push(`Server: ${artifact.target.serverName} ${artifact.target.serverVersion ?? ""}`);
-    }
-    lines.push("");
-    for (const check of artifact.checks) {
-        lines.push(`  [${check.status}] ${check.id}: ${check.message}`);
-    }
-    if (artifact.fatalError) {
-        lines.push(`\nFatal error: ${artifact.fatalError}`);
-    }
-    return lines.join("\n");
-}
+import { ensureTelemetryWarm } from "./tools/helpers.js";
+import * as scanTool from "./tools/scan.js";
+import * as checkServerTool from "./tools/check-server.js";
+import * as scoreServerTool from "./tools/score-server.js";
+import * as diffRunsTool from "./tools/diff-runs.js";
+import * as getLastRunTool from "./tools/get-last-run.js";
+import * as suggestServersTool from "./tools/suggest-servers.js";
+import * as recordTool from "./tools/record.js";
+import * as replayTool from "./tools/replay.js";
+import * as verifyTool from "./tools/verify-tool.js";
+import * as watchTool from "./tools/watch.js";
+import * as lockVerifyTool from "./tools/lock-verify.js";
+import * as getHistoryTool from "./tools/get-history.js";
+import * as ciReportTool from "./tools/ci-report.js";
+export { validateArgs, validateCommand, validatePath } from "./utils/security.js";
 export async function startServer() {
-    // Warm telemetry config cache
-    await loadTelemetryConfig();
+    await ensureTelemetryWarm();
     const server = new McpServer({
         name: "mcp-observatory",
         version: TOOL_VERSION,
     });
-    server.tool("scan", "Use this to check if all your MCP servers are healthy. Auto-discovers servers from Claude config files, connects to each one, and verifies tools/prompts/resources respond correctly. Use with deep=true to also invoke tools and confirm they actually execute. Returns pass/fail status for every server.", {
-        config: z.string().optional().describe("Path to a specific MCP config file. If omitted, scans default locations."),
-        deep: z.boolean().optional().describe("Also invoke safe tools to verify they execute."),
-        security: z.boolean().optional().describe("Run security analysis on tool schemas."),
-    }, async ({ config, deep, security }) => {
-        const startMs = Date.now();
-        const targets = await scanForTargets(config);
-        if (targets.length === 0) {
-            logRequest("scan", startMs);
-            return { content: [{ type: "text", text: "No MCP server configs found." }] };
-        }
-        const opts = {};
-        if (deep)
-            opts.invokeTools = true;
-        if (security)
-            opts.securityCheck = true;
-        const lines = [`Discovered ${targets.length} server(s):\n`];
-        for (const t of targets) {
-            if (t.config.targetId === "mcp-observatory")
-                continue;
-            lines.push(`--- ${t.config.targetId} (from ${t.source}) ---`);
-            try {
-                const artifact = await runTarget(t.config, opts);
-                lines.push(formatRun(artifact));
-            }
-            catch (error) {
-                const msg = errorMessage(error);
-                lines.push(`  Error: ${msg}`);
-            }
-            lines.push("");
-        }
-        logRequest("scan", startMs);
-        return { content: [{ type: "text", text: lines.join("\n") }] };
-    });
-    server.tool("check_server", "Use this to test a specific MCP server before installing or after updating it. Launches the server by command, checks all capabilities, and saves a run artifact for future comparison. Example: check_server({ command: 'npx -y @modelcontextprotocol/server-everything' }). Use deep=true to invoke tools, security=true to analyze schemas for vulnerabilities.", {
-        command: z.string().describe("The command to launch the MCP server (e.g. 'npx -y @modelcontextprotocol/server-everything')."),
-        args: z.array(z.string()).optional().describe("Additional arguments for the command."),
-        deep: z.boolean().optional().describe("Also invoke safe tools to verify they execute."),
-        security: z.boolean().optional().describe("Run security analysis on tool schemas."),
-    }, async ({ command, args, deep, security }) => {
-        const startMs = Date.now();
-        try {
-            validateCommand(command);
-            validateArgs(args ?? []);
-            const target = {
-                targetId: command,
-                adapter: "local-process",
-                command,
-                args: args ?? [],
-                timeoutMs: 15_000,
-            };
-            const opts = {};
-            if (deep)
-                opts.invokeTools = true;
-            if (security)
-                opts.securityCheck = true;
-            const artifact = await runTarget(target, opts);
-            const outDir = defaultRunsDirectory();
-            const outPath = await writeRunArtifact(artifact, outDir);
-            logRequest("check_server", startMs);
-            return {
-                content: [{ type: "text", text: `${formatRun(artifact)}\n\nArtifact saved: ${outPath}` }],
-            };
-        }
-        catch (error) {
-            const msg = errorMessage(error);
-            logRequest("check_server", startMs, true);
-            return { content: [{ type: "text", text: `Error checking server: ${msg}` }], isError: true };
-        }
-    });
-    server.tool("score_server", "Use this to get a quick health grade for an MCP server. Runs all checks (capabilities, tool invocation, security) and returns a 0-100 score with A-F grade and detailed breakdown across protocol compliance, schema quality, security, reliability, and performance.", {
-        command: z.string().describe("The command to launch the MCP server."),
-        args: z.array(z.string()).optional().describe("Additional arguments for the command."),
-    }, async ({ command, args }) => {
-        const startMs = Date.now();
-        try {
-            validateCommand(command);
-            validateArgs(args ?? []);
-            const target = {
-                targetId: command,
-                adapter: "local-process",
-                command,
-                args: args ?? [],
-                timeoutMs: 15_000,
-            };
-            const artifact = await runTarget(target, { invokeTools: true, securityCheck: true });
-            const outDir = defaultRunsDirectory();
-            await writeRunArtifact(artifact, outDir);
-            const score = artifact.healthScore;
-            if (!score) {
-                logRequest("score_server", startMs);
-                return { content: [{ type: "text", text: `${formatRun(artifact)}\n\nCould not compute health score.` }] };
-            }
-            const lines = [
-                `MCP Health Score: ${score.overall}/100 (${score.grade})`,
-                "",
-            ];
-            for (const dim of score.dimensions) {
-                lines.push(`  ${dim.name}: ${dim.score}/100 (weight: ${Math.round(dim.weight * 100)}%)`);
-                for (const detail of dim.details) {
-                    lines.push(`    → ${detail}`);
-                }
-            }
-            lines.push("", formatRun(artifact));
-            logRequest("score_server", startMs);
-            return { content: [{ type: "text", text: lines.join("\n") }] };
-        }
-        catch (error) {
-            const msg = errorMessage(error);
-            logRequest("score_server", startMs, true);
-            return { content: [{ type: "text", text: `Error scoring server: ${msg}` }], isError: true };
-        }
-    });
-    server.tool("diff_runs", "Use this to find what changed between two server checks. Compares two run artifacts and surfaces regressions (things that broke), recoveries (things that got fixed), schema drift (added/removed/changed tool parameters), and gate status changes. Essential after updating a server.", {
-        base: z.string().describe("Path to the base run artifact JSON file."),
-        head: z.string().describe("Path to the head run artifact JSON file."),
-        format: z.enum(["markdown", "json"]).optional().describe("Output format: 'markdown' (default) or 'json'."),
-    }, async ({ base, head, format }) => {
-        const startMs = Date.now();
-        try {
-            const runsDir = defaultRunsDirectory();
-            const basePath = validatePath(base, runsDir);
-            const headPath = validatePath(head, runsDir);
-            const baseArtifact = await readArtifact(basePath);
-            const headArtifact = await readArtifact(headPath);
-            if (baseArtifact.artifactType !== "run" || headArtifact.artifactType !== "run") {
-                return { content: [{ type: "text", text: "Both files must be run artifacts (not diff artifacts)." }], isError: true };
-            }
-            const diff = diffArtifacts(baseArtifact, headArtifact);
-            const output = format === "json"
-                ? JSON.stringify(diff, null, 2)
-                : renderMarkdown(diff);
-            logRequest("diff_runs", startMs);
-            return { content: [{ type: "text", text: output }] };
-        }
-        catch (error) {
-            const msg = errorMessage(error);
-            logRequest("diff_runs", startMs, true);
-            return { content: [{ type: "text", text: `Error diffing runs: ${msg}` }], isError: true };
-        }
-    });
-    server.tool("get_last_run", "Use this to retrieve the last check results for a server. Finds the most recent run artifact by target ID so you can review previous results or diff against a new run.", {
-        targetId: z.string().describe("The target ID to find the last run for (e.g. server name or command)."),
-    }, async ({ targetId }) => {
-        const startMs = Date.now();
-        try {
-            const dir = defaultRunsDirectory();
-            let files;
-            try {
-                files = await readdir(dir);
-            }
-            catch {
-                return { content: [{ type: "text", text: `No runs directory found at ${dir}` }], isError: true };
-            }
-            const needle = targetId.toLowerCase();
-            const matching = files
-                .filter((f) => f.endsWith(".json") && f.toLowerCase().includes(needle))
-                .sort()
-                .reverse();
-            if (matching.length === 0) {
-                return { content: [{ type: "text", text: `No run artifacts found for target "${targetId}" in ${dir}` }] };
-            }
-            const latest = matching[0];
-            const artifact = await readArtifact(path.join(dir, latest));
-            if (artifact.artifactType !== "run") {
-                return { content: [{ type: "text", text: `Latest matching file is not a run artifact: ${latest}` }], isError: true };
-            }
-            logRequest("get_last_run", startMs);
-            return {
-                content: [{ type: "text", text: `${formatRun(artifact)}\n\nFile: ${path.join(dir, latest)}` }],
-            };
-        }
-        catch (error) {
-            const msg = errorMessage(error);
-            logRequest("get_last_run", startMs, true);
-            return { content: [{ type: "text", text: `Error reading last run: ${msg}` }], isError: true };
-        }
-    });
-    server.tool("suggest_servers", "Use this when setting up a project or wondering what MCP servers to add. Scans the working directory for languages, frameworks, databases, and cloud providers, lists currently configured servers, and cross-references the MCP registry to recommend servers you're missing.", {
-        cwd: z.string().optional().describe("Working directory to scan for environment signals. Defaults to process.cwd()."),
-    }, async ({ cwd }) => {
-        const startMs = Date.now();
-        const workDir = cwd ?? process.cwd();
-        // Constrain to cwd subtree
-        const resolvedDir = path.resolve(workDir);
-        const cwdRoot = path.resolve(process.cwd());
-        if (!resolvedDir.startsWith(cwdRoot + path.sep) && resolvedDir !== cwdRoot) {
-            logRequest("suggest_servers", startMs, true);
-            return { content: [{ type: "text", text: `Path "${cwd}" resolves outside the working directory.` }], isError: true };
-        }
-        const sections = [];
-        // 1. Current MCP servers
-        try {
-            const targets = await scanForTargets();
-            if (targets.length > 0) {
-                const serverLines = targets.map((t) => {
-                    const id = t.config.targetId;
-                    const detail = t.config.adapter === "http"
-                        ? `(HTTP: ${t.config.url})`
-                        : `(command: ${t.config.command} ${t.config.args.join(" ")})`;
-                    return `  - ${id} ${detail} [source: ${t.source}]`;
-                });
-                sections.push(`## Currently Configured MCP Servers\n${serverLines.join("\n")}`);
-            }
-            else {
-                sections.push("## Currently Configured MCP Servers\nNone found.");
-            }
-        }
-        catch (error) {
-            const msg = errorMessage(error);
-            sections.push(`## Currently Configured MCP Servers\nError scanning: ${msg}`);
-        }
-        // 2. Environment detection
-        try {
-            const env = await detectEnvironment(workDir);
-            const envLines = [];
-            if (env.languages.length > 0)
-                envLines.push(`  Languages: ${env.languages.join(", ")}`);
-            if (env.frameworks.length > 0)
-                envLines.push(`  Frameworks: ${env.frameworks.join(", ")}`);
-            if (env.databases.length > 0)
-                envLines.push(`  Databases: ${env.databases.join(", ")}`);
-            if (env.cloud.length > 0)
-                envLines.push(`  Cloud: ${env.cloud.join(", ")}`);
-            if (env.cicd.length > 0)
-                envLines.push(`  CI/CD: ${env.cicd.join(", ")}`);
-            if (env.services.length > 0)
-                envLines.push(`  Services (detected from .env keys): ${env.services.join(", ")}`);
-            if (envLines.length > 0) {
-                sections.push(`## Detected Environment (${workDir})\n${envLines.join("\n")}`);
-            }
-            else {
-                sections.push(`## Detected Environment (${workDir})\nNo recognizable project signals found.`);
-            }
-        }
-        catch (error) {
-            const msg = errorMessage(error);
-            sections.push(`## Detected Environment\nError: ${msg}`);
-        }
-        // 3. MCP Registry
-        try {
-            const registryUrl = "https://registry.modelcontextprotocol.io/v0/servers";
-            const response = await fetch(registryUrl, {
-                signal: AbortSignal.timeout(10_000),
-                headers: { "Accept": "application/json" },
-            });
-            if (response.ok) {
-                const data = await response.json();
-                function formatRegistryEntry(entry) {
-                    // Registry returns { server: { name, description, ... }, ... }
-                    const srv = (typeof entry["server"] === "object" && entry["server"] !== null
-                        ? entry["server"] : entry);
-                    const rawName = srv["name"] ?? entry["name"] ?? entry["id"];
-                    const name = typeof rawName === "string" ? rawName : "unknown";
-                    const rawDesc = srv["description"] ?? entry["description"];
-                    const desc = typeof rawDesc === "string" ? ` — ${rawDesc}` : "";
-                    return `  - ${name}${desc}`;
-                }
-                if (Array.isArray(data)) {
-                    const entries = data.slice(0, 50);
-                    const registryLines = entries.map(formatRegistryEntry);
-                    sections.push(`## MCP Registry (${String(entries.length)} of ${String(data.length)} servers shown)\n${registryLines.join("\n")}`);
-                }
-                else if (typeof data === "object" && data !== null) {
-                    const obj = data;
-                    const servers = obj["servers"] ?? obj["results"] ?? obj["items"];
-                    if (Array.isArray(servers)) {
-                        const entries = servers.slice(0, 50);
-                        const registryLines = entries.map(formatRegistryEntry);
-                        sections.push(`## MCP Registry (${String(entries.length)} of ${String(servers.length)} servers shown)\n${registryLines.join("\n")}`);
-                    }
-                    else {
-                        sections.push(`## MCP Registry\nRegistry returned data but in an unexpected format. Keys: ${Object.keys(obj).join(", ")}`);
-                    }
-                }
-            }
-            else {
-                sections.push(`## MCP Registry\nRegistry returned HTTP ${String(response.status)}. The listing endpoint may not be publicly available.`);
-            }
-        }
-        catch (error) {
-            const msg = errorMessage(error);
-            sections.push(`## MCP Registry\nCould not reach registry: ${msg}`);
-        }
-        logRequest("suggest_servers", startMs);
-        return { content: [{ type: "text", text: sections.join("\n\n") }] };
-    });
-    server.tool("record", "Use this to capture a baseline of a working MCP server. Records all JSON-RPC traffic to a cassette file that can be replayed offline (no server needed) or used to verify future versions haven't broken anything. Like VCR for MCP.", {
-        command: z.string().describe("The command to launch the MCP server."),
-        args: z.array(z.string()).optional().describe("Additional arguments for the command."),
-    }, async ({ command, args }) => {
-        const startMs = Date.now();
-        try {
-            validateCommand(command);
-            validateArgs(args ?? []);
-            const target = {
-                targetId: command,
-                adapter: "local-process",
-                command,
-                args: args ?? [],
-                timeoutMs: 15_000,
-            };
-            const { artifact, cassetteEntries } = await runTargetRecording(target, { invokeTools: true });
-            if (!cassetteEntries || cassetteEntries.length === 0) {
-                return { content: [{ type: "text", text: "No traffic recorded." }], isError: true };
-            }
-            const cassette = {
-                version: 1,
-                targetId: target.targetId,
-                recordedAt: new Date().toISOString(),
-                transport: "stdio",
-                entries: cassetteEntries,
-            };
-            const cassettePath = await saveCassette(cassette, defaultCassettesDirectory());
-            logRequest("record", startMs);
-            return {
-                content: [{ type: "text", text: `${formatRun(artifact)}\n\nCassette saved: ${cassettePath}\n${cassetteEntries.length} entries recorded.\n\nReplay offline: replay({ cassette: "${cassettePath}" })\nVerify live: verify({ cassette: "${cassettePath}", command: "${command}" })` }],
-            };
-        }
-        catch (error) {
-            const msg = errorMessage(error);
-            logRequest("record", startMs, true);
-            return { content: [{ type: "text", text: `Error recording: ${msg}` }], isError: true };
-        }
-    });
-    server.tool("replay", "Use this to test a server without running it. Replays a previously recorded cassette offline and runs all checks against the recorded responses. Useful in CI or when the live server is unavailable.", {
-        cassette: z.string().describe("Path to a cassette JSON file."),
-    }, async ({ cassette: cassettePath }) => {
-        const startMs = Date.now();
-        try {
-            const cassettesDir = defaultCassettesDirectory();
-            validatePath(cassettePath, cassettesDir);
-            const { ReplayTransport } = await import("./transport/replay-transport.js");
-            const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
-            const { runToolsCheck } = await import("./checks/tools.js");
-            const { runPromptsCheck } = await import("./checks/prompts.js");
-            const { runResourcesCheck } = await import("./checks/resources.js");
-            const { runToolsInvokeCheck } = await import("./checks/tools-invoke.js");
-            const cassette = await loadCassette(cassettePath);
-            const replayTransport = new ReplayTransport(cassette.entries);
-            const client = new Client({ name: "mcp-observatory", version: TOOL_VERSION }, { capabilities: {} });
-            await client.connect(replayTransport);
-            const checkContext = {
-                client,
-                serverCapabilities: client.getServerCapabilities(),
-                target: { targetId: cassette.targetId, adapter: "local-process", command: "replay", args: [] },
-                timeoutMs: 10_000,
-                stderrLines: [],
-            };
-            const checks = [
-                (await runToolsCheck(checkContext)).result,
-                (await runPromptsCheck(checkContext)).result,
-                (await runResourcesCheck(checkContext)).result,
-                (await runToolsInvokeCheck(checkContext)).result,
-            ];
-            await client.close();
-            const lines = [`Replay of ${cassette.targetId} (${cassette.entries.length} entries):\n`];
-            for (const check of checks) {
-                lines.push(`  [${check.status}] ${check.id}: ${check.message}`);
-            }
-            logRequest("replay", startMs);
-            return { content: [{ type: "text", text: lines.join("\n") }] };
-        }
-        catch (error) {
-            const msg = errorMessage(error);
-            logRequest("replay", startMs, true);
-            return { content: [{ type: "text", text: `Error replaying: ${msg}` }], isError: true };
-        }
-    });
-    server.tool("verify", "Use this after updating a server to confirm nothing broke. Connects to the live server, sends the same requests from a recorded cassette, and compares responses. Reports exactly what changed — added tools, removed parameters, different response shapes.", {
-        cassette: z.string().describe("Path to a cassette JSON file."),
-        command: z.string().describe("The command to launch the MCP server."),
-        args: z.array(z.string()).optional().describe("Additional arguments for the command."),
-    }, async ({ cassette: cassettePath, command, args }) => {
-        const startMs = Date.now();
-        try {
-            validateCommand(command);
-            const cassettesDir = defaultCassettesDirectory();
-            validatePath(cassettePath, cassettesDir);
-            const cassette = await loadCassette(cassettePath);
-            const target = {
-                targetId: command,
-                adapter: "local-process",
-                command,
-                args: args ?? [],
-                timeoutMs: 15_000,
-            };
-            const { cassetteEntries } = await runTargetRecording(target, { invokeTools: true });
-            if (!cassetteEntries) {
-                return { content: [{ type: "text", text: "Failed to record live session for comparison." }], isError: true };
-            }
-            const result = compareResponses(cassette, cassetteEntries);
-            const lines = [`Verify: ${result.passed} passed, ${result.failed} changed, ${result.missing} missing\n`];
-            for (const entry of result.entries) {
-                const icon = entry.status === "pass" ? "✓" : entry.status === "fail" ? "✗" : "?";
-                lines.push(`  ${icon} ${entry.method}${entry.diff ? ` — ${entry.diff}` : ""}`);
-            }
-            logRequest("verify", startMs);
-            return { content: [{ type: "text", text: lines.join("\n") }] };
-        }
-        catch (error) {
-            const msg = errorMessage(error);
-            logRequest("verify", startMs, true);
-            return { content: [{ type: "text", text: `Error verifying: ${msg}` }], isError: true };
-        }
-    });
-    server.tool("watch", "Use this to check a server and see what changed since the last check. Runs all checks, saves the result, and diffs against the previous run for the same target. Shows regressions, recoveries, and schema drift in one call.", {
-        command: z.string().describe("The command to launch the MCP server."),
-        args: z.array(z.string()).optional().describe("Additional arguments for the command."),
-    }, async ({ command, args }) => {
-        const startMs = Date.now();
-        try {
-            validateCommand(command);
-            validateArgs(args ?? []);
-            const target = {
-                targetId: command,
-                adapter: "local-process",
-                command,
-                args: args ?? [],
-                timeoutMs: 15_000,
-            };
-            // Run current check
-            const artifact = await runTarget(target);
-            const outDir = defaultRunsDirectory();
-            const outPath = await writeRunArtifact(artifact, outDir);
-            // Find previous run to diff against
-            let diffText = "";
-            try {
-                const files = await readdir(outDir);
-                const needle = target.targetId.toLowerCase();
-                const matching = files
-                    .filter((f) => f.endsWith(".json") && f.toLowerCase().includes(needle) && path.join(outDir, f) !== outPath)
-                    .sort()
-                    .reverse();
-                if (matching.length > 0) {
-                    const prevArtifact = await readArtifact(path.join(outDir, matching[0]));
-                    if (prevArtifact.artifactType === "run") {
-                        const diff = diffArtifacts(prevArtifact, artifact);
-                        if (diff.summary.regressions > 0 || diff.summary.recoveries > 0 || diff.summary.added > 0 || diff.summary.removed > 0) {
-                            diffText = `\n\nChanges since last run:\n${renderMarkdown(diff)}`;
-                        }
-                        else {
-                            diffText = "\n\nNo changes since last run.";
-                        }
-                    }
-                }
-            }
-            catch {
-                // No previous run — that's fine
-            }
-            logRequest("watch", startMs);
-            return {
-                content: [{ type: "text", text: `${formatRun(artifact)}\n\nArtifact saved: ${outPath}${diffText}` }],
-            };
-        }
-        catch (error) {
-            const msg = errorMessage(error);
-            logRequest("watch", startMs, true);
-            return { content: [{ type: "text", text: `Error watching: ${msg}` }], isError: true };
-        }
-    });
-    server.tool("lock_verify", "Verify that live MCP servers still match a previously saved lock file. Detects schema drift, added/removed tools, and breaking changes.", {
-        config: z.string().optional().describe("Path to MCP config file."),
-    }, async ({ config }) => {
-        const startMs = Date.now();
-        try {
-            const lockFile = await readLockFile();
-            const targets = await scanForTargets(config);
-            const results = [];
-            let anyFailed = false;
-            for (const t of targets) {
-                const lockEntry = lockFile.servers.find(s => s.targetId === t.config.targetId);
-                if (!lockEntry)
-                    continue;
-                const artifact = await runTarget(t.config);
-                const result = verifyAgainstLock(lockEntry, artifact);
-                if (result.passed) {
-                    results.push(`✓ ${t.config.targetId}: no drift`);
-                }
-                else {
-                    anyFailed = true;
-                    results.push(`✗ ${t.config.targetId}: ${result.drift.length} changes`);
-                    for (const d of result.drift) {
-                        results.push(`  - ${d.category}: ${d.name} — ${d.change}`);
-                    }
-                }
-            }
-            if (results.length === 0) {
-                results.push("No servers in lock file match discovered targets.");
-            }
-            logRequest("lock_verify", startMs, anyFailed);
-            return { content: [{ type: "text", text: results.join("\n") }] };
-        }
-        catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            logRequest("lock_verify", startMs, true);
-            return { content: [{ type: "text", text: `Lock verify failed: ${msg}` }], isError: true };
-        }
-    });
-    server.tool("get_history", "Get health score trends for MCP servers from run history.", {
-        target: z.string().optional().describe("Filter to a specific target ID."),
-    }, async ({ target }) => {
-        const startMs = Date.now();
-        try {
-            const history = await readHistory();
-            let targetIds = [...new Set(history.entries.map(e => e.targetId))];
-            if (target)
-                targetIds = targetIds.filter(id => id === target);
-            if (targetIds.length === 0) {
-                logRequest("get_history", startMs);
-                return { content: [{ type: "text", text: "No history found. Run a scan or test first." }] };
-            }
-            const lines = [];
-            for (const id of targetIds) {
-                const trend = getTrend(id, history);
-                if (!trend)
-                    continue;
-                const { current } = trend;
-                const label = renderTrendLabel(trend);
-                lines.push(`${id}: ${current.grade} (${current.healthScore}) ${label}`);
-            }
-            logRequest("get_history", startMs);
-            return { content: [{ type: "text", text: lines.join("\n") }] };
-        }
-        catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            logRequest("get_history", startMs, true);
-            return { content: [{ type: "text", text: `History failed: ${msg}` }], isError: true };
-        }
-    });
-    server.tool("ci_report", "Generate a CI regression report from run artifacts.", {
-        artifactsDir: z.string().optional().describe("Directory containing run artifacts. Defaults to .mcp-observatory/runs/"),
-    }, async ({ artifactsDir }) => {
-        const startMs = Date.now();
-        try {
-            const { readdir, readFile } = await import("node:fs/promises");
-            const dir = artifactsDir ?? path.join(process.cwd(), ".mcp-observatory", "runs");
-            const files = await readdir(dir);
-            const artifacts = [];
-            for (const f of files) {
-                if (!f.endsWith(".json"))
-                    continue;
-                try {
-                    const raw = await readFile(path.join(dir, f), "utf8");
-                    const parsed = JSON.parse(raw);
-                    if (parsed["artifactType"] === "run")
-                        artifacts.push(parsed);
-                }
-                catch { /* skip invalid */ }
-            }
-            const report = buildCiReport(artifacts);
-            logRequest("ci_report", startMs);
-            return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
-        }
-        catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            logRequest("ci_report", startMs, true);
-            return { content: [{ type: "text", text: `CI report failed: ${msg}` }], isError: true };
-        }
-    });
+    server.tool(scanTool.name, scanTool.description, scanTool.schema, scanTool.handler);
+    server.tool(checkServerTool.name, checkServerTool.description, checkServerTool.schema, checkServerTool.handler);
+    server.tool(scoreServerTool.name, scoreServerTool.description, scoreServerTool.schema, scoreServerTool.handler);
+    server.tool(diffRunsTool.name, diffRunsTool.description, diffRunsTool.schema, diffRunsTool.handler);
+    server.tool(getLastRunTool.name, getLastRunTool.description, getLastRunTool.schema, getLastRunTool.handler);
+    server.tool(suggestServersTool.name, suggestServersTool.description, suggestServersTool.schema, suggestServersTool.handler);
+    server.tool(recordTool.name, recordTool.description, recordTool.schema, recordTool.handler);
+    server.tool(replayTool.name, replayTool.description, replayTool.schema, replayTool.handler);
+    server.tool(verifyTool.name, verifyTool.description, verifyTool.schema, verifyTool.handler);
+    server.tool(watchTool.name, watchTool.description, watchTool.schema, watchTool.handler);
+    server.tool(lockVerifyTool.name, lockVerifyTool.description, lockVerifyTool.schema, lockVerifyTool.handler);
+    server.tool(getHistoryTool.name, getHistoryTool.description, getHistoryTool.schema, getHistoryTool.handler);
+    server.tool(ciReportTool.name, ciReportTool.description, ciReportTool.schema, ciReportTool.handler);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }