@grafema/mcp 0.3.21 → 0.3.23

package/src/definitions/query-tools.ts

@@ -113,7 +113,7 @@ Use this when you need to:
 
 Returns semantic IDs that you can pass to get_context, get_node, get_neighbors, or find_guards.
 
-Supports partial matches on name and file. Use limit/offset for pagination.`,
+Supports partial matches on name and file. When a name filter returns no exact matches, automatically falls back to fuzzy name matching using token similarity (CamelCase/snake_case aware). Use limit/offset for pagination.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -214,6 +214,107 @@ Tip: Start with max_depth=5, increase if needed.`,
       required: ['source'],
     },
   },
+  {
+    name: 'trace_calls',
+    description: `Trace call chains from or to a function/method, following CALLS and CALLS_REMOTE edges transitively.
+
+Use this when you need to:
+- "What does this function eventually call?" (forward) — full call tree including cross-language hops
+- "Who calls this function?" (backward) — all callers up the stack
+- "Show the full call chain from handler to database" (forward with depth)
+
+Unlike trace_dataflow (which follows data assignments), this follows function CALLS edges:
+- CALLS: same-language function/method invocation
+- CALLS_REMOTE: cross-process/language boundary (IPC, HTTP, socket)
+
+Returns: Indented call tree showing each hop with file:line location.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source: {
+          type: 'string',
+          description: 'Function/method name or semantic ID to trace from',
+        },
+        file: {
+          type: 'string',
+          description: 'File path to disambiguate (optional)',
+        },
+        direction: {
+          type: 'string',
+          description: 'forward (callees), backward (callers), or both (default: forward)',
+          enum: ['forward', 'backward', 'both'],
+        },
+        max_depth: {
+          type: 'number',
+          description: 'Maximum chain depth (default: 10)',
+        },
+      },
+      required: ['source'],
+    },
+  },
+  {
+    name: 'get_shape',
+    description: `Get the shape (methods + properties) of a CLASS, INTERFACE, or typed variable.
+
+Shows all members including inherited ones via EXTENDS chain. For variables,
+follows INSTANCE_OF to find the type, then returns its shape.
+
+Use this to understand:
+- "What methods does GraphBackend have?" → get_shape(target="GraphBackend")
+- "What can I call on this variable?" → get_shape(target="db", file="handlers.ts")
+- "What does this interface require?" → get_shape(target="NodeRecord")
+
+Returns: members (methods + properties), extends chain, implements list.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: {
+          type: 'string',
+          description: 'CLASS, INTERFACE, or variable name (or semantic ID)',
+        },
+        file: {
+          type: 'string',
+          description: 'File path to disambiguate (optional)',
+        },
+      },
+      required: ['target'],
+    },
+  },
+  {
+    name: 'explain',
+    description: `Explain a code element using graph data — returns structured context + prompt for the LLM to summarize.
+
+Unlike other tools that return raw data, this tool returns graph query results
+PLUS a natural-language prompt asking the calling LLM to explain the results
+to the user. The LLM uses its own reasoning to produce a human-readable summary.
+
+No extra API calls needed — the calling model (Claude, GPT, etc.) does the summarization.
+
+Use cases:
+- "Explain where this value comes from" → dataflow trace + summarization prompt
+- "What does this function do?" → structure + calls + prompt to describe
+- "How is this variable used?" → forward trace + prompt to explain usage patterns
+
+The question parameter guides what graph data to fetch and how to frame the summary.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: {
+          type: 'string',
+          description: 'Variable, function, or node name to explain',
+        },
+        file: {
+          type: 'string',
+          description: 'File path to narrow scope',
+        },
+        question: {
+          type: 'string',
+          description: 'What to explain: "where does this value come from?", "what does this function do?", "how is this used?" (default: general explanation)',
+        },
+      },
+      required: ['target'],
+    },
+  },
   {
     name: 'check_invariant',
     description: `Check a one-off code invariant using a Datalog rule. Returns violations if broken.

package/src/handlers/analysis-handlers.ts

@@ -99,13 +99,19 @@ export async function handleGetStats(): Promise<ToolResult> {
     }
   }
 
