@zuvia-software-solutions/code-mapper 1.4.0

package/dist/mcp/resources.d.ts

@@ -0,0 +1,22 @@
+/** @file resources.ts
+ *  @description MCP resource definitions and handlers for AI agents
+ *  All resources use repo-scoped URIs: code-mapper://repo/{name}/context */
+import type { LocalBackend } from './local/local-backend.js';
+export interface ResourceDefinition {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+export interface ResourceTemplate {
+    uriTemplate: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+/** Static resources including per-repo resources and the global repos list */
+export declare function getResourceDefinitions(): ResourceDefinition[];
+/** Dynamic resource templates */
+export declare function getResourceTemplates(): ResourceTemplate[];
+/** Read a resource and return its content */
+export declare function readResource(uri: string, backend: LocalBackend): Promise<string>;

package/dist/mcp/resources.js

@@ -0,0 +1,379 @@
+// code-mapper/src/mcp/resources.ts
+/** @file resources.ts
+ *  @description MCP resource definitions and handlers for AI agents
+ *  All resources use repo-scoped URIs: code-mapper://repo/{name}/context */
+import { checkStaleness } from './staleness.js';
+/** Static resources including per-repo resources and the global repos list */
+export function getResourceDefinitions() {
+    return [
+        {
+            uri: 'code-mapper://repos',
+            name: 'All Indexed Repositories',
+            description: 'List of all indexed repos with stats. Read this first to discover available repos.',
+            mimeType: 'text/yaml',
+        },
+        {
+            uri: 'code-mapper://setup',
+            name: 'Code Mapper Setup Content',
+            description: 'Returns AGENTS.md content for all indexed repos. Useful for setup/onboarding.',
+            mimeType: 'text/markdown',
+        },
+    ];
+}
+/** Dynamic resource templates */
+export function getResourceTemplates() {
+    return [
+        {
+            uriTemplate: 'code-mapper://repo/{name}/context',
+            name: 'Repo Overview',
+            description: 'Codebase stats, staleness check, and available tools',
+            mimeType: 'text/yaml',
+        },
+        {
+            uriTemplate: 'code-mapper://repo/{name}/clusters',
+            name: 'Repo Modules',
+            description: 'All functional areas (Leiden clusters)',
+            mimeType: 'text/yaml',
+        },
+        {
+            uriTemplate: 'code-mapper://repo/{name}/processes',
+            name: 'Repo Processes',
+            description: 'All execution flows',
+            mimeType: 'text/yaml',
+        },
+        {
+            uriTemplate: 'code-mapper://repo/{name}/schema',
+            name: 'Graph Schema',
+            description: 'Node/edge schema for Cypher queries',
+            mimeType: 'text/yaml',
+        },
+        {
+            uriTemplate: 'code-mapper://repo/{name}/cluster/{clusterName}',
+            name: 'Module Detail',
+            description: 'Deep dive into a specific functional area',
+            mimeType: 'text/yaml',
+        },
+        {
+            uriTemplate: 'code-mapper://repo/{name}/process/{processName}',
+            name: 'Process Trace',
+            description: 'Step-by-step execution trace',
+            mimeType: 'text/yaml',
+        },
+    ];
+}
+/** Parse a resource URI to extract the repo name and resource type */
+function parseUri(uri) {
+    if (uri === 'code-mapper://repos')
+        return { resourceType: 'repos' };
+    if (uri === 'code-mapper://setup')
+        return { resourceType: 'setup' };
+    // Repo-scoped: code-mapper://repo/{name}/context
+    const repoMatch = uri.match(/^code-mapper:\/\/repo\/([^/]+)\/(.+)$/);
+    if (repoMatch) {
+        const repoName = decodeURIComponent(repoMatch[1]);
+        const rest = repoMatch[2];
+        if (rest.startsWith('cluster/')) {
+            return { repoName, resourceType: 'cluster', param: decodeURIComponent(rest.replace('cluster/', '')) };
+        }
+        if (rest.startsWith('process/')) {
+            return { repoName, resourceType: 'process', param: decodeURIComponent(rest.replace('process/', '')) };
+        }
+        return { repoName, resourceType: rest };
+    }
+    throw new Error(`Unknown resource URI: ${uri}`);
+}
+/** Read a resource and return its content */
+export async function readResource(uri, backend) {
+    const parsed = parseUri(uri);
+    // Global repos list (no repo context needed)
+    if (parsed.resourceType === 'repos') {
+        return getReposResource(backend);
+    }
+    // Setup resource (AGENTS.md content for all repos)
+    if (parsed.resourceType === 'setup') {
+        return getSetupResource(backend);
+    }
+    const repoName = parsed.repoName;
+    switch (parsed.resourceType) {
+        case 'context':
+            return getContextResource(backend, repoName);
+        case 'clusters':
+            return getClustersResource(backend, repoName);
+        case 'processes':
+            return getProcessesResource(backend, repoName);
+        case 'schema':
+            return getSchemaResource();
+        case 'cluster':
+            return getClusterDetailResource(parsed.param, backend, repoName);
+        case 'process':
+            return getProcessDetailResource(parsed.param, backend, repoName);
+        default:
+            throw new Error(`Unknown resource: ${uri}`);
+    }
+}
+// Resource Implementations
+/** List all indexed repositories */
+async function getReposResource(backend) {
+    const repos = await backend.listRepos();
+    if (repos.length === 0) {
+        return 'repos: []\n# No repositories indexed. Run: code-mapper analyze';
+    }
+    const lines = ['repos:'];
+    for (const repo of repos) {
+        lines.push(`  - name: "${repo.name}"`);
+        lines.push(`    path: "${repo.path}"`);
+        lines.push(`    indexed: "${repo.indexedAt}"`);
+        lines.push(`    commit: "${repo.lastCommit?.slice(0, 7) || 'unknown'}"`);
+        if (repo.stats) {
+            lines.push(`    files: ${repo.stats.files || 0}`);
+            lines.push(`    symbols: ${repo.stats.nodes || 0}`);
+            lines.push(`    processes: ${repo.stats.processes || 0}`);
+        }
+    }
+    if (repos.length > 1) {
+        lines.push('');
+        lines.push('# Multiple repos indexed. Use repo parameter in tool calls:');
+        lines.push(`# code-mapper_search({query: "auth", repo: "${repos[0].name}"})`);
+    }
+    return lines.join('\n');
+}
+/** Codebase overview for a specific repo */
+async function getContextResource(backend, repoName) {
+    // Resolve repo and check staleness
+    const repo = await backend.resolveRepo(repoName);
+    const repoId = repo.name.toLowerCase();
+    const context = backend.getContext(repoId) || backend.getContext();
+    if (!context) {
+        return 'error: No codebase loaded. Run: code-mapper analyze';
+    }
+    const repoPath = repo.repoPath;
+    const lastCommit = repo.lastCommit || 'HEAD';
+    const staleness = repoPath ? checkStaleness(repoPath, lastCommit) : { isStale: false, commitsBehind: 0 };
+    const lines = [
+        `project: ${context.projectName}`,
+    ];
+    if (staleness.isStale && staleness.hint) {
+        lines.push('');
+        lines.push(`staleness: "${staleness.hint}"`);
+    }
+    lines.push('');
+    lines.push('stats:');
+    lines.push(`  files: ${context.stats.fileCount}`);
+    lines.push(`  symbols: ${context.stats.functionCount}`);
+    lines.push(`  processes: ${context.stats.processCount}`);
+    lines.push('');
+    lines.push('tools_available:');
+    lines.push('  - query: Process-grouped code intelligence (execution flows related to a concept)');
+    lines.push('  - context: 360-degree symbol view (categorized refs, process participation)');
+    lines.push('  - impact: Blast radius analysis (what breaks if you change a symbol)');
+    lines.push('  - detect_changes: Git-diff impact analysis (what do your changes affect)');
+    lines.push('  - rename: Multi-file coordinated rename with confidence tags');
+    lines.push('  - cypher: Raw graph queries');
+    lines.push('  - list_repos: Discover all indexed repositories');
+    lines.push('');
+    lines.push('re_index: Run `npx code-mapper analyze` in terminal if data is stale');
+    lines.push('');
+    lines.push('resources_available:');
+    lines.push('  - code-mapper://repos: All indexed repositories');
+    lines.push(`  - code-mapper://repo/${context.projectName}/clusters: All functional areas`);
+    lines.push(`  - code-mapper://repo/${context.projectName}/processes: All execution flows`);
+    lines.push(`  - code-mapper://repo/${context.projectName}/cluster/{name}: Module details`);
+    lines.push(`  - code-mapper://repo/${context.projectName}/process/{name}: Process trace`);
+    return lines.join('\n');
+}
+/** Functional areas via backend.queryClusters() */
+async function getClustersResource(backend, repoName) {
+    try {
+        const result = await backend.queryClusters(repoName, 100);
+        if (!result.clusters || result.clusters.length === 0) {
+            return 'modules: []\n# No functional areas detected. Run: code-mapper analyze';
+        }
+        const displayLimit = 20;
+        const lines = ['modules:'];
+        const toShow = result.clusters.slice(0, displayLimit);
+        for (const cluster of toShow) {
+            const label = cluster.heuristicLabel || cluster.label || cluster.id;
+            lines.push(`  - name: "${label}"`);
+            lines.push(`    symbols: ${cluster.symbolCount || 0}`);
+            if (cluster.cohesion) {
+                lines.push(`    cohesion: ${(cluster.cohesion * 100).toFixed(0)}%`);
+            }
+        }
+        if (result.clusters.length > displayLimit) {
+            lines.push(`\n# Showing top ${displayLimit} of ${result.clusters.length} modules. Use code-mapper_query for deeper search.`);
+        }
+        return lines.join('\n');
+    }
+    catch (err) {
+        return `error: ${err.message}`;
+    }
+}
+/** Execution flows via backend.queryProcesses() */
+async function getProcessesResource(backend, repoName) {
+    try {
+        const result = await backend.queryProcesses(repoName, 50);
+        if (!result.processes || result.processes.length === 0) {
+            return 'processes: []\n# No processes detected. Run: code-mapper analyze';
+        }
+        const displayLimit = 20;
+        const lines = ['processes:'];
+        const toShow = result.processes.slice(0, displayLimit);
+        for (const proc of toShow) {
+            const label = proc.heuristicLabel || proc.label || proc.id;
+            lines.push(`  - name: "${label}"`);
+            lines.push(`    type: ${proc.processType || 'unknown'}`);
+            lines.push(`    steps: ${proc.stepCount || 0}`);
+        }
+        if (result.processes.length > displayLimit) {
+            lines.push(`\n# Showing top ${displayLimit} of ${result.processes.length} processes. Use code-mapper_query for deeper search.`);
+        }
+        return lines.join('\n');
+    }
+    catch (err) {
+        return `error: ${err.message}`;
+    }
+}
+/** Graph schema reference for Cypher queries */
+function getSchemaResource() {
+    return `# Code Mapper Graph Schema
+
+nodes:
+  - File: Source code files
+  - Folder: Directory containers
+  - Function: Functions and arrow functions
+  - Class: Class definitions
+  - Interface: Interface/type definitions
+  - Method: Class methods
+  - CodeElement: Catch-all for other code elements
+  - Community: Auto-detected functional area (Leiden algorithm)
+  - Process: Execution flow trace
+
+additional_node_types: "Multi-language: Struct, Enum, Macro, Typedef, Union, Namespace, Trait, Impl, TypeAlias, Const, Static, Property, Record, Delegate, Annotation, Constructor, Template, Module (use backticks in queries: \`Struct\`, \`Enum\`, etc.)"
+
+relationships:
+  - CONTAINS: File/Folder contains child
+  - DEFINES: File defines a symbol
+  - CALLS: Function/method invocation
+  - IMPORTS: Module imports
+  - EXTENDS: Class inheritance
+  - IMPLEMENTS: Interface implementation
+  - MEMBER_OF: Symbol belongs to community
+  - STEP_IN_PROCESS: Symbol is step N in process
+
+relationship_table: "All relationships use a single CodeRelation table with a 'type' property. Properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)"
+
+example_queries:
+  find_callers: |
+    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+    RETURN caller.name, caller.filePath
+  
+  find_community_members: |
+    MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+    WHERE c.heuristicLabel = "Auth"
+    RETURN s.name, labels(s) AS type
+  
+  trace_process: |
+    MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+    WHERE p.heuristicLabel = "LoginFlow"
+    RETURN s.name, r.step
+    ORDER BY r.step
+`;
+}
+/** Deep dive into a specific functional area */
+async function getClusterDetailResource(name, backend, repoName) {
+    try {
+        const result = await backend.queryClusterDetail(name, repoName);
+        if (result.error) {
+            return `error: ${result.error}`;
+        }
+        const cluster = result.cluster;
+        const members = result.members || [];
+        const lines = [
+            `module: "${cluster.heuristicLabel || cluster.label || cluster.id}"`,
+            `symbols: ${cluster.symbolCount || members.length}`,
+        ];
+        if (cluster.cohesion) {
+            lines.push(`cohesion: ${(cluster.cohesion * 100).toFixed(0)}%`);
+        }
+        if (members.length > 0) {
+            lines.push('');
+            lines.push('members:');
+            for (const member of members.slice(0, 20)) {
+                lines.push(`  - name: ${member.name}`);
+                lines.push(`    type: ${member.type}`);
+                lines.push(`    file: ${member.filePath}`);
+            }
+            if (members.length > 20) {
+                lines.push(`  # ... and ${members.length - 20} more`);
+            }
+        }
+        return lines.join('\n');
+    }
+    catch (err) {
+        return `error: ${err.message}`;
+    }
+}
+/** Step-by-step execution trace for a specific process */
+async function getProcessDetailResource(name, backend, repoName) {
+    try {
+        const result = await backend.queryProcessDetail(name, repoName);
+        if (result.error) {
+            return `error: ${result.error}`;
+        }
+        const proc = result.process;
+        const steps = result.steps || [];
+        const lines = [
+            `name: "${proc.heuristicLabel || proc.label || proc.id}"`,
+            `type: ${proc.processType || 'unknown'}`,
+            `step_count: ${proc.stepCount || steps.length}`,
+        ];
+        if (steps.length > 0) {
+            lines.push('');
+            lines.push('trace:');
+            for (const step of steps) {
+                lines.push(`  ${step.step}: ${step.name} (${step.filePath})`);
+            }
+        }
+        return lines.join('\n');
+    }
+    catch (err) {
+        return `error: ${err.message}`;
+    }
+}
+/** Generate AGENTS.md content for all indexed repos (used for onboarding) */
+async function getSetupResource(backend) {
+    const repos = await backend.listRepos();
+    if (repos.length === 0) {
+        return '# Code Mapper\n\nNo repositories indexed. Run: `npx code-mapper analyze` in a repository.';
+    }
+    const sections = [];
+    for (const repo of repos) {
+        const stats = repo.stats || {};
+        const lines = [
+            `# Code Mapper MCP — ${repo.name}`,
+            '',
+            `This project is indexed by Code Mapper as **${repo.name}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows).`,
+            '',
+            '## Tools',
+            '',
+            '| Tool | What it gives you |',
+            '|------|-------------------|',
+            '| `query` | Process-grouped code intelligence — execution flows related to a concept |',
+            '| `context` | 360-degree symbol view — categorized refs, processes it participates in |',
+            '| `impact` | Symbol blast radius — what breaks at depth 1/2/3 with confidence |',
+            '| `detect_changes` | Git-diff impact — what do your current changes affect |',
+            '| `rename` | Multi-file coordinated rename with confidence-tagged edits |',
+            '| `cypher` | Raw graph queries |',
+            '| `list_repos` | Discover indexed repos |',
+            '',
+            '## Resources',
+            '',
+            `- \`code-mapper://repo/${repo.name}/context\` — Stats, staleness check`,
+            `- \`code-mapper://repo/${repo.name}/clusters\` — All functional areas`,
+            `- \`code-mapper://repo/${repo.name}/processes\` — All execution flows`,
+            `- \`code-mapper://repo/${repo.name}/schema\` — Graph schema for Cypher`,
+        ];
+        sections.push(lines.join('\n'));
+    }
+    return sections.join('\n\n---\n\n');
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,10 @@
+/** @file server.ts
+ *  @description Model Context Protocol server for multi-repo code intelligence
+ *  Runs on stdio for external AI tools (Cursor, Claude) via MCP protocol
+ *  Tools: list_repos, query, cypher, context, impact, detect_changes, rename */
+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) */
+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

@@ -0,0 +1,217 @@
+// code-mapper/src/mcp/server.ts
+/** @file server.ts
+ *  @description Model Context Protocol server for multi-repo code intelligence
+ *  Runs on stdio for external AI tools (Cursor, Claude) via MCP protocol
+ *  Tools: list_repos, query, cypher, context, impact, detect_changes, rename */
+import { createRequire } from 'module';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CompatibleStdioServerTransport } from './compatible-stdio-transport.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CODE_MAPPER_TOOLS } from './tools.js';
+import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';
+// Next-step hints removed — LLMs already know how to chain tools from
+// the MCP tool descriptions. Hints wasted ~40 tokens per response.
+/** Create a configured MCP Server with all handlers registered (transport-agnostic) */
+export function createMCPServer(backend) {
+    // Preload embedding model in background so first query doesn't pay cold-start cost
+    import('./core/embedder.js').then(m => m.initEmbedder()).catch(() => { });
+    const require = createRequire(import.meta.url);
+    const pkgVersion = require('../../package.json').version;
+    const server = new Server({
+        name: 'code-mapper',
+        version: pkgVersion,
+    }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {},
+        },
+    });
+    // List resources
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const resources = getResourceDefinitions();
+        return {
+            resources: resources.map(r => ({
+                uri: r.uri,
+                name: r.name,
+                description: r.description,
+                mimeType: r.mimeType,
+            })),
+        };
+    });
+    // List resource templates (dynamic resources)
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+        const templates = getResourceTemplates();
+        return {
+            resourceTemplates: templates.map(t => ({
+                uriTemplate: t.uriTemplate,
+                name: t.name,
+                description: t.description,
+                mimeType: t.mimeType,
+            })),
+        };
+    });
+    // Read resource
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        try {
+            const content = await readResource(uri, backend);
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'text/yaml',
+                        text: content,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'text/plain',
+                        text: `Error: ${err.message}`,
+                    },
+                ],
+            };
+        }
+    });
+    // List tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: CODE_MAPPER_TOOLS.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        })),
+    }));
+    // Tool calls with next-step hints
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            const result = await backend.callTool(name, args);
+            const resultText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: resultText,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // List prompts
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+        prompts: [
+            {
+                name: 'detect_impact',
+                description: 'Analyze the impact of your current changes before committing. Guides through scope selection, change detection, process analysis, and risk assessment.',
+                arguments: [
+                    { name: 'scope', description: 'What to analyze: unstaged, staged, all, or compare', required: false },
+                    { name: 'base_ref', description: 'Branch/commit for compare scope', required: false },
+                ],
+            },
+            {
+                name: 'generate_map',
+                description: 'Generate architecture documentation from the knowledge graph. Creates a codebase overview with execution flows and mermaid diagrams.',
+                arguments: [
+                    { name: 'repo', description: 'Repository name (omit if only one indexed)', required: false },
+                ],
+            },
+        ],
+    }));
+    // Get prompt
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === 'detect_impact') {
+            const scope = args?.scope || 'all';
+            const baseRef = args?.base_ref || '';
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Analyze the impact of my current code changes before committing.
+
+Follow these steps:
+1. Run \`detect_changes(${JSON.stringify({ scope, ...(baseRef ? { base_ref: baseRef } : {}) })})\` to find what changed and affected processes
+2. For each changed symbol in critical processes, run \`context({name: "<symbol>"})\` to see its full reference graph
+3. For any high-risk items (many callers or cross-process), run \`impact({target: "<symbol>", direction: "upstream"})\` for blast radius
+4. Summarize: changes, affected processes, risk level, and recommended actions
+
+Present the analysis as a clear risk report.`,
+                        },
+                    },
+                ],
+            };
+        }
+        if (name === 'generate_map') {
+            const repo = args?.repo || '';
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Generate architecture documentation for this codebase using the knowledge graph.
+
+Follow these steps:
+1. READ \`code-mapper://repo/${repo || '{name}'}/context\` for codebase stats
+2. READ \`code-mapper://repo/${repo || '{name}'}/clusters\` to see all functional areas
+3. READ \`code-mapper://repo/${repo || '{name}'}/processes\` to see all execution flows
+4. For the top 5 most important processes, READ \`code-mapper://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`,
+                        },
+                    },
+                ],
+            };
+        }
+        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 stdio transport
+    const transport = new CompatibleStdioServerTransport();
+    await server.connect(transport);
+    // Graceful shutdown
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        try {
+            await backend.disconnect();
+        }
+        catch { }
+        try {
+            await server.close();
+        }
+        catch { }
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    // stdin close means the parent process is gone
+    process.stdin.on('end', shutdown);
+    process.stdin.on('error', () => shutdown());
+    process.stdout.on('error', () => shutdown());
+}

package/dist/mcp/staleness.d.ts

@@ -0,0 +1,10 @@
+/** @file staleness.ts
+ *  @description Checks if the Code Mapper index is behind the current git HEAD
+ *  Returns a hint for the LLM to call analyze if stale */
+export interface StalenessInfo {
+    isStale: boolean;
+    commitsBehind: number;
+    hint?: string;
+}
+/** Check how many commits the index is behind HEAD */
+export declare function checkStaleness(repoPath: string, lastCommit: string): StalenessInfo;

package/dist/mcp/staleness.js

@@ -0,0 +1,25 @@
+// code-mapper/src/mcp/staleness.ts
+/** @file staleness.ts
+ *  @description Checks if the Code Mapper index is behind the current git HEAD
+ *  Returns a hint for the LLM to call analyze if stale */
+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 = 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 {
+                isStale: true,
+                commitsBehind,
+                hint: `⚠️ Index is ${commitsBehind} commit${commitsBehind > 1 ? 's' : ''} behind HEAD. Run analyze tool to update.`,
+            };
+        }
+        return { isStale: false, commitsBehind: 0 };
+    }
+    catch {
+        // If git command fails, assume not stale (fail open)
+        return { isStale: false, commitsBehind: 0 };
+    }
+}