@grafema/mcp 0.2.12-beta → 0.3.0-beta

package/src/handlers/issue-handlers.ts

@@ -14,9 +14,7 @@ import type {
 
 export async function handleReportIssue(args: ReportIssueArgs): Promise<ToolResult> {
   const { title, description, context, labels = ['bug'] } = args;
-  // Use user's token if provided, otherwise fall back to project's issue-only token
-  const GRAFEMA_ISSUE_TOKEN = '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';
-  const githubToken = process.env.GITHUB_TOKEN || GRAFEMA_ISSUE_TOKEN;
+  const githubToken = process.env.GITHUB_TOKEN;
   const repo = 'Disentinel/grafema';
 
   // Build issue body
@@ -25,13 +23,12 @@ ${description}
 
 ${context ? `## Context\n\`\`\`\n${context}\n\`\`\`\n` : ''}
 ## Environment
-- Grafema version: 0.1.0-alpha.1
 - Reported via: MCP tool
 
 ---
-*This issue was automatically created via Grafema MCP server.*`;
+*This issue was created via Grafema MCP server.*`;
 
-  // Try GitHub API if token is available
+  // Try GitHub API if user has a token configured
   if (githubToken) {
     try {
       const response = await fetch(`https://api.github.com/repos/${repo}/issues`, {
@@ -51,21 +48,18 @@ ${context ? `## Context\n\`\`\`\n${context}\n\`\`\`\n` : ''}
       if (response.ok) {
         const issue = await response.json() as { html_url: string; number: number };
         return textResult(
-          `✅ Issue created successfully!\n\n` +
-          `**Issue #${issue.number}**: ${issue.html_url}\n\n` +
-          `Thank you for reporting this issue.`
+          `Issue created: #${issue.number} ${issue.html_url}`
         );
       } else {
         const error = await response.text();
         throw new Error(`GitHub API error: ${response.status} - ${error}`);
       }
     } catch (error) {
-      // Fall through to manual template if API fails
       console.error('[report_issue] GitHub API failed:', error);
     }
   }
 
-  // Fallback: return template for manual submission
+  // Return template for manual submission
   const issueUrl = `https://github.com/${repo}/issues/new`;
   const encodedTitle = encodeURIComponent(title);
   const encodedBody = encodeURIComponent(body);
@@ -73,9 +67,10 @@ ${context ? `## Context\n\`\`\`\n${context}\n\`\`\`\n` : ''}
   const directUrl = `${issueUrl}?title=${encodedTitle}&body=${encodedBody}&labels=${encodedLabels}`;
 
   return textResult(
-    `⚠️ Failed to create issue automatically. Please create it manually:\n\n` +
-    `**Quick link** (may truncate long descriptions):\n${directUrl}\n\n` +
-    `**Or copy this template to** ${issueUrl}:\n\n` +
-    `---\n**Title:** ${title}\n\n${body}\n---`
+    `Create issue manually:\n\n` +
+    `**Link:** ${directUrl}\n\n` +
+    `Or copy to ${issueUrl}:\n\n` +
+    `---\n**Title:** ${title}\n\n${body}\n---\n\n` +
+    `Tip: Set GITHUB_TOKEN env var to create issues automatically.`
   );
 }

package/src/handlers/knowledge-handlers.ts

@@ -0,0 +1,242 @@
+/**
+ * MCP Knowledge Handlers
+ */
+
+import { getOrCreateKnowledgeBase } from '../state.js';
+import { textResult, errorResult } from '../utils.js';
+import type {
+  ToolResult,
+  AddKnowledgeArgs,
+  QueryKnowledgeArgs,
+  QueryDecisionsArgs,
+  SupersedeFactArgs,
+  // Disabled: requires git-ingest (US-17). See US-17 in AI-AGENT-STORIES.md
+  // GitChurnArgs,
+  // GitCoChangeArgs,
+  // GitOwnershipArgs,
+  // GitArchaeologyArgs,
+} from '../types.js';
+import type { KBDecision, KBNodeType } from '@grafema/util';
+// Disabled: requires git-ingest (US-17). See US-17 in AI-AGENT-STORIES.md
+// import { getChurn, getCoChanges, getOwnership, getArchaeology } from '@grafema/util';
+
+/**
+ * Add a new knowledge node.
+ */
+export async function handleAddKnowledge(args: AddKnowledgeArgs): Promise<ToolResult> {
+  try {
+    const kb = await getOrCreateKnowledgeBase();
+
+    const node = await kb.addNode({
+      type: args.type as KBNodeType,
+      content: args.content,
+      slug: args.slug,
+      subtype: args.subtype,
+      scope: args.scope as 'global' | 'project' | 'module' | undefined,
+      projections: args.projections,
+      relates_to: args.relates_to,
+      status: args.status as KBDecision['status'],
+      confidence: args.confidence as 'high' | 'medium' | 'low',
+      effective_from: args.effective_from,
+      applies_to: args.applies_to,
+      task_id: args.task_id,
+    });
+
+    return textResult(
+      `Created ${node.type} node: ${node.id}\n` +
+      `File: ${node.filePath}\n` +
+      `Lifecycle: ${node.lifecycle}\n` +
+      (node.content.length > 200
+        ? `Content: ${node.content.slice(0, 200)}...`
+        : `Content: ${node.content}`)
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to add knowledge: ${message}`);
+  }
+}
+
+/**
+ * Query knowledge nodes with filters.
+ */
+export async function handleQueryKnowledge(args: QueryKnowledgeArgs): Promise<ToolResult> {
+  try {
+    const kb = await getOrCreateKnowledgeBase();
+
+    const nodes = await kb.queryNodes({
+      type: args.type as KBNodeType | undefined,
+      projection: args.projection,
+      relates_to: args.relates_to,
+      text: args.text,
+      include_dangling_only: args.include_dangling_only,
+    });
+
+    if (nodes.length === 0) {
+      return textResult('No matching knowledge nodes found.');
+    }
+
+    const lines: string[] = [`Found ${nodes.length} node(s):\n`];
+    for (const node of nodes) {
+      lines.push(`## ${node.id}`);
+      lines.push(`Type: ${node.type} | Lifecycle: ${node.lifecycle}`);
+      if (node.projections.length > 0) lines.push(`Projections: ${node.projections.join(', ')}`);
+      if (node.type === 'DECISION') {
+        const d = node as KBDecision;
+        lines.push(`Status: ${d.status}`);
+        if (d.applies_to?.length) lines.push(`Applies to: ${d.applies_to.join(', ')}`);
+      }
+
+      // Include resolution status for code references
+      const resolved = await kb.resolveReferences(node);
+      if (resolved.length > 0) {
+        lines.push('Code refs:');
+        for (const r of resolved) {
+          const icon = r.status === 'resolved' ? 'OK' : 'DANGLING';
+          lines.push(`  [${icon}] ${r.address}${r.codeNodeId ? ` → ${r.codeNodeId}` : ''}`);
+        }
+      }
+
+      lines.push('');
+      lines.push(node.content.length > 500 ? node.content.slice(0, 500) + '...' : node.content);
+      lines.push('');
+    }
+
+    return textResult(lines.join('\n'));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to query knowledge: ${message}`);
+  }
+}
+
+/**
+ * Query decisions, optionally filtered by module or status.
+ */
+export async function handleQueryDecisions(args: QueryDecisionsArgs): Promise<ToolResult> {
+  try {
+    const kb = await getOrCreateKnowledgeBase();
+
+    let decisions: KBDecision[];
+
+    if (args.module) {
+      decisions = await kb.activeDecisionsFor(args.module);
+      if (args.status) {
+        decisions = decisions.filter(d => d.status === args.status);
+      }
+    } else {
+      const nodes = await kb.queryNodes({
+        type: 'DECISION',
+        status: args.status,
+      });
+      decisions = nodes as KBDecision[];
+    }
+
+    if (decisions.length === 0) {
+      return textResult('No matching decisions found.');
+    }
+
+    const lines: string[] = [`Found ${decisions.length} decision(s):\n`];
+    for (const d of decisions) {
+      lines.push(`## ${d.id} [${d.status}]`);
+      if (d.applies_to?.length) lines.push(`Applies to: ${d.applies_to.join(', ')}`);
+      if (d.effective_from) lines.push(`Effective from: ${d.effective_from}`);
+      if (d.superseded_by) lines.push(`Superseded by: ${d.superseded_by}`);
+      lines.push('');
+      lines.push(d.content);
+      lines.push('');
+    }
+
+    return textResult(lines.join('\n'));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to query decisions: ${message}`);
+  }
+}
+
+/**
+ * Supersede an existing fact with a new version.
+ */
+export async function handleSupersedeFact(args: SupersedeFactArgs): Promise<ToolResult> {
+  try {
+    const kb = await getOrCreateKnowledgeBase();
+
+    const result = await kb.supersedeFact(args.old_id, args.new_content, args.new_slug);
+
+    return textResult(
+      `Superseded fact:\n` +
+      `Old: ${result.old.id} (now has superseded_by: ${result.old.superseded_by})\n` +
+      `New: ${result.new.id}\n` +
+      `File: ${result.new.filePath}`
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to supersede fact: ${message}`);
+  }
+}
+
+/**
+ * Get knowledge base statistics.
+ */
+export async function handleGetKnowledgeStats(): Promise<ToolResult> {
+  try {
+    const kb = await getOrCreateKnowledgeBase();
+    const stats = await kb.getStats();
+
+    const lines: string[] = [
+      `## Knowledge Base Stats\n`,
+      `Total nodes: ${stats.totalNodes}`,
+      `Total edges: ${stats.totalEdges}`,
+    ];
+
+    if (Object.keys(stats.byType).length > 0) {
+      lines.push('\n### By Type');
+      for (const [type, count] of Object.entries(stats.byType)) {
+        lines.push(`- ${type}: ${count}`);
+      }
+    }
+
+    if (Object.keys(stats.byLifecycle).length > 0) {
+      lines.push('\n### By Lifecycle');
+      for (const [lifecycle, count] of Object.entries(stats.byLifecycle)) {
+        lines.push(`- ${lifecycle}: ${count}`);
+      }
+    }
+
+    if (Object.keys(stats.edgesByType).length > 0) {
+      lines.push('\n### Edges by Type');
+      for (const [type, count] of Object.entries(stats.edgesByType)) {
+        lines.push(`- ${type}: ${count}`);
+      }
+    }
+
+    if (stats.danglingRefs.length > 0) {
+      lines.push(`\n### Dangling KB References (${stats.danglingRefs.length})`);
+      for (const ref of stats.danglingRefs.slice(0, 10)) {
+        lines.push(`- ${ref}`);
+      }
+      if (stats.danglingRefs.length > 10) {
+        lines.push(`... and ${stats.danglingRefs.length - 10} more`);
+      }
+    }
+
+    if (stats.danglingCodeRefs.length > 0) {
+      lines.push(`\n### Dangling Code References (${stats.danglingCodeRefs.length})`);
+      for (const ref of stats.danglingCodeRefs.slice(0, 10)) {
+        lines.push(`- ${ref.nodeId} → ${ref.address}`);
+      }
+      if (stats.danglingCodeRefs.length > 10) {
+        lines.push(`... and ${stats.danglingCodeRefs.length - 10} more`);
+      }
+    }
+
+    return textResult(lines.join('\n'));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to get knowledge stats: ${message}`);
+  }
+}
+
+// Disabled: requires git-ingest (US-17). See US-17 in AI-AGENT-STORIES.md
+// export async function handleGitChurn(args: GitChurnArgs): Promise<ToolResult> { ... }
+// export async function handleGitCoChange(args: GitCoChangeArgs): Promise<ToolResult> { ... }
+// export async function handleGitOwnership(args: GitOwnershipArgs): Promise<ToolResult> { ... }
+// export async function handleGitArchaeology(args: GitArchaeologyArgs): Promise<ToolResult> { ... }

package/src/handlers/notation-handlers.ts

@@ -0,0 +1,71 @@
+/**
+ * MCP Notation Handlers — describe tool
+ */
+
+import { ensureAnalyzed } from '../analysis.js';
+import { renderNotation, extractSubgraph, PERSPECTIVES, generateLegend, isGrafemaUri, toCompactSemanticId } from '@grafema/util';
+import type { DescribeOptions } from '@grafema/util';
+import { textResult, errorResult } from '../utils.js';
+import type { ToolResult, DescribeArgs } from '../types.js';
+
+export async function handleDescribe(
+  args: DescribeArgs,
+): Promise<ToolResult> {
+  const db = await ensureAnalyzed();
+  const { target, depth = 1, perspective } = args;
+
+  // Step 1: Resolve target → node ID
+  let node = await db.getNode(target);
+
+  // If not found by semantic ID, try queryNodes for file path or name
+  if (!node) {
+    // Try as file path (MODULE node)
+    for await (const n of db.queryNodes({ file: target, type: 'MODULE' })) {
+      node = n;
+      break;
+    }
+  }
+  if (!node) {
+    // Try by name (any type)
+    for await (const n of db.queryNodes({ name: target })) {
+      node = n;
+      break;
+    }
+  }
+
+  if (!node) {
+    const displayTarget = isGrafemaUri(target) ? toCompactSemanticId(target) : target;
+    return errorResult(
+      `Target not found: "${displayTarget}"\n` +
+      `Try: semantic ID (from find_nodes), file path, or node name.`,
+    );
+  }
+
+  // Step 2: Extract subgraph
+  const subgraph = await extractSubgraph(db, node.id, depth);
+
+  // Step 3: Build options
+  const options: DescribeOptions = {
+    depth,
+    includeLocations: depth >= 2,
+  };
+  if (perspective && PERSPECTIVES[perspective]) {
+    options.archetypeFilter = PERSPECTIVES[perspective];
+  }
+
+  // Step 4: Render
+  const notation = renderNotation(subgraph, options);
+
+  if (!notation.trim()) {
+    return textResult(
+      `[${node.type}] ${node.name ?? node.id}\nNo relationships found at depth=${depth}.`,
+    );
+  }
+
+  // Append legend (generated from archetypes.ts — single source of truth) + LOD hint
+  const depthHint = depth < 3
+    ? `Showing depth=${depth}. Use depth=${depth + 1} for more detail.`
+    : `Showing depth=${depth}.`;
+
+  return textResult(`${notation}\n\n${generateLegend()}\n${depthHint}`);
+}

package/src/handlers/project-handlers.ts

@@ -3,7 +3,7 @@
  */
 
 import { getProjectPath } from '../state.js';
-import { validateServices, validatePatterns, validateWorkspace, GRAFEMA_VERSION, getSchemaVersion } from '@grafema/core';
+import { validateServices, validatePatterns, validateWorkspace, GRAFEMA_VERSION, getSchemaVersion } from '@grafema/util';
 import { existsSync, readdirSync, statSync, writeFileSync, mkdirSync } from 'fs';
 import type { Dirent } from 'fs';
 import { join, basename } from 'path';

package/src/handlers/query-handlers.ts

@@ -9,9 +9,11 @@ import {
   guardResponseSize,
   serializeBigInt,
   findSimilarTypes,
+  extractQueriedTypes,
   textResult,
   errorResult,
 } from '../utils.js';
+import type { DatalogExplainResult, CypherResult } from '@grafema/types';
 import type {
   ToolResult,
   QueryGraphArgs,
@@ -26,42 +28,143 @@ import type {
 
 export async function handleQueryGraph(args: QueryGraphArgs): Promise<ToolResult> {
   const db = await ensureAnalyzed();
-  const { query, limit: requestedLimit, offset: requestedOffset, format: _format, explain: _explain } = args;
+  const { query, language, limit: requestedLimit, offset: requestedOffset, format: _format, explain, count } = args;
 
   const limit = normalizeLimit(requestedLimit);
   const offset = Math.max(0, requestedOffset || 0);
 
   try {
+    // Cypher query path
+    if (language === 'cypher') {
+      if (!('cypherQuery' in db)) {
+        return errorResult('Backend does not support Cypher queries');
+      }
+      const cypherFn = (db as unknown as { cypherQuery: (q: string) => Promise<CypherResult> }).cypherQuery;
+      const result = await cypherFn.call(db, query);
+
+      if (count) {
+        return textResult(`Count: ${result.rowCount}`);
+      }
+
+      if (result.rowCount === 0) {
+        return textResult('Query returned no results.');
+      }
+
+      const paginatedRows = result.rows.slice(offset, offset + limit);
+      const hasMore = offset + limit < result.rowCount;
+
+      const paginationInfo = formatPaginationInfo({
+        limit,
+        offset,
+        returned: paginatedRows.length,
+        total: result.rowCount,
+        hasMore,
+      });
+
+      // Format as table
+      const lines: string[] = [];
+      lines.push(`Found ${result.rowCount} row(s):${paginationInfo}`);
+      lines.push('');
+
+      // Column widths
+      const colWidths = result.columns.map((col, i) => {
+        let maxWidth = col.length;
+        for (const row of paginatedRows) {
+          const cellLen = String(row[i] ?? '').length;
+          if (cellLen > maxWidth) maxWidth = cellLen;
+        }
+        return Math.min(maxWidth, 60);
+      });
+
+      lines.push(result.columns.map((col, i) => col.padEnd(colWidths[i])).join('  '));
+      lines.push(colWidths.map(w => '-'.repeat(w)).join('  '));
+
+      for (const row of paginatedRows) {
+        const line = row.map((cell, i) => {
+          const s = String(cell ?? '');
+          return s.length > colWidths[i] ? s.slice(0, colWidths[i] - 1) + '\u2026' : s.padEnd(colWidths[i]);
+        }).join('  ');
+        lines.push(line);
+      }
+
+      return textResult(guardResponseSize(lines.join('\n')));
+    }
+
     // Check if backend supports Datalog queries
     if (!('checkGuarantee' in db)) {
       return errorResult('Backend does not support Datalog queries');
     }
 
+    // Explain mode — separate path with step-by-step trace
+    if (explain) {
+      const checkFn = (db as unknown as { checkGuarantee: (q: string, explain: true) => Promise<DatalogExplainResult> }).checkGuarantee;
+      const result = await checkFn.call(db, query, true);
+      return textResult(guardResponseSize(formatExplainOutput(result)));
+    }
+
     const checkFn = (db as unknown as { checkGuarantee: (q: string) => Promise<Array<{ bindings: Array<{ name: string; value: string }> }>> }).checkGuarantee;
-    const results = await checkFn(query);
+    const results = await checkFn.call(db, query);
     const total = results.length;
 
+    if (count) {
+      return textResult(`Count: ${total}`);
+    }
+
     if (total === 0) {
-      const nodeCounts = await db.countNodesByType();
-      const totalNodes = Object.values(nodeCounts).reduce((a, b) => a + b, 0);
+      const { nodeTypes, edgeTypes } = extractQueriedTypes(query);
+      const hasQueriedTypes = nodeTypes.length > 0 || edgeTypes.length > 0;
 
-      const typeMatch = query.match(/node\([^,]+,\s*"([^"]+)"\)/);
-      const queriedType = typeMatch ? typeMatch[1] : null;
+      const nodeCounts = await db.countNodesByType();
+      const edgeCounts = edgeTypes.length > 0 ? await db.countEdgesByType() : {};
+      const availableNodeTypes = Object.keys(nodeCounts);
+      const availableEdgeTypes = Object.keys(edgeCounts);
 
       let hint = '';
-      if (queriedType && !nodeCounts[queriedType]) {
-        const availableTypes = Object.keys(nodeCounts);
-        const similar = findSimilarTypes(queriedType, availableTypes);
-        if (similar.length > 0) {
-          hint = `\n💡 Did you mean: ${similar.join(', ')}?`;
+      if (hasQueriedTypes) {
+        const hintLines: string[] = [];
+
+        if (nodeTypes.length > 0 && availableNodeTypes.length === 0) {
+          hintLines.push('Graph has no nodes');
+        } else {
+          for (const queriedType of nodeTypes) {
+            if (!nodeCounts[queriedType]) {
+              const similar = findSimilarTypes(queriedType, availableNodeTypes);
+              if (similar.length > 0) {
+                hintLines.push(`Did you mean: ${similar.join(', ')}? (node type)`);
+              } else {
+                const typeList = availableNodeTypes.slice(0, 10).join(', ');
+                const more = availableNodeTypes.length > 10 ? '...' : '';
+                hintLines.push(`Available node types: ${typeList}${more}`);
+              }
+            }
+          }
+        }
+
+        if (edgeTypes.length > 0 && availableEdgeTypes.length === 0) {
+          hintLines.push('Graph has no edges');
         } else {
-          hint = `\n💡 Available types: ${availableTypes.slice(0, 10).join(', ')}${availableTypes.length > 10 ? '...' : ''}`;
+          for (const queriedType of edgeTypes) {
+            if (!edgeCounts[queriedType]) {
+              const similar = findSimilarTypes(queriedType, availableEdgeTypes);
+              if (similar.length > 0) {
+                hintLines.push(`Did you mean: ${similar.join(', ')}? (edge type)`);
+              } else {
+                const typeList = availableEdgeTypes.slice(0, 10).join(', ');
+                const more = availableEdgeTypes.length > 10 ? '...' : '';
+                hintLines.push(`Available edge types: ${typeList}${more}`);
+              }
+            }
+          }
+        }
+
+        if (hintLines.length > 0) {
+          hint = '\n' + hintLines.map(l => `Hint: ${l}`).join('\n');
         }
       }
 
-      return textResult(
-        `Query returned no results.${hint}\n📊 Graph: ${totalNodes.toLocaleString()} nodes`
-      );
+      const totalNodes = Object.values(nodeCounts).reduce((a, b) => a + b, 0);
+
+      return textResult(`Query returned no results.${hint}\nGraph: ${totalNodes.toLocaleString()} nodes`);
     }
 
     const paginatedResults = results.slice(offset, offset + limit);
@@ -69,16 +172,23 @@ export async function handleQueryGraph(args: QueryGraphArgs): Promise<ToolResult
 
     const enrichedResults: unknown[] = [];
     for (const result of paginatedResults) {
-      const nodeId = result.bindings?.find((b: DatalogBinding) => b.name === 'X')?.value;
-      if (nodeId) {
-        const node = await db.getNode(nodeId);
+      const xBinding = result.bindings?.find((b: DatalogBinding) => b.name === 'X');
+      if (xBinding) {
+        const node = await db.getNode(xBinding.value);
         if (node) {
           enrichedResults.push({
             ...node,
-            id: nodeId,
+            id: xBinding.value,
             file: node.file,
             line: node.line,
           });
+        } else {
+          // Non-node-ID binding (e.g. attr() string value) — return raw bindings map
+          const bindingsMap: Record<string, string> = {};
+          for (const b of result.bindings!) {
+            bindingsMap[b.name] = b.value;
+          }
+          enrichedResults.push(bindingsMap);
         }
       }
     }
@@ -106,7 +216,7 @@ export async function handleQueryGraph(args: QueryGraphArgs): Promise<ToolResult
 
 export async function handleFindCalls(args: FindCallsArgs): Promise<ToolResult> {
   const db = await ensureAnalyzed();
-  const { target: name, limit: requestedLimit, offset: requestedOffset, className } = args;
+  const { name, limit: requestedLimit, offset: requestedOffset, className } = args;
 
   const limit = normalizeLimit(requestedLimit);
   const offset = Math.max(0, requestedOffset || 0);
@@ -116,8 +226,15 @@ export async function handleFindCalls(args: FindCallsArgs): Promise<ToolResult>
   let totalMatched = 0;
 
   for await (const node of db.queryNodes({ type: 'CALL' })) {
-    if (node.name !== name && node['method'] !== name) continue;
-    if (className && node['object'] !== className) continue;
+    const nodeName = node.name ?? '';
+    // Method calls are stored as "receiver.method" (e.g., "kb.queryNodes", "<obj>.load").
+    // Extract the method part so find_calls("queryNodes") matches "kb.queryNodes".
+    const dotIdx = nodeName.lastIndexOf('.');
+    const methodPart = dotIdx >= 0 ? nodeName.slice(dotIdx + 1) : null;
+    const receiverPart = dotIdx >= 0 ? nodeName.slice(0, dotIdx) : null;
+
+    if (nodeName !== name && methodPart !== name) continue;
+    if (className && receiverPart !== className) continue;
 
     totalMatched++;
 
@@ -180,6 +297,52 @@ export async function handleFindCalls(args: FindCallsArgs): Promise<ToolResult>
   return textResult(guardResponseSize(responseText));
 }
 
+function formatExplainOutput(result: DatalogExplainResult): string {
+  const lines: string[] = [];
+
+  lines.push(`Query returned ${result.bindings.length} result(s).\n`);
+
+  if (result.explainSteps.length > 0) {
+    lines.push('Step-by-step execution:');
+    const maxSteps = 50;
+    const stepsToShow = result.explainSteps.slice(0, maxSteps);
+    for (const step of stepsToShow) {
+      const args = step.args.join(', ');
+      lines.push(`  ${step.step}. [${step.operation}] ${step.predicate}(${args}) \u2192 ${step.resultCount} result(s) (${step.durationUs} \u00b5s)`);
+      if (step.details) {
+        lines.push(`     ${step.details}`);
+      }
+    }
+    if (result.explainSteps.length > maxSteps) {
+      lines.push(`  ... ${result.explainSteps.length - maxSteps} more steps`);
+    }
+    lines.push('');
+  }
+
+  lines.push('Statistics:');
+  lines.push(`  Nodes visited:    ${result.stats.nodesVisited}`);
+  lines.push(`  Edges traversed:  ${result.stats.edgesTraversed}`);
+  lines.push(`  Rule evaluations: ${result.stats.ruleEvaluations}`);
+  lines.push(`  Total results:    ${result.stats.totalResults}`);
+  lines.push(`  Duration:         ${result.profile.totalDurationUs} \u00b5s`);
+  lines.push('');
+
+  if (result.bindings.length > 0) {
+    lines.push('Bindings:');
+    const maxBindings = 20;
+    const bindingsToShow = result.bindings.slice(0, maxBindings);
+    for (const row of bindingsToShow) {
+      const pairs = Object.entries(row).map(([k, v]) => `${k}=${v}`).join(', ');
+      lines.push(`  { ${pairs} }`);
+    }
+    if (result.bindings.length > maxBindings) {
+      lines.push(`  ... ${result.bindings.length - maxBindings} more results`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
 export async function handleFindNodes(args: FindNodesArgs): Promise<ToolResult> {
   const db = await ensureAnalyzed();
   const { type, name, file, limit: requestedLimit, offset: requestedOffset } = args;
@@ -191,6 +354,7 @@ export async function handleFindNodes(args: FindNodesArgs): Promise<ToolResult>
   if (type) filter.type = type;
   if (name) filter.name = name;
   if (file) filter.file = file;
+  filter.substringMatch = true;
 
   const nodes: GraphNode[] = [];
   let skipped = 0;

package/src/prompts.ts

@@ -2,7 +2,7 @@
  * MCP Prompts handler logic.
  * Extracted for testability — server.ts is a thin wrapper.
  */
-import { getOnboardingInstruction } from '@grafema/core';
+import { getOnboardingInstruction } from '@grafema/util';
 
 export interface PromptDefinition {
   name: string;