gitnexus 1.3.2 → 1.3.4

package/dist/mcp/local/local-backend.js

@@ -8,7 +8,8 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { initKuzu, executeQuery, closeKuzu, isKuzuReady } from '../core/kuzu-adapter.js';
-import { embedQuery, getEmbeddingDims, disposeEmbedder } from '../core/embedder.js';
+// Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
+// at MCP server startup — crashes on unsupported Node ABI versions (#89)
 // git utilities available if needed
 // import { isGitRepo, getCurrentCommit, getGitRoot } from '../../storage/git.js';
 import { listRegisteredRepos, } from '../../storage/repo-manager.js';
@@ -506,6 +507,7 @@ export class LocalBackend {
             const tableCheck = await executeQuery(repo.id, `MATCH (e:CodeEmbedding) RETURN COUNT(*) AS cnt LIMIT 1`);
             if (!tableCheck.length || (tableCheck[0].cnt ?? tableCheck[0][0]) === 0)
                 return [];
+            const { embedQuery, getEmbeddingDims } = await import('../core/embedder.js');
             const queryVec = await embedQuery(query);
             const dims = getEmbeddingDims();
             const queryVecStr = `[${queryVec.join(',')}]`;
@@ -901,29 +903,29 @@ export class LocalBackend {
     async detectChanges(repo, params) {
         await this.ensureInitialized(repo.id);
         const scope = params.scope || 'unstaged';
-        const { execSync } = await import('child_process');
-        // Build git diff command based on scope
-        let diffCmd;
+        const { execFileSync } = await import('child_process');
+        // Build git diff args based on scope (using execFileSync to avoid shell injection)
+        let diffArgs;
         switch (scope) {
             case 'staged':
-                diffCmd = 'git diff --staged --name-only';
+                diffArgs = ['diff', '--staged', '--name-only'];
                 break;
             case 'all':
-                diffCmd = 'git diff HEAD --name-only';
+                diffArgs = ['diff', 'HEAD', '--name-only'];
                 break;
             case 'compare':
                 if (!params.base_ref)
                     return { error: 'base_ref is required for "compare" scope' };
-                diffCmd = `git diff ${params.base_ref} --name-only`;
+                diffArgs = ['diff', params.base_ref, '--name-only'];
                 break;
             case 'unstaged':
             default:
-                diffCmd = 'git diff --name-only';
+                diffArgs = ['diff', '--name-only'];
                 break;
         }
         let changedFiles;
         try {
-            const output = execSync(diffCmd, { cwd: repo.repoPath, encoding: 'utf-8' });
+            const output = execFileSync('git', diffArgs, { cwd: repo.repoPath, encoding: 'utf-8' });
             changedFiles = output.trim().split('\n').filter(f => f.length > 0);
         }
         catch (err) {
@@ -1077,9 +1079,15 @@ export class LocalBackend {
         const graphFiles = new Set([sym.filePath, ...allIncoming.map(r => r.filePath)].filter(Boolean));
         // Simple text search across the repo for the old name (in files not already covered by graph)
         try {
-            const { execSync } = await import('child_process');
-            const rgCmd = `rg -l --type-add "code:*.{ts,tsx,js,jsx,py,go,rs,java}" -t code "\\b${oldName}\\b" .`;
-            const output = execSync(rgCmd, { cwd: repo.repoPath, encoding: 'utf-8', timeout: 5000 });
+            const { execFileSync } = await import('child_process');
+            const rgArgs = [
+                '-l',
+                '--type-add', 'code:*.{ts,tsx,js,jsx,py,go,rs,java}',
+                '-t', 'code',
+                `\\b${oldName}\\b`,
+                '.',
+            ];
+            const output = execFileSync('rg', rgArgs, { cwd: repo.repoPath, encoding: 'utf-8', timeout: 5000 });
             const files = output.trim().split('\n').filter(f => f.length > 0);
             for (const file of files) {
                 const normalizedFile = file.replace(/\\/g, '/').replace(/^\.\//, '');
@@ -1408,7 +1416,11 @@ export class LocalBackend {
     }
     async disconnect() {
         await closeKuzu(); // close all connections
-        await disposeEmbedder();
+        // Note: we intentionally do NOT call disposeEmbedder() here.
+        // ONNX Runtime's native cleanup segfaults on macOS and some Linux configs,
+        // and importing the embedder module on Node v24+ crashes if onnxruntime
+        // was never loaded during the session. Since process.exit(0) follows
+        // immediately after disconnect(), the OS reclaims everything. See #38, #89.
         this.repos.clear();
         this.contextCache.clear();
         this.initializedRepos.clear();

package/dist/mcp/server.d.ts

@@ -10,5 +10,14 @@
  * Tools: list_repos, query, cypher, context, impact, detect_changes, rename
  * Resources: repos, repo/{name}/context, repo/{name}/clusters, ...
  */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { LocalBackend } from './local/local-backend.js';
+/**
+ * Create a configured MCP Server with all handlers registered.
+ * Transport-agnostic — caller connects the desired transport.
+ */
+export declare function createMCPServer(backend: LocalBackend): Server;
+/**
+ * Start the MCP server on stdio transport (for CLI use).
+ */
 export declare function startMCPServer(backend: LocalBackend): Promise<void>;

package/dist/mcp/server.js

@@ -54,7 +54,11 @@ function getNextStepHint(toolName, args) {
             return '';
     }
 }
-export async function startMCPServer(backend) {
+/**
+ * Create a configured MCP Server with all handlers registered.
+ * Transport-agnostic — caller connects the desired transport.
+ */
+export function createMCPServer(backend) {
     const server = new Server({
         name: 'gitnexus',
         version: '1.1.9',
@@ -212,7 +216,7 @@ Present the analysis as a clear risk report.`,
 Follow these steps:
 1. READ \`gitnexus://repo/${repo || '{name}'}/context\` for codebase stats
 2. READ \`gitnexus://repo/${repo || '{name}'}/clusters\` to see all functional areas
-3. READ \`gitnexus://repo/${repo || '{name}'}/processes\` to see all execution flows  
+3. READ \`gitnexus://repo/${repo || '{name}'}/processes\` to see all execution flows
 4. For the top 5 most important processes, READ \`gitnexus://repo/${repo || '{name}'}/process/{name}\` for step-by-step traces
 5. Generate a mermaid architecture diagram showing the major areas and their connections
 6. Write an ARCHITECTURE.md file with: overview, functional areas, key execution flows, and the mermaid diagram`,
@@ -223,6 +227,13 @@ Follow these steps:
         }
         throw new Error(`Unknown prompt: ${name}`);
     });
+    return server;
+}
+/**
+ * Start the MCP server on stdio transport (for CLI use).
+ */
+export async function startMCPServer(backend) {
+    const server = createMCPServer(backend);
     // Connect to stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/mcp/staleness.js

@@ -4,14 +4,14 @@
  * Checks if the GitNexus index is behind the current git HEAD.
  * Returns a hint for the LLM to call analyze if stale.
  */
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 /**
  * Check how many commits the index is behind HEAD
  */
 export function checkStaleness(repoPath, lastCommit) {
     try {
         // Get count of commits between lastCommit and HEAD
-        const result = execSync(`git rev-list --count ${lastCommit}..HEAD`, { cwd: repoPath, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const result = execFileSync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], { cwd: repoPath, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
         const commitsBehind = parseInt(result, 10) || 0;
         if (commitsBehind > 0) {
             return {

package/dist/server/api.d.ts

@@ -1,8 +1,10 @@
 /**
- * HTTP API Server (Multi-Repo)
+ * HTTP API Server
  *
- * REST API for browser-based clients to query indexed repositories.
- * Uses LocalBackend for multi-repo support via the global registry —
- * the same backend the MCP server uses.
+ * REST API for browser-based clients to query the local .gitnexus/ index.
+ * Also hosts the MCP server over StreamableHTTP for remote AI tool access.
+ *
+ * Security: binds to 127.0.0.1 by default (use --host to override).
+ * CORS is restricted to localhost and the deployed site.
  */
-export declare const createServer: (port: number) => Promise<void>;
+export declare const createServer: (port: number, host?: string) => Promise<void>;

package/dist/server/api.js

@@ -1,21 +1,26 @@
 /**
- * HTTP API Server (Multi-Repo)
+ * HTTP API Server
  *
- * REST API for browser-based clients to query indexed repositories.
- * Uses LocalBackend for multi-repo support via the global registry —
- * the same backend the MCP server uses.
+ * REST API for browser-based clients to query the local .gitnexus/ index.
+ * Also hosts the MCP server over StreamableHTTP for remote AI tool access.
+ *
+ * Security: binds to 127.0.0.1 by default (use --host to override).
+ * CORS is restricted to localhost and the deployed site.
  */
 import express from 'express';
 import cors from 'cors';
 import path from 'path';
 import fs from 'fs/promises';
-import { LocalBackend } from '../mcp/local/local-backend.js';
+import { loadMeta, listRegisteredRepos } from '../storage/repo-manager.js';
+import { executeQuery, closeKuzu, withKuzuDb } from '../core/kuzu/kuzu-adapter.js';
 import { NODE_TABLES } from '../core/kuzu/schema.js';
-/**
- * Build the full knowledge graph for a repo by querying each node table
- * and all relationships via the backend's cypher tool.
- */
-const buildGraph = async (backend, repoName) => {
+import { searchFTSFromKuzu } from '../core/search/bm25-index.js';
+import { hybridSearch } from '../core/search/hybrid-search.js';
+// Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
+// at server startup — crashes on unsupported Node ABI versions (#89)
+import { LocalBackend } from '../mcp/local/local-backend.js';
+import { mountMCPEndpoints } from './mcp-http.js';
+const buildGraph = async () => {
     const nodes = [];
     for (const table of NODE_TABLES) {
         try {
@@ -35,9 +40,7 @@ const buildGraph = async (backend, repoName) => {
             else {
                 query = `MATCH (n:${table}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content`;
             }
-            const result = await backend.executeCypher(repoName, query);
-            // cypher returns the rows directly (array), or { error } on failure
-            const rows = Array.isArray(result) ? result : [];
+            const rows = await executeQuery(query);
             for (const row of rows) {
                 nodes.push({
                     id: row.id ?? row[0],
@@ -65,47 +68,43 @@ const buildGraph = async (backend, repoName) => {
         }
     }
     const relationships = [];
-    try {
-        const relResult = await backend.executeCypher(repoName, `MATCH (a)-[r:CodeRelation]->(b) RETURN a.id AS sourceId, b.id AS targetId, r.type AS type, r.confidence AS confidence, r.reason AS reason, r.step AS step`);
-        const relRows = Array.isArray(relResult) ? relResult : [];
-        for (const row of relRows) {
-            relationships.push({
-                id: `${row.sourceId}_${row.type}_${row.targetId}`,
-                type: row.type,
-                sourceId: row.sourceId,
-                targetId: row.targetId,
-                confidence: row.confidence,
-                reason: row.reason,
-                step: row.step,
-            });
-        }
-    }
-    catch (err) {
-        console.warn('GitNexus: relationship query failed:', err?.message);
+    const relRows = await executeQuery(`MATCH (a)-[r:CodeRelation]->(b) RETURN a.id AS sourceId, b.id AS targetId, r.type AS type, r.confidence AS confidence, r.reason AS reason, r.step AS step`);
+    for (const row of relRows) {
+        relationships.push({
+            id: `${row.sourceId}_${row.type}_${row.targetId}`,
+            type: row.type,
+            sourceId: row.sourceId,
+            targetId: row.targetId,
+            confidence: row.confidence,
+            reason: row.reason,
+            step: row.step,
+        });
     }
     return { nodes, relationships };
 };
-const httpStatus = (err) => {
-    const msg = err?.message ?? '';
-    if (msg.includes('not found') || msg.includes('No indexed'))
+const statusFromError = (err) => {
+    const msg = String(err?.message ?? '');
+    if (msg.includes('No indexed repositories') || msg.includes('not found'))
         return 404;
     if (msg.includes('Multiple repositories'))
         return 400;
     return 500;
 };
-export const createServer = async (port) => {
-    const backend = new LocalBackend();
-    const hasRepos = await backend.init();
-    if (!hasRepos) {
-        console.warn('GitNexus: No indexed repositories found. The server will start but most endpoints will return errors.');
-        console.warn('Run "gitnexus analyze" in a repository to index it first.');
+const requestedRepo = (req) => {
+    const fromQuery = typeof req.query.repo === 'string' ? req.query.repo : undefined;
+    if (fromQuery)
+        return fromQuery;
+    if (req.body && typeof req.body === 'object' && typeof req.body.repo === 'string') {
+        return req.body.repo;
     }
+    return undefined;
+};
+export const createServer = async (port, host = '127.0.0.1') => {
     const app = express();
+    // CORS: only allow localhost origins and the deployed site.
+    // Non-browser requests (curl, server-to-server) have no origin and are allowed.
     app.use(cors({
         origin: (origin, callback) => {
-            // Allow requests with no origin (curl, server-to-server), localhost, and the deployed site.
-            // The server binds to 127.0.0.1 so only the local machine can reach it — CORS just gates
-            // which browser-tab origins may issue the request.
             if (!origin
                 || origin.startsWith('http://localhost:')
                 || origin.startsWith('http://127.0.0.1:')
@@ -118,115 +117,140 @@ export const createServer = async (port) => {
         }
     }));
     app.use(express.json({ limit: '10mb' }));
-    // ─── GET /api/repos ─────────────────────────────────────────────
-    // List all indexed repositories
+    // Initialize MCP backend (multi-repo, shared across all MCP sessions)
+    const backend = new LocalBackend();
+    await backend.init();
+    const cleanupMcp = mountMCPEndpoints(app, backend);
+    // Helper: resolve a repo by name from the global registry, or default to first
+    const resolveRepo = async (repoName) => {
+        const repos = await listRegisteredRepos();
+        if (repos.length === 0)
+            return null;
+        if (repoName)
+            return repos.find(r => r.name === repoName) || null;
+        return repos[0]; // default to first
+    };
+    // List all registered repos
     app.get('/api/repos', async (_req, res) => {
         try {
-            const repos = await backend.listRepos();
-            res.json(repos);
+            const repos = await listRegisteredRepos();
+            res.json(repos.map(r => ({
+                name: r.name, path: r.path, indexedAt: r.indexedAt,
+                lastCommit: r.lastCommit, stats: r.stats,
+            })));
         }
         catch (err) {
             res.status(500).json({ error: err.message || 'Failed to list repos' });
         }
     });
-    // ─── GET /api/repo?repo=X ──────────────────────────────────────
-    // Get metadata for a specific repo
+    // Get repo info
     app.get('/api/repo', async (req, res) => {
         try {
-            const repoName = req.query.repo;
-            const repo = await backend.resolveRepo(repoName);
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found. Run: gitnexus analyze' });
+                return;
+            }
+            const meta = await loadMeta(entry.storagePath);
             res.json({
-                name: repo.name,
-                path: repo.repoPath,
-                indexedAt: repo.indexedAt,
-                lastCommit: repo.lastCommit,
-                stats: repo.stats || {},
+                name: entry.name,
+                repoPath: entry.path,
+                indexedAt: meta?.indexedAt ?? entry.indexedAt,
+                stats: meta?.stats ?? entry.stats ?? {},
             });
         }
         catch (err) {
-            res.status(httpStatus(err))
-                .json({ error: err.message || 'Repository not found' });
+            res.status(500).json({ error: err.message || 'Failed to get repo info' });
         }
     });
-    // ─── GET /api/graph?repo=X ─────────────────────────────────────
-    // Full knowledge graph (all nodes + relationships)
+    // Get full graph
     app.get('/api/graph', async (req, res) => {
         try {
-            const repoName = req.query.repo;
-            // Resolve repo to validate it exists and get the name
-            const repo = await backend.resolveRepo(repoName);
-            const graph = await buildGraph(backend, repo.name);
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const kuzuPath = path.join(entry.storagePath, 'kuzu');
+            const graph = await withKuzuDb(kuzuPath, async () => buildGraph());
             res.json(graph);
         }
         catch (err) {
-            res.status(httpStatus(err))
-                .json({ error: err.message || 'Failed to build graph' });
+            res.status(500).json({ error: err.message || 'Failed to build graph' });
         }
     });
-    // ─── POST /api/query ───────────────────────────────────────────
-    // Execute a raw Cypher query.
-    // This endpoint is intentionally unrestricted (no query validation) because
-    // the server binds to 127.0.0.1 only — it exposes full graph query
-    // capabilities to local clients by design.
+    // Execute Cypher query
     app.post('/api/query', async (req, res) => {
         try {
-            const repoName = (req.body.repo ?? req.query.repo);
             const cypher = req.body.cypher;
             if (!cypher) {
                 res.status(400).json({ error: 'Missing "cypher" in request body' });
                 return;
             }
-            const result = await backend.executeCypher(repoName, cypher);
-            if (result && !Array.isArray(result) && result.error) {
-                res.status(500).json({ error: result.error });
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
                 return;
             }
+            const kuzuPath = path.join(entry.storagePath, 'kuzu');
+            const result = await withKuzuDb(kuzuPath, () => executeQuery(cypher));
             res.json({ result });
         }
         catch (err) {
-            res.status(httpStatus(err))
-                .json({ error: err.message || 'Query failed' });
+            res.status(500).json({ error: err.message || 'Query failed' });
         }
     });
-    // ─── POST /api/search ──────────────────────────────────────────
-    // Process-grouped semantic search
+    // Search
     app.post('/api/search', async (req, res) => {
         try {
-            const repoName = (req.body.repo ?? req.query.repo);
             const query = (req.body.query ?? '').trim();
-            const limit = req.body.limit;
             if (!query) {
                 res.status(400).json({ error: 'Missing "query" in request body' });
                 return;
             }
-            const results = await backend.callTool('query', {
-                repo: repoName,
-                query,
-                limit,
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const kuzuPath = path.join(entry.storagePath, 'kuzu');
+            const parsedLimit = Number(req.body.limit ?? 10);
+            const limit = Number.isFinite(parsedLimit)
+                ? Math.max(1, Math.min(100, Math.trunc(parsedLimit)))
+                : 10;
+            const results = await withKuzuDb(kuzuPath, async () => {
+                const { isEmbedderReady } = await import('../core/embeddings/embedder.js');
+                if (isEmbedderReady()) {
+                    const { semanticSearch } = await import('../core/embeddings/embedding-pipeline.js');
+                    return hybridSearch(query, limit, executeQuery, semanticSearch);
+                }
+                // FTS-only fallback when embeddings aren't loaded
+                return searchFTSFromKuzu(query, limit);
             });
             res.json({ results });
         }
         catch (err) {
-            res.status(httpStatus(err))
-                .json({ error: err.message || 'Search failed' });
+            res.status(500).json({ error: err.message || 'Search failed' });
         }
     });
-    // ─── GET /api/file?repo=X&path=Y ──────────────────────────────
-    // Read a file from a resolved repo path on disk
+    // Read file — with path traversal guard
     app.get('/api/file', async (req, res) => {
         try {
-            const repoName = req.query.repo;
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
             const filePath = req.query.path;
             if (!filePath) {
-                res.status(400).json({ error: 'Missing "path" query parameter' });
+                res.status(400).json({ error: 'Missing path' });
                 return;
             }
-            const repo = await backend.resolveRepo(repoName);
-            // Resolve the full path and validate it stays within the repo root
-            const repoRoot = path.resolve(repo.repoPath);
+            // Prevent path traversal — resolve and verify the path stays within the repo root
+            const repoRoot = path.resolve(entry.path);
             const fullPath = path.resolve(repoRoot, filePath);
             if (!fullPath.startsWith(repoRoot + path.sep) && fullPath !== repoRoot) {
-                res.status(403).json({ error: 'Path traversal denied: path escapes repo root' });
+                res.status(403).json({ error: 'Path traversal denied' });
                 return;
             }
             const content = await fs.readFile(fullPath, 'utf-8');
@@ -237,87 +261,81 @@ export const createServer = async (port) => {
                 res.status(404).json({ error: 'File not found' });
             }
             else {
-                res.status(httpStatus(err))
-                    .json({ error: err.message || 'Failed to read file' });
+                res.status(500).json({ error: err.message || 'Failed to read file' });
             }
         }
     });
-    // ─── GET /api/processes?repo=X ─────────────────────────────────
-    // List all processes for a repo
+    // List all processes
     app.get('/api/processes', async (req, res) => {
         try {
-            const repoName = req.query.repo;
-            const result = await backend.queryProcesses(repoName);
+            const result = await backend.queryProcesses(requestedRepo(req));
             res.json(result);
         }
         catch (err) {
-            res.status(httpStatus(err))
-                .json({ error: err.message || 'Failed to query processes' });
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query processes' });
         }
     });
-    // ─── GET /api/process?repo=X&name=Y ───────────────────────────
-    // Get detailed process info including steps
+    // Process detail
     app.get('/api/process', async (req, res) => {
         try {
-            const repoName = req.query.repo;
-            const name = req.query.name;
+            const name = String(req.query.name ?? '').trim();
             if (!name) {
                 res.status(400).json({ error: 'Missing "name" query parameter' });
                 return;
             }
-            const result = await backend.queryProcessDetail(name, repoName);
-            if (result.error) {
+            const result = await backend.queryProcessDetail(name, requestedRepo(req));
+            if (result?.error) {
                 res.status(404).json({ error: result.error });
                 return;
             }
             res.json(result);
         }
         catch (err) {
-            res.status(httpStatus(err))
-                .json({ error: err.message || 'Failed to query process detail' });
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query process detail' });
         }
     });
-    // ─── GET /api/clusters?repo=X ─────────────────────────────────
-    // List all clusters for a repo
+    // List all clusters
     app.get('/api/clusters', async (req, res) => {
         try {
-            const repoName = req.query.repo;
-            const result = await backend.queryClusters(repoName);
+            const result = await backend.queryClusters(requestedRepo(req));
             res.json(result);
         }
         catch (err) {
-            res.status(httpStatus(err))
-                .json({ error: err.message || 'Failed to query clusters' });
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query clusters' });
         }
     });
-    // ─── GET /api/cluster?repo=X&name=Y ───────────────────────────
-    // Get detailed cluster info including members
+    // Cluster detail
     app.get('/api/cluster', async (req, res) => {
         try {
-            const repoName = req.query.repo;
-            const name = req.query.name;
+            const name = String(req.query.name ?? '').trim();
             if (!name) {
                 res.status(400).json({ error: 'Missing "name" query parameter' });
                 return;
             }
-            const result = await backend.queryClusterDetail(name, repoName);
-            if (result.error) {
+            const result = await backend.queryClusterDetail(name, requestedRepo(req));
+            if (result?.error) {
                 res.status(404).json({ error: result.error });
                 return;
             }
             res.json(result);
         }
         catch (err) {
-            res.status(httpStatus(err))
-                .json({ error: err.message || 'Failed to query cluster detail' });
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query cluster detail' });
         }
     });
-    const server = app.listen(port, '127.0.0.1', () => {
-        console.log(`GitNexus server running on http://localhost:${port}`);
-        console.log(`Serving ${hasRepos ? 'all indexed repositories' : 'no repositories (run gitnexus analyze first)'}`);
+    // Global error handler — catch anything the route handlers miss
+    app.use((err, _req, res, _next) => {
+        console.error('Unhandled error:', err);
+        res.status(500).json({ error: 'Internal server error' });
+    });
+    const server = app.listen(port, host, () => {
+        console.log(`GitNexus server running on http://${host}:${port}`);
     });
+    // Graceful shutdown — close Express + KuzuDB cleanly
     const shutdown = async () => {
         server.close();
+        await cleanupMcp();
+        await closeKuzu();
         await backend.disconnect();
         process.exit(0);
     };

package/dist/server/mcp-http.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP over HTTP
+ *
+ * Mounts the GitNexus MCP server on Express using StreamableHTTP transport.
+ * Each connecting client gets its own stateful session; the LocalBackend
+ * is shared across all sessions (thread-safe — lazy KuzuDB per repo).
+ *
+ * Sessions are cleaned up on explicit close or after SESSION_TTL_MS of inactivity
+ * (guards against network drops that never trigger onclose).
+ */
+import type { Express } from 'express';
+import type { LocalBackend } from '../mcp/local/local-backend.js';
+export declare function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Promise<void>;