@grafema/mcp 0.3.21 → 0.3.23

package/src/handlers/query-handlers.ts

@@ -272,6 +272,36 @@ export async function handleFindCalls(args: FindCallsArgs): Promise<ToolResult>
     });
   }
 
+  // Also find callback usages: where the function is passed as argument
+  // Pattern: CALL "action" → PASSES_ARGUMENT → REFERENCE "analyzeAction" → READS_FROM → FUNCTION
+  // Search: REFERENCE nodes with matching name that have incoming PASSES_ARGUMENT
+  if (totalMatched === 0 || calls.length < limit) {
+    for await (const ref of db.queryNodes({ type: 'REFERENCE', name })) {
+      const inEdges = await db.getIncomingEdges(ref.id, ['PASSES_ARGUMENT' as any]);
+      if (inEdges.length === 0) continue;
+
+      totalMatched++;
+      if (skipped < offset) { skipped++; continue; }
+      if (calls.length >= limit) continue;
+
+      const callerNode = await db.getNode(inEdges[0].src);
+      calls.push({
+        id: ref.id,
+        name: `${callerNode?.name ?? '?'}(${name})`,
+        object: undefined,
+        file: ref.file,
+        line: ref.line,
+        resolved: true,
+        target: callerNode ? {
+          type: callerNode.type,
+          name: callerNode.name ?? '',
+          file: callerNode.file,
+          line: callerNode.line,
+        } : null,
+      });
+    }
+  }
+
   if (totalMatched === 0) {
     return textResult(`No calls found for "${className ? className + '.' : ''}${name}"`);
   }
@@ -355,6 +385,7 @@ export async function handleFindNodes(args: FindNodesArgs): Promise<ToolResult>
   if (name) filter.name = name;
   if (file) filter.file = file;
   filter.substringMatch = true;
+  filter.fuzzyNameFallback = true;
 
   const nodes: GraphNode[] = [];
   let skipped = 0;
@@ -362,14 +393,39 @@ export async function handleFindNodes(args: FindNodesArgs): Promise<ToolResult>
 
   for await (const node of db.queryNodes(filter)) {
     totalMatched++;
+    if (skipped < offset) { skipped++; continue; }
+    if (nodes.length < limit) nodes.push(node);
+  }
 
