@supermodeltools/mcp-server 0.4.3 → 0.4.5

package/README.md

@@ -126,7 +126,7 @@ claude mcp list
 
 ## Tools
 
-### `analyze_codebase`
+### `explore_codebase`
 
 Analyzes code structure, dependencies, and relationships across a repository. Use this to understand unfamiliar codebases, plan refactorings, assess change impact, or map system architecture.
 
@@ -148,40 +148,54 @@ Analyzes code structure, dependencies, and relationships across a repository. Us
 
 | Argument | Type | Required | Description |
 |----------|------|----------|-------------|
-| `file` | string | Yes | Path to repository ZIP file |
+| `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}` |
-| `jq_filter` | string | No | jq filter to extract specific data (strongly recommended) |
+| `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. Create ZIP from your git repo
-git archive -o /tmp/repo.zip HEAD
-
-# 2. Get commit hash for cache key
+# 1. Get commit hash for cache key
 git rev-parse --short HEAD
 # Output: abc123
 
-# 3. Ask Claude to analyze
-# "Analyze the codebase at /tmp/repo.zip using key myproject:supermodel: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 /tmp/repo.zip to understand its architecture"
-- "Before I refactor the authentication module, analyze /tmp/repo.zip to show me what depends on it"
-- "What's the structure of the codebase in /tmp/repo.zip?"
+- "Analyze the codebase at . to understand its architecture"
+- "Before I refactor the authentication module, analyze this repo to show me what depends on it"
+- "What's the structure of the codebase in /Users/me/project?"
+
+**Automatic features:**
+- Respects `.gitignore` patterns automatically
+- Excludes sensitive files (`.env`, `*.pem`, credentials, etc.)
+- Skips dependencies (`node_modules`, `venv`, `vendor`)
+- Removes build outputs (`dist`, `build`, `out`)
+- Cleans up temporary files automatically
+- Cross-platform compatible
 
 ## Troubleshooting
 
 Debug logs go to stderr:
 
 - `[DEBUG] Server configuration:` - Startup config
+- `[DEBUG] Auto-zipping directory:` - Starting zip creation
+- `[DEBUG] Auto-zip complete:` - Zip stats (file count, size)
 - `[DEBUG] Making API request` - Request details
 - `[ERROR] API call failed:` - Error details with HTTP status
 
 **Common issues:**
 - 401: Check `SUPERMODEL_API_KEY` is set
-- ZIP too large: Exclude node_modules/dist (use `git archive`)
+- ZIP too large: Directory contains too many files/dependencies. Ensure `.gitignore` is configured properly
+- Permission denied: Check read permissions on the directory
+- Insufficient disk space: Free up space in your system's temp directory
+- Directory does not exist: Verify the path is correct and absolute
 
 ## Links
 

package/dist/cache/graph-cache.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * LRU Cache for indexed graphs
+ * Stores raw API responses + derived indexes for fast query execution
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.graphCache = exports.GraphCache = void 0;
+exports.buildIndexes = buildIndexes;
+exports.normalizePath = normalizePath;
+exports.toNodeDescriptor = toNodeDescriptor;
+/**
+ * Build indexes from raw SupermodelIR response
+ */
+function buildIndexes(raw, cacheKey) {
+    const nodes = raw.graph?.nodes || [];
+    const relationships = raw.graph?.relationships || [];
+    // Initialize indexes
+    const nodeById = new Map();
+    const labelIndex = new Map();
+    const pathIndex = new Map();
+    const dirIndex = new Map();
+    const nameIndex = new Map();
+    const callAdj = new Map();
+    const importAdj = new Map();
+    const domainIndex = new Map();
+    // Build node indexes
+    for (const node of nodes) {
+        const id = node.id;
+        const props = node.properties || {};
+        const labels = node.labels || [];
+        // nodeById
+        nodeById.set(id, node);
+        // labelIndex
+        for (const label of labels) {
+            if (!labelIndex.has(label)) {
+                labelIndex.set(label, []);
+            }
+            labelIndex.get(label).push(id);
+        }
+        // nameIndex (lowercase for case-insensitive search)
+        const name = props.name;
+        if (name) {
+            const lowerName = name.toLowerCase();
+            if (!nameIndex.has(lowerName)) {
+                nameIndex.set(lowerName, []);
+            }
+            nameIndex.get(lowerName).push(id);
+        }
+        // pathIndex - track what's defined in each file
+        const filePath = props.filePath;
+        if (filePath) {
+            const normalized = normalizePath(filePath);
+            if (!pathIndex.has(normalized)) {
+                pathIndex.set(normalized, { fileId: '', classIds: [], functionIds: [], typeIds: [] });
+            }
+            const entry = pathIndex.get(normalized);
+            const primaryLabel = labels[0];
+            if (primaryLabel === 'File') {
+                entry.fileId = id;
+            }
+            else if (primaryLabel === 'Class') {
+                entry.classIds.push(id);
+            }
+            else if (primaryLabel === 'Function') {
+                entry.functionIds.push(id);
+            }
+            else if (primaryLabel === 'Type') {
+                entry.typeIds.push(id);
+            }
+        }
+        // dirIndex - build directory tree
+        if (labels[0] === 'Directory') {
+            const dirPath = normalizePath(props.path || props.name || '');
+            if (!dirIndex.has(dirPath)) {
+                dirIndex.set(dirPath, []);
+            }
+        }
+        // Initialize adjacency lists for functions and files
+        if (labels[0] === 'Function') {
+            callAdj.set(id, { out: [], in: [] });
+        }
+        if (labels[0] === 'File' || labels[0] === 'LocalModule' || labels[0] === 'ExternalModule') {
+            importAdj.set(id, { out: [], in: [] });
+        }
+        // domainIndex
+        if (labels[0] === 'Domain' || labels[0] === 'Subdomain') {
+            domainIndex.set(name || id, { memberIds: [], relationships: [] });
+        }
+    }
+    // Build relationship indexes
+    for (const rel of relationships) {
+        const { type, startNode, endNode } = rel;
+        // Call adjacency
+        if (type === 'calls') {
+            if (callAdj.has(startNode)) {
+                callAdj.get(startNode).out.push(endNode);
+            }
+            if (callAdj.has(endNode)) {
+                callAdj.get(endNode).in.push(startNode);
+            }
+        }
+        // Import adjacency
+        if (type === 'IMPORTS') {
+            // Some graphs emit IMPORTS edges from non-File nodes (e.g. Function -> Module).
+            // Create adjacency lazily for any node that participates.
+            let startAdj = importAdj.get(startNode);
+            if (!startAdj) {
+                startAdj = { out: [], in: [] };
+                importAdj.set(startNode, startAdj);
+            }
+            startAdj.out.push(endNode);
+            let endAdj = importAdj.get(endNode);
+            if (!endAdj) {
+                endAdj = { out: [], in: [] };
+                importAdj.set(endNode, endAdj);
+            }
+            endAdj.in.push(startNode);
+        }
+        // Directory contains
+        if (type === 'CONTAINS_FILE' || type === 'CHILD_DIRECTORY') {
+            const startNode_ = nodeById.get(startNode);
+            if (startNode_ && startNode_.labels?.[0] === 'Directory') {
+                const dirPath = normalizePath(startNode_.properties?.path || startNode_.properties?.name || '');
+                if (dirIndex.has(dirPath)) {
+                    dirIndex.get(dirPath).push(endNode);
+                }
+            }
+        }
+        // Domain membership
+        if (type === 'belongsTo') {
+            const targetNode = nodeById.get(endNode);
+            if (targetNode) {
+                const domainName = targetNode.properties?.name;
+                if (domainIndex.has(domainName)) {
+                    domainIndex.get(domainName).memberIds.push(startNode);
+                }
+            }
+        }
+        // Domain relationships
+        const startNodeData = nodeById.get(startNode);
+        const endNodeData = nodeById.get(endNode);
+        if (startNodeData?.labels?.[0] === 'Domain' && endNodeData?.labels?.[0] === 'Domain') {
+            const domainName = startNodeData.properties?.name;
+            if (domainIndex.has(domainName)) {
+                domainIndex.get(domainName).relationships.push(rel);
+            }
+        }
+    }
+    // Compute summary
+    const summary = {
+        filesProcessed: raw.summary?.filesProcessed || labelIndex.get('File')?.length || 0,
+        classes: raw.summary?.classes || labelIndex.get('Class')?.length || 0,
+        functions: raw.summary?.functions || labelIndex.get('Function')?.length || 0,
+        types: raw.summary?.types || labelIndex.get('Type')?.length || 0,
+        domains: raw.summary?.domains || labelIndex.get('Domain')?.length || 0,
+        primaryLanguage: raw.summary?.primaryLanguage || 'unknown',
+        nodeCount: nodes.length,
+        relationshipCount: relationships.length,
+    };
+    return {
+        raw,
+        nodeById,
+        labelIndex,
+        pathIndex,
+        dirIndex,
+        nameIndex,
+        callAdj,
+        importAdj,
+        domainIndex,
+        summary,
+        cachedAt: new Date().toISOString(),
+        cacheKey,
+    };
+}
+/**
+ * Normalize file paths for consistent matching
+ */
+function normalizePath(path) {
+    return path.replace(/\\/g, '/');
+}
+/**
+ * Convert full node to lightweight descriptor
+ */
+function toNodeDescriptor(node) {
+    const props = node.properties || {};
+    return {
+        id: node.id,
+        labels: node.labels || [],
+        name: props.name,
+        filePath: props.filePath,
+        startLine: props.startLine,
+        endLine: props.endLine,
+        kind: props.kind,
+    };
+}
+/**
+ * LRU Cache for indexed graphs
+ */
+class GraphCache {
+    cache = new Map();
+    maxGraphs;
+    maxNodes;
+    currentNodes = 0;
+    constructor(options) {
+        this.maxGraphs = options?.maxGraphs || 20;
+        this.maxNodes = options?.maxNodes || 1000000;
+    }
+    get(cacheKey) {
+        const entry = this.cache.get(cacheKey);
+        if (entry) {
+            // Update access time (LRU)
+            entry.lastAccessed = Date.now();
+            return entry.graph;
+        }
+        return null;
+    }
+    set(cacheKey, graph) {
+        const nodeCount = graph.summary.nodeCount;
+        // Evict if needed
+        while ((this.cache.size >= this.maxGraphs || this.currentNodes + nodeCount > this.maxNodes) &&
+            this.cache.size > 0) {
+            this.evictOldest();
+        }
+        // Store
+        this.cache.set(cacheKey, {
+            graph,
+            nodeCount,
+            lastAccessed: Date.now(),
+        });
+        this.currentNodes += nodeCount;
+    }
+    has(cacheKey) {
+        return this.cache.has(cacheKey);
+    }
+    evictOldest() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache) {
+            if (entry.lastAccessed < oldestTime) {
+                oldestTime = entry.lastAccessed;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            const entry = this.cache.get(oldestKey);
+            this.currentNodes -= entry.nodeCount;
+            this.cache.delete(oldestKey);
+        }
+    }
+    status() {
+        return {
+            graphs: this.cache.size,
+            nodes: this.currentNodes,
+            keys: Array.from(this.cache.keys()),
+        };
+    }
+}
+exports.GraphCache = GraphCache;
+// Global cache instance
+exports.graphCache = new GraphCache();

package/dist/cache/graph-types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Type definitions for Supermodel IR graph data
+ * Mirrors the API response schema
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cache/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Cache module exports
+ */
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./graph-types"), exports);
+__exportStar(require("./graph-cache"), exports);

package/dist/queries/discovery.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Discovery queries: get_node, search, list_nodes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNode = getNode;
+exports.search = search;
+exports.listNodes = listNodes;
+const graph_cache_1 = require("../cache/graph-cache");
+const types_1 = require("./types");
+const DEFAULT_LIMIT = 200;
+/**
+ * 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');
+    }
+    const node = graph.nodeById.get(params.targetId);
+    if (!node) {
+        return (0, types_1.createError)('NOT_FOUND', `Node with id '${params.targetId}' not found`, {
+            detail: 'Use search or list_nodes to discover valid node IDs',
+        });
+    }
+    const result = {
+        node: (0, graph_cache_1.toNodeDescriptor)(node),
+    };
+    // Only include raw if explicitly requested (reduces response size)
+    if (params.includeRaw) {
+        result.raw = node;
+    }
+    return (0, types_1.createResponse)('get_node', graph.cacheKey, source, graph.cachedAt, result);
+}
+/**
+ * search - Simple substring search across node names
+ */
+function search(params, graph, source) {
+    if (!params.searchText) {
+        return (0, types_1.createError)('INVALID_PARAMS', 'searchText is required for search query');
+    }
+    const searchLower = params.searchText.toLowerCase();
+    const limit = params.limit || DEFAULT_LIMIT;
+    const labels = params.labels;
+    const filePrefix = params.filePathPrefix ? (0, graph_cache_1.normalizePath)(params.filePathPrefix) : null;
+    const results = [];
+    let scanned = 0;
+    // Scan through nameIndex for matches
+    for (const [name, ids] of graph.nameIndex) {
+        if (!name.includes(searchLower))
+            continue;
+        for (const id of ids) {
+            if (results.length >= limit)
+                break;
+            const node = graph.nodeById.get(id);
+            if (!node)
+                continue;
+            // Filter by labels if specified
+            if (labels && labels.length > 0) {
+                const nodeLabel = node.labels?.[0];
+                if (!nodeLabel || !labels.includes(nodeLabel))
+                    continue;
+            }
+            // Filter by file path prefix if specified
+            if (filePrefix) {
+                const filePath = node.properties?.filePath;
+                if (!filePath || !(0, graph_cache_1.normalizePath)(filePath).startsWith(filePrefix))
+                    continue;
+            }
+            results.push((0, graph_cache_1.toNodeDescriptor)(node));
+            scanned++;
+        }
+        if (results.length >= limit)
+            break;
+    }
+    const hasMore = results.length >= limit;
+    return (0, types_1.createResponse)('search', graph.cacheKey, source, graph.cachedAt, { nodes: results }, {
+        page: { limit, hasMore },
+        warnings: hasMore ? [`Results limited to ${limit}. Use more specific searchText or add filters.`] : undefined,
+    });
+}
+/**
+ * list_nodes - Filtered list of nodes by labels, namePattern, filePathPrefix
+ */
+function listNodes(params, graph, source) {
+    const limit = params.limit || DEFAULT_LIMIT;
+    const labels = params.labels;
+    const filePrefix = params.filePathPrefix ? (0, graph_cache_1.normalizePath)(params.filePathPrefix) : null;
+    const searchText = params.searchText?.toLowerCase();
+    const namePattern = params.namePattern;
+    // Compile regex if namePattern provided
+    let regex = null;
+    if (namePattern) {
+        try {
+            regex = new RegExp(namePattern, 'i');
+        }
+        catch (e) {
+            return (0, types_1.createError)('INVALID_PARAMS', `Invalid namePattern regex: ${namePattern}`);
+        }
+    }
+    const results = [];
+    // Determine which nodes to scan
+    let candidateIds;
+    if (labels && labels.length > 0) {
+        // Start with nodes matching specified labels (use Set to dedupe)
+        candidateIds = new Set();
+        for (const label of labels) {
+            const ids = graph.labelIndex.get(label) || [];
+            for (const id of ids) {
+                candidateIds.add(id);
+            }
+        }
+    }
+    else {
+        // Scan all nodes
+        candidateIds = new Set(graph.nodeById.keys());
+    }
+    for (const id of candidateIds) {
+        if (results.length >= limit)
+            break;
+        const node = graph.nodeById.get(id);
+        if (!node)
+            continue;
+        const props = node.properties || {};
+        const name = props.name;
+        const filePath = props.filePath;
+        // Filter by file path prefix
+        if (filePrefix) {
+            if (!filePath || !(0, graph_cache_1.normalizePath)(filePath).startsWith(filePrefix))
+                continue;
+        }
+        // Filter by search text (simple substring)
+        if (searchText) {
+            if (!name || !name.toLowerCase().includes(searchText))
+                continue;
+        }
+        // Filter by name pattern (regex)
+        if (regex) {
+            if (!name || !regex.test(name))
+                continue;
+        }
+        results.push((0, graph_cache_1.toNodeDescriptor)(node));
+    }
+    const hasMore = results.length >= limit;
+    return (0, types_1.createResponse)('list_nodes', graph.cacheKey, source, graph.cachedAt, { nodes: results }, {
+        page: { limit, hasMore },
+        warnings: hasMore ? [`Results limited to ${limit}. Add filters to narrow results.`] : undefined,
+    });
+}