@supermodeltools/mcp-server 0.9.6 → 0.10.0

package/README.md

@@ -4,7 +4,7 @@
 [![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
 [![CI](https://github.com/supermodeltools/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/supermodeltools/mcp/actions/workflows/ci.yml)
 
-MCP server that gives AI agents instant codebase understanding via the [Supermodel API](https://docs.supermodeltools.com). Two tools — `overview` and `symbol_context` — backed by pre-computed code graphs for sub-second responses.
+MCP server that gives AI agents instant codebase understanding via the [Supermodel API](https://docs.supermodeltools.com). Pre-computed code graphs enable sub-second responses for symbol lookups, call-graph traversal, and cross-subsystem analysis.
 
 ## Install
 
@@ -59,6 +59,7 @@ Get your API key from the [Supermodel Dashboard](https://dashboard.supermodeltoo
 | `SUPERMODEL_CACHE_DIR` | Directory for pre-computed graph cache files (optional) |
 | `SUPERMODEL_TIMEOUT_MS` | API request timeout in ms (default: 900000 / 15 min) |
 | `SUPERMODEL_NO_API_FALLBACK` | Set to disable on-demand API calls; cache-only mode (optional) |
+| `SUPERMODEL_EXPERIMENT` | Experiment mode. Set to `graphrag` to enable GraphRAG tools (optional) |
 
 ### Global Setup (Recommended)
 
@@ -132,56 +133,62 @@ Tools will use this directory automatically if no explicit `directory` parameter
 
 ## Tools
 
-### `overview`
+### `symbol_context` (Default Mode)
 
-Returns a pre-computed architectural map of the codebase in sub-second time. Call this first on any new task.
+Deep dive on a specific function, class, or method. Given a symbol name, instantly returns its definition location, source code, all callers, all callees, domain membership, and related symbols in the same file.
 
 **Output includes:**
-- Top architectural domains and their key files
-- Most-called hub functions (call graph centrality)
-- File, function, and class counts
-- Primary language and graph statistics
+- Definition location (file, line range) and source code
+- Callers (who calls this symbol)
+- Callees (what this symbol calls)
+- Architectural domain membership
+- Related symbols in the same file
+- File import statistics
 
 **Parameters:**
 
 | Argument | Type | Required | Description |
 |----------|------|----------|-------------|
+| `symbol` | string | No* | Name of the function, class, or method. Supports `ClassName.method` syntax and partial matching. |
+| `symbols` | string[] | No* | Array of symbol names for batch lookup. More efficient than multiple calls. |
 | `directory` | string | No | Path to repository directory. Omit if server was started with a default workdir. |
+| `brief` | boolean | No | Return compact output (no source code). Recommended for 3+ symbols. |
+
+\* Either `symbol` or `symbols` must be provided.
 
 **Example prompts:**
-- "Give me an overview of this codebase"
-- "What's the architecture of this project?"
+- "Look up the symbol `filter_queryset` in this codebase"
+- "What calls `QuerySet.filter` and what does it call?"
 
-### `symbol_context`
+### GraphRAG Mode (Experimental)
 
-Deep dive on a specific function, class, or method. Given a symbol name, instantly returns its definition location, all callers, all callees, domain membership, and related symbols in the same file.
+Activate with `SUPERMODEL_EXPERIMENT=graphrag`. Replaces `symbol_context` with a graph-oriented tool for call-graph traversal and cross-subsystem analysis.
 
-**Output includes:**
-- Definition location (file, line range)
-- Callers (who calls this symbol)
-- Callees (what this symbol calls)
-- Architectural domain membership
-- Related symbols in the same file
-- File import statistics
+#### `explore_function`
+
+BFS traversal of a function, class, or method call graph. Shows source code, callers, callees, and cross-subsystem boundaries with `← DIFFERENT SUBSYSTEM` markers.
 
 **Parameters:**
 
 | Argument | Type | Required | Description |
 |----------|------|----------|-------------|
-| `symbol` | string | Yes | Name of the function, class, or method. Supports `ClassName.method` syntax and partial matching. |
-| `directory` | string | No | Path to repository directory. Omit if server was started with a default workdir. |
+| `symbol` | string | Yes | Function, class, or method name to explore. Supports partial matching and `ClassName.method` syntax. |
+| `direction` | string | No | `downstream` (callees), `upstream` (callers), or `both` (default). |
+| `depth` | number | No | Hops to follow: 1–3 (default: 2). |
+| `directory` | string | No | Repository path. |
 
-**Example prompts:**
-- "Look up the symbol `filter_queryset` in this codebase"
-- "What calls `QuerySet.filter` and what does it call?"
+**Output:** Readable narrative showing upstream/downstream neighbors with domain context at each hop.
 
 ### 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
+**Default mode:**
+1. Identify symbols from the issue and call `symbol_context` to explore them (batch via `symbols` array or parallel calls)
+2. Use Read/Grep to examine source code at identified locations
+3. Start editing by turn 3. Max 3 MCP calls total.
+
+**GraphRAG mode:**
+1. Identify key symbols from the issue, call `explore_function` to understand their call-graph context. Issue multiple calls in parallel (read-only, safe).
+2. Use the cross-subsystem markers and source code from the response to start editing. Max 2 MCP calls total.
 
 ## Pre-computed Graphs
 

package/dist/server.js

@@ -49,7 +49,9 @@ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const sdk_1 = require("@supermodeltools/sdk");
 const overview_1 = require("./tools/overview");
-const symbol_context_1 = __importDefault(require("./tools/symbol-context"));
+const symbol_context_1 = __importStar(require("./tools/symbol-context"));
+const tool_variants_1 = require("./tools/tool-variants");
+const explore_function_1 = __importDefault(require("./tools/explore-function"));
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const zip_repository_1 = require("./utils/zip-repository");
 const graph_cache_1 = require("./cache/graph-cache");
@@ -81,13 +83,32 @@ class Server {
     constructor(defaultWorkdir, options) {
         this.defaultWorkdir = defaultWorkdir;
         this.options = options;
+        const experiment = process.env.SUPERMODEL_EXPERIMENT;
         // Note: noApiFallback is deferred to start() so startup precaching can use the API
-        this.server = new mcp_js_1.McpServer({
-            name: 'supermodel_api',
-            version: '0.0.1',
-        }, {
-            capabilities: { tools: {}, logging: {} },
-            instructions: `# Supermodel: Codebase Intelligence
+        const experimentInstructions = {
+            'minimal-instructions': 'Codebase analysis tool. Call symbol_context to look up functions/classes.',
+            'search-symbol': 'Codebase search tool. Use `search_symbol` alongside Grep and Read for parallel exploration.',
+            'split-tools': 'Codebase tools: `find_definition` locates symbols, `trace_calls` shows caller/callee graphs. Call them alongside Read, Grep, and Glob.',
+            'annotate': 'Codebase annotation tool. Fire `annotate` alongside your Read and Grep calls to enrich results with structural metadata.',
+            'graphrag': `# Supermodel: Codebase Intelligence
+
+One read-only tool for instant call-graph exploration.
+
+## Tool
+- \`explore_function\`: BFS traversal of a function/class call graph. Returns source code, callers, callees, and cross-subsystem boundaries with ← DIFFERENT SUBSYSTEM markers. Supports partial matching and "ClassName.method" syntax.
+
+## Workflow
+1. Identify key symbols from the issue, call \`explore_function\` to understand their call-graph context. Issue multiple calls in parallel (read-only, safe).
+2. Use file paths and source code from the response to start editing. Max 2 MCP calls total.
+
+## Rules
+- Do NOT use TodoWrite. Act directly.
+- NEVER create standalone test scripts. Run the repo's existing test suite to verify.
+- >2 MCP turns = diminishing returns. Get everything you need in one turn.`,
+        };
+        const instructions = experiment && experimentInstructions[experiment]
+            ? experimentInstructions[experiment]
+            : `# Supermodel: Codebase Intelligence
 
 One read-only tool for instant codebase understanding. Pre-computed graphs enable sub-second responses.
 
@@ -110,7 +131,13 @@ Run the full related test suite to catch regressions. Do NOT write standalone te
 - \`symbol_context\`: Source, callers, callees, domain for any function/class/method.
   Supports "Class.method", partial matching, and batch lookups via \`symbols\` array.
   Use \`brief: true\` for compact output when looking up 3+ symbols.
-  Read-only — safe to call in parallel.`,
+  Read-only — safe to call in parallel.`;
+        this.server = new mcp_js_1.McpServer({
+            name: 'supermodel_api',
+            version: '0.0.1',
+        }, {
+            capabilities: { tools: {}, logging: {} },
+            instructions,
         });
         const config = new sdk_1.Configuration({
             basePath: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com',
@@ -130,9 +157,29 @@ Run the full related test suite to catch regressions. Do NOT write standalone te
         this.setupHandlers();
     }
     setupHandlers() {
-        const allTools = [
-            symbol_context_1.default,
-        ];
+        const experiment = process.env.SUPERMODEL_EXPERIMENT;
+        // Experiment variants: swap tool definitions to test parallel calling behavior
+        let allTools;
+        switch (experiment) {
+            case 'minimal-schema':
+                allTools = [{ tool: symbol_context_1.minimalTool, handler: symbol_context_1.default.handler }];
+                break;
+            case 'search-symbol':
+                allTools = [tool_variants_1.searchSymbolEndpoint];
+                break;
+            case 'split-tools':
+                allTools = [tool_variants_1.findDefinitionEndpoint, tool_variants_1.traceCallsEndpoint];
+                break;
+            case 'annotate':
+                allTools = [tool_variants_1.annotateEndpoint];
+                break;
+            case 'graphrag':
+                allTools = [explore_function_1.default];
+                break;
+            default:
+                allTools = [symbol_context_1.default];
+                break;
+        }
         // Create a map for quick handler lookup
         const toolMap = new Map();
         for (const t of allTools) {
@@ -170,6 +217,9 @@ Run the full related test suite to catch regressions. Do NOT write standalone te
     injectOverviewInstructions(repoMap) {
         if (repoMap.size === 0)
             return;
+        // Skip overview injection during experiments to isolate variables (except graphrag)
+        if (process.env.SUPERMODEL_EXPERIMENT && process.env.SUPERMODEL_EXPERIMENT !== 'graphrag')
+            return;
         // Only inject if there's exactly 1 unique graph (SWE-bench always has exactly 1 repo)
         const uniqueGraphs = new Set([...repoMap.values()]);
         if (uniqueGraphs.size !== 1)

package/dist/tools/explore-function.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * `explore_function` tool — BFS call-graph traversal with domain annotations.
+ *
+ * Ported from codegraph-graphrag prototype. Key differences from `symbol_context`:
+ *  - Up to 3-hop BFS (vs 1-hop flat list)
+ *  - Every neighbor shows subdomain + domain
+ *  - ← DIFFERENT SUBSYSTEM marker for cross-boundary calls
+ *  - Hierarchical output with "Via" sections for multi-hop paths
+ *  - Source code included for the root symbol (saves a Read round-trip)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handler = exports.tool = void 0;
+const types_1 = require("../types");
+const graph_cache_1 = require("../cache/graph-cache");
+const api_helpers_1 = require("../utils/api-helpers");
+const symbol_context_1 = require("./symbol-context");
+const constants_1 = require("../constants");
+exports.tool = {
+    name: 'explore_function',
+    description: "Explore a function or class call-graph neighborhood. Returns source code, callers (upstream), callees (downstream), with subsystem/domain annotations and ← DIFFERENT SUBSYSTEM markers for cross-boundary calls. Accepts partial matching and ClassName.method syntax.",
+    inputSchema: {
+        type: 'object',
+        properties: {
+            symbol: {
+                type: 'string',
+                description: 'Function name to explore. Supports partial matching and "ClassName.method" syntax.',
+            },
+            direction: {
+                type: 'string',
+                enum: ['downstream', 'upstream', 'both'],
+                description: 'Which direction to explore: downstream (callees), upstream (callers), or both. Default: both.',
+            },
+            depth: {
+                type: 'number',
+                minimum: 1,
+                maximum: 3,
+                description: 'How many hops to follow (1-3). Default: 2.',
+            },
+            directory: {
+                type: 'string',
+                description: 'Repository path (optional, uses default if omitted).',
+            },
+        },
+        required: ['symbol'],
+    },
+    annotations: {
+        readOnlyHint: true,
+    },
+};
+/**
+ * Build a map from Subdomain name → parent Domain name by scanning partOf relationships.
+ * Computed once per call (fast — only scans Domain/Subdomain nodes).
+ */
+function buildSubdomainToParentMap(graph) {
+    const map = new Map();
+    const relationships = graph.raw.graph?.relationships || [];
+    for (const rel of relationships) {
+        if (rel.type !== 'partOf')
+            continue;
+        const startNode = graph.nodeById.get(rel.startNode);
+        const endNode = graph.nodeById.get(rel.endNode);
+        if (startNode?.labels?.[0] === 'Subdomain' &&
+            endNode?.labels?.[0] === 'Domain') {
+            const subName = startNode.properties?.name;
+            const domName = endNode.properties?.name;
+            if (subName && domName) {
+                map.set(subName, domName);
+            }
+        }
+    }
+    return map;
+}
+/**
+ * Resolve subdomain + domain for a node using domainIndex and the partOf map.
+ */
+function resolveDomain(graph, nodeId, subdomainToParent) {
+    let subdomain = null;
+    let domain = null;
+    for (const [name, data] of graph.domainIndex) {
+        if (!data.memberIds.includes(nodeId))
+            continue;
+        const domainNode = graph.nodeById.get(
+        // Find the node for this domain entry to check its label
+        [...graph.nameIndex.get(name.toLowerCase()) || []].find(id => {
+            const n = graph.nodeById.get(id);
+            return n?.labels?.[0] === 'Subdomain' || n?.labels?.[0] === 'Domain';
+        }) || '');
+        if (domainNode?.labels?.[0] === 'Subdomain') {
+            subdomain = name;
+            // Look up parent domain via partOf map
+            const parent = subdomainToParent.get(name);
+            if (parent)
+                domain = parent;
+        }
+        else if (domainNode?.labels?.[0] === 'Domain') {
+            domain = name;
+        }
+        // If we found a subdomain, that's the most specific — prefer it
+        if (subdomain)
+            break;
+    }
+    // If we only found a domain directly (no subdomain), that's fine
+    return { subdomain, domain };
+}
+// ── Node description ──
+function describeNode(graph, nodeId, refSubdomain, subdomainToParent) {
+    const node = graph.nodeById.get(nodeId);
+    if (!node)
+        return '(unknown)';
+    const name = node.properties?.name || '(unknown)';
+    const filePath = (0, graph_cache_1.normalizePath)(node.properties?.filePath || '');
+    const { subdomain, domain } = resolveDomain(graph, nodeId, subdomainToParent);
+    let loc = '';
+    if (subdomain && domain)
+        loc = `${subdomain} subsystem, ${domain} domain`;
+    else if (subdomain)
+        loc = `${subdomain} subsystem`;
+    else if (domain)
+        loc = `${domain} domain`;
+    let line = `\`${name}\``;
+    if (filePath)
+        line += ` — ${filePath}`;
+    if (loc)
+        line += ` — ${loc}`;
+    // Flag cross-subsystem edges
+    if (refSubdomain && subdomain && subdomain !== refSubdomain) {
+        line += '  ← DIFFERENT SUBSYSTEM';
+    }
+    return line;
+}
+// ── Handler ──
+const handler = async (client, args, defaultWorkdir) => {
+    const symbolArg = typeof args?.symbol === 'string' ? args.symbol.trim() : '';
+    if (!symbolArg) {
+        return (0, types_1.asErrorResult)({
+            type: 'validation_error',
+            message: 'Missing required "symbol" parameter.',
+            code: 'MISSING_SYMBOL',
+            recoverable: false,
+            suggestion: 'Provide the name of a function to explore.',
+        });
+    }
+    const direction = args?.direction || 'both';
+    if (!['downstream', 'upstream', 'both'].includes(direction)) {
+        return (0, types_1.asErrorResult)({
+            type: 'validation_error',
+            message: `Invalid direction "${direction}". Must be "downstream", "upstream", or "both".`,
+            code: 'INVALID_DIRECTION',
+            recoverable: false,
+            suggestion: 'Use "downstream" (callees), "upstream" (callers), or "both".',
+        });
+    }
+    const depth = Math.min(3, Math.max(1, Number(args?.depth) || 2));
+    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',
+            message: 'No directory provided and no default workdir configured.',
+            code: 'MISSING_DIRECTORY',
+            recoverable: false,
+            suggestion: 'Provide a directory parameter or start the MCP server with a workdir argument.',
+        });
+    }
+    let graph;
+    try {
+        graph = await (0, graph_cache_1.resolveOrFetchGraph)(client, directory);
+    }
+    catch (error) {
+        return (0, types_1.asErrorResult)((0, api_helpers_1.classifyApiError)(error));
+    }
+    // Resolve symbol name to a Function or Class node
+    const matches = (0, symbol_context_1.findSymbol)(graph, symbolArg);
+    const funcMatch = matches.find(n => n.labels?.[0] === 'Function' || n.labels?.[0] === 'Class');
+    if (!funcMatch) {
+        return (0, types_1.asErrorResult)({
+            type: 'not_found_error',
+            message: `No function or class matching "${symbolArg}" found in the code graph.`,
+            code: 'SYMBOL_NOT_FOUND',
+            recoverable: false,
+            suggestion: 'Try a different function name or use partial matching.',
+        });
+    }
+    const rootId = funcMatch.id;
+    const subdomainToParent = buildSubdomainToParentMap(graph);
+    const rootDomain = resolveDomain(graph, rootId, subdomainToParent);
+    const rootSubName = rootDomain.subdomain;
+    const lines = [];
+    lines.push(`## ${describeNode(graph, rootId, null, subdomainToParent)}`);
+    lines.push('');
+    // Include source code for the root symbol (saves agent a Read round-trip)
+    const rootSource = funcMatch.properties?.sourceCode;
+    if (rootSource) {
+        const sourceLines = rootSource.split('\n');
+        const truncated = sourceLines.length > constants_1.MAX_SOURCE_LINES;
+        const displayLines = truncated ? sourceLines.slice(0, constants_1.MAX_SOURCE_LINES) : sourceLines;
+        const startLine = funcMatch.properties?.startLine;
+        const filePath = (0, graph_cache_1.normalizePath)(funcMatch.properties?.filePath || '');
+        const ext = filePath.split('.').pop() || '';
+        lines.push(`### Source`);
+        lines.push('```' + ext);
+        if (startLine) {
+            displayLines.forEach((l, i) => { lines.push(`${startLine + i}: ${l}`); });
+        }
+        else {
+            displayLines.forEach(l => { lines.push(l); });
+        }
+        if (truncated)
+            lines.push(`... (${sourceLines.length - constants_1.MAX_SOURCE_LINES} more lines)`);
+        lines.push('```');
+        lines.push('');
+    }
+    // Downstream BFS (callees)
+    if (direction === 'downstream' || direction === 'both') {
+        lines.push('### Functions it calls:');
+        let frontier = [rootId];
+        const visited = new Set([rootId]);
+        for (let d = 1; d <= depth; d++) {
+            const nextFrontier = [];
+            if (d === 1) {
+                const callees = (graph.callAdj.get(rootId)?.out || [])
+                    .filter(id => { const l = graph.nodeById.get(id)?.labels?.[0]; return l === 'Function' || l === 'Class'; });
+                if (callees.length === 0) {
+                    lines.push('  (none)');
+                }
+                for (const [i, cId] of callees.entries()) {
+                    visited.add(cId);
+                    nextFrontier.push(cId);
+                    lines.push(`  ${i + 1}. ${describeNode(graph, cId, rootSubName, subdomainToParent)}`);
+                }
+            }
+            else {
+                let anyFound = false;
+                for (const parentId of frontier) {
+                    const parentNode = graph.nodeById.get(parentId);
+                    const parentName = parentNode?.properties?.name || '(unknown)';
+                    const callees = (graph.callAdj.get(parentId)?.out || [])
+                        .filter(id => { const l = graph.nodeById.get(id)?.labels?.[0]; return l === 'Function' || l === 'Class'; })
+                        .filter(id => !visited.has(id));
+                    if (callees.length === 0)
+                        continue;
+                    anyFound = true;
+                    lines.push(`  Via \`${parentName}\`:`);
+                    for (const cId of callees) {
+                        visited.add(cId);
+                        nextFrontier.push(cId);
+                        lines.push(`    → ${describeNode(graph, cId, rootSubName, subdomainToParent)}`);
+                    }
+                }
+                if (!anyFound) {
+                    lines.push(`  (no further calls at depth ${d})`);
+                }
+            }
+            frontier = nextFrontier;
+        }
+        lines.push('');
+    }
+    // Upstream BFS (callers)
+    if (direction === 'upstream' || direction === 'both') {
+        lines.push('### Functions that call it:');
+        let frontier = [rootId];
+        const visited = new Set([rootId]);
+        for (let d = 1; d <= depth; d++) {
+            const nextFrontier = [];
+            if (d === 1) {
+                const callers = (graph.callAdj.get(rootId)?.in || [])
+                    .filter(id => { const l = graph.nodeById.get(id)?.labels?.[0]; return l === 'Function' || l === 'Class'; });
+                if (callers.length === 0) {
+                    lines.push('  (none)');
+                }
+                for (const [i, cId] of callers.entries()) {
+                    visited.add(cId);
+                    nextFrontier.push(cId);
+                    lines.push(`  ${i + 1}. ${describeNode(graph, cId, rootSubName, subdomainToParent)}`);
+                }
+            }
+            else {
+                let anyFound = false;
+                for (const parentId of frontier) {
+                    const parentNode = graph.nodeById.get(parentId);
+                    const parentName = parentNode?.properties?.name || '(unknown)';
+                    const callers = (graph.callAdj.get(parentId)?.in || [])
+                        .filter(id => { const l = graph.nodeById.get(id)?.labels?.[0]; return l === 'Function' || l === 'Class'; })
+                        .filter(id => !visited.has(id));
+                    if (callers.length === 0)
+                        continue;
+                    anyFound = true;
+                    lines.push(`  Via \`${parentName}\`:`);
+                    for (const cId of callers) {
+                        visited.add(cId);
+                        nextFrontier.push(cId);
+                        lines.push(`    → ${describeNode(graph, cId, rootSubName, subdomainToParent)}`);
+                    }
+                }
+                if (!anyFound) {
+                    lines.push(`  (no further callers at depth ${d})`);
+                }
+            }
+            frontier = nextFrontier;
+        }
+        lines.push('');
+    }
+    return (0, types_1.asTextContentResult)(lines.join('\n'));
+};
+exports.handler = handler;
+exports.default = { tool: exports.tool, handler: exports.handler };

package/dist/tools/find-connections.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * `find_connections` tool — find how two subsystems/domains connect via call relationships.
+ *
+ * Ported from codegraph-graphrag prototype. Iterates domainIndex to find members
+ * of each domain, then scans callAdj for cross-domain call edges.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handler = exports.tool = void 0;
+const types_1 = require("../types");
+const graph_cache_1 = require("../cache/graph-cache");
+const api_helpers_1 = require("../utils/api-helpers");
+exports.tool = {
+    name: 'find_connections',
+    description: 'Find how two subsystems/domains connect. Returns the functions that bridge them via call relationships.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            domain_a: {
+                type: 'string',
+                description: 'First domain or subdomain name.',
+            },
+            domain_b: {
+                type: 'string',
+                description: 'Second domain or subdomain name.',
+            },
+            directory: {
+                type: 'string',
+                description: 'Repository path (optional, uses default if omitted).',
+            },
+        },
+        required: ['domain_a', 'domain_b'],
+    },
+    annotations: {
+        readOnlyHint: true,
+    },
+};
+/**
+ * Collect all Function node IDs that belong to a domain/subdomain (fuzzy name match).
+ */
+function collectDomainMembers(graph, query) {
+    const lower = query.toLowerCase();
+    const members = new Set();
+    for (const [name, data] of graph.domainIndex) {
+        if (!name.toLowerCase().includes(lower))
+            continue;
+        for (const id of data.memberIds) {
+            const node = graph.nodeById.get(id);
+            if (node?.labels?.[0] === 'Function') {
+                members.add(id);
+            }
+        }
+    }
+    return members;
+}
+const handler = async (client, args, defaultWorkdir) => {
+    const domainA = typeof args?.domain_a === 'string' ? args.domain_a.trim() : '';
+    const domainB = typeof args?.domain_b === 'string' ? args.domain_b.trim() : '';
+    if (!domainA || !domainB) {
+        return (0, types_1.asErrorResult)({
+            type: 'validation_error',
+            message: 'Missing required "domain_a" and/or "domain_b" parameters.',
+            code: 'MISSING_DOMAIN',
+            recoverable: false,
+            suggestion: 'Provide two domain or subdomain names to find connections between.',
+        });
+    }
+    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',
+            message: 'No directory provided and no default workdir configured.',
+            code: 'MISSING_DIRECTORY',
+            recoverable: false,
+            suggestion: 'Provide a directory parameter or start the MCP server with a workdir argument.',
+        });
+    }
+    let graph;
+    try {
+        graph = await (0, graph_cache_1.resolveOrFetchGraph)(client, directory);
+    }
+    catch (error) {
+        return (0, types_1.asErrorResult)((0, api_helpers_1.classifyApiError)(error));
+    }
+    const aNodes = collectDomainMembers(graph, domainA);
+    const bNodes = collectDomainMembers(graph, domainB);
+    if (aNodes.size === 0) {
+        return (0, types_1.asTextContentResult)(`No functions found in domain/subdomain matching "${domainA}".`);
+    }
+    if (bNodes.size === 0) {
+        return (0, types_1.asTextContentResult)(`No functions found in domain/subdomain matching "${domainB}".`);
+    }
+    // Find call edges between domain A and domain B in both directions
+    const bridges = [];
+    for (const aId of aNodes) {
+        const adj = graph.callAdj.get(aId);
+        if (!adj)
+            continue;
+        // A calls B (downstream)
+        for (const targetId of adj.out) {
+            if (!bNodes.has(targetId))
+                continue;
+            const srcNode = graph.nodeById.get(aId);
+            const tgtNode = graph.nodeById.get(targetId);
+            const srcName = srcNode?.properties?.name || '(unknown)';
+            const tgtName = tgtNode?.properties?.name || '(unknown)';
+            const srcFile = (0, graph_cache_1.normalizePath)(srcNode?.properties?.filePath || '');
+            const tgtFile = (0, graph_cache_1.normalizePath)(tgtNode?.properties?.filePath || '');
+            bridges.push(`\`${srcName}\` (${domainA}) calls \`${tgtName}\` (${domainB}) — ${srcFile} → ${tgtFile}`);
+        }
+    }
+    for (const bId of bNodes) {
+        const adj = graph.callAdj.get(bId);
+        if (!adj)
+            continue;
+        // B calls A (reverse direction)
+        for (const targetId of adj.out) {
+            if (!aNodes.has(targetId))
+                continue;
+            const srcNode = graph.nodeById.get(bId);
+            const tgtNode = graph.nodeById.get(targetId);
+            const srcName = srcNode?.properties?.name || '(unknown)';
+            const tgtName = tgtNode?.properties?.name || '(unknown)';
+            const srcFile = (0, graph_cache_1.normalizePath)(srcNode?.properties?.filePath || '');
+            const tgtFile = (0, graph_cache_1.normalizePath)(tgtNode?.properties?.filePath || '');
+            bridges.push(`\`${srcName}\` (${domainB}) calls \`${tgtName}\` (${domainA}) — ${srcFile} → ${tgtFile}`);
+        }
+    }
+    if (bridges.length === 0) {
+        return (0, types_1.asTextContentResult)(`No direct call connections found between "${domainA}" and "${domainB}".`);
+    }
+    return (0, types_1.asTextContentResult)(`Connections between ${domainA} and ${domainB}:\n\n${bridges.join('\n')}`);
+};
+exports.handler = handler;
+exports.default = { tool: exports.tool, handler: exports.handler };

