@grafema/mcp 0.3.29 → 0.3.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafema/mcp",
-  "version": "0.3.29",
+  "version": "0.3.31",
   "description": "MCP server for Grafema code analysis toolkit",
   "type": "module",
   "main": "./dist/server.js",
@@ -14,8 +14,8 @@
       "import": "./dist/server.js"
     },
     "./handlers": {
-      "types": "./dist/handlers.d.ts",
-      "import": "./dist/handlers.js"
+      "types": "./dist/handlers/index.d.ts",
+      "import": "./dist/handlers/index.js"
     }
   },
   "files": [
@@ -39,9 +39,9 @@
     "@modelcontextprotocol/sdk": "^1.25.1",
     "ajv": "^8.17.1",
     "yaml": "^2.8.2",
-    "@grafema/api": "0.3.29",
-    "@grafema/util": "0.3.29",
-    "@grafema/types": "0.3.29"
+    "@grafema/api": "0.3.31",
+    "@grafema/types": "0.3.31",
+    "@grafema/util": "0.3.31"
   },
   "optionalDependencies": {
     "@grafema/grafema-darwin-arm64": "0.3.29",
@@ -58,7 +58,7 @@
     "build": "tsc",
     "clean": "rm -rf dist",
     "start": "node dist/server.js",
-    "test": "node --import tsx --test test/*.test.ts",
-    "test:watch": "node --import tsx --test --watch test/*.test.ts"
+    "test": "node --import tsx --experimental-test-module-mocks --test --test-concurrency=1 test/*.test.ts",
+    "test:watch": "node --import tsx --experimental-test-module-mocks --test --test-concurrency=1 --watch test/*.test.ts"
   }
 }

package/src/definitions/enox-tools.ts

@@ -124,14 +124,13 @@ Example: recall(query="federation architecture", depth=2)`,
   },
   {
     name: 'semantic_search',
-    description: `Embedding-based similarity search across the knowledge graph.
+    description: `Substring search across knowledge-graph node names (case-insensitive).
 
-Use this for precise similarity matching — finds nodes whose content
-is semantically close to the query, even if exact keywords differ.
+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.
 
-More targeted than recall: returns ranked results without graph traversal.
-
-Example: semantic_search(query="Docker container auth token", top_k=5, domain="devops")`,
+Example: semantic_search(query="auth token", top_k=5, domain="devops")`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -147,10 +146,6 @@ Example: semantic_search(query="Docker container auth token", top_k=5, domain="d
           type: 'string',
           description: 'Filter results to a specific domain',
         },
-        include_edges: {
-          type: 'boolean',
-          description: 'Include edges connected to matched nodes (default: false)',
-        },
       },
       required: ['query'],
     },

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

package/src/handlers/enox-handlers.ts

@@ -348,14 +348,25 @@ export async function handleRecall(args: RecallArgs): Promise<ToolResult> {
 
 export interface SemanticSearchArgs {
   query: string;
-  limit?: number;
+  top_k?: number;
   domain?: string;
 }
 
-export async function handleSemanticSearch(args: SemanticSearchArgs): Promise<ToolResult> {
+/**
+ * Handle the `semantic_search` MCP tool.
+ *
+ * @param args - tool input. `top_k` (matching the published schema) caps the
+ *   number of results; defaults to 10 per the schema's documented default.
+ * @param clientOverride - optional RFDB client, injected by tests; production
+ *   callers omit it and the shared knowledge client is used.
+ */
+export async function handleSemanticSearch(
+  args: SemanticSearchArgs,
+  clientOverride?: RFDBClient,
+): Promise<ToolResult> {
   try {
-    const client = await getKnowledgeClient();
-    const limit = args.limit ?? 20;
+    const client = clientOverride ?? await getKnowledgeClient();
+    const limit = args.top_k ?? 10;
 
     // TODO: Wire to RFDB embedding engine when enabled.
     // For now, fall back to substring search via queryNodes.
@@ -378,9 +389,9 @@ export async function handleSemanticSearch(args: SemanticSearchArgs): Promise<To
     for (let i = 0; i < results.length; i++) {
       const node = results[i];
       const meta = parseMeta(node);
-      // Pseudo-similarity score based on match quality (placeholder until embeddings)
-      const similarity = (1.0 - (i * 0.05)).toFixed(2);
-      lines.push(`${i + 1}. [${similarity}] ${node.name} (${node.nodeType})`);
+      // NOTE: this is substring matching, not embeddings — do not fabricate a
+      // similarity score (it would read to an agent as a real metric). Just rank.
+      lines.push(`${i + 1}. ${node.name} (${node.nodeType})`);
       if (meta.domain) lines.push(`   Domain: ${meta.domain}`);
       if (meta.content) lines.push(`   ${String(meta.content).slice(0, 200)}`);
       lines.push('');

package/src/handlers/query-handlers.ts

@@ -524,22 +524,35 @@ async function enrichNodes(
 
 /** 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 {
+ * TYPE-%3Ename (URL-encoded, no file prefix), or raw node IDs.
+ *
+ * Exported for unit testing.
+ * @internal */
+export 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;
+
+  // Split file path from node descriptor on the FIRST literal '#' of the RAW
+  // (still percent-encoded) id, BEFORE decoding. The grafema:// URI form encodes
+  // the disambiguation counter ('#N', appended by computeSemanticIdV2 for hash
+  // collisions) as '%23N' inside the fragment. Decoding first and then splitting
+  // on the LAST '#' would mistake that counter for the path/fragment boundary and
+  // corrupt the label. A file path never contains a literal '#'. This mirrors the
+  // canonical parseSemanticIdV2 (packages/util/src/core/SemanticId.ts).
+  const hashIdx = semanticId.indexOf('#');
+  let rawFile = '';
+  let rawNode = semanticId;
   if (hashIdx !== -1) {
-    filePart = id.slice(0, hashIdx);
-    nodePart = id.slice(hashIdx + 1);
+    rawFile = semanticId.slice(0, hashIdx);
+    rawNode = semanticId.slice(hashIdx + 1);
   }
 
+  const decode = (s: string): string => {
+    try { return decodeURIComponent(s); } catch { return s; }
+  };
+  const filePart = decode(rawFile);
+  // Strip the trailing disambiguation counter ('#N') from the decoded descriptor.
+  const nodePart = decode(rawNode).replace(/#\d+$/, '');
+
   const fileName = filePart ? (filePart.split('/').pop() || '') : '';
 
   // Extract name from TYPE->name or TYPE->name[in:scope,h:hash]

package/dist/definitions.d.ts

@@ -1,23 +0,0 @@
-/**
- * MCP Tool Definitions
- */
-interface SchemaProperty {
-    type: string;
-    description?: string;
-    enum?: string[];
-    items?: SchemaProperty;
-    properties?: Record<string, SchemaProperty>;
-    required?: string[];
-}
-export interface ToolDefinition {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: 'object';
-        properties: Record<string, SchemaProperty>;
-        required?: string[];
-    };
-}
-export declare const TOOLS: ToolDefinition[];
-export {};
-//# sourceMappingURL=definitions.d.ts.map

package/dist/definitions.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../src/definitions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QAC3C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED,eAAO,MAAM,KAAK,EAAE,cAAc,EA+nBjC,CAAC"}