@grafema/mcp 0.2.11 → 0.3.0-beta

package/src/server.ts

@@ -2,7 +2,25 @@
 /**
  * Grafema MCP Server
  *
- * Provides code analysis tools via Model Context Protocol.
+ * Graph-driven code analysis for AI agents. Query the code graph instead of reading files.
+ *
+ * Use Grafema when you need to:
+ * - Navigate code structure (find callers, trace data flow, understand impact)
+ * - Answer "who calls this?", "where is this used?", "what does this affect?"
+ * - Analyze untyped/dynamic codebases where static analysis falls short
+ * - Track relationships across files without manual grep
+ *
+ * Core capabilities:
+ * - Datalog queries for pattern matching (query_graph)
+ * - Call graph navigation (find_calls, get_function_details)
+ * - Data flow tracing (trace_dataflow, trace_alias)
+ * - Graph traversal primitives (get_node, get_neighbors, traverse_graph)
+ * - Code guarantees/invariants (create_guarantee, check_guarantees)
+ *
+ * Workflow:
+ * 1. discover_services — identify project structure
+ * 2. analyze_project — build the graph
+ * 3. Use query tools to explore code relationships
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -15,7 +33,7 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import { PROMPTS, getPrompt } from './prompts.js';
 
-import { TOOLS } from './definitions.js';
+import { TOOLS } from './definitions/index.js';
 import { initializeFromArgs, setupLogging, getProjectPath } from './state.js';
 import { textResult, errorResult, log } from './utils.js';
 import { discoverServices } from './analysis.js';
@@ -43,6 +61,21 @@ import {
   handleReadProjectStructure,
   handleWriteConfig,
   handleGetFileOverview,
+  handleGetNode,
+  handleGetNeighbors,
+  handleTraverseGraph,
+  handleAddKnowledge,
+  handleQueryKnowledge,
+  handleQueryDecisions,
+  handleSupersedeFact,
+  handleGetKnowledgeStats,
+  // Disabled: requires git-ingest (US-17). See US-17 in AI-AGENT-STORIES.md
+  // handleGitChurn,
+  // handleGitCoChange,
+  // handleGitOwnership,
+  // handleGitArchaeology,
+  handleDescribe,
+  handleGraphQLQuery,
 } from './handlers/index.js';
 import type {
   ToolResult,
@@ -66,6 +99,20 @@ import type {
   ReadProjectStructureArgs,
   WriteConfigArgs,
   GetFileOverviewArgs,
+  GetNodeArgs,
+  GetNeighborsArgs,
+  TraverseGraphArgs,
+  AddKnowledgeArgs,
+  QueryKnowledgeArgs,
+  QueryDecisionsArgs,
+  SupersedeFactArgs,
+  // Disabled: requires git-ingest (US-17). See US-17 in AI-AGENT-STORIES.md
+  // GitChurnArgs,
+  // GitCoChangeArgs,
+  // GitOwnershipArgs,
+  // GitArchaeologyArgs,
+  DescribeArgs,
+  GraphQLQueryArgs,
 } from './types.js';
 
 /**
@@ -89,12 +136,32 @@ const server = new Server(
   {
     name: 'grafema-mcp',
     version: '0.1.0',
+    description: 'Graph-driven code analysis. Query the code graph instead of reading files. Navigate call graphs, trace data flow, verify guarantees. For AI agents working with untyped/dynamic codebases.',
   },
   {
     capabilities: {
       tools: {},
       prompts: {},
     },
+    instructions: `Grafema is a code graph — use it instead of reading files.
+
+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".`,
   }
 );
 
@@ -223,6 +290,63 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         result = await handleWriteConfig(asArgs<WriteConfigArgs>(args));
         break;
 
+      case 'get_node':
+        result = await handleGetNode(asArgs<GetNodeArgs>(args));
+        break;
+
+      case 'get_neighbors':
+        result = await handleGetNeighbors(asArgs<GetNeighborsArgs>(args));
+        break;
+
+      case 'traverse_graph':
+        result = await handleTraverseGraph(asArgs<TraverseGraphArgs>(args));
+        break;
+
+      case 'add_knowledge':
+        result = await handleAddKnowledge(asArgs<AddKnowledgeArgs>(args));
+        break;
+
+      case 'query_knowledge':
+        result = await handleQueryKnowledge(asArgs<QueryKnowledgeArgs>(args));
+        break;
+
+      case 'query_decisions':
+        result = await handleQueryDecisions(asArgs<QueryDecisionsArgs>(args));
+        break;
+
+      case 'supersede_fact':
+        result = await handleSupersedeFact(asArgs<SupersedeFactArgs>(args));
+        break;
+
+      case 'get_knowledge_stats':
+        result = await handleGetKnowledgeStats();
+        break;
+
+      // Disabled: requires git-ingest (US-17). See US-17 in AI-AGENT-STORIES.md
+      // case 'git_churn':
+      //   result = await handleGitChurn(asArgs<GitChurnArgs>(args));
+      //   break;
+      //
+      // case 'git_cochange':
+      //   result = await handleGitCoChange(asArgs<GitCoChangeArgs>(args));
+      //   break;
+      //
+      // case 'git_ownership':
+      //   result = await handleGitOwnership(asArgs<GitOwnershipArgs>(args));
+      //   break;
+      //
+      // case 'git_archaeology':
+      //   result = await handleGitArchaeology(asArgs<GitArchaeologyArgs>(args));
+      //   break;
+
+      case 'describe':
+        result = await handleDescribe(asArgs<DescribeArgs>(args));
+        break;
+
+      case 'query_graphql':
+        result = await handleGraphQLQuery(asArgs<GraphQLQueryArgs>(args));
+        break;
+
       default:
         result = errorResult(`Unknown tool: ${name}`);
     }

package/src/state.ts

@@ -4,8 +4,8 @@
 
 import { join } from 'path';
 import { existsSync, mkdirSync } from 'fs';
-import { RFDBServerBackend, GuaranteeManager, GuaranteeAPI } from '@grafema/core';
-import type { GuaranteeGraphBackend, GuaranteeGraph } from '@grafema/core';
+import { RFDBServerBackend, GuaranteeManager, GuaranteeAPI, KnowledgeBase } from '@grafema/util';
+import type { GuaranteeGraphBackend, GuaranteeGraph, ResolverBackend } from '@grafema/util';
 import { loadConfig } from './config.js';
 import { log, initLogger } from './utils.js';
 import type { AnalysisStatus } from './types.js';
@@ -21,6 +21,9 @@ let backgroundPid: number | null = null;
 let guaranteeManager: GuaranteeManager | null = null;
 let guaranteeAPI: GuaranteeAPI | null = null;
 
+// Knowledge base
+let knowledgeBase: KnowledgeBase | null = null;
+
 let analysisStatus: AnalysisStatus = {
   running: false,
   phase: null,
@@ -112,6 +115,10 @@ export function getGuaranteeAPI(): GuaranteeAPI | null {
   return guaranteeAPI;
 }
 
+export function getKnowledgeBase(): KnowledgeBase | null {
+  return knowledgeBase;
+}
+
 // === SETTERS ===
 export function setProjectPath(path: string): void {
   projectPath = path;
@@ -213,9 +220,28 @@ export async function waitForAnalysis(): Promise<void> {
   }
 }
 
-// === BACKEND ===
+// === RESET ===
+export function resetBackend(): void {
+  backend = null;
+  isAnalyzed = false;
+}
+
+export function resetKnowledgeBase(): void {
+  knowledgeBase = null;
+}
+
 export async function getOrCreateBackend(): Promise<GraphBackend> {
-  if (backend) return backend;
+  // Check if existing backend is still connected
+  if (backend) {
+    const rfdb = backend as unknown as RFDBServerBackend;
+    if (rfdb.connected) return backend;
+    // Connection died — reset and recreate
+    log('[Grafema MCP] Backend disconnected, reconnecting...');
+    backend = null;
+    isAnalyzed = false;
+    guaranteeManager = null;
+    guaranteeAPI = null;
+  }
 
   const grafemaDir = join(projectPath, '.grafema');
   const dbPath = join(grafemaDir, 'graph.rfdb');
@@ -230,7 +256,7 @@ export async function getOrCreateBackend(): Promise<GraphBackend> {
 
   log(`[Grafema MCP] Using RFDB server backend: socket=${socketPath || 'auto'}, db=${dbPath}`);
 
-  const rfdbBackend = new RFDBServerBackend({ socketPath, dbPath });
+  const rfdbBackend = new RFDBServerBackend({ socketPath, dbPath, clientName: 'mcp' });
   await rfdbBackend.connect();
   backend = rfdbBackend as unknown as GraphBackend;
 
@@ -243,21 +269,32 @@ export async function getOrCreateBackend(): Promise<GraphBackend> {
   }
 
   // Initialize guarantee managers
-  initializeGuaranteeManagers(rfdbBackend);
+  await initializeGuaranteeManagers(rfdbBackend);
 
   return backend;
 }
 
 /**
- * Initialize GuaranteeManager (Datalog-based) and GuaranteeAPI (contract-based)
+ * Initialize GuaranteeManager (Datalog-based) and GuaranteeAPI (contract-based).
+ * Loads guarantees from .grafema/guarantees.yaml if the file exists.
  */
