@sean.holung/minicode 0.3.1 → 0.3.3

package/dist/src/serve/mcp-server.js

@@ -0,0 +1,405 @@
+/**
+ * MCP (Model Context Protocol) server for minicode.
+ *
+ * Exposes minicode's symbol-aware tools and code map as an MCP server,
+ * allowing external agents (e.g. Claude Code) to use minicode's code
+ * intelligence while the web UI visualizes tool activity in real time.
+ */
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { z } from "zod";
+import { getSymbolDisplayName } from "../indexer/symbol-names.js";
+/** Active transports keyed by session ID. */
+const transports = new Map();
+/**
+ * Create and configure an McpServer with minicode's tools and resources.
+ */
+function createMcpServer(bridge, emit) {
+    const server = new McpServer({ name: "minicode", version: "0.2.0" }, { capabilities: { tools: {}, resources: {} } });
+    // ── Helper: wrap tool execution with WebSocket event broadcast ──
+    function wrapToolCall(toolName, input, fn) {
+        const start = Date.now();
+        emit({ type: "tool_call_start", name: toolName, input });
+        return fn().then((result) => {
+            emit({
+                type: "tool_call_end",
+                name: toolName,
+                input,
+                result: typeof result === "string" ? result : JSON.stringify(result),
+                elapsedMs: Date.now() - start,
+            });
+            return result;
+        }, (error) => {
+            emit({
+                type: "tool_call_end",
+                name: toolName,
+                input,
+                result: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                elapsedMs: Date.now() - start,
+            });
+            throw error;
+        });
+    }
+    // ── Tools ──
+    server.tool("read_symbol", "Read a specific function, class, interface, or type by name from the AST index. Returns source code, signature, dependencies, references, and annotations in one call — much more targeted than reading an entire file. PREFERRED over read_file for .ts/.tsx/.js/.jsx when you know the symbol name.", { name: z.string().describe("The symbol name or qualified name (e.g. 'Session' or 'Session.trim')") }, async ({ name }) => {
+        return wrapToolCall("read_symbol", { name }, async () => {
+            const sym = bridge.getSymbol(name);
+            if (!sym) {
+                return { content: [{ type: "text", text: `Symbol "${name}" not found in the project index.` }], isError: true };
+            }
+            const deps = bridge.getDependencies(name, 1);
+            const refs = bridge.getReferences(name);
+            const lines = [
+                `## ${sym.kind}: ${getSymbolDisplayName(sym)}`,
+                `File: ${sym.filePath}:${sym.startLine}`,
+                `Signature: ${sym.signature}`,
+                "",
+            ];
+            if (sym.docComment) {
+                lines.push(sym.docComment, "");
+            }
+            // Read source from file
+            const { readFileSync } = await import("node:fs");
+            try {
+                const fullPath = (await import("node:path")).resolve(bridge.getConfig().workspaceRoot, sym.filePath);
+                const fileContent = readFileSync(fullPath, "utf-8");
+                const fileLines = fileContent.split("\n");
+                const source = fileLines.slice(sym.startLine - 1, sym.endLine).join("\n");
+                lines.push("```", source, "```", "");
+            }
+            catch {
+                lines.push("(source unavailable)", "");
+            }
+            if (deps && deps.length > 0) {
+                lines.push("Dependencies:", ...deps.map((d) => `  - ${d.name} (${d.kind})`), "");
+            }
+            if (refs && refs.length > 0) {
+                lines.push("Referenced by:", ...refs.map((r) => `  - ${r.name ?? r.from} (${r.kind})`), "");
+            }
+            // Append annotations if present
+            const annotations = bridge.getAnnotationsForSymbol(sym.qualifiedName);
+            if (annotations.length > 0) {
+                lines.push(`[User annotation: ${annotations.join("; ")}]`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        });
+    });
+    server.tool("find_references", "Find all symbols that call, import, or reference a given symbol. Essential for understanding impact before making changes.", { name: z.string().describe("The symbol name to find references for") }, async ({ name }) => {
+        return wrapToolCall("find_references", { name }, async () => {
+            const refs = bridge.getReferences(name);
+            if (!refs || refs.length === 0) {
+                return { content: [{ type: "text", text: `No references found for "${name}".` }] };
+            }
+            const lines = [`References to "${name}":`, ...refs.map((r) => `  - ${r.name ?? r.from} (${r.kind})`)];
+            const annotations = bridge.getAnnotationsForSymbol(name);
+            if (annotations.length > 0) {
+                lines.push("", `[User annotation: ${annotations.join("; ")}]`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        });
+    });
+    server.tool("get_dependencies", "Get the dependency cone of a symbol — everything it calls, imports, extends, or references. Essential for understanding implementation and data flow.", {
+        name: z.string().describe("The symbol name to get dependencies for"),
+        depth: z.number().optional().default(2).describe("How many levels deep to traverse (default: 2)"),
+    }, async ({ name, depth }) => {
+        return wrapToolCall("get_dependencies", { name, depth }, async () => {
+            const deps = bridge.getDependencies(name, depth);
+            if (!deps || deps.length === 0) {
+                return { content: [{ type: "text", text: `No dependencies found for "${name}".` }] };
+            }
+            const lines = [
+                `Dependencies of "${name}" (depth=${depth}):`,
+                ...deps.map((d) => `  - ${d.qualifiedName} (${d.kind}) — ${d.filePath}`),
+            ];
+            const annotations = bridge.getAnnotationsForSymbol(name);
+            if (annotations.length > 0) {
+                lines.push("", `[User annotation: ${annotations.join("; ")}]`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        });
+    });
+    server.tool("search_code_map", "Search the project's AST-indexed symbols by name or substring. Returns matching function, class, interface, and type definitions with their file locations and signatures. PREFERRED over generic file search when looking for code symbols.", {
+        query: z.string().describe("Search query — matches against symbol names"),
+        kind: z.string().optional().describe("Filter by kind: function, class, interface, type, variable, method"),
+    }, async ({ query, kind }) => {
+        return wrapToolCall("search_code_map", { query, kind }, async () => {
+            const symbols = bridge.getSymbols();
+            const queryLower = query.toLowerCase();
+            let matches = symbols.filter((s) => {
+                const nameMatch = s.name.toLowerCase().includes(queryLower) ||
+                    s.qualifiedName.toLowerCase().includes(queryLower);
+                return nameMatch;
+            });
+            if (kind) {
+                matches = matches.filter((s) => s.kind === kind);
+            }
+            matches = matches.slice(0, 30);
+            if (matches.length === 0) {
+                return { content: [{ type: "text", text: `No symbols matching "${query}"${kind ? ` (kind: ${kind})` : ""}.` }] };
+            }
+            const lines = [
+                `Found ${matches.length} symbol(s) matching "${query}":`,
+                ...matches.map((s) => `  - ${s.name} (${s.kind}) — ${s.filePath}:${s.startLine}${s.signature ? `\n    ${s.signature}` : ""}`),
+            ];
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        });
+    });
+    server.tool("find_path", "Find the shortest dependency path between two symbols, or trace a symbol back to an entry point. Useful for understanding how code connects.", {
+        from: z.string().describe("Source symbol name"),
+        to: z.string().optional().describe("Target symbol name. If omitted, traces back to the nearest entry point."),
+    }, async ({ from, to }) => {
+        return wrapToolCall("find_path", { from, to }, async () => {
+            if (!bridge.hasIndex()) {
+                return { content: [{ type: "text", text: "No project index available." }], isError: true };
+            }
+            // Use the bridge's project index via getSymbol to verify symbols exist
+            const fromSym = bridge.getSymbol(from);
+            if (!fromSym) {
+                return { content: [{ type: "text", text: `Symbol "${from}" not found.` }], isError: true };
+            }
+            if (to) {
+                const toSym = bridge.getSymbol(to);
+                if (!toSym) {
+                    return { content: [{ type: "text", text: `Symbol "${to}" not found.` }], isError: true };
+                }
+            }
+            // Delegate to the find_path tool via the tool registry
+            // We need the actual ProjectIndex for this, so access it through the bridge's getGraph
+            const graph = bridge.getGraph();
+            if (!graph) {
+                return { content: [{ type: "text", text: "No project graph available." }], isError: true };
+            }
+            // Build adjacency for BFS
+            const adj = new Map();
+            for (const edge of graph.edges) {
+                let list = adj.get(edge.from);
+                if (!list) {
+                    list = [];
+                    adj.set(edge.from, list);
+                }
+                list.push(edge.to);
+                // Reverse direction too for path finding
+                let rList = adj.get(edge.to);
+                if (!rList) {
+                    rList = [];
+                    adj.set(edge.to, rList);
+                }
+                rList.push(edge.from);
+            }
+            const startId = fromSym.qualifiedName;
+            if (to) {
+                const toSym = bridge.getSymbol(to);
+                const endId = toSym.qualifiedName;
+                // BFS shortest path
+                const visited = new Set([startId]);
+                const parent = new Map();
+                const queue = [startId];
+                while (queue.length > 0) {
+                    const current = queue.shift();
+                    if (current === endId)
+                        break;
+                    for (const neighbor of adj.get(current) || []) {
+                        if (!visited.has(neighbor)) {
+                            visited.add(neighbor);
+                            parent.set(neighbor, current);
+                            queue.push(neighbor);
+                        }
+                    }
+                }
+                if (!parent.has(endId) && startId !== endId) {
+                    return { content: [{ type: "text", text: `No path found between "${from}" and "${to}".` }] };
+                }
+                const path = [];
+                let node = endId;
+                while (node !== startId) {
+                    path.unshift(node);
+                    node = parent.get(node);
+                }
+                path.unshift(startId);
+                return { content: [{ type: "text", text: `Path from "${from}" to "${to}" (${path.length} steps):\n${path.map((p, i) => `  ${i + 1}. ${p}`).join("\n")}` }] };
+            }
+            else {
+                // Trace to entry point (exported symbols with no incoming edges)
+                const hasIncoming = new Set();
+                for (const edge of graph.edges) {
+                    hasIncoming.add(edge.to);
+                }
+                const entryPoints = new Set(graph.nodes.filter((n) => n.exported && !hasIncoming.has(n.id)).map((n) => n.id));
+                // BFS from start, looking for any entry point
+                const visited = new Set([startId]);
+                const parent = new Map();
+                const queue = [startId];
+                let foundEntry = null;
+                while (queue.length > 0) {
+                    const current = queue.shift();
+                    if (entryPoints.has(current) && current !== startId) {
+                        foundEntry = current;
+                        break;
+                    }
+                    for (const neighbor of adj.get(current) || []) {
+                        if (!visited.has(neighbor)) {
+                            visited.add(neighbor);
+                            parent.set(neighbor, current);
+                            queue.push(neighbor);
+                        }
+                    }
+                }
+                if (!foundEntry) {
+                    return { content: [{ type: "text", text: `No entry point reachable from "${from}".` }] };
+                }
+                const path = [];
+                let node = foundEntry;
+                while (node !== startId) {
+                    path.unshift(node);
+                    node = parent.get(node);
+                }
+                path.unshift(startId);
+                return { content: [{ type: "text", text: `Path from "${from}" to entry point "${foundEntry}" (${path.length} steps):\n${path.map((p, i) => `  ${i + 1}. ${p}`).join("\n")}` }] };
+            }
+        });
+    });
+    // ── Annotation tools ──
+    server.tool("add_annotation", "Attach a note to a symbol in the project index. Annotations are injected into tool results when interacting with annotated code, and appear in the web UI graph. Use this to leave instructions or context for future interactions.", {
+        symbol: z.string().describe("The symbol name to annotate"),
+        text: z.string().max(500).describe("The annotation text (max 500 chars)"),
+    }, async ({ symbol, text }) => {
+        return wrapToolCall("add_annotation", { symbol, text }, async () => {
+            const success = bridge.addAnnotation(symbol, text);
+            if (!success) {
+                return { content: [{ type: "text", text: `Could not annotate "${symbol}" — symbol not found in the project index.` }], isError: true };
+            }
+            return { content: [{ type: "text", text: `Annotation added to "${symbol}": ${text}` }] };
+        });
+    });
+    server.tool("list_annotations", "List all annotations attached to symbols. Annotations are user-provided notes that guide how code should be handled.", {
+        symbol: z.string().optional().describe("If provided, list annotations for this symbol only. Otherwise list all."),
+    }, async ({ symbol }) => {
+        return wrapToolCall("list_annotations", { symbol }, async () => {
+            if (symbol) {
+                const notes = bridge.getAnnotationsForSymbol(symbol);
+                if (notes.length === 0) {
+                    return { content: [{ type: "text", text: `No annotations for "${symbol}".` }] };
+                }
+                return { content: [{ type: "text", text: `Annotations for "${symbol}":\n${notes.map((n, i) => `  ${i + 1}. ${n}`).join("\n")}` }] };
+            }
+            const all = bridge.getAnnotations();
+            const entries = Object.entries(all);
+            if (entries.length === 0) {
+                return { content: [{ type: "text", text: "No annotations in this session." }] };
+            }
+            const lines = entries.flatMap(([name, notes]) => [
+                `${name}:`,
+                ...notes.map((n, i) => `  ${i + 1}. ${n}`),
+            ]);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        });
+    });
+    // ── Resources ──
+    server.resource("code-map", "minicode://code-map", { description: "Compact project skeleton showing all indexed symbols with their signatures, ranked by importance. Provides a high-level overview of the codebase structure." }, async () => {
+        const codeMap = bridge.getCodeMap();
+        if (!codeMap) {
+            return { contents: [{ uri: "minicode://code-map", text: "No project index available.", mimeType: "text/plain" }] };
+        }
+        return { contents: [{ uri: "minicode://code-map", text: codeMap.text, mimeType: "text/plain" }] };
+    });
+    server.resource("structural-analysis", "minicode://structural-analysis", { description: "Structural analysis of the project: dependency cycles, fan-in/fan-out hotspots, and file coupling findings." }, async () => {
+        const analysis = bridge.getStructuralAnalysis();
+        if (!analysis) {
+            return { contents: [{ uri: "minicode://structural-analysis", text: "No project index available.", mimeType: "text/plain" }] };
+        }
+        const lines = [
+            `# Structural Analysis`,
+            `Symbols: ${analysis.summary.symbolCount} | Files: ${analysis.summary.fileCount} | Findings: ${analysis.summary.findingCount}`,
+            "",
+        ];
+        for (const finding of analysis.findings) {
+            lines.push(`## [${finding.severity.toUpperCase()}] ${finding.title}`, finding.summary, `Type: ${finding.type} | Symbols: ${finding.symbols.join(", ")}`, ...finding.rationale.map((r) => `  - ${r}`), "");
+        }
+        return { contents: [{ uri: "minicode://structural-analysis", text: lines.join("\n"), mimeType: "text/plain" }] };
+    });
+    return server;
+}
+/**
+ * Handle an incoming HTTP request on the /mcp path.
+ * Manages stateful sessions via session ID headers.
+ */
+export async function handleMcpRequest(req, res, bridge, emit) {
+    const sessionId = req.headers["mcp-session-id"];
+    if (req.method === "POST") {
+        // Read request body
+        const body = await new Promise((resolve) => {
+            let data = "";
+            req.on("data", (chunk) => { data += chunk.toString(); });
+            req.on("end", () => resolve(data));
+        });
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32700, message: "Parse error: invalid JSON in request body" }, id: null }));
+            return;
+        }
+        // Check if this is an initialization request (method: "initialize")
+        const parsedObj = parsed;
+        const isInit = Array.isArray(parsedObj)
+            ? parsedObj.some((m) => m.method === "initialize")
+            : parsedObj.method === "initialize";
+        if (isInit) {
+            // Create new transport and server for this session
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+            });
+            const server = createMcpServer(bridge, emit);
+            await server.connect(transport);
+            // Store transport by session ID once we know it
+            transport.onclose = () => {
+                if (transport.sessionId) {
+                    transports.delete(transport.sessionId);
+                }
+            };
+            await transport.handleRequest(req, res, parsed);
+            // After handling, the transport has a session ID
+            if (transport.sessionId) {
+                transports.set(transport.sessionId, transport);
+            }
+            return;
+        }
+        // Existing session
+        if (!sessionId || !transports.has(sessionId)) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid or missing session ID" }));
+            return;
+        }
+        const transport = transports.get(sessionId);
+        await transport.handleRequest(req, res, parsed);
+        return;
+    }
+    if (req.method === "GET") {
+        // SSE stream for server-initiated messages
+        if (!sessionId || !transports.has(sessionId)) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid or missing session ID" }));
+            return;
+        }
+        const transport = transports.get(sessionId);
+        await transport.handleRequest(req, res);
+        return;
+    }
+    if (req.method === "DELETE") {
+        // Session termination
+        if (sessionId && transports.has(sessionId)) {
+            const transport = transports.get(sessionId);
+            await transport.handleRequest(req, res);
+            transports.delete(sessionId);
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+        return;
+    }
+    res.writeHead(405, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Method not allowed" }));
+}

package/dist/src/serve/server.js

@@ -1,3 +1,4 @@
+import process from "node:process";
 import { createServer } from "node:http";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -5,7 +6,10 @@ import { fileURLToPath } from "node:url";
 import { AgentBridge } from "./agent-bridge.js";
 import { createWebSocketServer } from "./websocket.js";
 import { handleChatCompletions, handleModels } from "./openai-compat.js";
-import { formatConfigForDisplay } from "../agent/config.js";
+import { formatConfigForDisplay, getConfigMissing } from "../agent/config.js";
+import { applyPersistedConfigUpdates, buildStructuredConfigPayload } from "../agent/editable-config.js";
+import { sortModelsAlphabetically } from "../model-utils.js";
+import { handleMcpRequest } from "./mcp-server.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Resolve web dir: always serve from dist/src/web (built by scripts/build-web.mjs)
 // In dev (tsx): __dirname = src/serve → go up to project root, then dist/src/web
@@ -52,14 +56,24 @@ async function serveStatic(res, urlPath) {
         res.end("Not Found");
     }
 }