package/dist/tools/symbol-context.js

@@ -46,7 +46,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handler = exports.tool = void 0;
+exports.minimalTool = exports.handler = exports.tool = void 0;
 exports.findSymbol = findSymbol;
 exports.renderBriefSymbolContext = renderBriefSymbolContext;
 exports.renderSymbolContext = renderSymbolContext;
@@ -484,4 +484,19 @@ function findDomain(graph, nodeId) {
     }
     return null;
 }
+exports.minimalTool = {
+    name: 'symbol_context',
+    description: 'Look up a function or class by name.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'Symbol name.' },
+            directory: { type: 'string', description: 'Repo path.' },
+        },
+        required: [],
+    },
+    annotations: {
+        readOnlyHint: true,
+    },
+};
 exports.default = { tool: exports.tool, handler: exports.handler };

package/dist/tools/tool-variants.js

@@ -0,0 +1,255 @@
+"use strict";
+/**
+ * Experimental tool variants to test parallel calling behavior.
+ *
+ * Each variant reuses the same underlying graph + handler logic from
+ * symbol-context.ts but changes the tool name, description, and/or
+ * schema to test whether framing affects the model's willingness to
+ * call MCP tools in parallel with built-in tools (Read, Grep, etc.).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.annotateEndpoint = exports.annotateTool = exports.traceCallsEndpoint = exports.traceCallsTool = exports.findDefinitionEndpoint = exports.findDefinitionTool = exports.searchSymbolEndpoint = exports.searchSymbolTool = void 0;
+const types_1 = require("../types");
+const graph_cache_1 = require("../cache/graph-cache");
+const symbol_context_1 = require("./symbol-context");
+const constants_1 = require("../constants");
+// ─── Variant D: "search_symbol" ────────────────────────────────────
+// Hypothesis: framing as a search operation (like Grep/Glob) makes the
+// model treat it as parallel-safe alongside other search tools.
+exports.searchSymbolTool = {
+    name: 'search_symbol',
+    description: 'Search for a function, class, or method by name. Returns file location, callers, and callees. Like Grep but for code structure. Safe to call alongside Read, Grep, and Glob.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Function, class, or method name to search for.',
+            },
+            directory: {
+                type: 'string',
+                description: 'Repository path. Omit to use default.',
+            },
+        },
+        required: ['query'],
+    },
+    annotations: { readOnlyHint: true },
+};
+const searchSymbolHandler = async (client, args, defaultWorkdir) => {
+    const query = typeof args?.query === 'string' ? args.query.trim() : '';
+    if (!query) {
+        return (0, types_1.asErrorResult)({
+            type: 'validation_error',
+            message: 'Missing required "query" parameter.',
+            code: 'MISSING_QUERY',
+            recoverable: false,
+            suggestion: 'Provide the name of a function, class, or method to search for.',
+        });
+    }
+    const rawDir = args?.directory;
+    const directory = (rawDir && rawDir.trim()) || defaultWorkdir || process.cwd();
+    let graph;
+    try {
+        graph = await (0, graph_cache_1.resolveOrFetchGraph)(client, directory);
+    }
+    catch (error) {
+        return (0, types_1.asErrorResult)({ type: 'internal_error', message: error.message, code: 'GRAPH_ERROR', recoverable: false });
+    }
+    const matches = (0, symbol_context_1.findSymbol)(graph, query);
+    if (matches.length === 0) {
+        return (0, types_1.asTextContentResult)(`No symbol matching "${query}" found.`);
+    }
+    // Always brief — keep response small so model doesn't "wait for it"
+    const parts = matches.slice(0, 3).map(node => (0, symbol_context_1.renderBriefSymbolContext)(graph, node));
+    let result = parts.join('\n---\n\n');
+    if (matches.length > 3) {
+        result += `\n\n*... and ${matches.length - 3} more matches.*`;
+    }
+    return (0, types_1.asTextContentResult)(result);
+};
+exports.searchSymbolEndpoint = { tool: exports.searchSymbolTool, handler: searchSymbolHandler };
+// ─── Variant E: Split into find_definition + trace_calls ───────────
+// Hypothesis: two small tools give the model reason to call them in
+// parallel with each other AND with built-in tools.
+exports.findDefinitionTool = {
+    name: 'find_definition',
+    description: 'Find where a function, class, or method is defined. Returns file path and line number. Fast, read-only.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Symbol name to find.',
+            },
+            directory: {
+                type: 'string',
+                description: 'Repository path. Omit to use default.',
+            },
+        },
+        required: ['name'],
+    },
+    annotations: { readOnlyHint: true },
+};
+const findDefinitionHandler = async (client, args, defaultWorkdir) => {
+    const name = typeof args?.name === 'string' ? args.name.trim() : '';
+    if (!name) {
+        return (0, types_1.asErrorResult)({
+            type: 'validation_error',
+            message: 'Missing required "name" parameter.',
+            code: 'MISSING_NAME',
+            recoverable: false,
+        });
+    }
+    const rawDir = args?.directory;
+    const directory = (rawDir && rawDir.trim()) || defaultWorkdir || process.cwd();
+    let graph;
+    try {
+        graph = await (0, graph_cache_1.resolveOrFetchGraph)(client, directory);
+    }
+    catch (error) {
+        return (0, types_1.asErrorResult)({ type: 'internal_error', message: error.message, code: 'GRAPH_ERROR', recoverable: false });
+    }
+    const matches = (0, symbol_context_1.findSymbol)(graph, name);
+    if (matches.length === 0) {
+        return (0, types_1.asTextContentResult)(`No symbol matching "${name}" found.`);
+    }
+    // Ultra-compact: just location lines
+    const lines = matches.slice(0, 5).map(node => {
+        const sym = node.properties?.name || '(unknown)';
+        const fp = (0, graph_cache_1.normalizePath)(node.properties?.filePath || '');
+        const start = node.properties?.startLine || 0;
+        const end = node.properties?.endLine || 0;
+        const kind = node.labels?.[0]?.toLowerCase() || 'symbol';
+        return `${sym} (${kind}) — ${fp}:${start}-${end}`;
+    });
+    return (0, types_1.asTextContentResult)(lines.join('\n'));
+};
+exports.findDefinitionEndpoint = { tool: exports.findDefinitionTool, handler: findDefinitionHandler };
+exports.traceCallsTool = {
+    name: 'trace_calls',
+    description: 'Get the caller/callee graph for a function or method. Shows who calls it and what it calls. Fast, read-only.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Symbol name to trace.',
+            },
+            directory: {
+                type: 'string',
+                description: 'Repository path. Omit to use default.',
+            },
+        },
+        required: ['name'],
+    },
+    annotations: { readOnlyHint: true },
+};
+const traceCallsHandler = async (client, args, defaultWorkdir) => {
+    const name = typeof args?.name === 'string' ? args.name.trim() : '';
+    if (!name) {
+        return (0, types_1.asErrorResult)({
+            type: 'validation_error',
+            message: 'Missing required "name" parameter.',
+            code: 'MISSING_NAME',
+            recoverable: false,
+        });
+    }
+    const rawDir = args?.directory;
+    const directory = (rawDir && rawDir.trim()) || defaultWorkdir || process.cwd();
+    let graph;
+    try {
+        graph = await (0, graph_cache_1.resolveOrFetchGraph)(client, directory);
+    }
+    catch (error) {
+        return (0, types_1.asErrorResult)({ type: 'internal_error', message: error.message, code: 'GRAPH_ERROR', recoverable: false });
+    }
+    const matches = (0, symbol_context_1.findSymbol)(graph, name);
+    if (matches.length === 0) {
+        return (0, types_1.asTextContentResult)(`No symbol matching "${name}" found.`);
+    }
+    const node = matches[0];
+    const sym = node.properties?.name || '(unknown)';
+    const adj = graph.callAdj.get(node.id);
+    const lines = [`## ${sym}`];
+    if (adj && adj.in.length > 0) {
+        lines.push(`\n**Called by (${adj.in.length}):**`);
+        adj.in
+            .map(id => graph.nodeById.get(id))
+            .filter((n) => !!n)
+            .slice(0, constants_1.MAX_SYMBOL_CALLERS)
+            .forEach(n => {
+            const cName = n.properties?.name || '?';
+            const cFile = (0, graph_cache_1.normalizePath)(n.properties?.filePath || '');
+            const cLine = n.properties?.startLine || 0;
+            lines.push(`- \`${cName}\` — ${cFile}:${cLine}`);
+        });
+    }
+    if (adj && adj.out.length > 0) {
+        lines.push(`\n**Calls (${adj.out.length}):**`);
+        adj.out
+            .map(id => graph.nodeById.get(id))
+            .filter((n) => !!n)
+            .slice(0, constants_1.MAX_SYMBOL_CALLEES)
+            .forEach(n => {
+            const cName = n.properties?.name || '?';
+            const cFile = (0, graph_cache_1.normalizePath)(n.properties?.filePath || '');
+            const cLine = n.properties?.startLine || 0;
+            lines.push(`- \`${cName}\` — ${cFile}:${cLine}`);
+        });
+    }
+    return (0, types_1.asTextContentResult)(lines.join('\n'));
+};
+exports.traceCallsEndpoint = { tool: exports.traceCallsTool, handler: traceCallsHandler };
+// ─── Variant F: "annotate" ─────────────────────────────────────────
+// Hypothesis: framing as supplementary enrichment ("annotate your work")
+// makes the model fire it alongside other tools instead of waiting.
+exports.annotateTool = {
+    name: 'annotate',
+    description: 'Enrich your understanding with structural metadata for a symbol — definition location, callers, callees. Fire alongside Read or Grep to get parallel context. Read-only, zero side effects.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            symbol: {
+                type: 'string',
+                description: 'Function, class, or method name.',
+            },
+            directory: {
+                type: 'string',
+                description: 'Repository path. Omit to use default.',
+            },
+        },
+        required: ['symbol'],
+    },
+    annotations: { readOnlyHint: true },
+};
+const annotateHandler = async (client, args, defaultWorkdir) => {
+    const symbol = typeof args?.symbol === 'string' ? args.symbol.trim() : '';
+    if (!symbol) {
+        return (0, types_1.asErrorResult)({
+            type: 'validation_error',
+            message: 'Missing required "symbol" parameter.',
+            code: 'MISSING_SYMBOL',
+            recoverable: false,
+        });
+    }
+    const rawDir = args?.directory;
+    const directory = (rawDir && rawDir.trim()) || defaultWorkdir || process.cwd();
+    let graph;
+    try {
+        graph = await (0, graph_cache_1.resolveOrFetchGraph)(client, directory);
+    }
+    catch (error) {
+        return (0, types_1.asErrorResult)({ type: 'internal_error', message: error.message, code: 'GRAPH_ERROR', recoverable: false });
+    }
+    const matches = (0, symbol_context_1.findSymbol)(graph, symbol);
+    if (matches.length === 0) {
+        return (0, types_1.asTextContentResult)(`No symbol matching "${symbol}" found.`);
+    }
+    const parts = matches.slice(0, 3).map(node => (0, symbol_context_1.renderBriefSymbolContext)(graph, node));
+    let result = parts.join('\n---\n\n');
+    if (matches.length > 3) {
+        result += `\n\n*... and ${matches.length - 3} more matches.*`;
+    }
+    return (0, types_1.asTextContentResult)(result);
+};
+exports.annotateEndpoint = { tool: exports.annotateTool, handler: annotateHandler };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supermodeltools/mcp-server",
-  "version": "0.9.6",
+  "version": "0.10.0",
   "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.6",
+    "@supermodeltools/sdk": "0.10.0",
     "archiver": "^7.0.1",
     "ignore": "^7.0.5",
     "jq-web": "^0.6.2",