+  const actionHint =
+    nodeCount > 0
+      ? `\n\nGraph is ready — use find_nodes, find_calls, trace_dataflow to query it.`
+      : `\n\nGraph is empty — call analyze_project to build the graph first.`;
+
   return textResult(
     `Graph Statistics:\n\n` +
       `Total nodes: ${nodeCount.toLocaleString()}\n` +
       `Total edges: ${edgeCount.toLocaleString()}\n\n` +
       `Nodes by type:\n${JSON.stringify(nodesByType, null, 2)}\n\n` +
       `Edges by type:\n${JSON.stringify(edgesByType, null, 2)}` +
-      shardSection
+      shardSection +
+      actionHint
   );
 }
 

package/src/handlers/context-handlers.ts

@@ -4,7 +4,8 @@
 
 import { ensureAnalyzed } from '../analysis.js';
 import { getProjectPath } from '../state.js';
-import { findCallsInFunction, findContainingFunction, FileOverview, buildNodeContext, getNodeDisplayName, formatEdgeMetadata, STRUCTURAL_EDGE_TYPES, isGrafemaUri, toCompactSemanticId } from '@grafema/util';
+import { findCallsInFunction, findContainingFunction, FileOverview, buildNodeContext, getNodeDisplayName, formatEdgeMetadata, STRUCTURAL_EDGE_TYPES, isGrafemaUri, toCompactSemanticId, getShape } from '@grafema/util';
+import type { ClassIndex } from '@grafema/util';
 import type { CallInfo, CallerInfo, NodeContext } from '@grafema/util';
 import { existsSync, readFileSync, realpathSync } from 'fs';
 import { isAbsolute, join, relative } from 'path';
@@ -433,3 +434,81 @@ export async function handleGetFileOverview(
     return errorResult(`Failed to get file overview: ${message}`);
   }
 }
