@supermodeltools/mcp-server 0.7.0 → 0.7.2

package/dist/tools/report-bug.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * Tool for agents to submit bug reports as GitHub issues.
+ * Creates issues on the supermodeltools/mcp repository.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handler = exports.tool = exports.metadata = void 0;
+exports.formatBugReportBody = formatBugReportBody;
+const types_1 = require("../types");
+const github_1 = require("../utils/github");
+exports.metadata = {
+    resource: 'issues',
+    operation: 'write',
+    tags: ['bug-report', 'github'],
+    httpMethod: 'post',
+    httpPath: '/repos/supermodeltools/mcp/issues',
+    operationId: 'createBugReport',
+};
+exports.tool = {
+    name: 'report_bug',
+    description: `Submit a bug report to the Supermodel MCP server GitHub repository (${github_1.GITHUB_REPO}).
+
+Creates a GitHub issue with structured fields (steps to reproduce, expected vs actual behavior) formatted into a clear bug report. The Supermodel team actively monitors and responds to all submitted issues.
+
+Use this tool whenever you encounter a bug, error, or unexpected behavior with any Supermodel MCP tool or with the underlying Supermodel API. Examples include:
+- A tool returned an error that seems incorrect or unexpected
+- A tool produced results that don't match its description or documentation
+- You encountered a crash, hang, timeout, or other failure that appears to be a server-side issue
+- The API returned malformed, incomplete, or nonsensical data
+- An edge case or specific input caused a tool to break
+- You received an error with "reportable: true" in the structured error response
+
+Providing steps_to_reproduce, expected_behavior, and actual_behavior helps the team fix bugs faster, but only title and description are required.
+
+This tool requires a GITHUB_TOKEN environment variable. To set it up:
+1. Create a GitHub personal access token at https://github.com/settings/tokens with the "public_repo" scope
+2. Set it in your environment: export GITHUB_TOKEN=ghp_your_token_here
+3. Restart the MCP server`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            title: {
+                type: 'string',
+                description: 'Short, descriptive title for the bug (e.g. "get_call_graph fails on monorepo with symlinks").',
+            },
+            description: {
+                type: 'string',
+                description: 'What happened? Describe the bug clearly.',
+            },
+            steps_to_reproduce: {
+                type: 'string',
+                description: 'Step-by-step instructions to reproduce the bug.',
+            },
+            expected_behavior: {
+                type: 'string',
+                description: 'What you expected to happen.',
+            },
+            actual_behavior: {
+                type: 'string',
+                description: 'What actually happened instead.',
+            },
+            labels: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Optional labels to categorize the issue (e.g. ["bug", "crash"]).',
+            },
+        },
+        required: ['title', 'description'],
+    },
+};
+/**
+ * Format structured bug report fields into a markdown issue body.
+ */
+function formatBugReportBody(fields) {
+    const sections = [];
+    sections.push('## Description\n\n' + fields.description);
+    if (fields.steps_to_reproduce) {
+        sections.push('## Steps to Reproduce\n\n' + fields.steps_to_reproduce);
+    }
+    if (fields.expected_behavior) {
+        sections.push('## Expected Behavior\n\n' + fields.expected_behavior);
+    }
+    if (fields.actual_behavior) {
+        sections.push('## Actual Behavior\n\n' + fields.actual_behavior);
+    }
+    return sections.join('\n\n');
+}
+const handler = async (_client, args) => {
+    const tokenError = (0, github_1.validateGitHubToken)();
+    if (tokenError)
+        return (0, types_1.asErrorResult)(tokenError);
+    if (!args) {
+        return (0, types_1.asErrorResult)({
+            type: 'validation_error',
+            message: 'Missing required parameters: title and description.',
+            code: 'MISSING_PARAMETERS',
+            recoverable: false,
+            suggestion: 'Provide both "title" and "description" parameters.',
+        });
+    }
+    const { title, description, steps_to_reproduce, expected_behavior, actual_behavior, labels, } = args;
+    const titleError = (0, github_1.validateRequiredString)(title, 'title', 'INVALID_TITLE', 'Provide a short, descriptive title for the bug.');
+    if (titleError)
+        return (0, types_1.asErrorResult)(titleError);
+    const descError = (0, github_1.validateRequiredString)(description, 'description', 'INVALID_DESCRIPTION', 'Describe the bug clearly.');
+    if (descError)
+        return (0, types_1.asErrorResult)(descError);
+    const stepsError = (0, github_1.validateOptionalString)(steps_to_reproduce, 'steps_to_reproduce', 'INVALID_STEPS', 'Provide steps to reproduce as a string.');
+    if (stepsError)
+        return (0, types_1.asErrorResult)(stepsError);
+    const expectedError = (0, github_1.validateOptionalString)(expected_behavior, 'expected_behavior', 'INVALID_EXPECTED_BEHAVIOR', 'Describe expected behavior as a string.');
+    if (expectedError)
+        return (0, types_1.asErrorResult)(expectedError);
+    const actualError = (0, github_1.validateOptionalString)(actual_behavior, 'actual_behavior', 'INVALID_ACTUAL_BEHAVIOR', 'Describe actual behavior as a string.');
+    if (actualError)
+        return (0, types_1.asErrorResult)(actualError);
+    const labelsError = (0, github_1.validateLabels)(labels);
+    if (labelsError)
+        return (0, types_1.asErrorResult)(labelsError);
+    const body = formatBugReportBody({
+        description: description,
+        steps_to_reproduce: steps_to_reproduce,
+        expected_behavior: expected_behavior,
+        actual_behavior: actual_behavior,
+    });
+    return (0, github_1.createGitHubIssue)('report_bug', {
+        title: title,
+        body,
+        labels: labels,
+    }, 'Bug report created successfully.');
+};
+exports.handler = handler;
+exports.default = { metadata: exports.metadata, tool: exports.tool, handler: exports.handler };

