refactor: improve graph traversal output and configuration

- Reduce max traversal depth from 10 to 5 for better performance
- Add comprehensive parameter controls to search_codebase tool:
  - maxDepth, maxNodesPerChain, includeCode, snippetLength, skip
- Update tool descriptions with progressive optimization strategy
- Change chain format to show relationship paths instead of grouping
- Add projectRoot to output for relative path context
- Improve node formatting with semanticType and relative paths
- Standardize maxNodesPerChain to 5 (applied per depth level)
- Update snippet defaults: 700 chars, 30 max results displayed
- Remove unused groupConnectionsByRelationshipChain method
- Add helper methods for common root path calculation

Author: drewdrewH

src/constants.ts

@@ -1 +1 @@
-export const MAX_TRAVERSAL_DEPTH = 10;
+export const MAX_TRAVERSAL_DEPTH = 5;

src/mcp/constants.ts

@@ -36,13 +36,28 @@ export const TOOL_METADATA = {
     title: 'Search Codebase',
     description: `Search the codebase using semantic similarity to find relevant code, functions, classes, and implementations.
 
-Returns normalized JSON with source code snippets (maxDepth: 3, maxNodesPerChain: 4). Uses JSON:API pattern to deduplicate nodes.
+Returns normalized JSON with source code snippets. Uses JSON:API pattern to deduplicate nodes.
+
+**Default Usage (Recommended)**:
+Start with default parameters for richest context in a single call. Most queries complete successfully.
 
 Parameters:
 - query: Natural language description of what you're looking for
 - limit (default: 10): Number of initial vector search results to consider
 
-Response includes both relationship chains and actual source code for immediate understanding.`,
+**Token Optimization (Only if needed)**:
+Use these parameters ONLY if you encounter token limit errors (>25,000 tokens):
+
+- maxDepth (default: 3): Reduce to 1-2 for shallow exploration
+- maxNodesPerChain (default: 5): Limit chains shown per depth level
+- includeCode (default: true): Set false to get structure only, fetch code separately
+- snippetLength (default: 700): Reduce to 400-600 for smaller code snippets
+- skip (default: 0): For pagination (skip N results)
+
+**Progressive Strategy**:
+1. Try with defaults first
+2. If token error: Use maxDepth=1, includeCode=false for structure
+3. Then traverse deeper or Read specific files for full code`,
   },
   [TOOL_NAMES.naturalLanguageToCypher]: {
     title: 'Natural Language to Cypher',
@@ -60,7 +75,7 @@ Parameters:
 
 Advanced options (use when needed):
 - includeCode (default: true): Set to false for structure-only view without source code
-- maxNodesPerChain: Limit nodes shown per relationship chain (default: 8)
+- maxNodesPerChain (default: 5): Limit chains shown per depth level (applied independently at each depth)
 - summaryOnly: Set to true for just file paths and statistics without detailed traversal
 
 Best practices:
@@ -85,9 +100,9 @@ export const DEFAULTS = {
   traversalDepth: 3,
   skipOffset: 0,
   batchSize: 500,
-  maxResultsDisplayed: 20,
-  codeSnippetLength: 800,
-  chainSnippetLength: 800,
+  maxResultsDisplayed: 30,
+  codeSnippetLength: 700,
+  chainSnippetLength: 700,
 } as const;
 
 // Messages

src/mcp/handlers/traversal.handler.ts

@@ -35,7 +35,6 @@ interface Connection {
 
 export class TraversalHandler {
   private static readonly NODE_NOT_FOUND_QUERY = 'MATCH (n) WHERE n.id = $nodeId RETURN n';
-  private static readonly MAX_NODES_PER_CHAIN = 8;
 
   constructor(private neo4jService: Neo4jService) {}
 
@@ -47,7 +46,7 @@ export class TraversalHandler {
       relationshipTypes,
       includeStartNodeDetails = true,
       includeCode = false,
-      maxNodesPerChain = TraversalHandler.MAX_NODES_PER_CHAIN,
+      maxNodesPerChain = 5,
       summaryOnly = false,
       title = `Node Traversal from: ${nodeId}`,
       snippetLength = DEFAULTS.codeSnippetLength,
@@ -84,7 +83,7 @@ export class TraversalHandler {
       });
 
       return {
-        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(result) }],
       };
     } catch (error) {
       console.error('Node traversal error:', error);
@@ -137,25 +136,6 @@ export class TraversalHandler {
     );
   }
 
-  private groupConnectionsByRelationshipChain(connections: Connection[]): Record<string, Connection[]> {
-    return connections.reduce(
-      (acc, conn) => {
-        // Build chain with direction arrows
-        const chain =
-          conn.relationshipChain
-            ?.map((rel: any) => {
-              // rel has: { type, start, end, properties }
-              return rel.type;
-            })
-            .join(' → ') ?? 'Unknown';
-        acc[chain] ??= [];
-        acc[chain].push(conn);
-        return acc;
-      },
-      {} as Record<string, Connection[]>,
-    );
-  }
-
   private getRelationshipDirection(connection: Connection, startNodeId: string): 'OUTGOING' | 'INCOMING' | 'UNKNOWN' {
     // Check the first relationship in the chain to determine direction from start node
     const firstRel = connection.relationshipChain?.[0] as any;
@@ -190,29 +170,34 @@ export class TraversalHandler {
     // JSON:API normalization - collect all unique nodes
     const nodeMap = new Map<string, any>();
 
+    // Get common root path from all nodes
+    const allNodes = [startNode, ...traversalData.connections.map((c) => c.node)];
+    const projectRoot = this.getCommonRootPath(allNodes);
+
     // Add start node to map
     if (includeStartNodeDetails) {
-      const startNodeData = this.formatNodeJSON(startNode, includeCode, snippetLength);
+      const startNodeData = this.formatNodeJSON(startNode, includeCode, snippetLength, projectRoot);
       nodeMap.set(startNode.properties.id, startNodeData);
     }
 
     // Collect all unique nodes from connections
     traversalData.connections.forEach((conn) => {
       const nodeId = conn.node.properties.id;
       if (!nodeMap.has(nodeId)) {
-        nodeMap.set(nodeId, this.formatNodeJSON(conn.node, includeCode, snippetLength));
+        nodeMap.set(nodeId, this.formatNodeJSON(conn.node, includeCode, snippetLength, projectRoot));
       }
     });
 
     const byDepth = this.groupConnectionsByDepth(traversalData.connections);
 
     return {
+      projectRoot,
       totalConnections: traversalData.connections.length,
       uniqueFiles: this.getUniqueFileCount(traversalData.connections),
       maxDepth: Object.keys(byDepth).length > 0 ? Math.max(...Object.keys(byDepth).map((d) => parseInt(d))) : 0,
       startNodeId: includeStartNodeDetails ? startNode.properties.id : undefined,
       nodes: Object.fromEntries(nodeMap),
-      depths: this.formatConnectionsByDepthWithReferences(byDepth, maxNodesPerChain, startNode.properties.id),
+      depths: this.formatConnectionsByDepthWithReferences(byDepth, maxNodesPerChain),
     };
   }
 
@@ -227,36 +212,43 @@ export class TraversalHandler {
       Object.keys(byDepth).length > 0 ? Math.max(...Object.keys(byDepth).map((d) => parseInt(d))) : 0;
     const uniqueFiles = this.getUniqueFileCount(traversalData.connections);
 
+    const allNodes = [startNode, ...traversalData.connections.map((c) => c.node)];
+    const projectRoot = this.getCommonRootPath(allNodes);
+
     const fileMap = new Map<string, number>();
     traversalData.connections.forEach((conn) => {
       const filePath = conn.node.properties.filePath;
       if (filePath) {
-        fileMap.set(filePath, (fileMap.get(filePath) ?? 0) + 1);
+        const relativePath = this.makeRelativePath(filePath, projectRoot);
+        fileMap.set(relativePath, (fileMap.get(relativePath) ?? 0) + 1);
       }
     });
 
     const connectedFiles = Array.from(fileMap.entries())
       .sort((a, b) => b[1] - a[1])
       .map(([file, count]) => ({ file, nodeCount: count }));
 
+    const maxSummaryFiles = DEFAULTS.maxResultsDisplayed;
+
     return {
+      projectRoot,
       startNodeId: startNode.properties.id,
       nodes: {
-        [startNode.properties.id]: this.formatNodeJSON(startNode, false, 0),
+        [startNode.properties.id]: this.formatNodeJSON(startNode, false, 0, projectRoot),
       },
       totalConnections,
       maxDepth: maxDepthFound,
       uniqueFiles,
-      files: connectedFiles.slice(0, 20),
-      ...(fileMap.size > 20 && { hasMore: fileMap.size - 20 }),
+      files: connectedFiles.slice(0, maxSummaryFiles),
+      ...(fileMap.size > maxSummaryFiles && { hasMore: fileMap.size - maxSummaryFiles }),
     };
   }
 
-  private formatNodeJSON(node: Neo4jNode, includeCode: boolean, snippetLength: number): any {
+  private formatNodeJSON(node: Neo4jNode, includeCode: boolean, snippetLength: number, projectRoot?: string): any {
     const result: any = {
       id: node.properties.id,
-      type: node.labels[0] ?? 'Unknown',
-      filePath: node.properties.filePath,
+      type: node.properties.semanticType ?? node.labels.at(-1) ?? 'Unknown',
+      filePath: projectRoot ? this.makeRelativePath(node.properties.filePath, projectRoot) : node.properties.filePath,
     };
 
     if (node.properties.name) {
@@ -265,14 +257,15 @@ export class TraversalHandler {
 
     if (includeCode && node.properties.sourceCode && node.properties.coreType !== 'SourceFile') {
       const code = node.properties.sourceCode;
-      const maxLength = 1000; // Show max 1000 chars total
+      const maxLength = snippetLength; // Use the provided snippet length
 
       if (code.length <= maxLength) {
         result.sourceCode = code;
       } else {
-        // Show first 500 and last 500 characters
+        // Show first half and last half of the snippet
         const half = Math.floor(maxLength / 2);
-        result.sourceCode = code.substring(0, half) + '\n\n... [truncated] ...\n\n' + code.substring(code.length - half);
+        result.sourceCode =
+          code.substring(0, half) + '\n\n... [truncated] ...\n\n' + code.substring(code.length - half);
         result.hasMore = true;
         result.truncated = code.length - maxLength;
       }
@@ -284,38 +277,70 @@ export class TraversalHandler {
   private formatConnectionsByDepthWithReferences(
     byDepth: Record<number, Connection[]>,
     maxNodesPerChain: number,
-    startNodeId: string,
   ): any[] {
     return Object.keys(byDepth)
       .sort((a, b) => parseInt(a) - parseInt(b))
       .map((depth) => {
         const depthConnections = byDepth[parseInt(depth)];
-        const byRelChain = this.groupConnectionsByRelationshipChain(depthConnections);
-
-        const chains = Object.entries(byRelChain).map(([chain, nodes]) => {
-          const firstNode = nodes[0];
-          const direction = this.getRelationshipDirection(firstNode, startNodeId);
-          const displayNodes = nodes.slice(0, maxNodesPerChain);
-
-          const chainResult: any = {
-            via: chain,
-            direction,
-            count: nodes.length,
-            nodeIds: displayNodes.map((conn) => conn.node.properties.id),
-          };
 
-          if (nodes.length > maxNodesPerChain) {
-            chainResult.hasMore = nodes.length - maxNodesPerChain;
-          }
+        const connectionsToShow = Math.min(depthConnections.length, maxNodesPerChain);
 
-          return chainResult;
+        const chains = depthConnections.slice(0, connectionsToShow).map((conn) => {
+          return (
+            conn.relationshipChain?.map((rel: any) => ({
+              type: rel.type,
+              from: rel.start,
+              to: rel.end,
+            })) ?? []
+          );
         });
 
         return {
           depth: parseInt(depth),
           count: depthConnections.length,
           chains,
+          ...(depthConnections.length > connectionsToShow && {
+            hasMore: depthConnections.length - connectionsToShow,
+          }),
         };
       });
   }
+
+  private getCommonRootPath(nodes: Neo4jNode[]): string {
+    const filePaths = nodes.map((n) => n.properties.filePath).filter(Boolean) as string[];
+
+    if (filePaths.length === 0) return process.cwd();
+
+    // Split all paths into parts
+    const pathParts = filePaths.map((p) => p.split('/'));
+
+    // Find common prefix
+    const commonParts: string[] = [];
+    const firstPath = pathParts[0];
+
+    for (let i = 0; i < firstPath.length; i++) {
+      const part = firstPath[i];
+      if (pathParts.every((p) => p[i] === part)) {
+        commonParts.push(part);
+      } else {
+        break;
+      }
+    }
+
+    return commonParts.join('/') || '/';
+  }
+
+  private makeRelativePath(absolutePath: string | undefined, projectRoot: string): string {
+    if (!absolutePath) return '';
+    if (!projectRoot || projectRoot === '/') return absolutePath;
+
+    // Ensure both paths end consistently
+    const root = projectRoot.endsWith('/') ? projectRoot : projectRoot + '/';
+
+    if (absolutePath.startsWith(root)) {
+      return absolutePath.substring(root.length);
+    }
+
+    return absolutePath;
+  }
 }

src/mcp/tools/search-codebase.tool.ts

@@ -26,9 +26,41 @@ export const createSearchCodebaseTool = (server: McpServer): void => {
           .optional()
           .describe(`Maximum number of results to return (default: ${DEFAULTS.searchLimit})`)
           .default(DEFAULTS.searchLimit),
+        maxDepth: z
+          .number()
+          .int()
+          .optional()
+          .describe(`Maximum depth to traverse relationships (default: ${DEFAULTS.traversalDepth}, max: 10)`)
+          .default(DEFAULTS.traversalDepth),
+        maxNodesPerChain: z
+          .number()
+          .int()
+          .optional()
+          .describe('Maximum chains to show per depth level (default: 5, applied independently at each depth)')
+          .default(5),
+        skip: z.number().int().optional().describe('Number of results to skip for pagination (default: 0)').default(0),
+        includeCode: z
+          .boolean()
+          .optional()
+          .describe('Include source code snippets in results (default: true)')
+          .default(true),
+        snippetLength: z
+          .number()
+          .int()
+          .optional()
+          .describe(`Length of code snippets to include (default: ${DEFAULTS.codeSnippetLength})`)
+          .default(DEFAULTS.codeSnippetLength),
       },
     },
-    async ({ query, limit = DEFAULTS.searchLimit }) => {
+    async ({
+      query,
+      limit = DEFAULTS.searchLimit,
+      maxDepth = DEFAULTS.traversalDepth,
+      maxNodesPerChain = 5,
+      skip = 0,
+      includeCode = true,
+      snippetLength = DEFAULTS.codeSnippetLength,
+    }) => {
       try {
         await debugLog('Search codebase started', { query, limit });
 
@@ -54,14 +86,21 @@ export const createSearchCodebaseTool = (server: McpServer): void => {
         await debugLog('Vector search completed, starting traversal', {
           nodeId,
           resultsCount: vectorResults.length,
+          maxDepth,
+          maxNodesPerChain,
+          skip,
+          includeCode,
+          snippetLength,
         });
 
         return await traversalHandler.traverseFromNode(nodeId, {
-          maxDepth: 3,
+          maxDepth,
           direction: 'BOTH', // Show both incoming (who calls this) and outgoing (what this calls)
-          includeCode: true,
-          maxNodesPerChain: 4,
+          includeCode,
+          maxNodesPerChain,
+          skip,
           summaryOnly: false,
+          snippetLength,
           title: `Exploration from Node: ${nodeId}`,
         });
       } catch (error) {

src/mcp/tools/traverse-from-node.tool.ts

@@ -54,8 +54,8 @@ export const createTraverseFromNodeTool = (server: McpServer): void => {
           .number()
           .int()
           .optional()
-          .describe('Maximum nodes to show per relationship chain (default: 8)')
-          .default(8),
+          .describe('Maximum chains to show per depth level (default: 5, applied independently at each depth)')
+          .default(5),
         summaryOnly: z
           .boolean()
           .optional()
@@ -76,7 +76,7 @@ export const createTraverseFromNodeTool = (server: McpServer): void => {
       direction = 'BOTH',
       relationshipTypes,
       includeCode = true,
-      maxNodesPerChain = 8,
+      maxNodesPerChain = 5,
       summaryOnly = false,
       snippetLength = DEFAULTS.codeSnippetLength,
     }) => {