@supermodeltools/mcp-server 0.9.1 → 0.9.3

package/dist/constants.js

@@ -4,7 +4,7 @@
  * Single source of truth for configuration values
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_SYMBOL_RELATED = exports.MAX_SYMBOL_CALLEES = exports.MAX_SYMBOL_CALLERS = exports.MAX_OVERVIEW_HUB_FUNCTIONS = exports.MAX_OVERVIEW_DOMAINS = 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;
+exports.MAX_SOURCE_LINES = exports.MAX_SYMBOL_RELATED = exports.MAX_SYMBOL_CALLEES = exports.MAX_SYMBOL_CALLERS = exports.MAX_OVERVIEW_HUB_FUNCTIONS = exports.MAX_OVERVIEW_DOMAINS = 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
@@ -22,3 +22,4 @@ exports.MAX_OVERVIEW_HUB_FUNCTIONS = 10; // Top N hub functions to show
 exports.MAX_SYMBOL_CALLERS = 10; // Top N callers to show
 exports.MAX_SYMBOL_CALLEES = 10; // Top N callees to show
 exports.MAX_SYMBOL_RELATED = 8; // Related symbols in same file
+exports.MAX_SOURCE_LINES = 50; // Max lines of source code to include inline

package/dist/index.js

@@ -214,6 +214,13 @@ async function handlePrecache(args) {
     console.error('');
     console.error('Done! To use this cache, set SUPERMODEL_CACHE_DIR=' + outputDir);
 }
+// Graceful shutdown on signals (e.g., container stop, SSH drop)
+for (const signal of ['SIGTERM', 'SIGINT']) {
+    process.on(signal, () => {
+        logger.debug(`Received ${signal}, shutting down`);
+        process.exit(0);
+    });
+}
 main().catch((error) => {
     logger.error('Fatal error:', error);
     process.exit(1);

package/dist/server.js

@@ -91,21 +91,21 @@ class Server {
 
 Two tools for instant codebase understanding. Pre-computed graphs enable sub-second responses.
 
-## \`overview\` — Start here
-Get the architecture map: domains, key files, hub functions, file/class/function counts.
-Call this first on any new task to understand WHERE in the codebase to look.
+## Recommended workflow
+1. \`overview\` first to learn architecture and key symbols (1 call)
+2. \`symbol_context\` on 1-2 symbols from the issue to see source, callers, callees (1-2 calls)
+3. Stop calling MCP tools. Use the results to make your fix.
 
-## \`symbol_context\` — Deep dive on a symbol
-Given a function, class, or method name, get its definition location, callers, callees, domain membership, and related symbols in the same file.
-Use this when you know WHAT to investigate (e.g. from an issue description, stack trace, or grep result).
-Supports partial matching and "ClassName.method" syntax.
+## Anti-patterns
+- >3 MCP calls total = diminishing returns. Aim for 1 overview + 1-2 symbol lookups.
+- Chasing callers-of-callers burns iterations without helping.
 
-## Recommended workflow
-1. Call \`overview\` to understand the codebase architecture
-2. Read the issue/bug description and identify relevant domains and symbols
-3. Call \`symbol_context\` on key symbols to understand their structural context
-4. Use Read/Grep to examine the actual source code at the identified locations
-5. Make your fix and verify with tests`,
+## After fixing
+Run the project's existing test suite (e.g. pytest). Do NOT write standalone test scripts.
+
+## Tool reference
+- \`overview\`: Architecture map, domains, hub functions, file counts. Zero-arg, sub-second.
+- \`symbol_context\`: Source, callers, callees, domain for any function/class/method. Supports "Class.method" and partial matching.`,
         });
         const config = new sdk_1.Configuration({
             basePath: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com',
@@ -167,26 +167,27 @@ Supports partial matching and "ClassName.method" syntax.
                 logger.warn('Failed to load cache directory:', err.message || err);
             }
         }
+        // Connect transport FIRST so the MCP handshake completes immediately.
+        // This prevents Claude Code from timing out the server (MCP_TIMEOUT=60s)
+        // when precaching requires a slow API call.
+        const transport = new stdio_js_1.StdioServerTransport();
+        await this.server.connect(transport);
+        logger.info('Supermodel MCP Server running on stdio');
         // Precache the workdir's repo if --precache flag is set.
-        // Runs BEFORE noApiFallback is set so the API is available.
-        // On first run for a repo this calls the Supermodel API (5-15 min).
-        // The API has server-side idempotency caching, so repeated calls
-        // with the same repo+commit return instantly. Results are saved to
-        // cacheDir for cross-container persistence.
+        // Runs AFTER connect but BEFORE noApiFallback so the API is available.
+        // This is fire-and-forget from the MCP client's perspective — tools
+        // that arrive before precaching finishes will use on-demand API calls.
         if (this.options?.precache && this.defaultWorkdir) {
             try {
                 await (0, graph_cache_1.precacheForDirectory)(this.client, this.defaultWorkdir, cacheDir);
             }
             catch (err) {
-                // Non-fatal: if precaching fails, tools fall back to no-cache error
+                // Non-fatal: if precaching fails, tools fall back to on-demand API
                 logger.warn('Startup precache failed:', err.message || err);
             }
         }
         // NOW enable no-api-fallback (after precaching had its chance)
         (0, graph_cache_1.setNoApiFallback)(!!this.options?.noApiFallback);
-        const transport = new stdio_js_1.StdioServerTransport();
-        await this.server.connect(transport);
-        logger.info('Supermodel MCP Server running on stdio');
     }
 }
 exports.Server = Server;

