gitnexus 1.1.8 → 1.2.0

package/dist/mcp/resources.d.ts

@@ -20,7 +20,7 @@ export interface ResourceTemplate {
 /**
  * Static resources — includes per-repo resources and the global repos list
  */
-export declare function getResourceDefinitions(backend: LocalBackend): ResourceDefinition[];
+export declare function getResourceDefinitions(): ResourceDefinition[];
 /**
  * Dynamic resource templates
  */

package/dist/mcp/resources.js

@@ -8,54 +8,55 @@ import { checkStaleness } from './staleness.js';
 /**
  * Static resources — includes per-repo resources and the global repos list
  */
-export function getResourceDefinitions(backend) {
-    const resources = [
+export function getResourceDefinitions() {
+    return [
         {
             uri: 'gitnexus://repos',
             name: 'All Indexed Repositories',
             description: 'List of all indexed repos with stats. Read this first to discover available repos.',
             mimeType: 'text/yaml',
         },
+        {
+            uri: 'gitnexus://setup',
+            name: 'GitNexus Setup Content',
+            description: 'Returns AGENTS.md content for all indexed repos. Useful for setup/onboarding.',
+            mimeType: 'text/markdown',
+        },
     ];
-    // Add per-repo context resources
-    const repos = backend.listRepos();
-    for (const repo of repos) {
-        resources.push({
-            uri: `gitnexus://repo/${repo.name}/context`,
-            name: `${repo.name} Overview`,
-            description: `Codebase stats and available tools for ${repo.name}`,
-            mimeType: 'text/yaml',
-        });
-        resources.push({
-            uri: `gitnexus://repo/${repo.name}/clusters`,
-            name: `${repo.name} Clusters`,
-            description: `All functional clusters for ${repo.name}`,
-            mimeType: 'text/yaml',
-        });
-        resources.push({
-            uri: `gitnexus://repo/${repo.name}/processes`,
-            name: `${repo.name} Processes`,
-            description: `All execution flows for ${repo.name}`,
-            mimeType: 'text/yaml',
-        });
-        resources.push({
-            uri: `gitnexus://repo/${repo.name}/schema`,
-            name: `${repo.name} Schema`,
-            description: `Graph schema for Cypher queries on ${repo.name}`,
-            mimeType: 'text/yaml',
-        });
-    }
-    return resources;
 }
 /**
  * Dynamic resource templates
  */
 export function getResourceTemplates() {
     return [
+        {
+            uriTemplate: 'gitnexus://repo/{name}/context',
+            name: 'Repo Overview',
+            description: 'Codebase stats, staleness check, and available tools',
+            mimeType: 'text/yaml',
+        },
+        {
+            uriTemplate: 'gitnexus://repo/{name}/clusters',
+            name: 'Repo Modules',
+            description: 'All functional areas (Leiden clusters)',
+            mimeType: 'text/yaml',
+        },
+        {
+            uriTemplate: 'gitnexus://repo/{name}/processes',
+            name: 'Repo Processes',
+            description: 'All execution flows',
+            mimeType: 'text/yaml',
+        },
+        {
+            uriTemplate: 'gitnexus://repo/{name}/schema',
+            name: 'Graph Schema',
+            description: 'Node/edge schema for Cypher queries',
+            mimeType: 'text/yaml',
+        },
         {
             uriTemplate: 'gitnexus://repo/{name}/cluster/{clusterName}',
-            name: 'Cluster Detail',
-            description: 'Deep dive into a specific cluster',
+            name: 'Module Detail',
+            description: 'Deep dive into a specific functional area',
             mimeType: 'text/yaml',
         },
         {
@@ -72,6 +73,8 @@ export function getResourceTemplates() {
 function parseUri(uri) {
     if (uri === 'gitnexus://repos')
         return { resourceType: 'repos' };
+    if (uri === 'gitnexus://setup')
+        return { resourceType: 'setup' };
     // Repo-scoped: gitnexus://repo/{name}/context
     const repoMatch = uri.match(/^gitnexus:\/\/repo\/([^/]+)\/(.+)$/);
     if (repoMatch) {
@@ -96,6 +99,10 @@ export async function readResource(uri, backend) {
     if (parsed.resourceType === 'repos') {
         return getReposResource(backend);
     }
+    // Setup resource — returns AGENTS.md content for all repos
+    if (parsed.resourceType === 'setup') {
+        return getSetupResource(backend);
+    }
     const repoName = parsed.repoName;
     switch (parsed.resourceType) {
         case 'context':
@@ -157,15 +164,6 @@ async function getContextResource(backend, repoName) {
     const repoPath = repo.repoPath;
     const lastCommit = repo.lastCommit || 'HEAD';
     const staleness = repoPath ? checkStaleness(repoPath, lastCommit) : { isStale: false, commitsBehind: 0 };
-    // Get aggregated cluster count (matches what overview/clusters resource shows)
-    let clusterCount = context.stats.communityCount;
-    try {
-        const overview = await backend.callTool('overview', { showClusters: true, showProcesses: false, limit: 100, repo: repoName });
-        if (overview.clusters) {
-            clusterCount = overview.clusters.length;
-        }
-    }
-    catch { /* fall back to raw count */ }
     const lines = [
         `project: ${context.projectName}`,
     ];
@@ -177,39 +175,38 @@ async function getContextResource(backend, repoName) {
     lines.push('stats:');
     lines.push(`  files: ${context.stats.fileCount}`);
     lines.push(`  symbols: ${context.stats.functionCount}`);
-    lines.push(`  clusters: ${clusterCount}`);
     lines.push(`  processes: ${context.stats.processCount}`);
     lines.push('');
     lines.push('tools_available:');
-    lines.push('  - list_repos: Discover all indexed repositories');
-    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('  - 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 gitnexus analyze` in terminal if data is stale');
     lines.push('');
     lines.push('resources_available:');
     lines.push('  - gitnexus://repos: All indexed repositories');
-    lines.push(`  - gitnexus://repo/${context.projectName}/clusters: All clusters`);
-    lines.push(`  - gitnexus://repo/${context.projectName}/processes: All processes`);
-    lines.push(`  - gitnexus://repo/${context.projectName}/cluster/{name}: Cluster details`);
+    lines.push(`  - gitnexus://repo/${context.projectName}/clusters: All functional areas`);
+    lines.push(`  - gitnexus://repo/${context.projectName}/processes: All execution flows`);
+    lines.push(`  - gitnexus://repo/${context.projectName}/cluster/{name}: Module details`);
     lines.push(`  - gitnexus://repo/${context.projectName}/process/{name}: Process trace`);
     return lines.join('\n');
 }
 /**
- * Clusters resource
+ * Clusters resource — queries graph directly via backend.queryClusters()
  */
 async function getClustersResource(backend, repoName) {
     try {
-        // Request more than we display so aggregation has enough raw data
-        const result = await backend.callTool('overview', { showClusters: true, showProcesses: false, limit: 100, repo: repoName });
+        const result = await backend.queryClusters(repoName, 100);
         if (!result.clusters || result.clusters.length === 0) {
-            return 'clusters: []\n# No clusters detected. Run: gitnexus analyze';
+            return 'modules: []\n# No functional areas detected. Run: gitnexus analyze';
         }
         const displayLimit = 20;
-        const lines = ['clusters:'];
+        const lines = ['modules:'];
         const toShow = result.clusters.slice(0, displayLimit);
         for (const cluster of toShow) {
             const label = cluster.heuristicLabel || cluster.label || cluster.id;
@@ -218,12 +215,9 @@ async function getClustersResource(backend, repoName) {
             if (cluster.cohesion) {
                 lines.push(`    cohesion: ${(cluster.cohesion * 100).toFixed(0)}%`);
             }
-            if (cluster.subCommunities && cluster.subCommunities > 1) {
-                lines.push(`    sub_clusters: ${cluster.subCommunities}`);
-            }
         }
         if (result.clusters.length > displayLimit) {
-            lines.push(`\n# Showing top ${displayLimit} of ${result.clusters.length} clusters. Use gitnexus_search or gitnexus_explore for more.`);
+            lines.push(`\n# Showing top ${displayLimit} of ${result.clusters.length} modules. Use gitnexus_query for deeper search.`);
         }
         return lines.join('\n');
     }
@@ -232,11 +226,11 @@ async function getClustersResource(backend, repoName) {
     }
 }
 /**
- * Processes resource
+ * Processes resource — queries graph directly via backend.queryProcesses()
  */
 async function getProcessesResource(backend, repoName) {
     try {
-        const result = await backend.callTool('overview', { showClusters: false, showProcesses: true, limit: 50, repo: repoName });
+        const result = await backend.queryProcesses(repoName, 50);
         if (!result.processes || result.processes.length === 0) {
             return 'processes: []\n# No processes detected. Run: gitnexus analyze';
         }
@@ -250,7 +244,7 @@ async function getProcessesResource(backend, repoName) {
             lines.push(`    steps: ${proc.stepCount || 0}`);
         }
         if (result.processes.length > displayLimit) {
-            lines.push(`\n# Showing top ${displayLimit} of ${result.processes.length} processes. Use gitnexus_explore for more.`);
+            lines.push(`\n# Showing top ${displayLimit} of ${result.processes.length} processes. Use gitnexus_query for deeper search.`);
         }
         return lines.join('\n');
     }
@@ -266,22 +260,29 @@ function getSchemaResource() {
 
 nodes:
   - File: Source code files
+  - Folder: Directory containers
   - Function: Functions and arrow functions
   - Class: Class definitions
   - Interface: Interface/type definitions
   - Method: Class methods
-  - Community: Functional cluster (Leiden algorithm)
+  - 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
-  - DEFINES: File defines symbol
   - 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"})
@@ -300,26 +301,23 @@ example_queries:
 `;
 }
 /**
- * Cluster detail resource
+ * Cluster detail resource — queries graph directly via backend.queryClusterDetail()
  */
 async function getClusterDetailResource(name, backend, repoName) {
     try {
-        const result = await backend.callTool('explore', { name, type: 'cluster', repo: repoName });
+        const result = await backend.queryClusterDetail(name, repoName);
         if (result.error) {
             return `error: ${result.error}`;
         }
         const cluster = result.cluster;
         const members = result.members || [];
         const lines = [
-            `name: "${cluster.heuristicLabel || cluster.label || cluster.id}"`,
+            `module: "${cluster.heuristicLabel || cluster.label || cluster.id}"`,
             `symbols: ${cluster.symbolCount || members.length}`,
         ];
         if (cluster.cohesion) {
             lines.push(`cohesion: ${(cluster.cohesion * 100).toFixed(0)}%`);
         }
-        if (cluster.subCommunities && cluster.subCommunities > 1) {
-            lines.push(`sub_clusters: ${cluster.subCommunities}`);
-        }
         if (members.length > 0) {
             lines.push('');
             lines.push('members:');
@@ -339,11 +337,11 @@ async function getClusterDetailResource(name, backend, repoName) {
     }
 }
 /**
- * Process detail resource
+ * Process detail resource — queries graph directly via backend.queryProcessDetail()
  */
 async function getProcessDetailResource(name, backend, repoName) {
     try {
-        const result = await backend.callTool('explore', { name, type: 'process', repo: repoName });
+        const result = await backend.queryProcessDetail(name, repoName);
         if (result.error) {
             return `error: ${result.error}`;
         }
@@ -367,3 +365,43 @@ async function getProcessDetailResource(name, backend, repoName) {
         return `error: ${err.message}`;
     }
 }
+/**
+ * Setup resource — generates AGENTS.md content for all indexed repos.
+ * Useful for `gitnexus setup` onboarding or dynamic content injection.
+ */
+async function getSetupResource(backend) {
+    const repos = backend.listRepos();
+    if (repos.length === 0) {
+        return '# GitNexus\n\nNo repositories indexed. Run: `npx gitnexus analyze` in a repository.';
+    }
+    const sections = [];
+    for (const repo of repos) {
+        const stats = repo.stats || {};
+        const lines = [
+            `# GitNexus MCP — ${repo.name}`,
+            '',
+            `This project is indexed by GitNexus 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',
+            '',
+            `- \`gitnexus://repo/${repo.name}/context\` — Stats, staleness check`,
+            `- \`gitnexus://repo/${repo.name}/clusters\` — All functional areas`,
+            `- \`gitnexus://repo/${repo.name}/processes\` — All execution flows`,
+            `- \`gitnexus://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

@@ -7,7 +7,7 @@
  *
  * Supports multiple indexed repositories via the global registry.
  *
- * Tools: list_repos, search, cypher, overview, explore, impact, analyze
+ * Tools: list_repos, query, cypher, context, impact, detect_changes, rename
  * Resources: repos, repo/{name}/context, repo/{name}/clusters, ...
  */
 import type { LocalBackend } from './local/local-backend.js';

package/dist/mcp/server.js

@@ -7,12 +7,12 @@
  *
  * Supports multiple indexed repositories via the global registry.
  *
- * Tools: list_repos, search, cypher, overview, explore, impact, analyze
+ * 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, } from '@modelcontextprotocol/sdk/types.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';
 /**
@@ -31,27 +31,25 @@ function getNextStepHint(toolName, args) {
     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 'search':
-            return `\n\n---\n**Next:** To understand a result in context, use explore({name: "<symbol_name>", type: "symbol"${repoParam}}) to see its callers, callees, and cluster membership.`;
-        case 'explore': {
-            const exploreType = args?.type || 'symbol';
-            if (exploreType === 'symbol') {
-                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.`;
-            }
-            if (exploreType === 'cluster') {
-                return `\n\n---\n**Next:** To drill into a specific symbol, use explore({name: "<symbol_name>", type: "symbol"${repoParam}}). To see execution flows, READ gitnexus://repo/${repoPath}/processes.`;
-            }
-            if (exploreType === 'process') {
-                return `\n\n---\n**Next:** To explore any step in detail, use explore({name: "<step_name>", type: "symbol"${repoParam}}).`;
-            }
-            return '';
-        }
-        case 'overview':
-            return `\n\n---\n**Next:** To drill into a cluster, READ gitnexus://repo/${repoPath}/cluster/{name} or use explore({name: "<cluster_name>", type: "cluster"${repoParam}}).`;
+        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 explore({name: "<name>", type: "symbol"${repoParam}}). For schema reference, READ gitnexus://repo/${repoPath}/schema.`;
+            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 '';
     }
@@ -59,16 +57,17 @@ function getNextStepHint(toolName, args) {
 export async function startMCPServer(backend) {
     const server = new Server({
         name: 'gitnexus',
-        version: '1.1.0',
+        version: '1.1.9',
     }, {
         capabilities: {
             tools: {},
             resources: {},
+            prompts: {},
         },
     });
     // Handle list resources request
     server.setRequestHandler(ListResourcesRequestSchema, async () => {
-        const resources = getResourceDefinitions(backend);
+        const resources = getResourceDefinitions();
         return {
             resources: resources.map(r => ({
                 uri: r.uri,
@@ -154,6 +153,76 @@ export async function startMCPServer(backend) {
             };
         }
     });
+    // 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}`);
+    });
     // Connect to stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);