@zuvia-software-solutions/code-mapper 1.4.0

package/dist/mcp/tools.d.ts

@@ -0,0 +1,21 @@
+/** @file tools.ts
+ *  @description MCP tool definitions exposed to external AI agents
+ *  All tools support an optional `repo` parameter for multi-repo setups */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            default?: any;
+            items?: {
+                type: string;
+            };
+            enum?: string[];
+        }>;
+        required: string[];
+    };
+}
+export declare const CODE_MAPPER_TOOLS: ToolDefinition[];

package/dist/mcp/tools.js

@@ -0,0 +1,202 @@
+// code-mapper/src/mcp/tools.ts
+/** @file tools.ts
+ *  @description MCP tool definitions exposed to external AI agents
+ *  All tools support an optional `repo` parameter for multi-repo setups */
+export const CODE_MAPPER_TOOLS = [
+    {
+        name: 'list_repos',
+        description: `List all indexed repositories available to Code Mapper.
+
+Returns each repo's name, path, indexed date, last commit, and stats.
+
+WHEN TO USE: First step when multiple repos are indexed, or to discover available repos.
+AFTER THIS: READ code-mapper://repo/{name}/context for the repo you want to work with.
+
+When multiple repos are indexed, you MUST specify the "repo" parameter
+on other tools (query, context, impact, etc.) to target the correct one.`,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'query',
+        description: `Query the code knowledge graph for execution flows related to a concept.
+Returns processes (call chains) ranked by relevance, each with its symbols and file locations.
+
+WHEN TO USE: Understanding how code works together. Use this when you need execution flows and relationships, not just file matches. Complements grep/IDE search.
+AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).
+
+Returns results grouped by process (execution flow):
+- processes: ranked execution flows with relevance priority
+- process_symbols: all symbols in those flows with file locations and module (functional area)
+- definitions: standalone types/interfaces not in any process
+
+Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank Fusion.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Natural language or keyword search query' },
+                task_context: { type: 'string', description: 'What you are working on (e.g., "adding OAuth support"). Helps ranking.' },
+                goal: { type: 'string', description: 'What you want to find (e.g., "existing auth validation logic"). Helps ranking.' },
+                file_path: { type: 'string', description: 'Filter results to symbols in this file path (substring match)' },
+                limit: { type: 'number', description: 'Max processes to return (default: 5)', default: 5 },
+                max_symbols: { type: 'number', description: 'Max symbols per process (default: 10)', default: 10 },
+                include_content: { type: 'boolean', description: 'Include full symbol source code (default: false)', default: false },
+                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'cypher',
+        description: `Execute Cypher query against the code knowledge graph.
+
+WHEN TO USE: Complex structural queries that search/explore can't answer. READ code-mapper://repo/{name}/schema first for the full schema.
+AFTER THIS: Use context() on result symbols for deeper context.
+
+SCHEMA:
+- Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process
+- Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
+- All edges via single CodeRelation table with 'type' property
+- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, OVERRIDES, MEMBER_OF, STEP_IN_PROCESS
+- Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
+
+EXAMPLES:
+• Find callers of a function:
+  MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: "validateUser"}) RETURN a.name, a.filePath
+
+• Find community members:
+  MATCH (f)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) WHERE c.heuristicLabel = "Auth" RETURN f.name
+
+• Trace a process:
+  MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) WHERE p.heuristicLabel = "UserLogin" RETURN s.name, r.step ORDER BY r.step
+
+• Find all methods of a class:
+  MATCH (c:Class {name: "UserService"})-[r:CodeRelation {type: 'HAS_METHOD'}]->(m:Method) RETURN m.name, m.parameterCount, m.returnType
+
+• Find method overrides (MRO resolution):
+  MATCH (winner:Method)-[r:CodeRelation {type: 'OVERRIDES'}]->(loser:Method) RETURN winner.name, winner.filePath, loser.filePath, r.reason
+
+• Detect diamond inheritance:
+  MATCH (d:Class)-[:CodeRelation {type: 'EXTENDS'}]->(b1), (d)-[:CodeRelation {type: 'EXTENDS'}]->(b2), (b1)-[:CodeRelation {type: 'EXTENDS'}]->(a), (b2)-[:CodeRelation {type: 'EXTENDS'}]->(a) WHERE b1 <> b2 RETURN d.name, b1.name, b2.name, a.name
+
+OUTPUT: Returns { markdown, row_count } — results formatted as a Markdown table for easy reading.
+
+TIPS:
+- All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
+- Community = auto-detected functional area (Leiden algorithm)
+- Process = execution flow trace from entry point to terminal
+- Use heuristicLabel (not label) for human-readable community/process names`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Cypher query to execute' },
+                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'context',
+        description: `360-degree view of a single code symbol.
+Shows categorized incoming/outgoing references (calls, imports, extends, implements), process participation, and file location.
+
+WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
+AFTER THIS: Use impact() if planning changes, or READ code-mapper://repo/{name}/process/{processName} for full execution trace.
+
+Handles disambiguation: if multiple symbols share the same name, returns candidates for you to pick from. Use uid param for zero-ambiguity lookup from prior results.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Symbol name (e.g., "validateUser", "AuthService")' },
+                names: { type: 'array', items: { type: 'string' }, description: 'Multiple symbol names for bulk lookup (returns compact context for each)' },
+                uid: { type: 'string', description: 'Direct symbol UID from prior tool results (zero-ambiguity lookup)' },
+                file_path: { type: 'string', description: 'File path to disambiguate common names' },
+                include_content: { type: 'boolean', description: 'Include full symbol source code (default: false)', default: false },
+                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'detect_changes',
+        description: `Analyze uncommitted git changes and find affected execution flows.
+Maps git diff hunks to indexed symbols, then traces which processes are impacted.
+
+WHEN TO USE: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.
+AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ code-mapper://repo/{name}/process/{name} for full traces.
+
+Returns: changed symbols, affected processes, and a risk summary.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: { type: 'string', description: 'What to analyze: "unstaged" (default), "staged", "all", or "compare"', enum: ['unstaged', 'staged', 'all', 'compare'], default: 'unstaged' },
+                base_ref: { type: 'string', description: 'Branch/commit for "compare" scope (e.g., "main")' },
+                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'rename',
+        description: `Multi-file coordinated rename using the knowledge graph + text search.
+Finds all references via graph (high confidence) and regex text search (lower confidence). Preview by default.
+
+WHEN TO USE: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.
+AFTER THIS: Run detect_changes() to verify no unexpected side effects.
+
+Each edit is tagged with confidence:
+- "graph": found via knowledge graph relationships (high confidence, safe to accept)
+- "text_search": found via regex text search (lower confidence, review carefully)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol_name: { type: 'string', description: 'Current symbol name to rename' },
+                symbol_uid: { type: 'string', description: 'Direct symbol UID from prior tool results (zero-ambiguity)' },
+                new_name: { type: 'string', description: 'The new name for the symbol' },
+                file_path: { type: 'string', description: 'File path to disambiguate common names' },
+                dry_run: { type: 'boolean', description: 'Preview edits without modifying files (default: true)', default: true },
+                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+            },
+            required: ['new_name'],
+        },
+    },
+    {
+        name: 'impact',
+        description: `Analyze the blast radius of changing a code symbol.
+Returns affected symbols grouped by depth, plus risk assessment, affected execution flows, and affected modules.
+
+WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
+AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.
+
+Output includes:
+- risk: LOW / MEDIUM / HIGH / CRITICAL
+- summary: direct callers, processes affected, modules affected
+- affected_processes: which execution flows break and at which step
+- affected_modules: which functional areas are hit (direct vs indirect)
+- byDepth: all affected symbols grouped by traversal depth
+
+Depth groups:
+- d=1: WILL BREAK (direct callers/importers)
+- d=2: LIKELY AFFECTED (indirect)
+- d=3: MAY NEED TESTING (transitive)
+
+EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, OVERRIDES
+Confidence: 1.0 = certain, <0.8 = fuzzy match`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Name of function, class, or file to analyze' },
+                direction: { type: 'string', description: 'upstream (what depends on this) or downstream (what this depends on)' },
+                maxDepth: { type: 'number', description: 'Max relationship depth (default: 3)', default: 3 },
+                relationTypes: { type: 'array', items: { type: 'string' }, description: 'Filter: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, OVERRIDES (default: usage-based)' },
+                includeTests: { type: 'boolean', description: 'Include test files (default: false)' },
+                minConfidence: { type: 'number', description: 'Minimum confidence 0-1 (default: 0.7)' },
+                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+            },
+            required: ['target', 'direction'],
+        },
+    },
+];

