@supermodeltools/mcp-server 0.4.5 → 0.4.8

package/README.md

@@ -150,23 +150,11 @@ Analyzes code structure, dependencies, and relationships across a repository. Us
 |----------|------|----------|-------------|
 | `directory` | string | Yes* | Path to repository directory (automatic zipping) |
 | `file` | string | Yes* | Path to pre-zipped archive (deprecated) |
-| `Idempotency-Key` | string | Yes | Cache key in format `{repo}:{type}:{hash}` |
 | `query` | string | No | Query type (summary, search, list_nodes, etc.) |
 | `jq_filter` | string | No | jq filter for custom data extraction |
 
 \* Either `directory` (recommended) or `file` must be provided
 
-**Quick start:**
-
-```bash
-# 1. Get commit hash for cache key
-git rev-parse --short HEAD
-# Output: abc123
-
-# 2. Ask Claude to analyze (no manual zipping needed!)
-# "Analyze the codebase at /path/to/repo using key myproject:supermodel:abc123"
-```
-
 **Example prompts:**
 - "Analyze the codebase at . to understand its architecture"
 - "Before I refactor the authentication module, analyze this repo to show me what depends on it"

package/dist/cache/graph-cache.js

@@ -8,6 +8,7 @@ exports.graphCache = exports.GraphCache = void 0;
 exports.buildIndexes = buildIndexes;
 exports.normalizePath = normalizePath;
 exports.toNodeDescriptor = toNodeDescriptor;
+const constants_1 = require("../constants");
 /**
  * Build indexes from raw SupermodelIR response
  */