package/dist/tools/task-query-tools.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Task-specific query tools for focused codebase queries.
+ * These tools provide fast, targeted answers to specific code navigation questions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskQueryTools = exports.traceDataFlowToolDef = exports.findDefinitionToolDef = exports.traceCallChainToolDef = exports.findCallSitesToolDef = void 0;
+const types_1 = require("../types");
+const find_call_sites_1 = require("./find-call-sites");
+const trace_call_chain_1 = require("./trace-call-chain");
+const find_definition_1 = require("./find-definition");
+const trace_data_flow_1 = require("./trace-data-flow");
+/**
+ * Create a handler wrapper that calls the tool function and formats the result
+ */
+function createTaskQueryHandler(toolFunction, toolName) {
+    return async (client, args, defaultWorkdir) => {
+        if (!args) {
+            args = {};
+        }
+        // Inject default workdir if directory not provided
+        if (!args.path && defaultWorkdir) {
+            args.path = defaultWorkdir;
+        }
+        try {
+            // Call the tool function
+            const result = await toolFunction(args);
+            // Return formatted JSON response
+            return (0, types_1.asTextContentResult)(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            const message = typeof error?.message === 'string' ? error.message : String(error);
+            // Handle common error cases
+            if (message.includes('Graph not cached')) {
+                return (0, types_1.asErrorResult)({
+                    type: 'validation_error',
+                    message: 'Graph not cached. Run explore_codebase or get_call_graph first to analyze the repository.',
+                    code: 'GRAPH_NOT_CACHED',
+                    recoverable: true,
+                    suggestion: 'Call explore_codebase or one of the get_*_graph tools first to analyze and cache the repository graph.',
+                });
+            }
+            return (0, types_1.asErrorResult)({
+                type: 'internal_error',
+                message: `${toolName} failed: ${message}`,
+                code: 'TOOL_EXECUTION_FAILED',
+                recoverable: false,
+                reportable: true,
+            });
+        }
+    };
+}
+/**
+ * Create tool metadata for each task-specific query tool
+ */
+function createTaskQueryTool(config) {
+    const metadata = {
+        resource: 'queries',
+        operation: 'read',
+        tags: ['task-specific', 'query'],
+    };
+    const tool = {
+        name: config.name,
+        description: config.description,
+        inputSchema: config.inputSchema,
+    };
+    const handler = createTaskQueryHandler(config.handler, config.name);
+    return { metadata, tool, handler };
+}
+// Create individual tool definitions
+exports.findCallSitesToolDef = createTaskQueryTool(find_call_sites_1.findCallSitesTool);
+exports.traceCallChainToolDef = createTaskQueryTool(trace_call_chain_1.traceCallChainTool);
+exports.findDefinitionToolDef = createTaskQueryTool(find_definition_1.findDefinitionTool);
+exports.traceDataFlowToolDef = createTaskQueryTool(trace_data_flow_1.traceDataFlowTool);
+// Export all task query tools as an array for easy registration
+exports.taskQueryTools = [
+    exports.findCallSitesToolDef,
+    exports.traceCallChainToolDef,
+    exports.findDefinitionToolDef,
+    exports.traceDataFlowToolDef,
+];

package/dist/tools/trace-call-chain.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * Task-specific tool: Trace call chain between two functions
+ * Find shortest path showing how control flows from one function to another
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceCallChainTool = void 0;
+exports.traceCallChain = traceCallChain;
+const zod_1 = require("zod");
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const cache_1 = require("../cache");
+const TraceCallChainArgsSchema = zod_1.z.object({
+    path: zod_1.z.string().describe('Repository path'),
+    from_function: zod_1.z.string().describe('Starting function name'),
+    to_function: zod_1.z.string().describe('Target function name'),
+    max_depth: zod_1.z.number().optional().describe('Maximum call chain depth to search'),
+});
+/**
+ * Trace call chain from one function to another using BFS
+ */
+async function traceCallChain(args) {
+    const { path, from_function, to_function, max_depth = 10 } = args;
+    // Get cached graph
+    const cacheKey = getCacheKey(path);
+    const graph = cache_1.graphCache.get(cacheKey);
+    if (!graph) {
+        throw new Error('Graph not cached. Run explore_codebase first to analyze the repository.');
+    }
+    // Find source function
+    const fromNodes = findFunctionsByName(graph, from_function);
+    if (fromNodes.length === 0) {
+        return {
+            from_function,
+            to_function,
+            path_exists: false,
+            call_chain: [],
+            summary: `Source function "${from_function}" not found in codebase.`,
+        };
+    }
+    // Find target function
+    const toNodes = findFunctionsByName(graph, to_function);
+    if (toNodes.length === 0) {
+        return {
+            from_function,
+            to_function,
+            path_exists: false,
+            call_chain: [],
+            summary: `Target function "${to_function}" not found in codebase.`,
+        };
+    }
+    // Use first match if multiple functions with same name
+    const fromNode = fromNodes[0];
+    const toNode = toNodes[0];
+    // BFS to find shortest path
+    const path_result = findShortestCallPath(graph, fromNode.id, toNode.id, max_depth);
+    if (!path_result) {
+        return {
+            from_function,
+            to_function,
+            path_exists: false,
+            call_chain: [],
+            summary: `No call chain found from "${from_function}" to "${to_function}" within depth ${max_depth}.`,
+        };
+    }
+    // Build call chain steps
+    const callChain = [];
+    for (let i = 0; i < path_result.length; i++) {
+        const nodeId = path_result[i];
+        const node = graph.nodeById.get(nodeId);
+        if (!node)
+            continue;
+        const step = {
+            function_name: node.properties?.name || 'unknown',
+            file: node.properties?.filePath || 'unknown',
+            line: node.properties?.startLine || 0,
+        };
+        // Add call site info if there's a next function
+        if (i < path_result.length - 1) {
+            const nextNodeId = path_result[i + 1];
+            const edge = findCallEdge(graph, nodeId, nextNodeId);
+            if (edge) {
+                step.call_to_next = {
+                    line: edge.properties?.lineNumber || 0,
+                    column: edge.properties?.columnNumber,
+                };
+            }
+        }
+        callChain.push(step);
+    }
+    // Generate summary
+    const summary = generateSummary(from_function, to_function, callChain);
+    return {
+        from_function,
+        to_function,
+        path_exists: true,
+        call_chain: callChain,
+        summary,
+        chain_length: callChain.length,
+    };
+}
+/**
+ * BFS to find shortest path between two functions
+ */
+function findShortestCallPath(graph, fromId, toId, maxDepth) {
+    if (fromId === toId) {
+        return [fromId];
+    }
+    const queue = [{ id: fromId, path: [fromId] }];
+    const visited = new Set([fromId]);
+    while (queue.length > 0) {
+        const { id, path } = queue.shift();
+        // Check depth limit
+        if (path.length > maxDepth) {
+            continue;
+        }
+        // Get callees
+        const adj = graph.callAdj.get(id);
+        if (!adj)
+            continue;
+        for (const calleeId of adj.out) {
+            if (calleeId === toId) {
+                // Found target
+                return [...path, calleeId];
+            }
+            if (!visited.has(calleeId)) {
+                visited.add(calleeId);
+                queue.push({ id: calleeId, path: [...path, calleeId] });
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Helper: Find function nodes by name
+ */
+function findFunctionsByName(graph, name) {
+    const lowerName = name.toLowerCase();
+    const nodeIds = graph.nameIndex.get(lowerName) || [];
+    return nodeIds
+        .map((id) => graph.nodeById.get(id))
+        .filter((node) => node && node.labels?.[0] === 'Function');
+}
+/**
+ * Helper: Find specific call edge between two functions
+ */
+function findCallEdge(graph, fromId, toId) {
+    const relationships = graph.raw?.graph?.relationships || [];
+    return relationships.find((rel) => rel.type === 'calls' && rel.startNode === fromId && rel.endNode === toId);
+}
+/**
+ * Helper: Generate natural language summary
+ */
+function generateSummary(fromName, toName, chain) {
+    if (chain.length === 0) {
+        return `No call chain found from "${fromName}" to "${toName}".`;
+    }
+    if (chain.length === 2) {
+        return `"${fromName}" directly calls "${toName}".`;
+    }
+    const pathNames = chain.map(step => step.function_name);
+    const arrow = ' → ';
+    const pathStr = pathNames.join(arrow);
+    return `Call chain (${chain.length} steps): ${pathStr}`;
+}
+/**
+ * Helper: Generate cache key
+ */
+function getCacheKey(path) {
+    return `cache_${path}`;
+}
+/**
+ * Tool metadata for MCP registration
+ */
+exports.traceCallChainTool = {
+    name: 'trace_call_chain',
+    description: 'Trace the call chain from one function to another, showing the shortest path of function calls',
+    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(TraceCallChainArgsSchema),
+    handler: traceCallChain,
+};

package/dist/tools/trace-data-flow.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * Task-specific tool: Trace data flow for a variable/parameter
+ * Follow how data flows through function parameters and variables
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceDataFlowTool = void 0;
+exports.traceDataFlow = traceDataFlow;
+const zod_1 = require("zod");
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const cache_1 = require("../cache");
+const TraceDataFlowArgsSchema = zod_1.z.object({
+    path: zod_1.z.string().describe('Repository path'),
+    variable: zod_1.z.string().describe('Variable or parameter name to trace'),
+    function_name: zod_1.z.string().optional().describe('Function context (optional, helps narrow scope)'),
+    max_depth: zod_1.z.number().optional().describe('Maximum depth to trace'),
+});
+/**
+ * Trace data flow for a variable/parameter
+ */
+async function traceDataFlow(args) {
+    const { path, variable, function_name, max_depth = 5 } = args;
+    // Get cached graph
+    const cacheKey = getCacheKey(path);
+    const graph = cache_1.graphCache.get(cacheKey);
+    if (!graph) {
+        throw new Error('Graph not cached. Run explore_codebase first to analyze the repository.');
+    }
+    // Find variable/parameter nodes
+    const variableNodes = findVariablesByName(graph, variable, function_name);
+    if (variableNodes.length === 0) {
+        return {
+            variable,
+            function_context: function_name,
+            found: false,
+            flow_steps: [],
+            summary: function_name
+                ? `Variable "${variable}" not found in function "${function_name}".`
+                : `Variable "${variable}" not found in codebase.`,
+        };
+    }
+    // Build flow steps from the variable node
+    const flowSteps = [];
+    const visited = new Set();
+    // Start with the first matching variable
+    const startNode = variableNodes[0];
+    traceFromNode(graph, startNode, flowSteps, visited, 0, max_depth);
+    // If no flow found, at least report the definition
+    if (flowSteps.length === 0) {
+        const props = startNode.properties || {};
+        flowSteps.push({
+            step_type: 'definition',
+            location: {
+                function: props.scope || 'unknown',
+                file: props.filePath || 'unknown',
+                line: props.startLine || 0,
+            },
+            description: `Variable "${variable}" is defined here`,
+            variable_name: variable,
+        });
+    }
+    // Generate summary
+    const summary = generateSummary(variable, function_name, flowSteps);
+    return {
+        variable,
+        function_context: function_name,
+        found: true,
+        flow_steps: flowSteps,
+        summary,
+    };
+}
+/**
+ * Recursively trace data flow from a node
+ */
+function traceFromNode(graph, node, steps, visited, depth, maxDepth) {
+    if (depth >= maxDepth || visited.has(node.id)) {
+        return;
+    }
+    visited.add(node.id);
+    const props = node.properties || {};
+    // Add definition step
+    if (depth === 0) {
+        steps.push({
+            step_type: 'definition',
+            location: {
+                function: props.scope || 'unknown',
+                file: props.filePath || 'unknown',
+                line: props.startLine || 0,
+            },
+            description: `Variable "${props.name}" is defined`,
+            variable_name: props.name,
+        });
+    }
+    // Find relationships from this node
+    const relationships = graph.raw?.graph?.relationships || [];
+    for (const rel of relationships) {
+        if (rel.startNode !== node.id)
+            continue;
+        const targetNode = graph.nodeById.get(rel.endNode);
+        if (!targetNode)
+            continue;
+        const targetProps = targetNode.properties || {};
+        // Handle different relationship types
+        if (rel.type === 'USES' || rel.type === 'reads') {
+            steps.push({
+                step_type: 'usage',
+                location: {
+                    function: targetProps.name || 'unknown',
+                    file: targetProps.filePath || props.filePath || 'unknown',
+                    line: targetProps.startLine || 0,
+                },
+                description: `Used in ${targetProps.name || 'expression'}`,
+                variable_name: props.name,
+            });
+        }
+        else if (rel.type === 'ASSIGNS' || rel.type === 'writes') {
+            steps.push({
+                step_type: 'assignment',
+                location: {
+                    function: props.scope || 'unknown',
+                    file: props.filePath || 'unknown',
+                    line: rel.properties?.lineNumber || 0,
+                },
+                description: `Assigned value`,
+                variable_name: props.name,
+            });
+        }
+        else if (rel.type === 'PASSED_TO' || rel.type === 'argument_to') {
+            steps.push({
+                step_type: 'passed_to',
+                location: {
+                    function: targetProps.name || 'unknown',
+                    file: targetProps.filePath || 'unknown',
+                    line: targetProps.startLine || 0,
+                },
+                description: `Passed as argument to ${targetProps.name}`,
+                variable_name: props.name,
+            });
+            // Continue tracing in the called function
+            traceFromNode(graph, targetNode, steps, visited, depth + 1, maxDepth);
+        }
+        else if (rel.type === 'RETURNS') {
+            steps.push({
+                step_type: 'returned_from',
+                location: {
+                    function: props.scope || 'unknown',
+                    file: props.filePath || 'unknown',
+                    line: rel.properties?.lineNumber || 0,
+                },
+                description: `Returned from function`,
+                variable_name: props.name,
+            });
+        }
+        else if (rel.type === 'transforms_to' || rel.type === 'TRANSFORMS') {
+            steps.push({
+                step_type: 'transformation',
+                location: {
+                    function: props.scope || 'unknown',
+                    file: props.filePath || 'unknown',
+                    line: rel.properties?.lineNumber || 0,
+                },
+                description: `Transformed to ${targetProps.name}`,
+                variable_name: props.name,
+                transformed_to: targetProps.name,
+            });
+            // Continue tracing the transformed variable
+            traceFromNode(graph, targetNode, steps, visited, depth + 1, maxDepth);
+        }
+    }
+}
+/**
+ * Find variable/parameter nodes by name
+ */
+function findVariablesByName(graph, name, functionContext) {
+    const lowerName = name.toLowerCase();
+    const nodeIds = graph.nameIndex.get(lowerName) || [];
+    let nodes = nodeIds
+        .map((id) => graph.nodeById.get(id))
+        .filter((node) => {
+        if (!node)
+            return false;
+        const label = node.labels?.[0] || '';
+        return ['Variable', 'Parameter', 'Field', 'Constant'].includes(label);
+    });
+    // Filter by function context if provided
+    if (functionContext) {
+        const lowerContext = functionContext.toLowerCase();
+        nodes = nodes.filter((node) => {
+            const scope = (node.properties?.scope || '').toLowerCase();
+            return scope.includes(lowerContext);
+        });
+    }
+    return nodes;
+}
+/**
+ * Generate natural language summary
+ */
+function generateSummary(variable, functionContext, steps) {
+    if (steps.length === 0) {
+        return `No data flow found for "${variable}".`;
+    }
+    if (steps.length === 1) {
+        return `Variable "${variable}" is defined but not used in tracked data flows.`;
+    }
+    // Count step types
+    const usages = steps.filter(s => s.step_type === 'usage').length;
+    const passedTo = steps.filter(s => s.step_type === 'passed_to').length;
+    const transforms = steps.filter(s => s.step_type === 'transformation').length;
+    const parts = [];
+    if (usages > 0)
+        parts.push(`${usages} usage(s)`);
+    if (passedTo > 0)
+        parts.push(`passed to ${passedTo} function(s)`);
+    if (transforms > 0)
+        parts.push(`${transforms} transformation(s)`);
+    const context = functionContext ? ` in "${functionContext}"` : '';
+    return `Data flow for "${variable}"${context}: ${parts.join(', ')} (${steps.length} total steps)`;
+}
+/**
+ * Helper: Generate cache key
+ */
+function getCacheKey(path) {
+    return `cache_${path}`;
+}
+/**
+ * Tool metadata for MCP registration
+ */
+exports.traceDataFlowTool = {
+    name: 'trace_data_flow',
+    description: 'Trace how data flows through a variable or parameter, showing usage, transformations, and passing between functions',
+    inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(TraceDataFlowArgsSchema),
+    handler: traceDataFlow,
+};