+
+// === GET SHAPE ===
+
+export async function handleGetShape(args: { target: string; file?: string }): Promise<ToolResult> {
+  const db = await ensureAnalyzed();
+  const { target, file } = args;
+
+  // Find the target node
+  let targetNode: GraphNode | null = await db.getNode(target);
+  if (!targetNode) {
+    // Search by name, preferring CLASS/INTERFACE
+    for (const type of ['CLASS', 'INTERFACE', 'VARIABLE', 'CONSTANT', 'PARAMETER']) {
+      for await (const node of db.queryNodes({ type, name: target })) {
+        if (file && !node.file?.includes(file)) continue;
+        targetNode = node;
+        break;
+      }
+      if (targetNode) break;
+    }
+  }
+  if (!targetNode) {
+    return errorResult(`Target "${target}" not found. Provide a CLASS, INTERFACE, or typed variable name.`);
+  }
+
+  // Build class index for EXTENDS chain walking
+  const classIndex: ClassIndex = new Map();
+  for await (const node of db.queryNodes({ type: 'CLASS' })) {
+    if (node.name) classIndex.set(node.name, String(node.id));
+  }
+  for await (const node of db.queryNodes({ type: 'INTERFACE' })) {
+    if (node.name) classIndex.set(node.name, String(node.id));
+  }
+
+  const backend = {
+    getNode: (id: string) => db.getNode(id),
+    getOutgoingEdges: (id: string) => db.getOutgoingEdges(id),
+    getIncomingEdges: (id: string) => db.getIncomingEdges(id),
+  };
+
+  const shape = await getShape(backend as never, String(targetNode.id), classIndex);
+  if (!shape) {
+    return errorResult(`Could not determine shape for "${target}". It may not be a CLASS, INTERFACE, or typed variable.`);
+  }
+
+  // Format output
+  const lines: string[] = [];
+  lines.push(`## Shape: ${shape.name} (${shape.nodeType})`);
+  if (shape.file) lines.push(`File: ${shape.file}`);
+  if (shape.extends.length > 0) lines.push(`Extends: ${shape.extends.join(' → ')}`);
+  if (shape.implements.length > 0) lines.push(`Implements: ${shape.implements.join(', ')}`);
+  lines.push(`Confidence: ${shape.confidence}`);
+  lines.push('');
+
+  // Group members by source
+  const bySource = new Map<string, typeof shape.members>();
+  for (const m of shape.members) {
+    if (!bySource.has(m.from)) bySource.set(m.from, []);
+    bySource.get(m.from)!.push(m);
+  }
+
+  for (const [source, members] of bySource) {
+    const label = source === shape.name ? 'Own members' : `Inherited from ${source}`;
+    lines.push(`### ${label} (${members.length})`);
+    const methods = members.filter(m => m.kind === 'method' || m.kind === 'method_signature');
+    const props = members.filter(m => m.kind === 'property' || m.kind === 'property_signature');
+    if (methods.length > 0) {
+      lines.push(`Methods: ${methods.map(m => m.name).join(', ')}`);
+    }
+    if (props.length > 0) {
+      lines.push(`Properties: ${props.map(m => m.name).join(', ')}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`Total: ${shape.members.length} members`);
+
+  return textResult(lines.join('\n'));
+}

package/src/handlers/dataflow-handlers.ts

@@ -16,12 +16,14 @@ import type {
   ToolResult,
   TraceAliasArgs,
   TraceDataFlowArgs,
+  TraceCallChainArgs,
   CheckInvariantArgs,
   GraphNode,
 } from '../types.js';
 import {
   traceDataflow,
   renderTraceNarrative,
+  traceCallChain,
   type DataflowBackend,
   type TraceDetail,
 } from '@grafema/util';
@@ -155,6 +157,168 @@ export async function handleTraceDataFlow(args: TraceDataFlowArgs): Promise<Tool
   }));
 }
 
+// === TRACE CALL CHAIN ===
+
+export async function handleTraceCallChain(args: TraceCallChainArgs): Promise<ToolResult> {
+  const db = await ensureAnalyzed();
+  const { source, file, direction = 'forward', max_depth = 10 } = args;
+
+  // Find source node (same resolution logic as trace_dataflow)
+  let sourceNode: GraphNode | null = await db.getNode(source);
+  if (!sourceNode) {
+    let fallbackNode: GraphNode | null = null;
+    for (const type of ['FUNCTION', 'METHOD']) {
+      for await (const node of db.queryNodes({ type, name: source })) {
+        if (file && !node.file?.includes(file)) {
+          if (!fallbackNode) fallbackNode = node;
+          continue;
+        }
+        sourceNode = node;
+        break;
+      }
+      if (sourceNode) break;
+    }
+    if (!sourceNode && fallbackNode) {
+      sourceNode = fallbackNode;
+    }
+  }
+  if (!sourceNode) {
+    const displaySource = isGrafemaUri(source) ? toCompactSemanticId(source) : source;
+    return errorResult(`Source "${displaySource}" not found. Provide a FUNCTION or METHOD name.`);
+  }
+
+  const results = await traceCallChain(db as never, sourceNode.id, {
+    direction: direction as 'forward' | 'backward' | 'both',
+    maxDepth: max_depth,
+    limit: 100,
+  });
+
+  // Render as indented call tree
+  const lines: string[] = [];
+  const sourceName = sourceNode.name || source;
+  const sourceFile = sourceNode.file ? sourceNode.file.split('/').pop() : '';
+
+  for (const result of results) {
+    lines.push(`## ${result.direction === 'forward' ? 'Outgoing calls from' : 'Incoming callers of'} ${sourceName} (${sourceFile}:${sourceNode.line ?? '?'})`);
+    lines.push('');
+
+    if (result.chain.length === 0) {
+      lines.push('  (no calls found)');
+      continue;
+    }
+
+    for (const hop of result.chain) {
+      const indent = '  '.repeat(hop.depth + 1);
+      const prefix = hop.remote ? '> calls_remote' : '> calls';
+      const shortFile = hop.file ? hop.file.split('/').pop() : '?';
+      const loc = hop.line ? `${shortFile}:${hop.line}` : shortFile;
+      const unresolvedTag = hop.resolved ? '' : ' [unresolved]';
+      lines.push(`${indent}${prefix} ${hop.name} (${loc})${unresolvedTag}`);
+    }
+
+    lines.push('');
+    lines.push(`${result.totalFound} hop(s) found`);
+  }
+
+  lines.push('');
+  lines.push('Legend: > calls = local call, > calls_remote = cross-process/language boundary');
+
+  return textResult(lines.join('\n'));
+}
+
+// === EXPLAIN (graph data + LLM prompt injection) ===
+
+export interface ExplainArgs {
+  target: string;
+  file?: string;
+  question?: string;
+}
+
+export async function handleExplain(args: ExplainArgs): Promise<ToolResult> {
+  const db = await ensureAnalyzed();
+  const { target, file, question } = args;
+
+  // 1. Find the target node
+  let targetNode: GraphNode | null = await db.getNode(target);
+  if (!targetNode) {
+    for await (const node of db.queryNodes({ name: target })) {
+      if (file && !node.file?.includes(file)) continue;
+      targetNode = node;
+      break;
+    }
+  }
+  if (!targetNode) {
+    // Try PARAMETER, CONSTANT
+    for (const type of ['PARAMETER', 'CONSTANT', 'IMPORT_BINDING']) {
+      for await (const node of db.queryNodes({ type, name: target })) {
+        if (file && !node.file?.includes(file)) continue;
+        targetNode = node;
+        break;
+      }
+      if (targetNode) break;
+    }
+  }
+  if (!targetNode) {
+    return errorResult(`Target "${target}" not found`);
+  }
+
+  // 2. Gather graph context based on question type
+  const dfDb = db as unknown as DataflowBackend;
+  const sections: string[] = [];
+
+  const nodeType = targetNode.nodeType || targetNode.type;
+  const nodeName = targetNode.name || target;
+  const nodeFile = targetNode.file || '';
+
+  sections.push(`## ${nodeType} "${nodeName}" in ${nodeFile}`);
+
+  // Always include dataflow (both directions)
+  const trace = await traceDataflow(dfDb, targetNode.id, {
+    direction: 'both',
+    maxDepth: 8,
+    limit: 30,
+  });
+  const traceText = renderTraceNarrative(trace, nodeName, { detail: 'normal' });
+  sections.push(`### Dataflow\n${traceText}`);
+
+  // Include structure context if it's a function
+  if (nodeType === 'FUNCTION') {
+    const allOutEdges = await db.getOutgoingEdges(targetNode.id);
+    const allInEdges = await db.getIncomingEdges(targetNode.id);
+    const outSummary: string[] = [];
+    const inSummary: string[] = [];
+    for (const edge of allOutEdges.slice(0, 15)) {
+      if (['CALLS', 'CONTAINS', 'HAS_SCOPE'].includes(edge.type)) {
+        const dst = await db.getNode(edge.dst);
+        if (dst) outSummary.push(`${edge.type} → ${dst.nodeType} "${dst.name}"`);
+      }
+    }
+    for (const edge of allInEdges.slice(0, 15)) {
+      if (['CALLS', 'CONTAINS'].includes(edge.type)) {
+        const src = await db.getNode(edge.src);
+        if (src) inSummary.push(`${edge.type} ← ${src.nodeType} "${src.name}"`);
+      }
+    }
+    if (outSummary.length) sections.push(`### Outgoing\n${outSummary.join('\n')}`);
+    if (inSummary.length) sections.push(`### Incoming\n${inSummary.join('\n')}`);
+  }
+
+  // 3. Prompt injection — instruct the calling LLM to summarize
+  const questionText = question || `what is "${nodeName}" and how is it used?`;
+  const prompt = `
+---
+INSTRUCTION: Based on the graph data above, answer the user's question in 2-3 concise sentences.
+Question: "${questionText}"
+Focus on: data origins, transformations, and where the value ends up.
+Use concrete names from the trace (function names, variable names, file paths).
+Do NOT repeat the raw graph data — synthesize it into a human-readable explanation.
+---`;
+
+  sections.push(prompt);
+
+  return textResult(sections.join('\n\n'));
+}
+
 // === CHECK INVARIANT (unchanged) ===
 
 export async function handleCheckInvariant(args: CheckInvariantArgs): Promise<ToolResult> {

package/src/handlers/index.ts

@@ -3,10 +3,11 @@
  */
 
 export { handleQueryGraph, handleFindCalls, handleFindNodes } from './query-handlers.js';
-export { handleTraceAlias, handleTraceDataFlow, handleCheckInvariant } from './dataflow-handlers.js';
+export { handleTraceAlias, handleTraceDataFlow, handleTraceCallChain, handleCheckInvariant, handleExplain } from './dataflow-handlers.js';
+export type { ExplainArgs } from './dataflow-handlers.js';
 export { handleAnalyzeProject, handleGetAnalysisStatus, handleGetStats, handleGetSchema } from './analysis-handlers.js';
 export { handleCreateGuarantee, handleListGuarantees, handleCheckGuarantees, handleDeleteGuarantee } from './guarantee-handlers.js';
-export { handleGetFunctionDetails, handleGetContext, handleGetFileOverview } from './context-handlers.js';
+export { handleGetFunctionDetails, handleGetContext, handleGetFileOverview, handleGetShape } from './context-handlers.js';
 export { handleReadProjectStructure, handleWriteConfig } from './project-handlers.js';
 export { handleGetCoverage } from './coverage-handlers.js';
 export { handleFindGuards } from './guard-handlers.js';