+async function buildWebSettingsPayload(config, minicodeHome) {
+    return buildStructuredConfigPayload(config, minicodeHome);
+}
 /** Create the HTTP request handler. Exported for testing. */
-export function createRequestHandler(bridge) {
+export function createRequestHandler(bridge, emit, options = {}) {
     const config = bridge.getConfig();
+    const emitFn = emit ?? (() => { });
+    const minicodeHome = options.minicodeHome;
     return (req, res) => {
         const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
         const method = req.method ?? "GET";
         const pathname = url.pathname;
         const handle = async () => {
+            // MCP (Model Context Protocol) endpoint
+            if (pathname === "/mcp") {
+                await handleMcpRequest(req, res, bridge, emitFn);
+                return;
+            }
             // OpenAI-compatible routes
             if (pathname === "/v1/models" && method === "GET") {
                 handleModels(req, res);
@@ -71,21 +85,85 @@ export function createRequestHandler(bridge) {
             }
             // Minicode REST API
             if (pathname === "/api/status" && method === "GET") {
+                const missing = getConfigMissing(config);
                 sendJson(res, 200, {
                     status: bridge.isBusy() ? "busy" : "ready",
                     workspace: config.workspaceRoot,
                     model: config.model,
                     provider: config.modelProvider,
+                    needsSetup: missing.length > 0,
+                    missing,
                 });
                 return;
             }
+            if (pathname === "/api/models" && method === "GET") {
+                const models = sortModelsAlphabetically(await bridge.listModels());
+                sendJson(res, 200, { models, activeModel: config.model });
+                return;
+            }
+            if (pathname === "/api/model" && method === "POST") {
+                const body = JSON.parse(await readBody(req));
+                if (!body.model || typeof body.model !== "string") {
+                    sendJson(res, 400, { error: "model is required" });
+                    return;
+                }
+                bridge.switchModel(body.model);
+                sendJson(res, 200, { model: body.model });
+                return;
+            }
+            if (pathname === "/api/context" && method === "GET") {
+                if (!bridge.isReady()) {
+                    sendJson(res, 200, { contextTokens: 0, maxContextTokens: 0 });
+                    return;
+                }
+                const status = bridge.getAgent().getContextStatus();
+                sendJson(res, 200, status);
+                return;
+            }
             if (pathname === "/api/config" && method === "GET") {
-                sendJson(res, 200, { config: formatConfigForDisplay(config) });
+                const structured = await buildWebSettingsPayload(config, minicodeHome);
+                sendJson(res, 200, {
+                    config: formatConfigForDisplay(config),
+                    settings: structured,
+                    restartRequired: true,
+                    secretsUiSupported: false,
+                });
+                return;
+            }
+            if (pathname === "/api/config" && method === "POST") {
+                const body = JSON.parse(await readBody(req));
+                if (!body.updates || typeof body.updates !== "object") {
+                    sendJson(res, 400, { error: "updates object is required" });
+                    return;
+                }
+                try {
+                    const result = await applyPersistedConfigUpdates({
+                        updates: body.updates,
+                        ...(minicodeHome ? { minicodeHome } : {}),
+                    });
+                    const structured = await buildWebSettingsPayload(config, minicodeHome);
+                    sendJson(res, 200, {
+                        ok: true,
+                        scope: "global",
+                        path: result.path,
+                        saved: result.saved,
+                        restartRequired: true,
+                        message: "Persisted config updated. Restart minicode to apply changes to new sessions.",
+                        settings: structured,
+                    });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : "Failed to update config";
+                    sendJson(res, 400, { error: message });
+                }
                 return;
             }
             if (pathname === "/api/sessions" && method === "GET") {
                 const sessions = await bridge.listSess();
-                sendJson(res, 200, { sessions });
+                sendJson(res, 200, {
+                    sessions,
+                    currentSessionId: bridge.getCurrentSessionId(),
+                });
                 return;
             }
             if (pathname === "/api/sessions/save" && method === "POST") {
@@ -175,6 +253,47 @@ export function createRequestHandler(bridge) {
                 sendJson(res, 200, result);
                 return;
             }
+            if (pathname === "/api/analysis" && method === "GET") {
+                const result = bridge.getStructuralAnalysis();
+                if (!result) {
+                    sendJson(res, 404, { error: "No project index available" });
+                    return;
+                }
+                sendJson(res, 200, result);
+                return;
+            }
+            if (pathname === "/api/analysis/explain" && method === "POST") {
+                const body = JSON.parse(await readBody(req));
+                if (!body.findingId || typeof body.findingId !== "string") {
+                    sendJson(res, 400, { error: "findingId is required" });
+                    return;
+                }
+                res.writeHead(200, {
+                    "Content-Type": "text/event-stream",
+                    "Cache-Control": "no-cache",
+                    Connection: "keep-alive",
+                });
+                const abortController = new AbortController();
+                req.on("close", () => abortController.abort());
+                try {
+                    await bridge.explainStructuralFinding(body.findingId, (event) => {
+                        if (!res.writableEnded) {
+                            res.write(`data: ${JSON.stringify(event)}\n\n`);
+                        }
+                    }, abortController.signal);
+                }
+                catch (error) {
+                    if (!res.writableEnded) {
+                        const msg = error instanceof Error ? error.message : "Unknown error";
+                        res.write(`data: ${JSON.stringify({ type: "error", message: msg })}\n\n`);
+                    }
+                }
+                if (!res.writableEnded) {
+                    res.write("data: [DONE]\n\n");
+                    res.end();
+                }
+                return;
+            }
             if (pathname === "/api/focus" && method === "GET") {
                 sendJson(res, 200, { pinned: bridge.getPinnedSymbols() });
                 return;
@@ -307,6 +426,36 @@ export function createRequestHandler(bridge) {
         });
     };
 }
+/** Force-shutdown timeout in ms. If graceful close hasn't finished, exit anyway. */
+const SHUTDOWN_TIMEOUT_MS = 3_000;
+/**
+ * Forcefully shut down the serve process. Terminates all WebSocket clients,
+ * destroys open HTTP sockets, and stops the server. Exported for testing.
+ */
+export function shutdownServe(server, wss, openSockets, exit = (code) => process.exit(code)) {
+    console.log("\nShutting down...");
+    // 1. Terminate every connected WebSocket client immediately.
+    //    wss.close() only stops accepting *new* connections — existing clients
+    //    stay open, which keeps the HTTP server alive (the root cause of #39).
+    for (const client of wss.clients) {
+        client.terminate();
+    }
+    wss.close();
+    // 2. Destroy all open TCP sockets so server.close() can finish.
+    for (const socket of openSockets) {
+        socket.destroy();
+    }
+    openSockets.clear();
+    // 3. Stop accepting new connections and exit once drained.
+    server.close(() => {
+        exit(0);
+    });
+    // 4. Safety net: if something still holds the event loop, force-exit.
+    setTimeout(() => {
+        console.error("Shutdown timed out — forcing exit.");
+        exit(1);
+    }, SHUTDOWN_TIMEOUT_MS).unref();
+}
 export async function runServe(verbose, port) {
     console.log("Initializing agent...");
     // Set up broadcast plumbing
@@ -314,7 +463,7 @@ export async function runServe(verbose, port) {
     const bridge = new AgentBridge((msg) => broadcastFn(msg), verbose);
     await bridge.init();
     const config = bridge.getConfig();
-    const handler = createRequestHandler(bridge);
+    const handler = createRequestHandler(bridge, (msg) => broadcastFn(msg));
     const server = createServer(handler);
     // WebSocket server — captures the real broadcast function
     const wss = createWebSocketServer(server, bridge);
@@ -328,13 +477,18 @@ export async function runServe(verbose, port) {
             }
         }
     };
+    // Track open sockets so we can destroy them on shutdown
+    const openSockets = new Set();
+    server.on("connection", (socket) => {
+        openSockets.add(socket);
+        socket.on("close", () => openSockets.delete(socket));
+    });
+    // Start file watcher for automatic reindexing
+    bridge.startFileWatcher();
     // Graceful shutdown
     process.on("SIGINT", () => {
-        console.log("\nShutting down...");
-        wss.close();
-        server.close(() => {
-            process.exit(0);
-        });
+        bridge.stopFileWatcher();
+        shutdownServe(server, wss, openSockets);
     });
     server.listen(port, "127.0.0.1", () => {
         console.log(`\nminicode serve`);
@@ -342,6 +496,7 @@ export async function runServe(verbose, port) {
         console.log(`  Model:     ${config.model} (${config.modelProvider})`);
         console.log(`  Web UI:    http://localhost:${port}`);
         console.log(`  OpenAI:    http://localhost:${port}/v1`);
+        console.log(`  MCP:       http://localhost:${port}/mcp`);
         console.log(`\nPress Ctrl+C to stop.\n`);
     });
     // Keep alive

package/dist/src/serve/websocket.js

@@ -22,6 +22,14 @@ export function createWebSocketServer(httpServer, bridge) {
             else if (msg.type === "cancel") {
                 bridge.cancel();
             }
+            else if (msg.type === "switch_model") {
+                bridge.switchModel(msg.model);
+                const changed = { type: "model_changed", model: msg.model };
+                // Broadcast to all clients
+                for (const client of wss.clients) {
+                    client.send(JSON.stringify(changed));
+                }
+            }
         });
     });
     return wss;