@grafema/mcp 0.3.28 → 0.3.31

package/src/definitions/enox-tools.ts

@@ -0,0 +1,454 @@
+/**
+ * Enox Tools — persistent knowledge graph (long-term memory)
+ *
+ * Enox is a federated knowledge graph shared across sessions and projects.
+ * These tools provide CRUD operations on nodes and edges, semantic search,
+ * graph traversal, and document storage.
+ */
+
+import type { ToolDefinition } from './types.js';
+
+const RELATION_TYPES = [
+  'depends_on',
+  'supersedes',
+  'implements',
+  'contradicts',
+  'part_of',
+  'extends',
+  'enables',
+  'isomorphic_to',
+  'decided_on',
+  'discussed_on',
+  'changed_on',
+  'created_on',
+  'preceded_by',
+  'triggered_by',
+  'prefers',
+  'distrusts',
+  'values',
+  'rejects',
+  'believes',
+  'about',
+  'references',
+  'blocks',
+  'decomposes_into',
+  'related_to',
+  'similar_to',
+  'requires',
+  'supports',
+  'outperforms',
+  'fails_on',
+  'introduces',
+  'uses',
+  'is_based_on',
+  'equivalent_to',
+  'foundational_for',
+  'builds_on',
+  'contributes_to',
+  'alternative_to',
+  'refutes',
+  'challenges',
+  'applies_to',
+  'exports',
+] as const;
+
+export const ENOX_TOOLS: ToolDefinition[] = [
+  {
+    name: 'remember',
+    description: `Quick knowledge write — store a fact about a subject.
+
+Use this when you:
+- Discover something worth remembering across sessions
+- Want to record an experiment result, decision, or observation
+- Need a quick "jot it down" without specifying exact graph structure
+
+The subject becomes a node (or reuses an existing one), and the fact is stored
+as an assertion from that node.
+
+Example: remember(subject="RFDB compaction", fact="flush_data_only was a no-op in V2 engine", domain="engineering")`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        subject: {
+          type: 'string',
+          description: 'The entity this fact is about (becomes a node)',
+        },
+        fact: {
+          type: 'string',
+          description: 'The fact or observation to record',
+        },
+        domain: {
+          type: 'string',
+          description: 'Knowledge domain (default: "memory")',
+        },
+        confidence: {
+          type: 'number',
+          description: 'Confidence level 0-1 (default: 0.9)',
+        },
+        relation: {
+          type: 'string',
+          description: 'Relation type for the assertion edge',
+          enum: [...RELATION_TYPES],
+        },
+      },
+      required: ['subject', 'fact'],
+    },
+  },
+  {
+    name: 'recall',
+    description: `Broad "what do we know about X" — combines embedding search with graph traversal.
+
+Use this at session start or before making decisions to check for prior art,
+known failures, and existing context.
+
+Depth controls how far to traverse from matched nodes:
+- 1: direct matches only (fast)
+- 2: matches + their neighbors (default, good balance)
+- 3: two hops out (broader context, slower)
+
+Example: recall(query="federation architecture", depth=2)`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'What to recall — natural language query',
+        },
+        depth: {
+          type: 'number',
+          description: 'Traversal depth from matched nodes: 1-3 (default: 1)',
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'semantic_search',
+    description: `Substring search across knowledge-graph node names (case-insensitive).
+
+NOTE: despite the name, embedding-based semantic ranking is not wired yet
+(RFD-63). This currently matches substrings of node names — results are
+plain matches, not similarity-ranked. Use recall for broader retrieval.
+
+Example: semantic_search(query="auth token", top_k=5, domain="devops")`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Natural language search query',
+        },
+        top_k: {
+          type: 'number',
+          description: 'Maximum number of results to return (default: 10)',
+        },
+        domain: {
+          type: 'string',
+          description: 'Filter results to a specific domain',
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'enox_explore',
+    description: `Get all edges around an entity in the knowledge graph — see everything connected to it.
+
+Use this to understand the full context of an entity: what it relates to,
+what depends on it, what contradicts it, etc.
+
+Returns all incoming and outgoing edges with connected node summaries.
+
+Example: explore(entity="RFDB V2 engine")`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        entity: {
+          type: 'string',
+          description: 'Name or ID of the entity to explore',
+        },
+      },
+      required: ['entity'],
+    },
+  },
+  {
+    name: 'add_assertion',
+    description: `Create a precise edge between two nodes in the knowledge graph.
+
+Use this when you need exact control over the graph structure:
+- Specific relation type between two entities
+- Confidence level on an assertion
+- Domain scoping
+
+Both "from" and "to" become nodes if they don't exist yet.
+
+Example: add_assertion(from="Grafema", relation="uses", to="RFDB", context="RFDB is the storage engine for code graphs", confidence=1.0)`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from: {
+          type: 'string',
+          description: 'Source entity name or ID',
+        },
+        relation: {
+          type: 'string',
+          description: 'Relation type for the edge',
+          enum: [...RELATION_TYPES],
+        },
+        to: {
+          type: 'string',
+          description: 'Target entity name or ID',
+        },
+        context: {
+          type: 'string',
+          description: 'Additional context or evidence for this assertion',
+        },
+        confidence: {
+          type: 'number',
+          description: 'Confidence level 0-1',
+        },
+        domain: {
+          type: 'string',
+          description: 'Knowledge domain this assertion belongs to',
+        },
+      },
+      required: ['from', 'relation', 'to'],
+    },
+  },
+  {
+    name: 'update_assertion',
+    description: `Update an existing edge in the knowledge graph.
+
+Use this to change the context or confidence of a previously recorded assertion
+without deleting and re-creating it.
+
+Example: update_assertion(fact_id="edge-abc123", confidence=0.5, context="Partially confirmed after testing")`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fact_id: {
+          type: 'string',
+          description: 'ID of the assertion/edge to update',
+        },
+        context: {
+          type: 'string',
+          description: 'Updated context or evidence',
+        },
+        confidence: {
+          type: 'number',
+          description: 'Updated confidence level 0-1',
+        },
+      },
+      required: ['fact_id'],
+    },
+  },
+  {
+    name: 'delete_assertion',
+    description: `Remove an edge from the knowledge graph.
+
+Use this when an assertion is wrong, outdated, or no longer relevant.
+Consider using update_assertion to lower confidence instead of deleting,
+or add_assertion with "supersedes" relation to record the replacement.
+
+Example: delete_assertion(fact_id="edge-abc123")`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fact_id: {
+          type: 'string',
+          description: 'ID of the assertion/edge to remove',
+        },
+      },
+      required: ['fact_id'],
+    },
+  },
+  {
+    name: 'enox_query',
+    description: `Filter nodes in the knowledge graph by type, domain, or name.
+
+Use this for exact filtering when you know what you're looking for.
+Unlike semantic_search, this does exact/substring matching on fields.
+
+Example: query_graph(type="decision", domain="engineering", limit=20)`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: {
+          type: 'string',
+          description: 'Filter by node type',
+        },
+        domain: {
+          type: 'string',
+          description: 'Filter by knowledge domain',
+        },
+        name: {
+          type: 'string',
+          description: 'Filter by node name (substring match)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results (default: 50)',
+        },
+      },
+    },
+  },
+  {
+    name: 'enox_traverse',
+    description: `Graph traversal from a knowledge entity following specific edge types and direction.
+
+Use this for structured exploration:
+- "What does X depend on?" → traverse(start="X", direction="outgoing", edge_types=["depends_on"])
+- "What supersedes X?" → traverse(start="X", direction="incoming", edge_types=["supersedes"])
+- Full neighborhood: traverse(start="X", direction="both", max_depth=2)
+
+Returns nodes with depth info (0 = start, 1 = direct, 2+ = transitive).
+
+Example: traverse(start="RFDB", direction="outgoing", edge_types=["depends_on", "uses"], max_depth=3)`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        start: {
+          type: 'string',
+          description: 'Starting entity name or ID',
+        },
+        direction: {
+          type: 'string',
+          description: 'Traversal direction (default: "both")',
+          enum: ['outgoing', 'incoming', 'both'],
+        },
+        edge_types: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Filter by edge/relation types. Omit for all.',
+        },
+        max_depth: {
+          type: 'number',
+          description: 'Maximum traversal depth (default: 2)',
+        },
+      },
+      required: ['start'],
+    },
+  },
+  {
+    name: 'enox_stats',
+    description: `Get statistics about the Enox knowledge graph.
+
+Use this to:
+- Check if the knowledge graph has content
+- See node and edge counts by type
+- Assess graph density and coverage
+
+Returns: total nodes, total edges, counts by type, domain distribution.`,
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'recent_activity',
+    description: `Get recently created or updated nodes and edges.
+
+Use this at session start to see what other sessions have recorded recently.
+Helps avoid duplicating work and provides continuity across sessions.
+
+Example: recent_activity(since="2026-05-20T00:00:00Z", limit=10)`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        since: {
+          type: 'string',
+          description: 'ISO 8601 date — only show activity after this time',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results (default: 20)',
+        },
+      },
+    },
+  },
+  {
+    name: 'update_node',
+    description: `Update metadata on an existing node in the knowledge graph.
+
+Use this to rename, re-domain, or add descriptions to existing nodes
+without affecting their edges.
+
+Example: update_node(node_id="node-abc123", description="V2 storage engine with segment-based persistence")`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        node_id: {
+          type: 'string',
+          description: 'ID of the node to update',
+        },
+        name: {
+          type: 'string',
+          description: 'Updated node name',
+        },
+        domain: {
+          type: 'string',
+          description: 'Updated knowledge domain',
+        },
+        description: {
+          type: 'string',
+          description: 'Updated node description',
+        },
+      },
+      required: ['node_id'],
+    },
+  },
+  {
+    name: 'crawl_entity',
+    description: `Run ontological crawl on a code entity — generate hypotheses and verify against code graph.
+Uses the Grafema code graph for verification. Records findings in knowledge database.
+Example: crawl_entity(entity="compactionEnricher", context="TypeScript enricher creating FEATURE nodes")`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        entity: { type: 'string', description: 'Entity name to crawl' },
+        context: { type: 'string', description: 'Brief description of what this entity is' },
+        depth: { type: 'number', description: 'How many perspectives to explore (default: 3)' },
+      },
+      required: ['entity'],
+    },
+  },
+  {
+    name: 'save_document',
+    description: `Store a document or artifact as a node in the knowledge graph.
+
+Use this for longer-form content that should be persisted:
+- ADRs (Architecture Decision Records)
+- Postmortems and incident reports
+- Specifications and design documents
+- Session notes and artifacts
+
+The document becomes a node with its content stored. Use relates_to to
+link it to relevant entities in the graph.
+
+Example: save_document(title="ADR: Federation via thick client", content="## Context\\n...", doc_type="adr", relates_to=["Grafema", "RFDB"])`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: {
+          type: 'string',
+          description: 'Document title (becomes the node name)',
+        },
+        content: {
+          type: 'string',
+          description: 'Full document content (markdown supported)',
+        },
+        doc_type: {
+          type: 'string',
+          description: 'Document type (default: "note")',
+          enum: ['adr', 'postmortem', 'spec', 'note', 'artifact'],
+        },
+        relates_to: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Node IDs or names of related entities to link to',
+        },
+      },
+      required: ['title', 'content'],
+    },
+  },
+];