package/dist/server/api.d.ts

@@ -0,0 +1,5 @@
+/** @file api.ts
+ *  @description REST API server for browser clients to query local .code-mapper/ indexes
+ *  Also hosts MCP server over StreamableHTTP for remote AI tool access
+ *  Binds to 127.0.0.1 by default with CORS restricted to localhost */
+export declare const createServer: (port: number, host?: string) => Promise<void>;

package/dist/server/api.js

@@ -0,0 +1,340 @@
+// code-mapper/src/server/api.ts
+/** @file api.ts
+ *  @description REST API server for browser clients to query local .code-mapper/ indexes
+ *  Also hosts MCP server over StreamableHTTP for remote AI tool access
+ *  Binds to 127.0.0.1 by default with CORS restricted to localhost */
+import express from 'express';
+import cors from 'cors';
+import path from 'path';
+import fs from 'fs/promises';
+import { loadMeta, listRegisteredRepos } from '../storage/repo-manager.js';
+import { executeQuery, closeLbug, withLbugDb } from '../core/lbug/lbug-adapter.js';
+import { NODE_TABLES } from '../core/lbug/schema.js';
+import { searchFTSFromLbug } 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 {
+            let query = '';
+            if (table === 'File') {
+                query = `MATCH (n:File) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.content AS content`;
+            }
+            else if (table === 'Folder') {
+                query = `MATCH (n:Folder) RETURN n.id AS id, n.name AS name, n.filePath AS filePath`;
+            }
+            else if (table === 'Community') {
+                query = `MATCH (n:Community) RETURN n.id AS id, n.label AS label, n.heuristicLabel AS heuristicLabel, n.cohesion AS cohesion, n.symbolCount AS symbolCount`;
+            }
+            else if (table === 'Process') {
+                query = `MATCH (n:Process) RETURN n.id AS id, n.label AS label, n.heuristicLabel AS heuristicLabel, n.processType AS processType, n.stepCount AS stepCount, n.communities AS communities, n.entryPointId AS entryPointId, n.terminalId AS terminalId`;
+            }
+            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 rows = await executeQuery(query);
+            for (const row of rows) {
+                nodes.push({
+                    id: row.id ?? row[0],
+                    label: table,
+                    properties: {
+                        name: row.name ?? row.label ?? row[1],
+                        filePath: row.filePath ?? row[2],
+                        startLine: row.startLine,
+                        endLine: row.endLine,
+                        content: row.content,
+                        heuristicLabel: row.heuristicLabel,
+                        cohesion: row.cohesion,
+                        symbolCount: row.symbolCount,
+                        processType: row.processType,
+                        stepCount: row.stepCount,
+                        communities: row.communities,
+                        entryPointId: row.entryPointId,
+                        terminalId: row.terminalId,
+                    },
+                });
+            }
+        }
+        catch {
+            // ignore empty tables
+        }
+    }
+    const relationships = [];
+    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 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;
+};
+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: localhost origins + deployed site only
+    // Non-browser requests (curl, server-to-server) have no origin and are allowed
+    app.use(cors({
+        origin: (origin, callback) => {
+            if (!origin
+                || origin.startsWith('http://localhost:')
+                || origin.startsWith('http://127.0.0.1:')
+                || origin === 'https://code-mapper.vercel.app') {
+                callback(null, true);
+            }
+            else {
+                callback(new Error('Not allowed by CORS'));
+            }
+        }
+    }));
+    app.use(express.json({ limit: '10mb' }));
+    // Initialize MCP backend (multi-repo, shared across all MCP sessions)
+    const backend = new LocalBackend();
+    await backend.init();
+    const cleanupMcp = mountMCPEndpoints(app, backend);
+    // 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 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 repo info
+    app.get('/api/repo', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found. Run: code-mapper analyze' });
+                return;
+            }
+            const meta = await loadMeta(entry.storagePath);
+            res.json({
+                name: entry.name,
+                repoPath: entry.path,
+                indexedAt: meta?.indexedAt ?? entry.indexedAt,
+                stats: meta?.stats ?? entry.stats ?? {},
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Failed to get repo info' });
+        }
+    });
+    // Get full graph
+    app.get('/api/graph', async (req, res) => {
+        try {
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const lbugPath = path.join(entry.storagePath, 'lbug');
+            const graph = await withLbugDb(lbugPath, async () => buildGraph());
+            res.json(graph);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Failed to build graph' });
+        }
+    });
+    // Execute Cypher query
+    app.post('/api/query', async (req, res) => {
+        try {
+            const cypher = req.body.cypher;
+            if (!cypher) {
+                res.status(400).json({ error: 'Missing "cypher" in request body' });
+                return;
+            }
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const lbugPath = path.join(entry.storagePath, 'lbug');
+            const result = await withLbugDb(lbugPath, () => executeQuery(cypher));
+            res.json({ result });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Query failed' });
+        }
+    });
+    // Search
+    app.post('/api/search', async (req, res) => {
+        try {
+            const query = (req.body.query ?? '').trim();
+            if (!query) {
+                res.status(400).json({ error: 'Missing "query" in request body' });
+                return;
+            }
+            const entry = await resolveRepo(requestedRepo(req));
+            if (!entry) {
+                res.status(404).json({ error: 'Repository not found' });
+                return;
+            }
+            const lbugPath = path.join(entry.storagePath, 'lbug');
+            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 withLbugDb(lbugPath, 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 searchFTSFromLbug(query, limit);
+            });
+            res.json({ results });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Search failed' });
+        }
+    });
+    // Read file (with path traversal guard)
+    app.get('/api/file', async (req, res) => {
+        try {
+            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' });
+                return;
+            }
+            // Prevent path traversal: resolve and verify path stays within 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' });
+                return;
+            }
+            const content = await fs.readFile(fullPath, 'utf-8');
+            res.json({ content });
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                res.status(404).json({ error: 'File not found' });
+            }
+            else {
+                res.status(500).json({ error: err.message || 'Failed to read file' });
+            }
+        }
+    });
+    // List all processes
+    app.get('/api/processes', async (req, res) => {
+        try {
+            const result = await backend.queryProcesses(requestedRepo(req));
+            res.json(result);
+        }
+        catch (err) {
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query processes' });
+        }
+    });
+    // Process detail
+    app.get('/api/process', async (req, res) => {
+        try {
+            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, requestedRepo(req));
+            if (result?.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query process detail' });
+        }
+    });
+    // List all clusters
+    app.get('/api/clusters', async (req, res) => {
+        try {
+            const result = await backend.queryClusters(requestedRepo(req));
+            res.json(result);
+        }
+        catch (err) {
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query clusters' });
+        }
+    });
+    // Cluster detail
+    app.get('/api/cluster', async (req, res) => {
+        try {
+            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, requestedRepo(req));
+            if (result?.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(statusFromError(err)).json({ error: err.message || 'Failed to query cluster detail' });
+        }
+    });
+    // Global error handler
+    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(`Code Mapper server running on http://${host}:${port}`);
+    });
+    // Graceful shutdown
+    const shutdown = async () => {
+        server.close();
+        await cleanupMcp();
+        await closeLbug();
+        await backend.disconnect();
+        process.exit(0);
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+};

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

