@grafema/mcp 0.1.0-alpha.1

package/dist/handlers.js

@@ -0,0 +1,747 @@
+/**
+ * MCP Tool Handlers
+ */
+import { ensureAnalyzed } from './analysis.js';
+import { getProjectPath, getAnalysisStatus, setIsAnalyzed, getOrCreateBackend, getGuaranteeManager, getGuaranteeAPI } from './state.js';
+import { normalizeLimit, formatPaginationInfo, guardResponseSize, serializeBigInt, findSimilarTypes, textResult, errorResult, } from './utils.js';
+import { isGuaranteeType } from '@grafema/core';
+// === QUERY HANDLERS ===
+export async function handleQueryGraph(args) {
+    const db = await ensureAnalyzed();
+    const { query, limit: requestedLimit, offset: requestedOffset, format } = args;
+    const explain = args.explain;
+    const limit = normalizeLimit(requestedLimit);
+    const offset = Math.max(0, requestedOffset || 0);
+    try {
+        // Check if backend supports Datalog queries
+        if (!('checkGuarantee' in db)) {
+            return errorResult('Backend does not support Datalog queries');
+        }
+        const checkFn = db.checkGuarantee;
+        const results = await checkFn(query);
+        const total = results.length;
+        if (total === 0) {
+            const nodeCounts = await db.countNodesByType();
+            const totalNodes = Object.values(nodeCounts).reduce((a, b) => a + b, 0);
+            const typeMatch = query.match(/node\([^,]+,\s*"([^"]+)"\)/);
+            const queriedType = typeMatch ? typeMatch[1] : null;
+            let hint = '';
+            if (queriedType && !nodeCounts[queriedType]) {
+                const availableTypes = Object.keys(nodeCounts);
+                const similar = findSimilarTypes(queriedType, availableTypes);
+                if (similar.length > 0) {
+                    hint = `\n💡 Did you mean: ${similar.join(', ')}?`;
+                }
+                else {
+                    hint = `\n💡 Available types: ${availableTypes.slice(0, 10).join(', ')}${availableTypes.length > 10 ? '...' : ''}`;
+                }
+            }
+            return textResult(`Query returned no results.${hint}\n📊 Graph: ${totalNodes.toLocaleString()} nodes`);
+        }
+        const paginatedResults = results.slice(offset, offset + limit);
+        const hasMore = offset + limit < total;
+        const enrichedResults = [];
+        for (const result of paginatedResults) {
+            const nodeId = result.bindings?.find((b) => b.name === 'X')?.value;
+            if (nodeId) {
+                const node = await db.getNode(nodeId);
+                if (node) {
+                    enrichedResults.push({
+                        ...node,
+                        id: nodeId,
+                        file: node.file,
+                        line: node.line,
+                    });
+                }
+            }
+        }
+        const paginationInfo = formatPaginationInfo({
+            limit,
+            offset,
+            returned: enrichedResults.length,
+            total,
+            hasMore,
+        });
+        const responseText = `Found ${total} result(s):${paginationInfo}\n\n${JSON.stringify(serializeBigInt(enrichedResults), null, 2)}`;
+        return textResult(guardResponseSize(responseText));
+    }
+    catch (error) {
+        return errorResult(error.message);
+    }
+}
+export async function handleFindCalls(args) {
+    const db = await ensureAnalyzed();
+    const { target: name, limit: requestedLimit, offset: requestedOffset } = args;
+    const className = args.className;
+    const limit = normalizeLimit(requestedLimit);
+    const offset = Math.max(0, requestedOffset || 0);
+    const calls = [];
+    let skipped = 0;
+    let totalMatched = 0;
+    for await (const node of db.queryNodes({ type: 'CALL' })) {
+        if (node.name !== name && node.method !== name)
+            continue;
+        if (className && node.object !== className)
+            continue;
+        totalMatched++;
+        if (skipped < offset) {
+            skipped++;
+            continue;
+        }
+        if (calls.length >= limit)
+            continue;
+        const callsEdges = await db.getOutgoingEdges(node.id, ['CALLS']);
+        const isResolved = callsEdges.length > 0;
+        let target = null;
+        if (isResolved) {
+            const targetNode = await db.getNode(callsEdges[0].dst);
+            target = targetNode
+                ? {
+                    type: targetNode.type,
+                    name: targetNode.name,
+                    file: targetNode.file,
+                    line: targetNode.line,
+                }
+                : null;
+        }
+        calls.push({
+            id: node.id,
+            name: node.name,
+            object: node.object,
+            file: node.file,
+            line: node.line,
+            resolved: isResolved,
+            target,
+        });
+    }
+    if (totalMatched === 0) {
+        return textResult(`No calls found for "${className ? className + '.' : ''}${name}"`);
+    }
+    const resolved = calls.filter((c) => c.resolved).length;
+    const unresolved = calls.length - resolved;
+    const hasMore = offset + calls.length < totalMatched;
+    const paginationInfo = formatPaginationInfo({
+        limit,
+        offset,
+        returned: calls.length,
+        total: totalMatched,
+        hasMore,
+    });
+    const responseText = `Found ${totalMatched} call(s) to "${className ? className + '.' : ''}${name}":${paginationInfo}\n` +
+        `- Resolved: ${resolved}\n` +
+        `- Unresolved: ${unresolved}\n\n` +
+        JSON.stringify(serializeBigInt(calls), null, 2);
+    return textResult(guardResponseSize(responseText));
+}
+export async function handleFindNodes(args) {
+    const db = await ensureAnalyzed();
+    const { type, name, file, limit: requestedLimit, offset: requestedOffset } = args;
+    const limit = normalizeLimit(requestedLimit);
+    const offset = Math.max(0, requestedOffset || 0);
+    const filter = {};
+    if (type)
+        filter.type = type;
+    if (name)
+        filter.name = name;
+    if (file)
+        filter.file = file;
+    const nodes = [];
+    let skipped = 0;
+    let totalMatched = 0;
+    for await (const node of db.queryNodes(filter)) {
+        totalMatched++;
+        if (skipped < offset) {
+            skipped++;
+            continue;
+        }
+        if (nodes.length < limit) {
+            nodes.push(node);
+        }
+    }
+    if (totalMatched === 0) {
+        return textResult('No nodes found matching criteria');
+    }
+    const hasMore = offset + nodes.length < totalMatched;
+    const paginationInfo = formatPaginationInfo({
+        limit,
+        offset,
+        returned: nodes.length,
+        total: totalMatched,
+        hasMore,
+    });
+    return textResult(`Found ${totalMatched} node(s):${paginationInfo}\n\n${JSON.stringify(serializeBigInt(nodes), null, 2)}`);
+}
+// === TRACE HANDLERS ===
+export async function handleTraceAlias(args) {
+    const db = await ensureAnalyzed();
+    const { identifier: variableName, file } = args;
+    const projectPath = getProjectPath();
+    let varNode = null;
+    for await (const node of db.queryNodes({ type: 'VARIABLE' })) {
+        if (node.name === variableName && node.file?.includes(file || '')) {
+            varNode = node;
+            break;
+        }
+    }
+    if (!varNode) {
+        for await (const node of db.queryNodes({ type: 'CONSTANT' })) {
+            if (node.name === variableName && node.file?.includes(file || '')) {
+                varNode = node;
+                break;
+            }
+        }
+    }
+    if (!varNode) {
+        return errorResult(`Variable "${variableName}" not found in ${file || 'project'}`);
+    }
+    const chain = [];
+    const visited = new Set();
+    let current = varNode;
+    const MAX_DEPTH = 20;
+    while (current && chain.length < MAX_DEPTH) {
+        if (visited.has(current.id)) {
+            chain.push({ type: 'CYCLE_DETECTED', id: current.id });
+            break;
+        }
+        visited.add(current.id);
+        chain.push({
+            type: current.type,
+            name: current.name,
+            file: current.file,
+            line: current.line,
+        });
+        const edges = await db.getOutgoingEdges(current.id, ['ASSIGNED_FROM']);
+        if (edges.length === 0)
+            break;
+        current = await db.getNode(edges[0].dst);
+    }
+    return textResult(`Alias chain for "${variableName}" (${chain.length} steps):\n\n${JSON.stringify(serializeBigInt(chain), null, 2)}`);
+}
+export async function handleTraceDataFlow(args) {
+    const db = await ensureAnalyzed();
+    const { source, direction = 'forward', max_depth = 10 } = args;
+    // Find source node
+    let sourceNode = null;
+    // Try to find by ID first
+    sourceNode = await db.getNode(source);
+    // If not found, search by name
+    if (!sourceNode) {
+        for await (const node of db.queryNodes({ name: source })) {
+            sourceNode = node;
+            break;
+        }
+    }
+    if (!sourceNode) {
+        return errorResult(`Source "${source}" not found`);
+    }
+    const visited = new Set();
+    const paths = [];
+    async function trace(nodeId, depth, path) {
+        if (depth > max_depth || visited.has(nodeId))
+            return;
+        visited.add(nodeId);
+        const newPath = [...path, nodeId];
+        if (direction === 'forward' || direction === 'both') {
+            const outEdges = await db.getOutgoingEdges(nodeId, [
+                'ASSIGNED_FROM',
+                'DERIVES_FROM',
+                'PASSES_ARGUMENT',
+            ]);
+            for (const edge of outEdges) {
+                await trace(edge.dst, depth + 1, newPath);
+            }
+        }
+        if (direction === 'backward' || direction === 'both') {
+            const inEdges = await db.getIncomingEdges(nodeId, [
+                'ASSIGNED_FROM',
+                'DERIVES_FROM',
+                'PASSES_ARGUMENT',
+            ]);
+            for (const edge of inEdges) {
+                await trace(edge.src, depth + 1, newPath);
+            }
+        }
+        if (depth > 0) {
+            paths.push(newPath);
+        }
+    }
+    await trace(sourceNode.id, 0, []);
+    return textResult(`Data flow from "${source}" (${paths.length} paths):\n\n${JSON.stringify(paths, null, 2)}`);
+}
+export async function handleCheckInvariant(args) {
+    const db = await ensureAnalyzed();
+    const { rule, name: description } = args;
+    if (!('checkGuarantee' in db)) {
+        return errorResult('Backend does not support Datalog queries');
+    }
+    try {
+        const checkFn = db.checkGuarantee;
+        const violations = await checkFn(rule);
+        const total = violations.length;
+        if (total === 0) {
+            return textResult(`✅ Invariant holds: ${description || 'No violations found'}`);
+        }
+        const enrichedViolations = [];
+        for (const v of violations.slice(0, 20)) {
+            const nodeId = v.bindings?.find((b) => b.name === 'X')?.value;
+            if (nodeId) {
+                const node = await db.getNode(nodeId);
+                if (node) {
+                    enrichedViolations.push({
+                        id: nodeId,
+                        type: node.type,
+                        name: node.name,
+                        file: node.file,
+                        line: node.line,
+                    });
+                }
+            }
+        }
+        return textResult(`❌ ${total} violation(s) found:\n\n${JSON.stringify(serializeBigInt(enrichedViolations), null, 2)}${total > 20 ? `\n\n... and ${total - 20} more` : ''}`);
+    }
+    catch (error) {
+        return errorResult(error.message);
+    }
+}
+// === ANALYSIS HANDLERS ===
+export async function handleAnalyzeProject(args) {
+    const { service, force } = args;
+    if (force) {
+        setIsAnalyzed(false);
+    }
+    try {
+        await ensureAnalyzed(service || null);
+        const status = getAnalysisStatus();
+        return textResult(`✅ Analysis complete!\n` +
+            `- Services discovered: ${status.servicesDiscovered}\n` +
+            `- Services analyzed: ${status.servicesAnalyzed}\n` +
+            `- Total time: ${status.timings.total || 'N/A'}s`);
+    }
+    catch (error) {
+        return errorResult(error.message);
+    }
+}
+export async function handleGetAnalysisStatus() {
+    const status = getAnalysisStatus();
+    return textResult(`Analysis Status:\n` +
+        `- Running: ${status.running}\n` +
+        `- Phase: ${status.phase || 'N/A'}\n` +
+        `- Message: ${status.message || 'N/A'}\n` +
+        `- Services discovered: ${status.servicesDiscovered}\n` +
+        `- Services analyzed: ${status.servicesAnalyzed}\n` +
+        (status.error ? `- Error: ${status.error}\n` : ''));
+}
+export async function handleGetStats() {
+    const db = await getOrCreateBackend();
+    const nodeCount = await db.nodeCount();
+    const edgeCount = await db.edgeCount();
+    const nodesByType = await db.countNodesByType();
+    const edgesByType = await db.countEdgesByType();
+    return textResult(`Graph Statistics:\n\n` +
+        `Total nodes: ${nodeCount.toLocaleString()}\n` +
+        `Total edges: ${edgeCount.toLocaleString()}\n\n` +
+        `Nodes by type:\n${JSON.stringify(nodesByType, null, 2)}\n\n` +
+        `Edges by type:\n${JSON.stringify(edgesByType, null, 2)}`);
+}
+export async function handleGetSchema(args) {
+    const db = await getOrCreateBackend();
+    const { type = 'all' } = args;
+    const nodesByType = await db.countNodesByType();
+    const edgesByType = await db.countEdgesByType();
+    let output = '';
+    if (type === 'nodes' || type === 'all') {
+        output += `Node Types (${Object.keys(nodesByType).length}):\n`;
+        for (const [t, count] of Object.entries(nodesByType)) {
+            output += `  - ${t}: ${count}\n`;
+        }
+    }
+    if (type === 'edges' || type === 'all') {
+        output += `\nEdge Types (${Object.keys(edgesByType).length}):\n`;
+        for (const [t, count] of Object.entries(edgesByType)) {
+            output += `  - ${t}: ${count}\n`;
+        }
+    }
+    return textResult(output);
+}
+// === GUARANTEE HANDLERS ===
+/**
+ * Create a new guarantee (Datalog-based or contract-based)
+ */
+export async function handleCreateGuarantee(args) {
+    await getOrCreateBackend(); // Ensure managers are initialized
+    const { name, rule, type, priority, status, owner, schema, condition, description, governs, severity } = args;
+    try {
+        // Determine if this is a contract-based guarantee
+        if (type && isGuaranteeType(type)) {
+            // Contract-based guarantee
+            const api = getGuaranteeAPI();
+            if (!api) {
+                return errorResult('GuaranteeAPI not initialized');
+            }
+            const guarantee = await api.createGuarantee({
+                type,
+                name,
+                priority,
+                status,
+                owner,
+                schema,
+                condition,
+                description,
+                governs,
+            });
+            return textResult(`✅ Created contract-based guarantee: ${guarantee.id}\n` +
+                `Type: ${guarantee.type}\n` +
+                `Priority: ${guarantee.priority}\n` +
+                `Status: ${guarantee.status}` +
+                (guarantee.description ? `\nDescription: ${guarantee.description}` : ''));
+        }
+        else {
+            // Datalog-based guarantee
+            if (!rule) {
+                return errorResult('Datalog-based guarantee requires "rule" field');
+            }
+            const manager = getGuaranteeManager();
+            if (!manager) {
+                return errorResult('GuaranteeManager not initialized');
+            }
+            const guarantee = await manager.create({
+                id: name,
+                name,
+                rule,
+                severity: severity || 'warning',
+                governs: governs || ['**/*.js'],
+            });
+            return textResult(`✅ Created Datalog-based guarantee: ${guarantee.id}\n` +
+                `Rule: ${guarantee.rule}\n` +
+                `Severity: ${guarantee.severity}`);
+        }
+    }
+    catch (error) {
+        return errorResult(`Failed to create guarantee: ${error.message}`);
+    }
+}
+/**
+ * List all guarantees (both Datalog-based and contract-based)
+ */
+export async function handleListGuarantees() {
+    await getOrCreateBackend(); // Ensure managers are initialized
+    const results = [];
+    try {
+        // List Datalog-based guarantees
+        const manager = getGuaranteeManager();
+        if (manager) {
+            const datalogGuarantees = await manager.list();
+            if (datalogGuarantees.length > 0) {
+                results.push('## Datalog-based Guarantees\n');
+                for (const g of datalogGuarantees) {
+                    results.push(`- **${g.id}** (${g.severity})`);
+                    results.push(`  Rule: ${g.rule.substring(0, 80)}${g.rule.length > 80 ? '...' : ''}`);
+                }
+            }
+        }
+        // List contract-based guarantees
+        const api = getGuaranteeAPI();
+        if (api) {
+            const contractGuarantees = await api.findGuarantees();
+            if (contractGuarantees.length > 0) {
+                if (results.length > 0)
+                    results.push('\n');
+                results.push('## Contract-based Guarantees\n');
+                for (const g of contractGuarantees) {
+                    results.push(`- **${g.id}** [${g.priority}] (${g.status})`);
+                    if (g.description)
+                        results.push(`  ${g.description}`);
+                }
+            }
+        }
+        if (results.length === 0) {
+            return textResult('No guarantees defined yet.');
+        }
+        return textResult(results.join('\n'));
+    }
+    catch (error) {
+        return errorResult(`Failed to list guarantees: ${error.message}`);
+    }
+}
+/**
+ * Check guarantees (both Datalog-based and contract-based)
+ */
+export async function handleCheckGuarantees(args) {
+    await getOrCreateBackend(); // Ensure managers are initialized
+    const { names } = args;
+    const results = [];
+    let totalPassed = 0;
+    let totalFailed = 0;
+    try {
+        const manager = getGuaranteeManager();
+        const api = getGuaranteeAPI();
+        if (names && names.length > 0) {
+            // Check specific guarantees
+            for (const name of names) {
+                // Try Datalog-based first
+                if (manager) {
+                    try {
+                        const result = await manager.check(name);
+                        if (result.passed) {
+                            totalPassed++;
+                            results.push(`✅ ${result.guaranteeId}: PASSED`);
+                        }
+                        else {
+                            totalFailed++;
+                            results.push(`❌ ${result.guaranteeId}: FAILED (${result.violationCount} violations)`);
+                            for (const v of result.violations.slice(0, 5)) {
+                                results.push(`   - ${v.file}:${v.line} (${v.type})`);
+                            }
+                            if (result.violationCount > 5) {
+                                results.push(`   ... and ${result.violationCount - 5} more`);
+                            }
+                        }
+                        continue;
+                    }
+                    catch {
+                        // Not a Datalog guarantee, try contract-based
+                    }
+                }
+                // Try contract-based
+                if (api) {
+                    try {
+                        const result = await api.checkGuarantee(name);
+                        if (result.passed) {
+                            totalPassed++;
+                            results.push(`✅ ${result.id}: PASSED`);
+                        }
+                        else {
+                            totalFailed++;
+                            results.push(`❌ ${result.id}: FAILED`);
+                            for (const err of result.errors.slice(0, 5)) {
+                                results.push(`   - ${err}`);
+                            }
+                        }
+                    }
+                    catch {
+                        results.push(`⚠️ ${name}: Not found`);
+                    }
+                }
+            }
+        }
+        else {
+            // Check all guarantees
+            if (manager) {
+                const datalogResult = await manager.checkAll();
+                totalPassed += datalogResult.passed;
+                totalFailed += datalogResult.failed;
+                if (datalogResult.total > 0) {
+                    results.push('## Datalog Guarantees\n');
+                    for (const r of datalogResult.results) {
+                        if (r.passed) {
+                            results.push(`✅ ${r.guaranteeId}: PASSED`);
+                        }
+                        else {
+                            results.push(`❌ ${r.guaranteeId}: FAILED (${r.violationCount} violations)`);
+                        }
+                    }
+                }
+            }
+            if (api) {
+                const contractResult = await api.checkAllGuarantees();
+                totalPassed += contractResult.passed;
+                totalFailed += contractResult.failed;
+                if (contractResult.total > 0) {
+                    if (results.length > 0)
+                        results.push('\n');
+                    results.push('## Contract Guarantees\n');
+                    for (const r of contractResult.results) {
+                        if (r.passed) {
+                            results.push(`✅ ${r.id}: PASSED`);
+                        }
+                        else {
+                            results.push(`❌ ${r.id}: FAILED`);
+                        }
+                    }
+                }
+            }
+        }
+        if (results.length === 0) {
+            return textResult('No guarantees to check.');
+        }
+        const summary = `\n---\nTotal: ${totalPassed + totalFailed} | ✅ Passed: ${totalPassed} | ❌ Failed: ${totalFailed}`;
+        return textResult(results.join('\n') + summary);
+    }
+    catch (error) {
+        return errorResult(`Failed to check guarantees: ${error.message}`);
+    }
+}
+/**
+ * Delete a guarantee
+ */
+export async function handleDeleteGuarantee(args) {
+    await getOrCreateBackend(); // Ensure managers are initialized
+    const { name } = args;
+    try {
+        // Try Datalog-based first
+        const manager = getGuaranteeManager();
+        if (manager) {
+            try {
+                await manager.delete(name);
+                return textResult(`✅ Deleted Datalog guarantee: ${name}`);
+            }
+            catch {
+                // Not found in Datalog, try contract-based
+            }
+        }
+        // Try contract-based
+        const api = getGuaranteeAPI();
+        if (api) {
+            const deleted = await api.deleteGuarantee(name);
+            if (deleted) {
+                return textResult(`✅ Deleted contract guarantee: ${name}`);
+            }
+        }
+        return errorResult(`Guarantee not found: ${name}`);
+    }
+    catch (error) {
+        return errorResult(`Failed to delete guarantee: ${error.message}`);
+    }
+}
+// === COVERAGE & DOCS ===
+export async function handleGetCoverage(args) {
+    const db = await getOrCreateBackend();
+    const projectPath = getProjectPath();
+    const { path: targetPath = projectPath } = args;
+    const nodeCount = await db.nodeCount();
+    const moduleNodes = db.findByType ? await db.findByType('MODULE') : [];
+    return textResult(`Coverage for ${targetPath}:\n` +
+        `- Analyzed files: ${moduleNodes.length}\n` +
+        `- Total nodes: ${nodeCount}\n`);
+}
+export async function handleGetDocumentation(args) {
+    const { topic = 'overview' } = args;
+    const docs = {
+        overview: `
+# Grafema Code Analysis
+
+Grafema is a static code analyzer that builds a graph of your codebase.
+
+## Key Tools
+- query_graph: Execute Datalog queries
+- find_calls: Find function/method calls
+- trace_alias: Trace variable aliases
+- check_invariant: Verify code invariants
+
+## Quick Start
+1. Use get_stats to see graph size
+2. Use find_nodes to explore the codebase
+3. Use query_graph for complex queries
+`,
+        queries: `
+# Datalog Queries
+
+## Syntax
+violation(X) :- node(X, "TYPE"), attr(X, "name", "value").
+
+## Available Predicates
+- node(Id, Type) - match nodes
+- edge(Src, Dst, Type) - match edges
+- attr(Id, Name, Value) - match attributes
+- \\+ - negation (not)
+
+## Examples
+Find all functions:
+  violation(X) :- node(X, "FUNCTION").
+
+Find unresolved calls:
+  violation(X) :- node(X, "CALL"), \\+ edge(X, _, "CALLS").
+`,
+        types: `
+# Node & Edge Types
+
+## Core Node Types
+- MODULE, FUNCTION, CLASS, METHOD, VARIABLE
+- CALL, IMPORT, EXPORT, PARAMETER
+
+## HTTP/Network
+- http:route, http:request, db:query
+
+## Edge Types
+- CONTAINS, CALLS, DEPENDS_ON
+- ASSIGNED_FROM, INSTANCE_OF, PASSES_ARGUMENT
+`,
+        guarantees: `
+# Code Guarantees
+
+Guarantees are persistent code invariants.
+
+## Create
+Use create_guarantee with a name and Datalog rule.
+
+## Check
+Use check_guarantees to verify all guarantees.
+
+## Example
+Name: no-eval
+Rule: violation(X) :- node(X, "CALL"), attr(X, "name", "eval").
+`,
+    };
+    const content = docs[topic] || docs.overview;
+    return textResult(content.trim());
+}
+// === BUG REPORTING ===
+export async function handleReportIssue(args) {
+    const { title, description, context, labels = ['bug'] } = args;
+    const githubToken = process.env.GITHUB_TOKEN;
+    const repo = 'Disentinel/grafema';
+    // Build issue body
+    const body = `## Description
+${description}
+
+${context ? `## Context\n\`\`\`\n${context}\n\`\`\`\n` : ''}
+## Environment
+- Grafema version: 0.1.0-alpha.1
+- Reported via: MCP tool
+
+---
+*This issue was automatically created via Grafema MCP server.*`;
+    // Try GitHub API if token is available
+    if (githubToken) {
+        try {
+            const response = await fetch(`https://api.github.com/repos/${repo}/issues`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `token ${githubToken}`,
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/vnd.github.v3+json',
+                },
+                body: JSON.stringify({
+                    title,
+                    body,
+                    labels: labels.filter(l => ['bug', 'enhancement', 'documentation', 'question'].includes(l)),
+                }),
+            });
+            if (response.ok) {
+                const issue = await response.json();
+                return textResult(`✅ Issue created successfully!\n\n` +
+                    `**Issue #${issue.number}**: ${issue.html_url}\n\n` +
+                    `Thank you for reporting this issue.`);
+            }
+            else {
+                const error = await response.text();
+                throw new Error(`GitHub API error: ${response.status} - ${error}`);
+            }
+        }
+        catch (error) {
+            // Fall through to manual template if API fails
+            console.error('[report_issue] GitHub API failed:', error);
+        }
+    }
+    // Fallback: return template for manual submission
+    const issueUrl = `https://github.com/${repo}/issues/new`;
+    const encodedTitle = encodeURIComponent(title);
+    const encodedBody = encodeURIComponent(body);
+    const encodedLabels = encodeURIComponent(labels.join(','));
+    const directUrl = `${issueUrl}?title=${encodedTitle}&body=${encodedBody}&labels=${encodedLabels}`;
+    return textResult(`⚠️ GITHUB_TOKEN not configured. Please create the issue manually:\n\n` +
+        `**Quick link** (may truncate long descriptions):\n${directUrl}\n\n` +
+        `**Or copy this template to** ${issueUrl}:\n\n` +
+        `---\n**Title:** ${title}\n\n${body}\n---\n\n` +
+        `To enable automatic issue creation, set GITHUB_TOKEN environment variable.`);
+}