gitnexus 1.1.0 → 1.1.2

package/dist/mcp/resources.js

@@ -2,8 +2,7 @@
  * MCP Resources (Multi-Repo)
  *
  * Provides structured on-demand data to AI agents.
- * Supports repo-scoped URIs (gitnexus://repo/{name}/context)
- * and backwards-compatible global URIs (gitnexus://context).
+ * All resources use repo-scoped URIs: gitnexus://repo/{name}/context
  */
 import { checkStaleness } from './staleness.js';
 /**
@@ -24,7 +23,7 @@ export function getResourceDefinitions(backend) {
         resources.push({
             uri: `gitnexus://repo/${repo.name}/context`,
             name: `${repo.name} Overview`,
-            description: `Codebase stats, hotspots, and available tools for ${repo.name}`,
+            description: `Codebase stats and available tools for ${repo.name}`,
             mimeType: 'text/yaml',
         });
         resources.push({
@@ -46,10 +45,6 @@ export function getResourceDefinitions(backend) {
             mimeType: 'text/yaml',
         });
     }
-    // Backwards compat: if only 1 repo, also expose global URIs
-    if (repos.length === 1) {
-        resources.push({ uri: 'gitnexus://context', name: `${repos[0].name} 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' });
-    }
     return resources;
 }
 /**
@@ -69,57 +64,27 @@ export function getResourceTemplates() {
             description: 'Step-by-step execution trace',
             mimeType: 'text/yaml',
         },
-        // Backwards-compatible templates (for single-repo setups)
-        {
-            uriTemplate: 'gitnexus://cluster/{name}',
-            name: 'Cluster Detail',
-            description: 'Deep dive into a specific cluster (single-repo shorthand)',
-            mimeType: 'text/yaml',
-        },
-        {
-            uriTemplate: 'gitnexus://process/{name}',
-            name: 'Process Trace',
-            description: 'Step-by-step execution trace (single-repo shorthand)',
-            mimeType: 'text/yaml',
-        },
     ];
 }
 /**
- * Parse a resource URI to extract the repo name (if present) and resource type.
+ * Parse a resource URI to extract the repo name and resource type.
  */
 function parseUri(uri) {
+    if (uri === 'gitnexus://repos')
+        return { resourceType: 'repos' };
     // Repo-scoped: gitnexus://repo/{name}/context
     const repoMatch = uri.match(/^gitnexus:\/\/repo\/([^/]+)\/(.+)$/);
     if (repoMatch) {
         const repoName = decodeURIComponent(repoMatch[1]);
         const rest = repoMatch[2];
-        // gitnexus://repo/{name}/cluster/{clusterName}
         if (rest.startsWith('cluster/')) {
             return { repoName, resourceType: 'cluster', param: decodeURIComponent(rest.replace('cluster/', '')) };
         }
-        // gitnexus://repo/{name}/process/{processName}
         if (rest.startsWith('process/')) {
             return { repoName, resourceType: 'process', param: decodeURIComponent(rest.replace('process/', '')) };
         }
         return { repoName, resourceType: rest };
     }
-    // Global (backwards compat): gitnexus://context, gitnexus://cluster/{name}
-    if (uri === 'gitnexus://repos')
-        return { resourceType: 'repos' };
-    if (uri === 'gitnexus://context')
-        return { resourceType: 'context' };
-    if (uri === 'gitnexus://clusters')
-        return { resourceType: 'clusters' };
-    if (uri === 'gitnexus://processes')
-        return { resourceType: 'processes' };
-    if (uri === 'gitnexus://schema')
-        return { resourceType: 'schema' };
-    if (uri.startsWith('gitnexus://cluster/')) {
-        return { resourceType: 'cluster', param: decodeURIComponent(uri.replace('gitnexus://cluster/', '')) };
-    }
-    if (uri.startsWith('gitnexus://process/')) {
-        return { resourceType: 'process', param: decodeURIComponent(uri.replace('gitnexus://process/', '')) };
-    }
     throw new Error(`Unknown resource URI: ${uri}`);
 }
 /**
@@ -131,13 +96,7 @@ export async function readResource(uri, backend) {
     if (parsed.resourceType === 'repos') {
         return getReposResource(backend);
     }
-    // Resolve the target repo
-    let repoName;
-    if (parsed.repoName) {
-        repoName = parsed.repoName;
-    }
-    // For backwards-compat URIs without repo name, resolveRepo() will auto-detect (single-repo)
-    // The backend.callTool already does resolveRepo internally, so we pass repoName as `repo` param.
+    const repoName = parsed.repoName;
     switch (parsed.resourceType) {
         case 'context':
             return getContextResource(backend, repoName);
@@ -235,18 +194,27 @@ async function getContextResource(backend, repoName) {
  */
 async function getClustersResource(backend, repoName) {
     try {
-        const result = await backend.callTool('overview', { showClusters: true, showProcesses: false, limit: 50, repo: repoName });
+        // 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 });
         if (!result.clusters || result.clusters.length === 0) {
             return 'clusters: []\n# No clusters detected. Run: gitnexus analyze';
         }
+        const displayLimit = 20;
         const lines = ['clusters:'];
-        for (const cluster of result.clusters) {
+        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 (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.`);
         }
         return lines.join('\n');
     }
@@ -263,13 +231,18 @@ async function getProcessesResource(backend, repoName) {
         if (!result.processes || result.processes.length === 0) {
             return 'processes: []\n# No processes detected. Run: gitnexus analyze';
         }
+        const displayLimit = 20;
         const lines = ['processes:'];
-        for (const proc of result.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 gitnexus_explore for more.`);
+        }
         return lines.join('\n');
     }
     catch (err) {
@@ -280,41 +253,41 @@ async function getProcessesResource(backend, repoName) {
  * 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
+    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
 `;
 }
 /**
@@ -335,6 +308,9 @@ async function getClusterDetailResource(name, 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 (members.length > 0) {
             lines.push('');
             lines.push('members:');

package/dist/mcp/tools.js

@@ -7,12 +7,12 @@
 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.
-Use this to discover which repos are available before querying.
-
-When multiple repos are indexed, you MUST specify the "repo" parameter
+        description: `List all indexed repositories available to GitNexus.
+
+Returns each repo's name, path, indexed date, last commit, and stats.
+Use this to discover which repos are available before querying.
+
+When multiple repos are indexed, you MUST specify the "repo" parameter
 on other tools (search, explore, impact, etc.) to target the correct one.`,
         inputSchema: {
             type: 'object',
@@ -22,23 +22,23 @@ on other tools (search, explore, impact, etc.) to target the correct one.`,
     },
     {
         name: 'analyze',
-        description: `Index or re-index a 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
-
-Also registers the repo in the global registry so the MCP server can serve it.
-
-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
-
+        description: `Index or re-index a 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
+
+Also registers the repo in the global registry so the MCP server can serve it.
+
+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',
@@ -53,14 +53,14 @@ Note: This may take 30-120 seconds for large repos.`,
     },
     {
         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)
-
+        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',
@@ -75,25 +75,25 @@ RETURNS: Array of {name, type, filePath, cluster?, connections[]?, fusedScore, s
     },
     {
         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
+        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',
@@ -106,14 +106,14 @@ TIPS:
     },
     {
         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
-
+        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',
@@ -127,13 +127,13 @@ Use after search to understand context of a specific node.`,
     },
     {
         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
-
+        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',
@@ -148,23 +148,23 @@ Use to understand overall codebase structure before diving deep.`,
     },
     {
         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)
+        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',

package/package.json

@@ -1,80 +1,80 @@
-{
-  "name": "gitnexus",
-  "version": "1.1.0",
-  "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
-  "author": "Abhigyan Patwari",
-  "license": "PolyForm-Noncommercial-1.0.0",
-  "homepage": "https://github.com/abhigyanpatwari/GitNexus#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/abhigyanpatwari/GitNexus.git",
-    "directory": "gitnexus"
-  },
-  "bugs": {
-    "url": "https://github.com/abhigyanpatwari/GitNexus/issues"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "code-intelligence",
-    "knowledge-graph",
-    "cursor",
-    "claude",
-    "ai-agent",
-    "gitnexus",
-    "static-analysis",
-    "codebase-indexing"
-  ],
-  "type": "module",
-  "bin": {
-    "gitnexus": "dist/cli/index.js"
-  },
-  "files": [
-    "dist",
-    "skills",
-    "vendor"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx watch src/cli/index.ts",
-    "prepare": "npm run build"
-  },
-  "dependencies": {
-    "@huggingface/transformers": "^3.0.0",
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "commander": "^12.0.0",
-    "cors": "^2.8.5",
-    "express": "^4.19.2",
-    "glob": "^11.0.0",
-    "graphology": "^0.25.4",
-    "graphology-indices": "^0.17.0",
-    "graphology-utils": "^2.3.0",
-    "kuzu": "^0.11.3",
-    "lru-cache": "^11.0.0",
-    "mnemonist": "^0.39.0",
-    "ora": "^8.0.0",
-    "pandemonium": "^2.4.0",
-    "tree-sitter": "^0.21.0",
-    "tree-sitter-c": "^0.21.0",
-    "tree-sitter-c-sharp": "^0.21.0",
-    "tree-sitter-cpp": "^0.22.0",
-    "tree-sitter-go": "^0.21.0",
-    "tree-sitter-java": "^0.21.0",
-    "tree-sitter-javascript": "^0.21.0",
-    "tree-sitter-python": "^0.21.0",
-    "tree-sitter-rust": "^0.21.0",
-    "tree-sitter-typescript": "^0.21.0",
-    "typescript": "^5.4.5",
-    "uuid": "^13.0.0"
-  },
-  "devDependencies": {
-    "@types/cors": "^2.8.17",
-    "@types/express": "^4.17.21",
-    "@types/node": "^20.0.0",
-    "@types/uuid": "^10.0.0",
-    "tsx": "^4.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "gitnexus",
+  "version": "1.1.2",
+  "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
+  "author": "Abhigyan Patwari",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "homepage": "https://github.com/abhigyanpatwari/GitNexus#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abhigyanpatwari/GitNexus.git",
+    "directory": "gitnexus"
+  },
+  "bugs": {
+    "url": "https://github.com/abhigyanpatwari/GitNexus/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "code-intelligence",
+    "knowledge-graph",
+    "cursor",
+    "claude",
+    "ai-agent",
+    "gitnexus",
+    "static-analysis",
+    "codebase-indexing"
+  ],
+  "type": "module",
+  "bin": {
+    "gitnexus": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "vendor"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/cli/index.ts",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^12.0.0",
+    "cors": "^2.8.5",
+    "express": "^4.19.2",
+    "glob": "^11.0.0",
+    "graphology": "^0.25.4",
+    "graphology-indices": "^0.17.0",
+    "graphology-utils": "^2.3.0",
+    "kuzu": "^0.11.3",
+    "lru-cache": "^11.0.0",
+    "mnemonist": "^0.39.0",
+    "ora": "^8.0.0",
+    "pandemonium": "^2.4.0",
+    "tree-sitter": "^0.21.0",
+    "tree-sitter-c": "^0.21.0",
+    "tree-sitter-c-sharp": "^0.21.0",
+    "tree-sitter-cpp": "^0.22.0",
+    "tree-sitter-go": "^0.21.0",
+    "tree-sitter-java": "^0.21.0",
+    "tree-sitter-javascript": "^0.21.0",
+    "tree-sitter-python": "^0.21.0",
+    "tree-sitter-rust": "^0.21.0",
+    "tree-sitter-typescript": "^0.21.0",
+    "typescript": "^5.4.5",
+    "uuid": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "@types/uuid": "^10.0.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}