@@ -0,0 +1,7 @@
+/** @file mcp-http.ts
+ *  @description Mounts Code Mapper MCP server on Express using StreamableHTTP transport
+ *  Each client gets a stateful session; LocalBackend is shared (thread-safe)
+ *  Sessions are evicted on close or after idle timeout */
+import type { Express } from 'express';
+import type { LocalBackend } from '../mcp/local/local-backend.js';
+export declare function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Promise<void>;

package/dist/server/mcp-http.js

@@ -0,0 +1,95 @@
+// code-mapper/src/server/mcp-http.ts
+/** @file mcp-http.ts
+ *  @description Mounts Code Mapper MCP server on Express using StreamableHTTP transport
+ *  Each client gets a stateful session; LocalBackend is shared (thread-safe)
+ *  Sessions are evicted on close or after idle timeout */
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMCPServer } from '../mcp/server.js';
+import { randomUUID } from 'crypto';
+/** Idle sessions are evicted after 30 minutes */
+const SESSION_TTL_MS = 30 * 60 * 1000;
+/** Cleanup sweep runs every 5 minutes */
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+export function mountMCPEndpoints(app, backend) {
+    const sessions = new Map();
+    // Periodic cleanup of idle sessions
+    const cleanupTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [id, session] of sessions) {
+            if (now - session.lastActivity > SESSION_TTL_MS) {
+                try {
+                    session.server.close();
+                }
+                catch { }
+                sessions.delete(id);
+            }
+        }
+    }, CLEANUP_INTERVAL_MS);
+    if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) {
+        cleanupTimer.unref();
+    }
+    const handleMcpRequest = async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (sessionId && sessions.has(sessionId)) {
+            // Existing session — delegate to its transport
+            const session = sessions.get(sessionId);
+            session.lastActivity = Date.now();
+            await session.transport.handleRequest(req, res, req.body);
+        }
+        else if (sessionId) {
+            // Unknown/expired session ID (per MCP spec, tell client to re-initialize)
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32001, message: 'Session not found. Re-initialize.' },
+                id: null,
+            });
+        }
+        else if (req.method === 'POST') {
+            // No session ID — new client initializing
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+            });
+            const server = createMCPServer(backend);
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            if (transport.sessionId) {
+                sessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() });
+                transport.onclose = () => {
+                    sessions.delete(transport.sessionId);
+                };
+            }
+        }
+        else {
+            res.status(400).json({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'No valid session. Send a POST to initialize.' },
+                id: null,
+            });
+        }
+    };
+    app.all('/api/mcp', (req, res) => {
+        void handleMcpRequest(req, res).catch((err) => {
+            console.error('MCP HTTP request failed:', err);
+            if (res.headersSent)
+                return;
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'Internal MCP server error' },
+                id: null,
+            });
+        });
+    });
+    const cleanup = async () => {
+        clearInterval(cleanupTimer);
+        const closers = [...sessions.values()].map(async (session) => {
+            try {
+                await Promise.resolve(session.server.close());
+            }
+            catch { }
+        });
+        sessions.clear();
+        await Promise.allSettled(closers);
+    };
+    console.log('MCP HTTP endpoints mounted at /api/mcp');
+    return cleanup;
+}