gitnexus 1.0.0

package/dist/mcp/resources.d.ts

@@ -0,0 +1,31 @@
+/**
+ * MCP Resources
+ *
+ * Provides structured on-demand data to AI agents.
+ * Resources complement tools by offering lightweight, cacheable data.
+ */
+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 available when codebase is indexed
+ */
+export declare function getResourceDefinitions(projectName: string): 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,279 @@
+/**
+ * MCP Resources
+ *
+ * Provides structured on-demand data to AI agents.
+ * Resources complement tools by offering lightweight, cacheable data.
+ */
+import { checkStaleness } from './staleness.js';
+/**
+ * Static resources available when codebase is indexed
+ */
+export function getResourceDefinitions(projectName) {
+    return [
+        {
+            uri: 'gitnexus://context',
+            name: `${projectName} Overview`,
+            description: 'Codebase stats, hotspots, and available tools',
+            mimeType: 'text/yaml',
+        },
+        {
+            uri: 'gitnexus://clusters',
+            name: 'All Clusters',
+            description: 'List of all functional clusters with stats',
+            mimeType: 'text/yaml',
+        },
+        {
+            uri: 'gitnexus://processes',
+            name: 'All Processes',
+            description: 'List of all execution flows with types',
+            mimeType: 'text/yaml',
+        },
+        {
+            uri: 'gitnexus://schema',
+            name: 'Graph Schema',
+            description: 'Node types and relationships for Cypher queries',
+            mimeType: 'text/yaml',
+        },
+    ];
+}
+/**
+ * Dynamic resource templates
+ */
+export function getResourceTemplates() {
+    return [
+        {
+            uriTemplate: 'gitnexus://cluster/{name}',
+            name: 'Cluster Detail',
+            description: 'Deep dive into a specific cluster',
+            mimeType: 'text/yaml',
+        },
+        {
+            uriTemplate: 'gitnexus://process/{name}',
+            name: 'Process Trace',
+            description: 'Step-by-step execution trace',
+            mimeType: 'text/yaml',
+        },
+    ];
+}
+/**
+ * Read a resource and return its content
+ */
+export async function readResource(uri, backend) {
+    // Static resources
+    if (uri === 'gitnexus://context') {
+        return getContextResource(backend);
+    }
+    if (uri === 'gitnexus://clusters') {
+        return getClustersResource(backend);
+    }
+    if (uri === 'gitnexus://processes') {
+        return getProcessesResource(backend);
+    }
+    if (uri === 'gitnexus://schema') {
+        return getSchemaResource();
+    }
+    // Dynamic resources
+    if (uri.startsWith('gitnexus://cluster/')) {
+        const name = uri.replace('gitnexus://cluster/', '');
+        return getClusterDetailResource(name, backend);
+    }
+    if (uri.startsWith('gitnexus://process/')) {
+        const name = uri.replace('gitnexus://process/', '');
+        return getProcessDetailResource(name, backend);
+    }
+    throw new Error(`Unknown resource: ${uri}`);
+}
+/**
+ * Context resource - codebase overview
+ */
+async function getContextResource(backend) {
+    const context = backend.context;
+    if (!context) {
+        return 'error: No codebase loaded. Run: gitnexus analyze';
+    }
+    // Check staleness
+    const repoPath = backend.repoPath;
+    const lastCommit = backend.meta?.lastCommit || 'HEAD';
+    const staleness = repoPath ? checkStaleness(repoPath, lastCommit) : { isStale: false, commitsBehind: 0 };
+    const lines = [
+        `project: ${context.projectName}`,
+    ];
+    // Add staleness warning if index is behind
+    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(`  clusters: ${context.stats.communityCount}`);
+    lines.push(`  processes: ${context.stats.processCount}`);
+    lines.push('');
+    lines.push('tools_available:');
+    lines.push('  - search: Hybrid semantic + keyword search');
+    lines.push('  - explore: Deep dive on symbol/cluster/process');
+    lines.push('  - impact: Blast radius analysis');
+    lines.push('  - overview: List all clusters and processes');
+    lines.push('  - cypher: Raw graph queries');
+    lines.push('  - analyze: Re-index to update stale data');
+    lines.push('');
+    lines.push('resources_available:');
+    lines.push('  - gitnexus://clusters: All clusters');
+    lines.push('  - gitnexus://processes: All processes');
+    lines.push('  - gitnexus://cluster/{name}: Cluster details');
+    lines.push('  - gitnexus://process/{name}: Process trace');
+    return lines.join('\n');
+}
+/**
+ * Clusters resource - list all clusters
+ */
+async function getClustersResource(backend) {
+    try {
+        const result = await backend.callTool('overview', { showClusters: true, showProcesses: false, limit: 50 });
+        if (!result.clusters || result.clusters.length === 0) {
+            return 'clusters: []\n# No clusters detected. Run: gitnexus analyze';
+        }
+        const lines = ['clusters:'];
+        for (const cluster of result.clusters) {
+            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)}%`);
+            }
+        }
+        return lines.join('\n');
+    }
+    catch (err) {
+        return `error: ${err.message}`;
+    }
+}
+/**
+ * Processes resource - list all processes
+ */
+async function getProcessesResource(backend) {
+    try {
+        const result = await backend.callTool('overview', { showClusters: false, showProcesses: true, limit: 50 });
+        if (!result.processes || result.processes.length === 0) {
+            return 'processes: []\n# No processes detected. Run: gitnexus analyze';
+        }
+        const lines = ['processes:'];
+        for (const proc of result.processes) {
+            const label = proc.heuristicLabel || proc.label || proc.id;
+            lines.push(`  - name: "${label}"`);
+            lines.push(`    type: ${proc.processType || 'unknown'}`);
+            lines.push(`    steps: ${proc.stepCount || 0}`);
+        }
+        return lines.join('\n');
+    }
+    catch (err) {
+        return `error: ${err.message}`;
+    }
+}
+/**
+ * Schema resource - graph structure for Cypher queries
+ */
+function getSchemaResource() {
+    return `# GitNexus Graph Schema
+
+nodes:
+  - File: Source code files
+  - Function: Functions and arrow functions
+  - Class: Class definitions
+  - Interface: Interface/type definitions
+  - Method: Class methods
+  - Community: Functional cluster (Leiden algorithm)
+  - Process: Execution flow trace
+
+relationships:
+  - CALLS: Function/method invocation
+  - IMPORTS: Module imports
+  - EXTENDS: Class inheritance
+  - IMPLEMENTS: Interface implementation
+  - DEFINES: File defines symbol
+  - MEMBER_OF: Symbol belongs to community
+  - STEP_IN_PROCESS: Symbol is step N in process
+
+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)[0] 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
+`;
+}
+/**
+ * Cluster detail resource
+ */
+async function getClusterDetailResource(name, backend) {
+    try {
+        const result = await backend.callTool('explore', { name, type: 'cluster' });
+        if (result.error) {
+            return `error: ${result.error}`;
+        }
+        const cluster = result.cluster;
+        const members = result.members || [];
+        const lines = [
+            `name: "${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}`;
+    }
+}
+/**
+ * Process detail resource
+ */
+async function getProcessDetailResource(name, backend) {
+    try {
+        const result = await backend.callTool('explore', { name, type: 'process' });
+        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}`;
+    }
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP Server
+ *
+ * Model Context Protocol server that runs on stdio.
+ * External AI tools (Cursor, Claude) spawn this process and
+ * communicate via stdin/stdout using the MCP protocol.
+ *
+ * Tools: context, search, cypher, overview, explore, impact, analyze
+ * Resources: context, clusters, processes, schema, cluster/{name}, process/{name}
+ */
+import type { LocalBackend } from './local/local-backend.js';
+export declare function startMCPServer(backend: LocalBackend): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,130 @@
+/**
+ * MCP Server
+ *
+ * Model Context Protocol server that runs on stdio.
+ * External AI tools (Cursor, Claude) spawn this process and
+ * communicate via stdin/stdout using the MCP protocol.
+ *
+ * Tools: context, search, cypher, overview, explore, impact, analyze
+ * Resources: context, clusters, processes, schema, cluster/{name}, process/{name}
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { GITNEXUS_TOOLS } from './tools.js';
+import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';
+export async function startMCPServer(backend) {
+    const server = new Server({
+        name: 'gitnexus',
+        version: '0.2.0',
+    }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+        },
+    });
+    // Handle list resources request
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const context = backend.context;
+        if (!context) {
+            return { resources: [] };
+        }
+        const resources = getResourceDefinitions(context.projectName);
+        return {
+            resources: resources.map(r => ({
+                uri: r.uri,
+                name: r.name,
+                description: r.description,
+                mimeType: r.mimeType,
+            })),
+        };
+    });
+    // Handle list resource templates request (for 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,
+            })),
+        };
+    });
+    // Handle read resource request
+    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}`,
+                    },
+                ],
+            };
+        }
+    });
+    // Handle list tools request
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: GITNEXUS_TOOLS.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        })),
+    }));
+    // Handle tool calls
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            const result = await backend.callTool(name, args);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Connect to stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Handle graceful shutdown
+    process.on('SIGINT', async () => {
+        await backend.disconnect();
+        await server.close();
+        process.exit(0);
+    });
+    process.on('SIGTERM', async () => {
+        await backend.disconnect();
+        await server.close();
+        process.exit(0);
+    });
+}