package/src/definitions/index.ts

@@ -11,7 +11,7 @@ import { GUARANTEE_TOOLS } from './guarantee-tools.js';
 import { CONTEXT_TOOLS } from './context-tools.js';
 import { PROJECT_TOOLS } from './project-tools.js';
 import { GRAPH_TOOLS } from './graph-tools.js';
-import { KNOWLEDGE_TOOLS } from './knowledge-tools.js';
+import { ENOX_TOOLS } from './enox-tools.js';
 import { NOTATION_TOOLS } from './notation-tools.js';
 import { GRAPHQL_TOOLS } from './graphql-tools.js';
 import { REGISTRY_TOOLS } from './registry-tools.js';
@@ -23,7 +23,7 @@ export const TOOLS: ToolDefinition[] = [
   ...CONTEXT_TOOLS,
   ...PROJECT_TOOLS,
   ...GRAPH_TOOLS,
-  ...KNOWLEDGE_TOOLS,
+  ...ENOX_TOOLS,
   ...NOTATION_TOOLS,
   ...GRAPHQL_TOOLS,
   ...REGISTRY_TOOLS,

package/src/handlers/coverage-handlers.ts

@@ -31,9 +31,19 @@ export async function handleGetCoverage(args: GetCoverageArgs): Promise<ToolResu
     output += `File breakdown:\n`;
     output += `  Total files:     ${result.total}\n`;
     output += `  Analyzed:        ${result.analyzed.count} (${result.percentages.analyzed}%) - in graph\n`;
+    if (result.failed.count > 0) {
+      output += `  Failed:          ${result.failed.count} (${result.percentages.failed}%) - skipped/failed during analysis\n`;
+    }
     output += `  Unsupported:     ${result.unsupported.count} (${result.percentages.unsupported}%) - no indexer available\n`;
     output += `  Unreachable:     ${result.unreachable.count} (${result.percentages.unreachable}%) - not imported from entrypoints\n`;
 
+    if (result.failed.count > 0) {
+      output += `\nFailed files by reason:\n`;
+      for (const [category, files] of Object.entries(result.failed.byCategory)) {
+        output += `  ${category}: ${files.length} files\n`;
+      }
+    }
+
     if (result.unsupported.count > 0) {
       output += `\nUnsupported files by extension:\n`;
       for (const [ext, files] of Object.entries(result.unsupported.byExtension)) {

package/src/handlers/documentation-handlers.ts

@@ -40,11 +40,21 @@ Grafema is a static code analyzer that builds a graph of your codebase.
 ## Syntax
 violation(X) :- node(X, "TYPE"), attr(X, "name", "value").
 
-## Available Predicates
-- type(Id, Type) - match nodes (alias: node)
-- edge(Src, Dst, Type) - match edges
-- attr(Id, Name, Value) - match node attributes (name, file, line, etc.)
-- \\+ - negation (not)
+## Node / Edge / Attribute Predicates
+- node(Id, Type) - match nodes by type (alias: type(Id, Type))
+- edge(Src, Dst, Type) - match outgoing edges Src -> Dst of the given type
+- incoming(Dst, Src, Type) - match edges pointing TO Dst (reverse of edge)
+- path(Src, Dst) - transitive reachability Src -> Dst (BFS over edges)
+- attr(Id, Name, Value) - match node attributes (name, file, line, ...; nested paths like "a.b" supported)
+- attr_edge(Src, Dst, EdgeType, AttrName, Value) - match EDGE attributes; Src/Dst/EdgeType/AttrName must be bound, Value may be variable/constant/wildcard
+- parent_function(NodeId, FunctionId) - bind the enclosing FUNCTION of NodeId via CONTAINS; NodeId must be bound; empty at module level
+
+## Negation & String Predicates
+- \\+ - negation (not); also for negative joins on a dst-position variable, e.g. \\+ edge(X, _, "CALLS")
+- neq(X, Y) - inequality; BOTH arguments must be bound
+- starts_with(Value, Prefix) - string prefix match
+- not_starts_with(Value, Prefix) - negative string prefix match
+- string_contains(Value, Substring) - substring match
 
 ## Numeric Comparison Predicates
 - gt(Value, Threshold) - greater than
@@ -55,6 +65,11 @@ violation(X) :- node(X, "TYPE"), attr(X, "name", "value").
 Values are parsed as floating-point numbers. Non-numeric values produce no matches.
 Use with attr() to filter by metadata values (e.g., metrics, line numbers).
 
+## Limitations
+- No aggregations (count/sum/avg), no GROUP BY, no ORDER BY - aggregate/sort client-side.
+- Predicate ORDER matters: bind a variable (via node/edge/attr) before a comparison /
+  string / attr_edge predicate uses it, or the query fails to place ("circular dependency").
+
 ## Examples
 Find all functions:
   violation(X) :- node(X, "FUNCTION").
@@ -67,6 +82,12 @@ Find files where parsing took > 500ms:
 
 Find functions with more than 100 lines:
   violation(X, Lines) :- node(X, "FUNCTION"), attr(X, "line", Start), attr(X, "endLine", End), gt(End, Start).
+
+Find the enclosing function of every call:
+  violation(C, F) :- node(C, "CALL"), parent_function(C, F).
+
+Find nodes that have incoming CALLS edges (i.e. are called):
+  violation(D) :- incoming(D, _, "CALLS").
 `,
     types: `
 # Node & Edge Types