package/dist/tools/overview.js

@@ -17,7 +17,7 @@ const api_helpers_1 = require("../utils/api-helpers");
 const constants_1 = require("../constants");
 exports.tool = {
     name: 'overview',
-    description: `CALL THIS FIRST before grep or find. Returns a pre-computed architectural map of the entire codebase in sub-second time at zero cost. Gives you what grep/find cannot: which domains own which files, the most-called hub functions (call graph centrality), and how the codebase is structured across domains. Output is a concise summary with top architectural domains and their key files, highest-traffic functions, and file/function/class counts. Use this to know exactly where to look instead of guessing with grep.`,
+    description: `Returns a pre-computed architectural map of the entire codebase: which domains own which files, the most-called hub functions (call graph centrality), file/function/class counts. Sub-second, zero cost. Useful when you need to understand the overall structure before diving in. Skip this if you already know what file or symbol to investigate — use symbol_context or file reading instead.`,
     inputSchema: {
         type: 'object',
         properties: {
@@ -30,7 +30,8 @@ exports.tool = {
     },
 };
 const handler = async (client, args, defaultWorkdir) => {
-    const directory = args?.directory ?? defaultWorkdir;
+    const rawDir = args?.directory;
+    const directory = (rawDir && rawDir.trim()) || defaultWorkdir || process.cwd();
     if (!directory || typeof directory !== 'string') {
         return (0, types_1.asErrorResult)({
             type: 'validation_error',

package/dist/tools/symbol-context.js

@@ -2,8 +2,9 @@
 /**
  * `symbol_context` tool -- deep dive on a specific symbol.
  *
- * Given a function, class, or method name, returns (<5KB markdown):
+ * Given a function, class, or method name, returns (<10KB markdown):
  *  - Definition location (file, line)
+ *  - Source code (up to MAX_SOURCE_LINES)
  *  - Callers (who calls this)
  *  - Callees (what this calls)
  *  - Domain membership
@@ -11,15 +12,53 @@
  *
  * Backed by pre-computed graphs (sub-second) with on-demand API fallback.
  */
+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 });
 exports.handler = exports.tool = void 0;
+exports.findSymbol = findSymbol;
+exports.renderSymbolContext = renderSymbolContext;
+exports.languageFromExtension = languageFromExtension;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
 const types_1 = require("../types");
 const graph_cache_1 = require("../cache/graph-cache");
 const api_helpers_1 = require("../utils/api-helpers");
 const constants_1 = require("../constants");
 exports.tool = {
     name: 'symbol_context',
-    description: `Strictly better than grep for understanding a function, class, or method. Given a symbol name, instantly returns its definition location, all callers, all callees, architectural domain, and related symbols in the same file -- structural context that grep cannot reconstruct. Sub-second, zero cost. Supports partial matching ("filter" finds "QuerySet.filter", "filter_queryset", etc.) and "ClassName.method" syntax. Use this whenever you have a symbol name from a stack trace, issue, or search result and need to understand how it connects to the rest of the codebase.`,
+    description: `Strictly better than grep for understanding a function, class, or method. Given a symbol name, instantly returns its source code, definition location, all callers, all callees, architectural domain, and related symbols in the same file -- structural context that grep cannot reconstruct. Sub-second, zero cost. Supports partial matching ("filter" finds "QuerySet.filter", "filter_queryset", etc.) and "ClassName.method" syntax. Use this whenever you have a symbol name from a stack trace, issue, or search result and need to understand how it connects to the rest of the codebase.`,
     inputSchema: {
         type: 'object',
         properties: {
@@ -37,7 +76,8 @@ exports.tool = {
 };
 const handler = async (client, args, defaultWorkdir) => {
     const symbol = typeof args?.symbol === 'string' ? args.symbol.trim() : '';
-    const directory = args?.directory ?? defaultWorkdir;
+    const rawDir = args?.directory;
+    const directory = (rawDir && rawDir.trim()) || defaultWorkdir || process.cwd();
     if (!symbol) {
         return (0, types_1.asErrorResult)({
             type: 'validation_error',
@@ -73,10 +113,8 @@ const handler = async (client, args, defaultWorkdir) => {
             `- Use the \`overview\` tool to see available domains and key functions`);
     }
     // Render results for top matches (usually 1, sometimes a few)
-    const rendered = matches
-        .slice(0, 3)
-        .map(node => renderSymbolContext(graph, node))
-        .join('\n---\n\n');
+    const renderedParts = await Promise.all(matches.slice(0, 3).map(node => renderSymbolContext(graph, node, directory)));
+    const rendered = renderedParts.join('\n---\n\n');
     if (matches.length > 3) {
         return (0, types_1.asTextContentResult)(rendered + `\n\n*... and ${matches.length - 3} more matches. Use a more specific name to narrow results.*`);
     }
@@ -100,7 +138,12 @@ function findSymbol(graph, query) {
         return exactIds
             .map(id => graph.nodeById.get(id))
             .filter(n => n && isCodeSymbol(n))
-            .sort((a, b) => symbolPriority(a) - symbolPriority(b));
+            .sort((a, b) => {
+            const pDiff = symbolPriority(a) - symbolPriority(b);
+            if (pDiff !== 0)
+                return pDiff;
+            return callerCount(graph, b) - callerCount(graph, a);
+        });
     }
     // Strategy 2: ClassName.method match
     if (className && methodName) {
@@ -116,13 +159,21 @@ function findSymbol(graph, query) {
             return fp && classFilePaths.has(fp);
         });
         if (matched.length > 0) {
-            return matched.sort((a, b) => symbolPriority(a) - symbolPriority(b));
+            return matched.sort((a, b) => {
+                const pDiff = symbolPriority(a) - symbolPriority(b);
+                if (pDiff !== 0)
+                    return pDiff;
+                return callerCount(graph, b) - callerCount(graph, a);
+            });
         }
     }
     // Strategy 3: Substring match (for partial names)
+    if (lowerQuery.length < 2) {
+        return [];
+    }
     const substringMatches = [];
     for (const [name, ids] of graph.nameIndex) {
-        if (name.includes(lowerQuery) || lowerQuery.includes(name)) {
+        if (name.includes(lowerQuery)) {
             for (const id of ids) {
                 const node = graph.nodeById.get(id);
                 if (node && isCodeSymbol(node)) {
@@ -131,7 +182,7 @@ function findSymbol(graph, query) {
             }
         }
     }
-    // Sort by relevance: exact prefix > contains > contained-in
+    // Sort by relevance: exact prefix > contains, then symbol priority, then caller count
     substringMatches.sort((a, b) => {
         const aName = (a.properties?.name || '').toLowerCase();
         const bName = (b.properties?.name || '').toLowerCase();
@@ -139,7 +190,10 @@ function findSymbol(graph, query) {
         const bPrefix = bName.startsWith(lowerQuery) ? 0 : 1;
         if (aPrefix !== bPrefix)
             return aPrefix - bPrefix;
-        return symbolPriority(a) - symbolPriority(b);
+        const pDiff = symbolPriority(a) - symbolPriority(b);
+        if (pDiff !== 0)
+            return pDiff;
+        return callerCount(graph, b) - callerCount(graph, a);
     });
     return substringMatches.slice(0, 10);
 }
@@ -157,8 +211,11 @@ function symbolPriority(node) {
         return 2;
     return 3;
 }
+function callerCount(graph, node) {
+    return graph.callAdj.get(node.id)?.in.length || 0;
+}
 // ── Rendering ──
-function renderSymbolContext(graph, node) {
+async function renderSymbolContext(graph, node, directory) {
     const name = node.properties?.name || '(unknown)';
     const rawFilePath = node.properties?.filePath || '';
     const filePath = (0, graph_cache_1.normalizePath)(rawFilePath);
@@ -178,6 +235,31 @@ function renderSymbolContext(graph, node) {
         lines.push(`**Domain:** ${domain}`);
     }
     lines.push('');
+    // Source code
+    if (filePath && startLine > 0) {
+        try {
+            const absPath = path.resolve(directory, filePath);
+            const content = await fs_1.promises.readFile(absPath, 'utf-8');
+            const fileLines = content.split('\n');
+            const end = endLine > 0 ? Math.min(endLine, startLine + constants_1.MAX_SOURCE_LINES - 1) : startLine + constants_1.MAX_SOURCE_LINES - 1;
+            const sourceSlice = fileLines.slice(startLine - 1, end);
+            if (sourceSlice.length > 0) {
+                const lang = languageFromExtension(filePath);
+                lines.push(`### Source`);
+                lines.push('');
+                lines.push(`\`\`\`${lang}`);
+                lines.push(sourceSlice.join('\n'));
+                lines.push('```');
+                if (endLine > 0 && endLine > startLine + constants_1.MAX_SOURCE_LINES - 1) {
+                    lines.push(`*... truncated (showing ${constants_1.MAX_SOURCE_LINES} of ${endLine - startLine + 1} lines)*`);
+                }
+                lines.push('');
+            }
+        }
+        catch {
+            // File unreadable — skip source section silently
+        }
+    }
     // Callers
     const adj = graph.callAdj.get(node.id);
     if (adj && adj.in.length > 0) {
@@ -274,6 +356,48 @@ function renderSymbolContext(graph, node) {
     }
     return lines.join('\n');
 }
+function languageFromExtension(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const map = {
+        '.ts': 'typescript',
+        '.tsx': 'typescript',
+        '.js': 'javascript',
+        '.jsx': 'javascript',
+        '.py': 'python',
+        '.rb': 'ruby',
+        '.go': 'go',
+        '.rs': 'rust',
+        '.java': 'java',
+        '.kt': 'kotlin',
+        '.cs': 'csharp',
+        '.cpp': 'cpp',
+        '.c': 'c',
+        '.h': 'c',
+        '.hpp': 'cpp',
+        '.swift': 'swift',
+        '.php': 'php',
+        '.scala': 'scala',
+        '.sh': 'bash',
+        '.bash': 'bash',
+        '.yaml': 'yaml',
+        '.yml': 'yaml',
+        '.json': 'json',
+        '.xml': 'xml',
+        '.html': 'html',
+        '.css': 'css',
+        '.sql': 'sql',
+        '.r': 'r',
+        '.lua': 'lua',
+        '.dart': 'dart',
+        '.ex': 'elixir',
+        '.exs': 'elixir',
+        '.erl': 'erlang',
+        '.hs': 'haskell',
+        '.ml': 'ocaml',
+        '.clj': 'clojure',
+    };
+    return map[ext] || '';
+}
 function findDomain(graph, nodeId) {
     for (const [domainName, data] of graph.domainIndex) {
         if (data.memberIds.includes(nodeId)) {

package/dist/utils/api-helpers.js

@@ -66,6 +66,16 @@ function classifyApiError(error) {
             details: { errorType: typeof error },
         };
     }
+    // Fast-fail: no pre-computed cache and API fallback disabled
+    if (error.code === 'NO_CACHE') {
+        return {
+            type: 'cache_error',
+            message: error.message || 'No pre-computed graph available for this repository.',
+            code: 'NO_CACHE',
+            recoverable: false,
+            suggestion: 'Use grep, find, and file reading to explore the codebase instead. Or run the precache command and set SUPERMODEL_CACHE_DIR.',
+        };
+    }
     if (error.response) {
         const status = error.response.status;
         switch (status) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supermodeltools/mcp-server",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "MCP server for Supermodel API - code graph generation for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -38,7 +38,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.1",
-    "@supermodeltools/sdk": "0.9.1",
+    "@supermodeltools/sdk": "0.9.3",
     "archiver": "^7.0.1",
     "ignore": "^7.0.5",
     "jq-web": "^0.6.2",