-    if (skipped < offset) {
-      skipped++;
-      continue;
+  // === Progressive fallback chain ===
+  let fallbackLevel = 'exact';
+
+  // Level 2: type relaxation ("did you mean?")
+  if (totalMatched === 0 && type && name) {
+    fallbackLevel = 'type_relaxed';
+    const relaxedFilter: Record<string, unknown> = {};
+    if (name) relaxedFilter.name = name;
+    if (file) relaxedFilter.file = file;
+    relaxedFilter.substringMatch = true;
+    relaxedFilter.fuzzyNameFallback = true;
+
+    for await (const node of db.queryNodes(relaxedFilter)) {
+      totalMatched++;
+      if (nodes.length < 5) nodes.push(node);
     }
+  }
 
-    if (nodes.length < limit) {
-      nodes.push(node);
+  // Level 3: grep fallback — search source files, enrich with nearest graph nodes
+  if (totalMatched === 0 && name) {
+    fallbackLevel = 'grep_enriched';
+    const grepResults = await grepAndEnrich(db, name, file);
+    if (grepResults.length > 0) {
+      const typeList = [...new Set(grepResults.map(r => r.type).filter(Boolean))].join(', ');
+      return textResult(
+        `No graph nodes matched "${name}"${type ? ` (type: ${type})` : ''}. ` +
+        `Found ${grepResults.length} match(es) via text search, enriched with graph context (${typeList || 'unresolved'}):\n\n` +
+        JSON.stringify(serializeBigInt(grepResults), null, 2)
+      );
     }
   }
 
@@ -377,20 +433,189 @@ export async function handleFindNodes(args: FindNodesArgs): Promise<ToolResult>
     return textResult('No nodes found matching criteria');
   }
 
+  // === Rich context enrichment ===
+  // For each found node, add structural context (methods, calls, imports)
+  // Only enrich when result set is small enough (≤10 nodes) to avoid latency
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const enriched = nodes.length <= 10
+    ? await enrichNodes(db as any, nodes)
+    : nodes;
+
   const hasMore = offset + nodes.length < totalMatched;
   const paginationInfo = formatPaginationInfo({
-    limit,
-    offset,
-    returned: nodes.length,
-    total: totalMatched,
-    hasMore,
+    limit, offset, returned: nodes.length, total: totalMatched, hasMore,
   });
 
+  const fallbackNote = fallbackLevel === 'type_relaxed'
+    ? `No ${type} nodes found matching "${name}". Showing results without type filter:\n`
+    : '';
+
   return textResult(
-    `Found ${totalMatched} node(s):${paginationInfo}\n\n${JSON.stringify(
-      serializeBigInt(nodes),
-      null,
-      2
+    `${fallbackNote}Found ${totalMatched} node(s):${paginationInfo}\n\n${JSON.stringify(
+      serializeBigInt(enriched), null, 2
     )}`
   );
 }
+
+/** Enrich nodes with structural context from graph edges */
+async function enrichNodes(
+  db: { getOutgoingEdges(id: string, types?: string[] | null): Promise<Array<Record<string, unknown>>>; getIncomingEdges(id: string, types?: string[] | null): Promise<Array<Record<string, unknown>>> },
+  nodes: GraphNode[]
+): Promise<Array<GraphNode & { _context?: Record<string, unknown> }>> {
+  const result = [];
+  for (const node of nodes) {
+    const nodeId = node.id;
+    if (!nodeId) { result.push(node); continue; }
+
+    const context: Record<string, unknown> = {};
+    try {
+      // Get key outgoing edges (what this node uses/calls/contains)
+      const outEdges = await db.getOutgoingEdges(nodeId, null);
+      const edgeType = (e: Record<string, unknown>) => String(e.type || '');
+      const edgeSrc = (e: Record<string, unknown>) => String(e.src || '');
+
+      const containsCount = outEdges.filter(e => edgeType(e) === 'CONTAINS').length;
+      const callsOut = outEdges.filter(e => edgeType(e) === 'CALLS');
+      const imports = outEdges.filter(e => edgeType(e) === 'IMPORTS_FROM');
+
+      const inEdges = await db.getIncomingEdges(nodeId, null);
+      const callsIn = inEdges.filter(e => edgeType(e) === 'CALLS');
+      const containedBy = inEdges.filter(e => edgeType(e) === 'CONTAINS');
+
+      if (containsCount > 0) context.contains = containsCount;
+      if (callsOut.length > 0) context.calls_out = callsOut.length;
+      if (callsIn.length > 0) {
+        context.called_by = callsIn.length;
+        context.callers = callsIn.slice(0, 3).map(e => humanReadableId(edgeSrc(e)));
+      }
+      if (imports.length > 0) context.imports = imports.length;
+      if (containedBy.length > 0) {
+        context.parent = humanReadableId(edgeSrc(containedBy[0]));
+      }
+
+      // For CLASS/INTERFACE nodes: list methods and properties
+      const nodeType = String(node.type || '');
+      if (nodeType === 'CLASS' || nodeType === 'INTERFACE') {
+        const edgeDst = (e: Record<string, unknown>) => String(e.dst || '');
+        const methodEdges = outEdges.filter(e => edgeType(e) === 'HAS_METHOD');
+        const containsEdges = outEdges.filter(e => edgeType(e) === 'CONTAINS');
+        const memberEdges = methodEdges.length > 0 ? methodEdges : containsEdges;
+        if (memberEdges.length > 0 && memberEdges.length <= 30) {
+          const members = memberEdges
+            .map(e => humanReadableId(edgeDst(e)))
+            .filter(n => n !== '?');
+          if (members.length > 0) context.members = members.slice(0, 15);
+        } else if (memberEdges.length > 30) {
+          context.member_count = memberEdges.length;
+        }
+      }
+    } catch {
+      // Edge queries may fail for some node types — skip enrichment silently
+    }
+
+    if (Object.keys(context).length > 0) {
+      result.push({ ...node, _context: context });
+    } else {
+      result.push(node);
+    }
+  }
+  return result;
+}
+
+/** Convert a semantic ID to human-readable "name in file.ts" format.
+ * Handles: grafema://host/path/file.ts#TYPE->name[scope], path/file.ts#TYPE->name,
+ * TYPE-%3Ename (URL-encoded, no file prefix), or raw node IDs. */
+function humanReadableId(semanticId: string): string {
+  if (!semanticId) return '?';
+  // Decode URI components first
+  let id = semanticId;
+  try { id = decodeURIComponent(id); } catch { /* keep as-is */ }
+
+  // Find the # separator between file path and node descriptor
+  const hashIdx = id.lastIndexOf('#');
+  let filePart = '';
+  let nodePart = id;
+  if (hashIdx !== -1) {
+    filePart = id.slice(0, hashIdx);
+    nodePart = id.slice(hashIdx + 1);
+  }
+
+  const fileName = filePart ? (filePart.split('/').pop() || '') : '';
+
+  // Extract name from TYPE->name or TYPE->name[in:scope,h:hash]
+  const arrowIdx = nodePart.indexOf('->');
+  if (arrowIdx === -1) return fileName || nodePart;
+
+  let name = nodePart.slice(arrowIdx + 2);
+  // Strip scope/hash info [in:xxx,h:xxx]
+  const bracketIdx = name.indexOf('[');
+  let scope = '';
+  if (bracketIdx > 0) {
+    const scopeStr = name.slice(bracketIdx + 1, -1);
+    const inMatch = scopeStr.match(/in:([^,]+)/);
+    if (inMatch) scope = inMatch[1];
+    name = name.slice(0, bracketIdx);
+  }
+
+  // Build readable string: "name" or "name (in scope)" or "name in file.ts"
+  if (scope && scope !== name) {
+    return fileName ? `${name} (in ${scope}) in ${fileName}` : `${name} (in ${scope})`;
+  }
+  return fileName ? `${name} in ${fileName}` : name || '?';
+}
+
+/** Grep source files for a name, then find nearest graph nodes for each match */
+async function grepAndEnrich(
+  db: { queryNodes(filter: Record<string, unknown>): AsyncIterable<GraphNode> },
+  name: string,
+  filePattern?: string
+): Promise<Array<{ file: string; line: number; match: string; type?: string; node_name?: string; node_id?: string }>> {
+  const { execFileSync } = await import('child_process');
+  const { getProjectPath } = await import('../state.js');
+  const projectRoot = getProjectPath();
+  if (!projectRoot) return [];
+
+  try {
+    const args = ['-rn', '--include=*.ts', '--include=*.js', '--include=*.tsx', '-l', name];
+    if (filePattern) args.push(filePattern);
+    else args.push(projectRoot);
+
+    const output = execFileSync('grep', args, {
+      timeout: 5000,
+      maxBuffer: 50000,
+      encoding: 'utf-8',
+    }).trim();
+    if (!output) return [];
+
+    const files = output.split('\n').slice(0, 5);
+    const results = [];
+
+    for (const matchFile of files) {
+      // Find graph nodes in this file
+      const relPath = matchFile.replace(projectRoot + '/', '');
+      const fileNodes: GraphNode[] = [];
+      for await (const node of db.queryNodes({ file: relPath, substringMatch: true })) {
+        if (fileNodes.length < 3) fileNodes.push(node);
+        else break;
+      }
+
+      if (fileNodes.length > 0) {
+        for (const n of fileNodes) {
+          results.push({
+            file: relPath,
+            line: n.line || 0,
+            match: name,
+            type: n.type,
+            node_name: n.name,
+            node_id: n.id,
+          });
+        }
+      } else {
+        results.push({ file: relPath, line: 0, match: name });
+      }
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}

package/src/server.ts

@@ -44,6 +44,7 @@ import {
   handleFindNodes,
   handleTraceAlias,
   handleTraceDataFlow,
+  handleTraceCallChain,
   handleCheckInvariant,
   handleAnalyzeProject,
   handleGetAnalysisStatus,
@@ -62,6 +63,7 @@ import {
   handleReadProjectStructure,
   handleWriteConfig,
   handleGetFileOverview,
+  handleGetShape,
   handleGetNode,
   handleGetNeighbors,
   handleTraverseGraph,
@@ -78,7 +80,9 @@ import {
   handleDescribe,
   handleGraphQLQuery,
   handleQueryRegistry,
+  handleExplain,
 } from './handlers/index.js';
+import type { ExplainArgs } from './handlers/index.js';
 import type {
   ToolResult,
   ReportIssueArgs,
@@ -90,6 +94,7 @@ import type {
   FindNodesArgs,
   TraceAliasArgs,
   TraceDataFlowArgs,
+  TraceCallChainArgs,
   CheckInvariantArgs,
   AnalyzeProjectArgs,
   GetSchemaArgs,
@@ -101,6 +106,7 @@ import type {
   ReadProjectStructureArgs,
   WriteConfigArgs,
   GetFileOverviewArgs,
+  GetShapeArgs,
   GetNodeArgs,
   GetNeighborsArgs,
   TraverseGraphArgs,
@@ -152,20 +158,47 @@ const server = new Server(
 START HERE: call get_stats to check if the graph is loaded (nodeCount > 0).
 If nodeCount is 0, call analyze_project first.
 
-EXPLORATION WORKFLOW:
-1. To understand a file → get_file_overview (shows imports, exports, functions, classes with relationships)
-2. To find functions/classes/modules → find_nodes (filter by type, name, or file pattern)
-3. To find who calls a function → find_calls (returns call sites with resolution status)
-4. To understand data flow → trace_dataflow (forward: where does this value go? backward: where does it come from?)
-5. To understand full context of a node → get_context (shows surrounding code, scope chain, relationships)
-6. For complex pattern queries → query_graph with Datalog (call get_documentation topic="queries" for syntax)
-7. To query architectural decisions and facts → query_knowledge, query_decisions, get_knowledge_stats
-8. To get a compact visual summary → describe (renders DSL notation with archetype-grouped operators)
-9. For DSL syntax reference → get_documentation topic="notation"
-
-KEY INSIGHT: find_nodes supports partial matching on name and file fields.
-Example: find_nodes(file="auth/") returns all nodes in files matching "auth/".
-Example: find_nodes(name="redis", type="CALL") finds all calls containing "redis".`,
+IMPORTANT: for structural questions about code (who calls what, where is something defined,
+how does data flow), avoid using Grep — it only does text matching and misses calls through
+aliases, re-exports, and dynamic dispatch. Use graph tools instead.
+
+TOOL ROUTING — use the right tool for the task:
+- "Where is X defined?" → find_nodes(name="X") or find_nodes(name="X", type="CLASS")
+- "Who calls function X?" → find_calls(name="X")
+- "What does file X contain?" → get_file_overview(file="X")
+- "How does data flow from A to B?" → trace_dataflow(source="A", direction="forward")
+- "What's the structure of class X?" → describe(nodeId="X")
+- "Find all classes in directory Y" → find_nodes(type="CLASS", file="Y/")
+- For text search in comments or strings → Grep
+- For reading exact source code → Read
+
+EXAMPLES — how to answer common questions using graph tools:
+
+Example 1: "Where is the drag and drop handler for the file explorer?"
+  → find_nodes(name="DragAndDrop", type="CLASS")
+  → Result: FileDragAndDrop in src/vs/workbench/contrib/files/browser/views/explorerViewer.ts
+  → Then: get_file_overview(file="explorerViewer.ts") to see related classes
+
+Example 2: "Who calls the createTerminal method?"
+  → find_calls(name="createTerminal")
+  → Result: 12 call sites across 5 files with file:line locations
+  → Then: Read specific call sites for implementation details
+
+Example 3: "What is the lifecycle of a terminal instance?"
+  → find_nodes(name="Terminal", type="CLASS") to find key classes
+  → find_calls(name="createTerminal") to find entry points
+  → trace_dataflow(source="TerminalInstance", direction="forward") to trace the flow
+  → Combine graph results with targeted Read for implementation details
+
+find_nodes supports partial matching: find_nodes(file="auth/") matches all files in auth/.
+find_nodes(name="redis", type="CALL") finds all calls containing "redis".
+
+TIP: If unsure about the type, omit it — find_nodes(name="Foo") searches all types.
+Results include _context with callers, members, and parent — often no follow-up needed.
+
+BUG FIX PATTERN: After identifying a bug in a method, use find_calls(name="method") to check
+ALL callers. Other components may call the same method without the guard your fix adds.
+This catches "same bug, different caller" patterns common in large codebases.`,
   }
 );
 
@@ -217,6 +250,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         result = await handleTraceDataFlow(asArgs<TraceDataFlowArgs>(args));
         break;
 
+      case 'trace_calls':
+        result = await handleTraceCallChain(asArgs<TraceCallChainArgs>(args));
+        break;
+
+      case 'explain':
+        result = await handleExplain(asArgs<ExplainArgs>(args));
+        break;
+
       case 'check_invariant':
         result = await handleCheckInvariant(asArgs<CheckInvariantArgs>(args));
         break;
@@ -286,6 +327,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         result = await handleGetFileOverview(asArgs<GetFileOverviewArgs>(args));
         break;
 
+      case 'get_shape':
+        result = await handleGetShape(asArgs<GetShapeArgs>(args));
+        break;
+
       case 'read_project_structure':
         result = await handleReadProjectStructure(asArgs<ReadProjectStructureArgs>(args));
         break;

package/src/types.ts

@@ -74,6 +74,18 @@ export interface TraceDataFlowArgs {
   detail?: 'summary' | 'normal' | 'full';
 }
 
+export interface TraceCallChainArgs {
+  source: string;
+  file?: string;
+  direction?: string;
+  max_depth?: number;
+}
+
+export interface GetShapeArgs {
+  target: string;
+  file?: string;
+}
+
 export interface CheckInvariantArgs {
   rule: string;
   name?: string;