@@ -200,10 +201,12 @@ class GraphCache {
     cache = new Map();
     maxGraphs;
     maxNodes;
+    maxAgeMs;
     currentNodes = 0;
     constructor(options) {
-        this.maxGraphs = options?.maxGraphs || 20;
-        this.maxNodes = options?.maxNodes || 1000000;
+        this.maxGraphs = options?.maxGraphs || constants_1.DEFAULT_MAX_GRAPHS;
+        this.maxNodes = options?.maxNodes || constants_1.DEFAULT_MAX_NODES;
+        this.maxAgeMs = options?.maxAgeMs || constants_1.DEFAULT_CACHE_TTL_MS;
     }
     get(cacheKey) {
         const entry = this.cache.get(cacheKey);
@@ -216,16 +219,20 @@ class GraphCache {
     }
     set(cacheKey, graph) {
         const nodeCount = graph.summary.nodeCount;
+        // Evict stale entries first
+        this.evictStale();
         // Evict if needed
         while ((this.cache.size >= this.maxGraphs || this.currentNodes + nodeCount > this.maxNodes) &&
             this.cache.size > 0) {
             this.evictOldest();
         }
         // Store
+        const now = Date.now();
         this.cache.set(cacheKey, {
             graph,
             nodeCount,
-            lastAccessed: Date.now(),
+            lastAccessed: now,
+            createdAt: now,
         });
         this.currentNodes += nodeCount;
     }
@@ -247,6 +254,28 @@ class GraphCache {
             this.cache.delete(oldestKey);
         }
     }
+    /**
+     * Evict all cache entries that have exceeded their TTL (maxAgeMs)
+     * This method can be called manually or is automatically invoked before adding new entries
+     * @returns Number of entries evicted
+     */
+    evictStale() {
+        const now = Date.now();
+        const keysToEvict = [];
+        // Find all stale entries
+        for (const [key, entry] of this.cache) {
+            if (now - entry.createdAt > this.maxAgeMs) {
+                keysToEvict.push(key);
+            }
+        }
+        // Evict them
+        for (const key of keysToEvict) {
+            const entry = this.cache.get(key);
+            this.currentNodes -= entry.nodeCount;
+            this.cache.delete(key);
+        }
+        return keysToEvict.length;
+    }
     status() {
         return {
             graphs: this.cache.size,

package/dist/constants.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Application-wide constants
+ * Single source of truth for configuration values
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_NEIGHBORHOOD_DEPTH = exports.DEFAULT_QUERY_LIMIT = exports.DEFAULT_CACHE_TTL_MS = exports.DEFAULT_MAX_NODES = exports.DEFAULT_MAX_GRAPHS = exports.MAX_ZIP_SIZE_BYTES = exports.ZIP_CLEANUP_AGE_MS = exports.CONNECTION_TIMEOUT_MS = exports.DEFAULT_API_TIMEOUT_MS = void 0;
+// HTTP timeout configuration
+exports.DEFAULT_API_TIMEOUT_MS = 900_000; // 15 minutes (complex repos can take 10+ min)
+exports.CONNECTION_TIMEOUT_MS = 30_000; // 30 seconds to establish connection
+// ZIP configuration
+exports.ZIP_CLEANUP_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+exports.MAX_ZIP_SIZE_BYTES = 500 * 1024 * 1024; // 500MB default
+// Cache configuration
+exports.DEFAULT_MAX_GRAPHS = 20; // Maximum number of graphs to cache
+exports.DEFAULT_MAX_NODES = 1_000_000; // Maximum total nodes across all cached graphs
+exports.DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour - time-to-live for cached graphs
+// Query defaults
+exports.DEFAULT_QUERY_LIMIT = 200; // Default result limit for queries
+exports.MAX_NEIGHBORHOOD_DEPTH = 3; // Maximum traversal depth for neighborhood queries

package/dist/index.js

@@ -1,12 +1,46 @@
 #!/usr/bin/env node
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const server_1 = require("./server");
+const logger = __importStar(require("./utils/logger"));
 async function main() {
     const server = new server_1.Server();
     await server.start();
 }
 main().catch((error) => {
-    console.error('Fatal error:', error);
+    logger.error('Fatal error:', error);
     process.exit(1);
 });

package/dist/queries/discovery.js

@@ -8,17 +8,22 @@ exports.search = search;
 exports.listNodes = listNodes;
 const graph_cache_1 = require("../cache/graph-cache");
 const types_1 = require("./types");
-const DEFAULT_LIMIT = 200;
+const constants_1 = require("../constants");
+const DEFAULT_LIMIT = constants_1.DEFAULT_QUERY_LIMIT;
 /**
  * get_node - Return full details for a specific node ID
  */
 function getNode(params, graph, source) {
     if (!params.targetId) {
-        return (0, types_1.createError)('INVALID_PARAMS', 'targetId is required for get_node query');
+        console.error('[ERROR] get_node called without targetId');
+        return (0, types_1.createError)('INVALID_PARAMS', 'Missing required parameter: targetId', {
+            detail: 'Use search or list_nodes to find valid node IDs, then call get_node with the targetId',
+        });
     }
     const node = graph.nodeById.get(params.targetId);
     if (!node) {
-        return (0, types_1.createError)('NOT_FOUND', `Node with id '${params.targetId}' not found`, {
+        console.error('[ERROR] Node not found:', params.targetId);
+        return (0, types_1.createError)('NOT_FOUND', `Node not found: ${params.targetId}`, {
             detail: 'Use search or list_nodes to discover valid node IDs',
         });
     }
@@ -36,7 +41,10 @@ function getNode(params, graph, source) {
  */
 function search(params, graph, source) {
     if (!params.searchText) {
-        return (0, types_1.createError)('INVALID_PARAMS', 'searchText is required for search query');
+        console.error('[ERROR] search called without searchText');
+        return (0, types_1.createError)('INVALID_PARAMS', 'Missing required parameter: searchText', {
+            detail: 'Provide a search term to find nodes by name substring',
+        });
     }
     const searchLower = params.searchText.toLowerCase();
     const limit = params.limit || DEFAULT_LIMIT;
@@ -94,7 +102,14 @@ function listNodes(params, graph, source) {
             regex = new RegExp(namePattern, 'i');
         }
         catch (e) {
-            return (0, types_1.createError)('INVALID_PARAMS', `Invalid namePattern regex: ${namePattern}`);
+            // Log detailed error for debugging
+            const errorMsg = e instanceof Error ? e.message : String(e);
+            console.error('[ERROR] Invalid regex pattern');
+            console.error('[ERROR] Pattern:', namePattern);
+            console.error('[ERROR] Error:', errorMsg);
+            return (0, types_1.createError)('INVALID_PARAMS', `Invalid regex pattern: ${errorMsg}`, {
+                detail: `Pattern: ${namePattern}`,
+            });
         }
     }
     const results = [];

package/dist/queries/index.js

@@ -54,9 +54,10 @@ async function executeQuery(params, apiResponse) {
     }
     // All other queries require a graph
     if (!graph) {
-        return (0, types_1.createError)('CACHE_MISS', `Graph not found in cache for key '${cacheKey}'`, {
+        console.error('[ERROR] Cache miss for key:', cacheKey);
+        return (0, types_1.createError)('CACHE_MISS', `Graph not cached. The query engine will fetch it from the API.`, {
             retryable: true,
-            detail: 'Re-call with the same file and idempotencyKey to fetch from API',
+            detail: 'This is a normal first-time operation. The graph will be cached for subsequent queries.',
         });
     }
     // Dispatch to appropriate handler
@@ -99,9 +100,15 @@ function dispatchQuery(params, graph, source) {
         // Not implemented yet
         case 'uses_in_file':
         case 'list_files_in_dir':
-            return (0, types_1.createError)('INVALID_QUERY', `Query type '${params.query}' is not yet implemented`);
+            console.error('[ERROR] Unimplemented query type requested:', params.query);
+            return (0, types_1.createError)('INVALID_QUERY', `Query type '${params.query}' is not yet implemented`, {
+                detail: 'This query is planned for a future release',
+            });
         default:
-            return (0, types_1.createError)('INVALID_QUERY', `Unknown query type: ${params.query}`);
+            console.error('[ERROR] Unknown query type:', params.query);
+            return (0, types_1.createError)('INVALID_QUERY', `Unknown query type: ${params.query}`, {
+                detail: 'Use graph_status to see available query types',
+            });
     }
 }
 /**
@@ -129,8 +136,12 @@ async function executeJqQuery(params, graph, source) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return (0, types_1.createError)('BAD_JQ', `jq filter error: ${message}`, {
-            detail: params.jq_filter,
+        // Log detailed error for debugging
+        console.error('[ERROR] jq filter execution failed');
+        console.error('[ERROR] Filter:', params.jq_filter);
+        console.error('[ERROR] Error:', message);
+        return (0, types_1.createError)('BAD_JQ', `Invalid jq filter syntax. ${message}`, {
+            detail: `Filter: ${params.jq_filter}`,
         });
     }
 }
@@ -144,63 +155,63 @@ function getAvailableQueries() {
         {
             query: 'graph_status',
             description: 'Check if graph is cached and get summary stats',
-            requiredParams: ['file', 'idempotencyKey'],
+            requiredParams: ['idempotencyKey'],
             optionalParams: [],
             phase: 'v1',
         },
         {
             query: 'summary',
             description: 'Get high-level stats about the codebase',
-            requiredParams: ['file', 'idempotencyKey'],
+            requiredParams: ['idempotencyKey'],
             optionalParams: [],
             phase: 'v1',
         },
         {
             query: 'get_node',
             description: 'Get full details for a specific node by ID',
-            requiredParams: ['file', 'idempotencyKey', 'targetId'],
+            requiredParams: ['idempotencyKey', 'targetId'],
             optionalParams: [],
             phase: 'v1',
         },
         {
             query: 'search',
             description: 'Search nodes by name substring',
-            requiredParams: ['file', 'idempotencyKey', 'searchText'],
+            requiredParams: ['idempotencyKey', 'searchText'],
             optionalParams: ['labels', 'filePathPrefix', 'limit'],
             phase: 'v1',
         },
         {
             query: 'list_nodes',
             description: 'List nodes with filters (labels, namePattern, filePathPrefix)',
-            requiredParams: ['file', 'idempotencyKey'],
+            requiredParams: ['idempotencyKey'],
             optionalParams: ['labels', 'namePattern', 'filePathPrefix', 'searchText', 'limit'],
             phase: 'v1',
         },
         {
             query: 'function_calls_in',
             description: 'Find all callers of a function',
-            requiredParams: ['file', 'idempotencyKey', 'targetId'],
+            requiredParams: ['idempotencyKey', 'targetId'],
             optionalParams: ['limit'],
             phase: 'v1',
         },
         {
             query: 'function_calls_out',
             description: 'Find all functions called by a function',
-            requiredParams: ['file', 'idempotencyKey', 'targetId'],
+            requiredParams: ['idempotencyKey', 'targetId'],
             optionalParams: ['limit'],
             phase: 'v1',
         },
         {
             query: 'definitions_in_file',
             description: 'Get all classes, functions, types defined in a file',
-            requiredParams: ['file', 'idempotencyKey'],
+            requiredParams: ['idempotencyKey'],
             optionalParams: ['targetId', 'filePathPrefix', 'limit'],
             phase: 'v1',
         },
         {
             query: 'jq',
             description: 'Execute raw jq filter (escape hatch)',
-            requiredParams: ['file', 'idempotencyKey', 'jq_filter'],
+            requiredParams: ['idempotencyKey', 'jq_filter'],
             optionalParams: [],
             phase: 'v1',
         },
@@ -208,28 +219,28 @@ function getAvailableQueries() {
         {
             query: 'file_imports',
             description: 'Get imports for a file (outgoing and incoming)',
-            requiredParams: ['file', 'idempotencyKey', 'targetId'],
+            requiredParams: ['idempotencyKey', 'targetId'],
             optionalParams: ['limit'],
             phase: 'v1.1',
         },
         {
             query: 'domain_map',
             description: 'List all domains with relationships',
-            requiredParams: ['file', 'idempotencyKey'],
+            requiredParams: ['idempotencyKey'],
             optionalParams: [],
             phase: 'v1.1',
         },
         {
             query: 'domain_membership',
             description: 'Get members of a domain',
-            requiredParams: ['file', 'idempotencyKey'],
+            requiredParams: ['idempotencyKey'],
             optionalParams: ['targetId', 'searchText', 'limit'],
             phase: 'v1.1',
         },
         {
             query: 'neighborhood',
             description: 'Get ego graph around a node',
-            requiredParams: ['file', 'idempotencyKey', 'targetId'],
+            requiredParams: ['idempotencyKey', 'targetId'],
             optionalParams: ['depth', 'relationshipTypes', 'limit'],
             phase: 'v1.1',
         },

package/dist/queries/traversal.js

@@ -12,23 +12,32 @@ exports.domainMembership = domainMembership;
 exports.neighborhood = neighborhood;
 const graph_cache_1 = require("../cache/graph-cache");
 const types_1 = require("./types");
-const DEFAULT_LIMIT = 200;
+const constants_1 = require("../constants");
+const DEFAULT_LIMIT = constants_1.DEFAULT_QUERY_LIMIT;
 /**
  * function_calls_in - Find all callers of a function
  */
 function functionCallsIn(params, graph, source) {
     if (!params.targetId) {
-        return (0, types_1.createError)('INVALID_PARAMS', 'targetId is required for function_calls_in query');
+        console.error('[ERROR] function_calls_in called without targetId');
+        return (0, types_1.createError)('INVALID_PARAMS', 'Missing required parameter: targetId', {
+            detail: 'Use search or list_nodes with labels=["Function"] to find function IDs',
+        });
     }
     // Verify target exists and is a function
     const targetNode = graph.nodeById.get(params.targetId);
     if (!targetNode) {
-        return (0, types_1.createError)('NOT_FOUND', `Node with id '${params.targetId}' not found`, {
+        console.error('[ERROR] Node not found:', params.targetId);
+        return (0, types_1.createError)('NOT_FOUND', `Node not found: ${params.targetId}`, {
             detail: 'Use search or list_nodes with labels=["Function"] to discover function IDs',
         });
     }
     if (targetNode.labels?.[0] !== 'Function') {
-        return (0, types_1.createError)('INVALID_PARAMS', `Node '${params.targetId}' is not a Function (got ${targetNode.labels?.[0]})`);
+        const actualLabel = targetNode.labels?.[0] || 'unknown';
+        console.error('[ERROR] Node is not a Function:', params.targetId, 'is', actualLabel);
+        return (0, types_1.createError)('INVALID_PARAMS', `Node is not a Function (found ${actualLabel})`, {
+            detail: 'This query only works on Function nodes. Use search with labels=["Function"] to find functions',
+        });
     }
     const adj = graph.callAdj.get(params.targetId);
     if (!adj) {
@@ -60,17 +69,25 @@ function functionCallsIn(params, graph, source) {
  */
 function functionCallsOut(params, graph, source) {
     if (!params.targetId) {
-        return (0, types_1.createError)('INVALID_PARAMS', 'targetId is required for function_calls_out query');
+        console.error('[ERROR] function_calls_out called without targetId');
+        return (0, types_1.createError)('INVALID_PARAMS', 'Missing required parameter: targetId', {
+            detail: 'Use search or list_nodes with labels=["Function"] to find function IDs',
+        });
     }
     // Verify target exists and is a function
     const targetNode = graph.nodeById.get(params.targetId);
     if (!targetNode) {
-        return (0, types_1.createError)('NOT_FOUND', `Node with id '${params.targetId}' not found`, {
+        console.error('[ERROR] Node not found:', params.targetId);
+        return (0, types_1.createError)('NOT_FOUND', `Node not found: ${params.targetId}`, {
             detail: 'Use search or list_nodes with labels=["Function"] to discover function IDs',
         });
     }
     if (targetNode.labels?.[0] !== 'Function') {
-        return (0, types_1.createError)('INVALID_PARAMS', `Node '${params.targetId}' is not a Function (got ${targetNode.labels?.[0]})`);
+        const actualLabel = targetNode.labels?.[0] || 'unknown';
+        console.error('[ERROR] Node is not a Function:', params.targetId, 'is', actualLabel);
+        return (0, types_1.createError)('INVALID_PARAMS', `Node is not a Function (found ${actualLabel})`, {
+            detail: 'This query only works on Function nodes. Use search with labels=["Function"] to find functions',
+        });
     }
     const adj = graph.callAdj.get(params.targetId);
     if (!adj) {
@@ -106,10 +123,17 @@ function definitionsInFile(params, graph, source) {
     if (params.targetId) {
         const targetNode = graph.nodeById.get(params.targetId);
         if (!targetNode) {
-            return (0, types_1.createError)('NOT_FOUND', `Node with id '${params.targetId}' not found`);
+            console.error('[ERROR] Node not found:', params.targetId);
+            return (0, types_1.createError)('NOT_FOUND', `Node not found: ${params.targetId}`, {
+                detail: 'Use search or list_nodes with labels=["File"] to find file nodes',
+            });
         }
         if (targetNode.labels?.[0] !== 'File') {
-            return (0, types_1.createError)('INVALID_PARAMS', `Node '${params.targetId}' is not a File (got ${targetNode.labels?.[0]})`);
+            const actualLabel = targetNode.labels?.[0] || 'unknown';
+            console.error('[ERROR] Node is not a File:', params.targetId, 'is', actualLabel);
+            return (0, types_1.createError)('INVALID_PARAMS', `Node is not a File (found ${actualLabel})`, {
+                detail: 'This query requires a File node. Use search with labels=["File"] to find files',
+            });
         }
         filePath = targetNode.properties?.filePath || targetNode.properties?.path;
     }
@@ -117,10 +141,16 @@ function definitionsInFile(params, graph, source) {
         filePath = params.filePathPrefix;
     }
     else {
-        return (0, types_1.createError)('INVALID_PARAMS', 'Either targetId (file node ID) or filePathPrefix is required');
+        console.error('[ERROR] definitions_in_file called without targetId or filePathPrefix');
+        return (0, types_1.createError)('INVALID_PARAMS', 'Missing required parameter: targetId or filePathPrefix', {
+            detail: 'Provide either a file node ID (targetId) or a file path (filePathPrefix)',
+        });
     }
     if (!filePath) {
-        return (0, types_1.createError)('INVALID_PARAMS', 'Could not determine file path');
+        console.error('[ERROR] Could not determine file path from node');
+        return (0, types_1.createError)('INVALID_PARAMS', 'Could not determine file path from the provided node', {
+            detail: 'The node is missing filePath or path properties',
+        });
     }
     const normalizedPath = (0, graph_cache_1.normalizePath)(filePath);
     const pathEntry = graph.pathIndex.get(normalizedPath);
@@ -134,8 +164,9 @@ function definitionsInFile(params, graph, source) {
             }
         }
         if (resolvedPath === normalizedPath) {
-            return (0, types_1.createError)('NOT_FOUND', `No definitions found for file '${filePath}'`, {
-                detail: 'File may not exist in the analyzed codebase or has no class/function/type definitions',
+            console.error('[ERROR] File not found in codebase:', filePath);
+            return (0, types_1.createError)('NOT_FOUND', `File not found in analyzed codebase: ${filePath}`, {
+                detail: 'The file may not exist, may be excluded by .gitignore, or has no definitions',
             });
         }
     }
@@ -173,15 +204,24 @@ function definitionsInFile(params, graph, source) {
  */
 function fileImports(params, graph, source) {
     if (!params.targetId) {
-        return (0, types_1.createError)('INVALID_PARAMS', 'targetId is required for file_imports query');
+        console.error('[ERROR] file_imports called without targetId');
+        return (0, types_1.createError)('INVALID_PARAMS', 'Missing required parameter: targetId', {
+            detail: 'Use search or list_nodes with labels=["File"] to find file nodes',
+        });
     }
     const targetNode = graph.nodeById.get(params.targetId);
     if (!targetNode) {
-        return (0, types_1.createError)('NOT_FOUND', `Node with id '${params.targetId}' not found`);
+        console.error('[ERROR] Node not found:', params.targetId);
+        return (0, types_1.createError)('NOT_FOUND', `Node not found: ${params.targetId}`, {
+            detail: 'Use search or list_nodes to discover valid node IDs',
+        });
     }
     const label = targetNode.labels?.[0];
     if (label !== 'File' && label !== 'LocalModule' && label !== 'ExternalModule') {
-        return (0, types_1.createError)('INVALID_PARAMS', `Node '${params.targetId}' is not a File/Module (got ${label})`);
+        console.error('[ERROR] Node is not a File/Module:', params.targetId, 'is', label);
+        return (0, types_1.createError)('INVALID_PARAMS', `Node is not a File/Module (found ${label})`, {
+            detail: 'This query requires a File, LocalModule, or ExternalModule node',
+        });
     }
     const limit = params.limit || DEFAULT_LIMIT;
     const outIds = new Set();
@@ -275,13 +315,19 @@ function domainMap(params, graph, source) {
  */
 function domainMembership(params, graph, source) {
     if (!params.searchText && !params.targetId) {
-        return (0, types_1.createError)('INVALID_PARAMS', 'searchText (domain name) or targetId (domain node ID) is required');
+        console.error('[ERROR] domain_membership called without searchText or targetId');
+        return (0, types_1.createError)('INVALID_PARAMS', 'Missing required parameter: searchText or targetId', {
+            detail: 'Provide either a domain name (searchText) or domain node ID (targetId)',
+        });
     }
     let domainName;
     if (params.targetId) {
         const node = graph.nodeById.get(params.targetId);
         if (!node) {
-            return (0, types_1.createError)('NOT_FOUND', `Node with id '${params.targetId}' not found`);
+            console.error('[ERROR] Node not found:', params.targetId);
+            return (0, types_1.createError)('NOT_FOUND', `Node not found: ${params.targetId}`, {
+                detail: 'Use domain_map to discover domain nodes',
+            });
         }
         domainName = node.properties?.name;
     }
@@ -290,7 +336,8 @@ function domainMembership(params, graph, source) {
     }
     const domainEntry = graph.domainIndex.get(domainName);
     if (!domainEntry) {
-        return (0, types_1.createError)('NOT_FOUND', `Domain '${domainName}' not found`, {
+        console.error('[ERROR] Domain not found:', domainName);
+        return (0, types_1.createError)('NOT_FOUND', `Domain not found: ${domainName}`, {
             detail: 'Use domain_map to list available domains',
         });
     }
@@ -312,13 +359,19 @@ function domainMembership(params, graph, source) {
  */
 function neighborhood(params, graph, source) {
     if (!params.targetId) {
-        return (0, types_1.createError)('INVALID_PARAMS', 'targetId is required for neighborhood query');
+        console.error('[ERROR] neighborhood called without targetId');
+        return (0, types_1.createError)('INVALID_PARAMS', 'Missing required parameter: targetId', {
+            detail: 'Use search or list_nodes to find a node, then explore its neighborhood',
+        });
     }
     const targetNode = graph.nodeById.get(params.targetId);
     if (!targetNode) {
-        return (0, types_1.createError)('NOT_FOUND', `Node with id '${params.targetId}' not found`);
+        console.error('[ERROR] Node not found:', params.targetId);
+        return (0, types_1.createError)('NOT_FOUND', `Node not found: ${params.targetId}`, {
+            detail: 'Use search or list_nodes to discover valid node IDs',
+        });
     }
-    const depth = Math.min(params.depth || 1, 3); // Cap at 3 to prevent explosion
+    const depth = Math.min(params.depth || 1, constants_1.MAX_NEIGHBORHOOD_DEPTH);
     const limit = params.limit || 100;
     // Only include relationship types we actually implement
     const relationshipTypes = params.relationshipTypes || ['calls', 'IMPORTS'];