package/dist/mcp/staleness.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Staleness Check
+ *
+ * Checks if the GitNexus 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,29 @@
+/**
+ * Staleness Check
+ *
+ * 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';
+/**
+ * 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 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 };
+    }
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,24 @@
+/**
+ * MCP Tool Definitions
+ *
+ * Defines the tools that GitNexus exposes to external AI agents.
+ * Only includes tools that provide unique value over native IDE capabilities.
+ */
+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 GITNEXUS_TOOLS: ToolDefinition[];

package/dist/mcp/tools.js

@@ -0,0 +1,160 @@
+/**
+ * MCP Tool Definitions
+ *
+ * Defines the tools that GitNexus exposes to external AI agents.
+ * Only includes tools that provide unique value over native IDE capabilities.
+ */
+export const GITNEXUS_TOOLS = [
+    {
+        name: 'analyze',
+        description: `Index or re-index the current repository. Runs the full pipeline in-process.
+
+Creates .gitnexus/ in repo root with:
+- Knowledge graph (functions, classes, calls, imports)
+- Full-text search indexes
+- Community detection (Leiden)
+- Process tracing
+- Embeddings for semantic search
+
+Run this when:
+- First time using GitNexus on a repo
+- After major code changes
+- When staleness warning appears in gitnexus://context
+- When 'not indexed' error appears
+
+Note: This may take 30-120 seconds for large repos.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Repo path (default: current directory)' },
+                force: { type: 'boolean', description: 'Re-index even if exists', default: false },
+                skipEmbeddings: { type: 'boolean', description: 'Skip embedding generation (faster)', default: false },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'search',
+        description: `Hybrid search (keyword + semantic) across the codebase.
+Returns code nodes with cluster context and optional graph connections.
+
+BETTER THAN IDE search because:
+- Cluster context (which functional area each result belongs to)
+- Relationship data (callers/callees with depth=full)
+- Hybrid ranking (BM25 + semantic via Reciprocal Rank Fusion)
+
+RETURNS: Array of {name, type, filePath, cluster?, connections[]?, fusedScore, searchSource}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Natural language or keyword search query' },
+                limit: { type: 'number', description: 'Max results to return', default: 10 },
+                depth: { type: 'string', description: 'Result detail: "definitions" (symbols only) or "full" (with relationships)', enum: ['definitions', 'full'], default: 'definitions' },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'cypher',
+        description: `Execute Cypher query against the code knowledge graph.
+
+SCHEMA:
+- Nodes: File, Folder, Function, Class, Interface, Method, Community, Process
+- Edges via CodeRelation.type: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, CONTAINS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+EXAMPLES:
+• Find callers of a function:
+  MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: "validateUser"}) RETURN a.name, a.filePath
+
+• Find all functions in a community:
+  MATCH (f:Function)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community {label: "Auth"}) RETURN f.name
+
+• Find steps in a process:
+  MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process {label: "UserLogin"}) RETURN s.name, r.step ORDER BY r.step
+
+TIPS:
+- All relationships use CodeRelation table with 'type' property
+- Community = functional cluster detected by Leiden algorithm
+- Process = execution flow trace from entry point to terminal`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Cypher query to execute' },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'explore',
+        description: `Deep dive on a symbol, cluster, or process.
+
+TYPE: symbol | cluster | process
+
+For SYMBOL: Shows cluster membership, process participation, callers/callees
+For CLUSTER: Shows members, cohesion score, processes touching it
+For PROCESS: Shows step-by-step trace, clusters traversed, entry/terminal points
+
+Use after search to understand context of a specific node.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Name of symbol, cluster, or process to explore' },
+                type: { type: 'string', description: 'Type: symbol, cluster, or process' },
+            },
+            required: ['name', 'type'],
+        },
+    },
+    {
+        name: 'overview',
+        description: `Get codebase map showing all clusters and processes.
+
+Returns:
+- All communities (clusters) with member counts and cohesion scores
+- All processes with step counts and types (intra/cross-community)
+- High-level architectural view
+
+Use to understand overall codebase structure before diving deep.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                showProcesses: { type: 'boolean', description: 'Include process list', default: true },
+                showClusters: { type: 'boolean', description: 'Include cluster list', default: true },
+                limit: { type: 'number', description: 'Max items per category', default: 20 },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'impact',
+        description: `Analyze the impact of changing a code element.
+Returns all nodes affected by modifying the target, with distance, edge type, and confidence.
+
+USE BEFORE making changes to understand ripple effects.
+
+Output includes:
+- Affected processes (with step positions)
+- Affected clusters (direct/indirect)
+- Risk assessment (critical/high/medium/low)
+- Callers/dependents grouped by depth
+
+EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS
+Confidence: 100% = certain, <80% = fuzzy match
+
+Depth groups:
+- d=1: WILL BREAK (direct callers/importers)
+- d=2: LIKELY AFFECTED (indirect)
+- d=3: MAY NEED TESTING (transitive)`,
+        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 (default: usage-based)' },
+                includeTests: { type: 'boolean', description: 'Include test files (default: false)' },
+                minConfidence: { type: 'number', description: 'Minimum confidence 0-1 (default: 0.7)' },
+            },
+            required: ['target', 'direction'],
+        },
+    },
+];

package/dist/server/api.d.ts

@@ -0,0 +1,6 @@
+/**
+ * HTTP API Server
+ *
+ * REST API for browser-based clients to query the local .gitnexus/ index.
+ */
+export declare const createServer: (port: number) => Promise<void>;