-function initializeGuaranteeManagers(rfdbBackend: RFDBServerBackend): void {
+async function initializeGuaranteeManagers(rfdbBackend: RFDBServerBackend): Promise<void> {
   // GuaranteeManager for Datalog-based guarantees
   // Cast to GuaranteeGraph interface expected by GuaranteeManager
   const guaranteeGraph = rfdbBackend as unknown as GuaranteeGraph;
   guaranteeManager = new GuaranteeManager(guaranteeGraph, projectPath);
   log(`[Grafema MCP] GuaranteeManager initialized`);
 
+  // Load guarantees from YAML (idempotent, skips existing)
+  try {
+    const result = await guaranteeManager.loadFromYaml();
+    if (result.imported > 0 || result.skipped > 0) {
+      log(`[Grafema MCP] Guarantees loaded from YAML: ${result.imported} imported, ${result.skipped} skipped`);
+    }
+  } catch (err) {
+    log(`[Grafema MCP] Warning: failed to load guarantees from YAML: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
   // GuaranteeAPI for contract-based guarantees
   const guaranteeGraphBackend = rfdbBackend as unknown as GuaranteeGraphBackend;
   guaranteeAPI = new GuaranteeAPI(guaranteeGraphBackend);
@@ -277,6 +314,29 @@ export function setupLogging(): void {
   initLogger(grafemaDir);
 }
 
+// === KNOWLEDGE BASE ===
+/**
+ * Get or create the KnowledgeBase singleton.
+ * Lazy-initializes from knowledge/ directory on first access.
+ * If a backend is available, wires up the SemanticAddressResolver.
+ */
+export async function getOrCreateKnowledgeBase(): Promise<KnowledgeBase> {
+  if (knowledgeBase) return knowledgeBase;
+
+  const kbDir = join(projectPath, 'knowledge');
+  knowledgeBase = new KnowledgeBase(kbDir);
+  await knowledgeBase.load();
+  log(`[Grafema MCP] KnowledgeBase loaded from ${kbDir}`);
+
+  // Wire up resolver with backend if available (cast to ResolverBackend — RFDBServerBackend has getAllNodes)
+  if (backend) {
+    knowledgeBase.setBackend(backend as unknown as ResolverBackend);
+    log(`[Grafema MCP] KnowledgeBase resolver wired to backend`);
+  }
+
+  return knowledgeBase;
+}
+
 // === INITIALIZATION ===
 export function initializeFromArgs(): void {
   const args = process.argv.slice(2);

package/src/types.ts

@@ -36,20 +36,23 @@ export interface PaginationParams {
 }
 
 // === CONFIG ===
-export type { GrafemaConfig } from '@grafema/core';
+export type { GrafemaConfig } from '@grafema/util';
 export type { MCPConfig } from './config.js';
 
 // === TOOL ARGUMENTS ===
 export interface QueryGraphArgs {
   query: string;
+  language?: 'datalog' | 'cypher';
   limit?: number;
   offset?: number;
   format?: 'table' | 'json' | 'tree';
   explain?: boolean;
+  /** When true, returns only the count of matching results instead of the full result list */
+  count?: boolean;
 }
 
 export interface FindCallsArgs {
-  target: string;
+  name: string;
   limit?: number;
   offset?: number;
   include_indirect?: boolean;
@@ -68,6 +71,7 @@ export interface TraceDataFlowArgs {
   direction?: 'forward' | 'backward' | 'both';
   max_depth?: number;
   limit?: number;
+  detail?: 'summary' | 'normal' | 'full';
 }
 
 export interface CheckInvariantArgs {
@@ -265,7 +269,7 @@ export interface GetFunctionDetailsArgs {
 }
 
 // Re-export types from core for convenience
-export type { CallInfo, CallerInfo, FindCallsOptions } from '@grafema/core';
+export type { CallInfo, CallerInfo, FindCallsOptions } from '@grafema/util';
 
 /**
  * Datalog query result binding
@@ -343,3 +347,94 @@ export interface WriteConfigArgs {
     roots?: string[];
   };
 }
+
+// === Graph traversal tools (REG-521) ===
+
+export interface GetNodeArgs {
+  semanticId: string;
+}
+
+export interface GetNeighborsArgs {
+  semanticId: string;
+  direction?: 'outgoing' | 'incoming' | 'both';
+  edgeTypes?: string[];
+}
+
+export interface TraverseGraphArgs {
+  startNodeIds: string[];
+  edgeTypes: string[];
+  maxDepth?: number;
+  direction?: 'outgoing' | 'incoming';
+}
+
+// === KNOWLEDGE ARGS (REG-626) ===
+
+export interface AddKnowledgeArgs {
+  type: string;
+  content: string;
+  slug?: string;
+  subtype?: string;
+  scope?: string;
+  relates_to?: string[];
+  projections?: string[];
+  status?: string;
+  confidence?: string;
+  effective_from?: string;
+  applies_to?: string[];
+  task_id?: string;
+}
+
+export interface QueryKnowledgeArgs {
+  type?: string;
+  projection?: string;
+  relates_to?: string;
+  text?: string;
+  include_dangling_only?: boolean;
+}
+
+export interface QueryDecisionsArgs {
+  module?: string;
+  status?: string;
+}
+
+export interface SupersedeFactArgs {
+  old_id: string;
+  new_content: string;
+  new_slug?: string;
+}
+
+// === DESCRIBE ARGS (DSL notation) ===
+
+export interface DescribeArgs {
+  target: string;
+  depth?: number;
+  perspective?: string;
+}
+
+// === GIT QUERY ARGS (REG-628) ===
+
+export interface GitChurnArgs {
+  limit?: number;
+  since?: string;
+}
+
+export interface GitCoChangeArgs {
+  file: string;
+  min_support?: number;
+}
+
+export interface GitOwnershipArgs {
+  file: string;
+}
+
+export interface GitArchaeologyArgs {
+  file: string;
+}
+
+// === GRAPHQL ARGS (REG-666) ===
+
+export interface GraphQLQueryArgs {
+  query: string;
+  variables?: Record<string, unknown>;
+  operationName?: string;
+}

package/src/utils.ts

@@ -108,7 +108,7 @@ export function findSimilarTypes(
 
   for (const type of availableTypes) {
     const dist = levenshtein(queriedLower, type.toLowerCase());
-    if (dist > 0 && dist <= maxDistance) {
+    if (dist <= maxDistance && (dist > 0 || queriedType !== type)) {
       similar.push(type);
     }
   }
@@ -116,6 +116,27 @@ export function findSimilarTypes(
   return similar;
 }
 
+export function extractQueriedTypes(query: string): { nodeTypes: string[]; edgeTypes: string[] } {
+  const nodeTypes: string[] = [];
+  const edgeTypes: string[] = [];
+
+  // Match node(VAR, "TYPE") and type(VAR, "TYPE") — both are valid node predicates.
+  // type() is an alias for node(), added in REG-518.
+  const nodeRegex = /\b(?:node|type)\([^,)]+,\s*"([^"]+)"\)/g;
+  let m: RegExpExecArray | null;
+  while ((m = nodeRegex.exec(query)) !== null) {
+    nodeTypes.push(m[1]);
+  }
+
+  // Match edge(SRC, DST, "TYPE") and incoming(DST, SRC, "TYPE")
+  const edgeRegex = /\b(?:edge|incoming)\([^,)]+,\s*[^,)]+,\s*"([^"]+)"\)/g;
+  while ((m = edgeRegex.exec(query)) !== null) {
+    edgeTypes.push(m[1]);
+  }
+
+  return { nodeTypes, edgeTypes };
+}
+
 // Levenshtein distance implementation
 export function levenshtein(a: string, b: string): number {
   const m = a.length;