@veewo/gitnexus 1.3.4

package/dist/mcp/server.js

@@ -0,0 +1,251 @@
+/**
+ * MCP Server (Multi-Repo)
+ *
+ * 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.
+ *
+ * Supports multiple indexed repositories via the global registry.
+ *
+ * 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 { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { GITNEXUS_TOOLS } from './tools.js';
+import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';
+/**
+ * Next-step hints appended to tool responses.
+ *
+ * Agents often stop after one tool call. These hints guide them to the
+ * logical next action, creating a self-guiding workflow without hooks.
+ *
+ * Design: Each hint is a short, actionable instruction (not a suggestion).
+ * The hint references the specific tool/resource to use next.
+ */
+function getNextStepHint(toolName, args) {
+    const repo = args?.repo;
+    const repoParam = repo ? `, repo: "${repo}"` : '';
+    const repoPath = repo || '{name}';
+    switch (toolName) {
+        case 'list_repos':
+            return `\n\n---\n**Next:** READ gitnexus://repo/{name}/context for any repo above to get its overview and check staleness.`;
+        case 'query':
+            return `\n\n---\n**Next:** To understand a specific symbol in depth, use context({name: "<symbol_name>"${repoParam}}) to see categorized refs and process participation.`;
+        case 'context':
+            return `\n\n---\n**Next:** If planning changes, use impact({target: "${args?.name || '<name>'}", direction: "upstream"${repoParam}}) to check blast radius. To see execution flows, READ gitnexus://repo/${repoPath}/processes.`;
+        case 'impact':
+            return `\n\n---\n**Next:** Review d=1 items first (WILL BREAK). To check affected execution flows, READ gitnexus://repo/${repoPath}/processes.`;
+        case 'detect_changes':
+            return `\n\n---\n**Next:** Review affected processes. Use context() on high-risk changed symbols. READ gitnexus://repo/${repoPath}/process/{name} for full execution traces.`;
+        case 'rename':
+            return `\n\n---\n**Next:** Run detect_changes(${repoParam ? `{repo: "${repo}"}` : ''}) to verify no unexpected side effects from the rename.`;
+        case 'cypher':
+            return `\n\n---\n**Next:** To explore a result symbol, use context({name: "<name>"${repoParam}}). For schema reference, READ gitnexus://repo/${repoPath}/schema.`;
+        // Legacy tool names — still return useful hints
+        case 'search':
+            return `\n\n---\n**Next:** To understand a result in context, use context({name: "<symbol_name>"${repoParam}}).`;
+        case 'explore':
+            return `\n\n---\n**Next:** If planning changes, use impact({target: "<name>", direction: "upstream"${repoParam}}).`;
+        case 'overview':
+            return `\n\n---\n**Next:** To drill into an area, READ gitnexus://repo/${repoPath}/cluster/{name}. To see execution flows, READ gitnexus://repo/${repoPath}/processes.`;
+        default:
+            return '';
+    }
+}
+/**
+ * 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',
+    }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {},
+        },
+    });
+    // Handle list resources request
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const resources = getResourceDefinitions();
+        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 — append next-step hints to guide agent workflow
+    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);
+            const hint = getNextStepHint(name, args);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: resultText + hint,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Handle list prompts request
+    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 },
+                ],
+            },
+        ],
+    }));
+    // Handle get prompt request
+    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 \`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
+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`,
+                        },
+                    },
+                ],
+            };
+        }
+        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);
+    // 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.
+ * 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 GITNEXUS_TOOLS: ToolDefinition[];

package/dist/mcp/tools.js

@@ -0,0 +1,195 @@
+/**
+ * MCP Tool Definitions
+ *
+ * Defines the tools that GitNexus exposes to external AI agents.
+ * All tools support an optional `repo` parameter for multi-repo setups.
+ */
+export const GITNEXUS_TOOLS = [
+    {
+        name: 'list_repos',
+        description: `List all indexed repositories available to GitNexus.
+
+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 gitnexus://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.' },
+                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 gitnexus://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, 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
+
+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 gitnexus://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")' },
+                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 gitnexus://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
+Confidence: 1.0 = certain, <0.8 = fuzzy match`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Name of function, class, or file to analyze' },
+                target_uid: { type: 'string', description: 'Optional exact symbol UID (preferred when target name is ambiguous)' },
+                file_path: { type: 'string', description: 'Optional file path filter to disambiguate target name' },
+                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.3)' },
+                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,10 @@
+/**
+ * HTTP API Server
+ *
+ * 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, host?: string) => Promise<void>;