@claudetools/tools 0.1.0

package/dist/handlers/tool-handlers.js

@@ -0,0 +1,1108 @@
+// =============================================================================
+// MCP Tool Execution Handlers
+// =============================================================================
+import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { mcpLogger } from '../logger.js';
+import { getDefaultProjectId, DEFAULT_USER_ID, lastContextUsed, setLastContextUsed } from '../helpers/config.js';
+import { EXPERT_WORKERS, matchTaskToWorker } from '../helpers/workers.js';
+import { searchMemory, addMemory, storeFact, getContext, getSummary, getEntities, injectContext, apiRequest } from '../helpers/api-client.js';
+import { queryDependencies, analyzeImpact } from '../helpers/dependencies.js';
+import { checkPatterns } from '../helpers/patterns.js';
+import { formatContextForClaude } from '../helpers/formatter.js';
+import { createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask, parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, } from '../helpers/tasks.js';
+export function registerToolHandlers(server) {
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        // Resolve project ID - use provided arg, or get default (may throw if not configured)
+        let projectId;
+        try {
+            projectId = args?.project_id || getDefaultProjectId();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Failed to resolve project ID';
+            mcpLogger.error('TOOL', `Project ID resolution failed for ${name}`, error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const timer = mcpLogger.startTimer();
+        // Log tool call
+        mcpLogger.toolCall(name, args || {});
+        try {
+            switch (name) {
+                case 'memory_explain': {
+                    if (!lastContextUsed) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'No memory context was injected in the last response. This could mean:\n- The query did not trigger memory need detection\n- No relevant facts were found\n- Auto-inject is disabled',
+                                },
+                            ],
+                        };
+                    }
+                    const meta = lastContextUsed.metadata;
+                    let explanation = '# Memory Context Explanation\n\n';
+                    explanation += `**Memory Needed:** ${meta.memoryNeeded ? 'Yes' : 'No'}\n`;
+                    explanation += `**Retrieval Time:** ${meta.retrievalTimeMs}ms\n`;
+                    explanation += `**Facts Scored:** ${meta.factsScored}\n`;
+                    explanation += `**Facts Included:** ${meta.factsIncluded}\n`;
+                    explanation += `**Average Relevance:** ${(meta.avgRelevanceScore * 100).toFixed(1)}%\n\n`;
+                    if (lastContextUsed.augmentedSystemPrompt) {
+                        explanation += '## Injected Context\n\n';
+                        explanation += '```\n' + lastContextUsed.augmentedSystemPrompt + '\n```\n';
+                    }
+                    return {
+                        content: [{ type: 'text', text: explanation }],
+                    };
+                }
+                case 'memory_inject': {
+                    const query = args?.query;
+                    const result = await injectContext(projectId, query);
+                    // Store for explain
+                    setLastContextUsed(result);
+                    if (!result.augmentedSystemPrompt) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `No relevant context found for query. Reason: ${result.metadata.reason || 'below threshold'}`,
+                                },
+                            ],
+                        };
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Context injected (${result.metadata.factsIncluded} facts, ${result.metadata.retrievalTimeMs}ms):\n\n${result.augmentedSystemPrompt}`,
+                            },
+                        ],
+                    };
+                }
+                case 'memory_search': {
+                    const query = args?.query;
+                    const limit = args?.limit || 10;
+                    mcpLogger.searchQuery(query, 'hybrid');
+                    const searchTimer = mcpLogger.startTimer();
+                    const context = await searchMemory(projectId, query, limit);
+                    mcpLogger.searchResults(context.relevant_facts.length, context.relevant_entities.length, searchTimer());
+                    mcpLogger.toolResult(name, true, timer(), `${context.relevant_facts.length} facts, ${context.relevant_entities.length} entities`);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: formatContextForClaude(context),
+                            },
+                        ],
+                    };
+                }
+                case 'memory_add': {
+                    const sessionId = args?.session_id;
+                    const messages = args?.messages;
+                    const extractFacts = args?.extract_facts ?? true;
+                    const result = await addMemory(projectId, sessionId, messages, extractFacts);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Added ${result.episode_ids.length} episode(s) to memory.`,
+                            },
+                        ],
+                    };
+                }
+                case 'memory_store_fact': {
+                    const entity1 = args?.entity1;
+                    const relationship = args?.relationship;
+                    const entity2 = args?.entity2;
+                    const context = args?.context;
+                    const result = await storeFact(projectId, entity1, relationship, entity2, context);
+                    mcpLogger.memoryStore(entity1, relationship, entity2);
+                    mcpLogger.toolResult(name, true, timer(), `ID: ${result.fact_id}`);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Stored fact: "${entity1} ${relationship} ${entity2}" (ID: ${result.fact_id})`,
+                            },
+                        ],
+                    };
+                }
+                case 'memory_get_context': {
+                    const query = args?.query;
+                    const context = await getContext(projectId, query);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: formatContextForClaude(context),
+                            },
+                        ],
+                    };
+                }
+                case 'memory_summary': {
+                    const summary = await getSummary(projectId);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: summary,
+                            },
+                        ],
+                    };
+                }
+                case 'memory_list_entities': {
+                    const entities = await getEntities(projectId);
+                    if (entities.length === 0) {
+                        return {
+                            content: [{ type: 'text', text: 'No entities found in memory.' }],
+                        };
+                    }
+                    const formatted = entities
+                        .map((e) => `- **${e.name}** [${e.labels.join(', ')}]`)
+                        .join('\n');
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `## Known Entities\n\n${formatted}`,
+                            },
+                        ],
+                    };
+                }
+                case 'query_dependencies': {
+                    const functionName = args?.function_name;
+                    const direction = args?.direction || 'both';
+                    const depth = args?.depth || 1;
+                    const queryTimer = mcpLogger.startTimer();
+                    const result = await queryDependencies(projectId, functionName, direction, depth);
+                    mcpLogger.queryDependencies(functionName, direction, result.forward.length + result.reverse.length, queryTimer());
+                    let output = `# Dependencies for \`${functionName}\`\n\n`;
+                    if (direction === 'forward' || direction === 'both') {
+                        output += `## Forward Dependencies (What ${functionName} calls)\n\n`;
+                        if (result.forward.length === 0) {
+                            output += `No functions called by \`${functionName}\`\n\n`;
+                        }
+                        else {
+                            result.forward.forEach((dep) => {
+                                output += `- **${dep.function}**\n`;
+                                output += `  - Context: ${dep.context}\n`;
+                            });
+                            output += '\n';
+                        }
+                    }
+                    if (direction === 'reverse' || direction === 'both') {
+                        output += `## Reverse Dependencies (What calls ${functionName})\n\n`;
+                        if (result.reverse.length === 0) {
+                            output += `No functions call \`${functionName}\`\n\n`;
+                        }
+                        else {
+                            result.reverse.forEach((dep) => {
+                                output += `- **${dep.function}**\n`;
+                                output += `  - Context: ${dep.context}\n`;
+                            });
+                            output += '\n';
+                        }
+                    }
+                    output += `\n**Summary:** ${result.forward.length} forward, ${result.reverse.length} reverse dependencies`;
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: output,
+                            },
+                        ],
+                    };
+                }
+                case 'analyze_impact': {
+                    const functionName = args?.function_name;
+                    const analysisType = args?.analysis_type || 'change';
+                    const maxDepth = Math.min(args?.max_depth || 3, 5);
+                    const impactTimer = mcpLogger.startTimer();
+                    const result = await analyzeImpact(projectId, functionName, analysisType, maxDepth);
+                    mcpLogger.impactAnalysis(functionName, analysisType, result.riskLevel, result.totalAffected, impactTimer());
+                    let output = `# Impact Analysis for \`${functionName}\`\n\n`;
+                    output += `**Analysis Type:** ${analysisType}\n`;
+                    output += `**Risk Level:** ${result.riskLevel}\n\n`;
+                    // Direct callers
+                    output += `## Direct Impact (Depth 1)\n\n`;
+                    if (result.directCallers.length === 0) {
+                        output += `No functions directly call \`${functionName}\`\n\n`;
+                    }
+                    else {
+                        output += `Functions that call ${functionName} directly:\n\n`;
+                        result.directCallers.forEach((caller) => {
+                            output += `- **${caller.function}** (${caller.risk} risk)\n`;
+                        });
+                        output += '\n';
+                    }
+                    // Indirect callers
+                    if (result.indirectCallers.length > 0) {
+                        output += `## Indirect Impact (Depth 2+)\n\n`;
+                        output += `Functions affected through call chain:\n\n`;
+                        result.indirectCallers.forEach((caller) => {
+                            output += `- **${caller.function}** (depth ${caller.depth})\n`;
+                            output += `  - Path: ${caller.path.join(' -> ')}\n`;
+                        });
+                        output += '\n';
+                    }
+                    // Summary
+                    output += `## Summary\n\n`;
+                    output += `- **Direct affected:** ${result.directCallers.length} function(s)\n`;
+                    output += `- **Indirect affected:** ${result.indirectCallers.length} function(s)\n`;
+                    output += `- **Total affected:** ${result.totalAffected} function(s)\n`;
+                    output += `- **Risk level:** ${result.riskLevel}\n\n`;
+                    // Recommendations
+                    output += `## Recommendations\n\n`;
+                    result.recommendations.forEach((rec) => {
+                        output += `- ${rec}\n`;
+                    });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: output,
+                            },
+                        ],
+                    };
+                }
+                case 'check_patterns': {
+                    const code = args?.code;
+                    const filePath = args?.file_path;
+                    const checkTypesArg = args?.check_types;
+                    const checkTypes = checkTypesArg?.map(t => t) || ['all'];
+                    const patternTimer = mcpLogger.startTimer();
+                    const result = checkPatterns(code, checkTypes);
+                    mcpLogger.patternCheck(code.length, result.warnings.length, result.securityScore, result.performanceScore, patternTimer());
+                    let output = `# Pattern Analysis\n\n`;
+                    if (filePath) {
+                        output += `**File:** ${filePath}\n`;
+                    }
+                    output += `**Overall Risk:** ${result.overallRisk}\n`;
+                    output += `**Security Score:** ${result.securityScore}/100\n`;
+                    output += `**Performance Score:** ${result.performanceScore}/100\n\n`;
+                    if (result.warnings.length === 0) {
+                        output += `No patterns detected. Code looks clean.\n`;
+                    }
+                    else {
+                        // Group warnings by type
+                        const securityWarnings = result.warnings.filter(w => w.type === 'security');
+                        const performanceWarnings = result.warnings.filter(w => w.type === 'performance');
+                        if (securityWarnings.length > 0) {
+                            output += `## Security Warnings (${securityWarnings.length})\n\n`;
+                            securityWarnings.forEach((w) => {
+                                output += `### ${w.severity}: ${w.pattern}\n`;
+                                if (w.line)
+                                    output += `- **Line:** ${w.line}\n`;
+                                output += `- **Issue:** ${w.description}\n`;
+                                output += `- **Fix:** ${w.recommendation}\n\n`;
+                            });
+                        }
+                        if (performanceWarnings.length > 0) {
+                            output += `## Performance Warnings (${performanceWarnings.length})\n\n`;
+                            performanceWarnings.forEach((w) => {
+                                output += `### ${w.severity}: ${w.pattern}\n`;
+                                if (w.line)
+                                    output += `- **Line:** ${w.line}\n`;
+                                output += `- **Issue:** ${w.description}\n`;
+                                output += `- **Fix:** ${w.recommendation}\n\n`;
+                            });
+                        }
+                    }
+                    output += `---\n`;
+                    output += `**Total Warnings:** ${result.warnings.length}\n`;
+                    output += `**Critical:** ${result.warnings.filter(w => w.severity === 'CRITICAL').length}\n`;
+                    output += `**High:** ${result.warnings.filter(w => w.severity === 'HIGH').length}\n`;
+                    output += `**Medium:** ${result.warnings.filter(w => w.severity === 'MEDIUM').length}\n`;
+                    output += `**Low:** ${result.warnings.filter(w => w.severity === 'LOW').length}\n`;
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: output,
+                            },
+                        ],
+                    };
+                }
+                // =========================================================================
+                // TASK MANAGEMENT TOOL HANDLERS
+                // =========================================================================
+                case 'task_plan_draft': {
+                    // This tool does NOT create anything in the database
+                    // It just formats a plan for user review
+                    const goal = args?.goal;
+                    const epicTitle = args?.epic_title;
+                    const approach = args?.approach;
+                    const context = args?.context;
+                    const tasks = args?.tasks;
+                    const risks = args?.risks;
+                    const questions = args?.questions;
+                    const priority = args?.priority || 'medium';
+                    mcpLogger.toolResult(name, true, timer());
+                    let output = `## Plan: ${epicTitle}\n\n`;
+                    output += `**Goal:** ${goal}\n\n`;
+                    if (context) {
+                        output += `**Context:** ${context}\n\n`;
+                    }
+                    if (approach) {
+                        output += `**Approach:** ${approach}\n\n`;
+                    }
+                    output += `### Tasks\n\n`;
+                    tasks.forEach((t, i) => {
+                        const effort = t.effort ? ` (${t.effort})` : '';
+                        output += `${i + 1}. **${t.title}**${effort}\n`;
+                        if (t.description)
+                            output += `   ${t.description}\n`;
+                        if (t.acceptance_criteria?.length) {
+                            output += `   - Criteria: ${t.acceptance_criteria.join('; ')}\n`;
+                        }
+                        output += '\n';
+                    });
+                    if (risks?.length) {
+                        output += `### Risks\n`;
+                        risks.forEach(r => { output += `- ${r}\n`; });
+                        output += '\n';
+                    }
+                    if (questions?.length) {
+                        output += `### Questions\n`;
+                        questions.forEach(q => { output += `- ${q}\n`; });
+                        output += '\n';
+                    }
+                    output += `---\n`;
+                    output += `Reply **"go"** to commit this plan, or provide feedback to adjust.\n`;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_plan': {
+                    const goal = args?.goal;
+                    const epicTitle = args?.epic_title;
+                    const tasks = args?.tasks;
+                    const priority = args?.priority || 'medium';
+                    // Create the epic first
+                    const epicResult = await createTask(DEFAULT_USER_ID, projectId, {
+                        type: 'epic',
+                        title: epicTitle,
+                        description: goal,
+                        priority,
+                    });
+                    const epic = epicResult.data;
+                    const createdTasks = [];
+                    // Create each task under the epic with worker assignment
+                    for (const taskDef of tasks) {
+                        // Match task to expert worker
+                        const worker = matchTaskToWorker({
+                            title: taskDef.title,
+                            description: taskDef.description,
+                            domain: taskDef.domain,
+                        });
+                        const taskResult = await createTask(DEFAULT_USER_ID, projectId, {
+                            type: 'task',
+                            title: taskDef.title,
+                            description: taskDef.description,
+                            parent_id: epic.id,
+                            priority,
+                            estimated_effort: taskDef.effort,
+                            agent_type: worker.id,
+                            domain: taskDef.domain,
+                        });
+                        createdTasks.push({ task: taskResult.data, worker });
+                    }
+                    mcpLogger.toolResult(name, true, timer());
+                    // Group tasks by worker for parallel dispatch overview
+                    const byWorker = new Map();
+                    for (const item of createdTasks) {
+                        const existing = byWorker.get(item.worker.id) || [];
+                        existing.push(item);
+                        byWorker.set(item.worker.id, existing);
+                    }
+                    let output = `# Work Plan Created\n\n`;
+                    output += `## Epic: ${epic.title}\n`;
+                    output += `**ID:** \`${epic.id}\`\n`;
+                    output += `**Priority:** ${priority}\n\n`;
+                    output += `**Goal:** ${goal}\n\n`;
+                    output += `## Tasks (${createdTasks.length})\n\n`;
+                    createdTasks.forEach((item, i) => {
+                        output += `${i + 1}. **${item.task.title}**\n`;
+                        output += `   - ID: \`${item.task.id}\`\n`;
+                        output += `   - Worker: ${item.worker.name} (\`${item.worker.id}\`)\n`;
+                        if (item.task.estimated_effort)
+                            output += `   - Effort: ${item.task.estimated_effort}\n`;
+                        if (item.task.description)
+                            output += `   - ${item.task.description.slice(0, 100)}${item.task.description.length > 100 ? '...' : ''}\n`;
+                        output += '\n';
+                    });
+                    output += `## Worker Distribution\n\n`;
+                    for (const [workerId, items] of byWorker) {
+                        const worker = EXPERT_WORKERS[workerId];
+                        output += `- **${worker.name}**: ${items.length} task(s)\n`;
+                    }
+                    output += `\n---\n\n`;
+                    output += `## Execution Options\n\n`;
+                    output += `**Sequential:** Use \`task_start\` with each task ID.\n\n`;
+                    output += `**Parallel:** Use \`task_dispatch\` to spawn workers:\n`;
+                    output += `\`\`\`\ntask_dispatch(epic_id="${epic.id}")\n\`\`\`\n`;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_start': {
+                    const taskId = args?.task_id;
+                    const agentId = args?.agent_id || 'claude-code';
+                    // Claim the task
+                    const claimResult = await claimTask(DEFAULT_USER_ID, projectId, taskId, agentId, 60);
+                    // Update status to in_progress
+                    await updateTaskStatus(DEFAULT_USER_ID, projectId, taskId, 'in_progress', agentId);
+                    mcpLogger.toolResult(name, true, timer());
+                    const data = claimResult.data;
+                    let output = `# Starting: ${data.task.title}\n\n`;
+                    output += `**Task ID:** ${taskId}\n`;
+                    output += `**Status:** in_progress\n`;
+                    output += `**Lock expires:** ${data.lock_expires_at}\n\n`;
+                    if (data.task.description) {
+                        output += `## Description\n${data.task.description}\n\n`;
+                    }
+                    const criteria = parseJsonArray(data.task.acceptance_criteria);
+                    if (criteria.length) {
+                        output += `## Acceptance Criteria\n`;
+                        criteria.forEach((c, i) => {
+                            output += `${i + 1}. ${c}\n`;
+                        });
+                        output += '\n';
+                    }
+                    if (data.context?.length) {
+                        output += `## Previous Context\n`;
+                        data.context.forEach((c) => {
+                            output += `### ${c.context_type} (${c.added_by})\n`;
+                            output += `${c.content}\n\n`;
+                        });
+                    }
+                    output += `---\n`;
+                    output += `Use \`task_complete\` when done, or \`task_add_context\` to log progress.\n`;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_complete': {
+                    const taskId = args?.task_id;
+                    const summary = args?.summary;
+                    const agentId = args?.agent_id || 'claude-code';
+                    // Add completion context
+                    await addTaskContext(DEFAULT_USER_ID, projectId, taskId, 'work_log', summary, agentId);
+                    // Release and mark as done
+                    const releaseResult = await releaseTask(DEFAULT_USER_ID, projectId, taskId, agentId, 'done', summary);
+                    const task = releaseResult.data.task;
+                    // Check for newly unblocked tasks (orchestration awareness)
+                    const newlyUnblocked = await resolveTaskDependencies(DEFAULT_USER_ID, projectId, taskId, task.parent_id || undefined);
+                    mcpLogger.toolResult(name, true, timer());
+                    let output = `# Completed: ${task.title}\n\n`;
+                    output += `**Task ID:** \`${taskId}\`\n`;
+                    output += `**Status:** done ✅\n\n`;
+                    output += `## Summary\n${summary}\n\n`;
+                    // Show newly unblocked tasks for orchestration
+                    if (newlyUnblocked.length > 0) {
+                        output += `---\n\n`;
+                        output += `## 🔓 Newly Unblocked Tasks (${newlyUnblocked.length})\n\n`;
+                        for (const unblocked of newlyUnblocked) {
+                            const worker = matchTaskToWorker({
+                                title: unblocked.title,
+                                description: unblocked.description || undefined,
+                                domain: unblocked.domain || undefined,
+                            });
+                            output += `- **${unblocked.title}** (\`${unblocked.id}\`)\n`;
+                            output += `  → Worker: ${worker.name}\n`;
+                        }
+                        output += `\n**Next:** Use \`task_dispatch\` to spawn parallel workers for unblocked tasks.\n`;
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_create': {
+                    const taskType = args?.type;
+                    const title = args?.title;
+                    const description = args?.description;
+                    const parentId = args?.parent_id;
+                    const priority = args?.priority;
+                    const acceptanceCriteria = args?.acceptance_criteria;
+                    const estimatedEffort = args?.estimated_effort;
+                    const tags = args?.tags;
+                    const blockedBy = args?.blocked_by;
+                    const result = await createTask(DEFAULT_USER_ID, projectId, {
+                        type: taskType,
+                        title,
+                        description,
+                        parent_id: parentId,
+                        priority,
+                        acceptance_criteria: acceptanceCriteria,
+                        estimated_effort: estimatedEffort,
+                        tags,
+                        blocked_by: blockedBy,
+                    });
+                    mcpLogger.toolResult(name, true, timer());
+                    const task = result.data;
+                    let output = `# Task Created\n\n`;
+                    output += `**ID:** ${task.id}\n`;
+                    output += `**Type:** ${task.type}\n`;
+                    output += `**Title:** ${task.title}\n`;
+                    output += `**Status:** ${task.status}\n`;
+                    output += `**Priority:** ${task.priority}\n`;
+                    if (task.parent_id)
+                        output += `**Parent:** ${task.parent_id}\n`;
+                    if (task.description)
+                        output += `\n**Description:**\n${task.description}\n`;
+                    const taskCriteria = parseJsonArray(task.acceptance_criteria);
+                    if (taskCriteria.length) {
+                        output += `\n**Acceptance Criteria:**\n`;
+                        taskCriteria.forEach((c, i) => {
+                            output += `${i + 1}. ${c}\n`;
+                        });
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_list': {
+                    const filters = {
+                        type: args?.type,
+                        status: args?.status,
+                        parent_id: args?.parent_id,
+                        assigned_to: args?.assigned_to,
+                        limit: args?.limit,
+                    };
+                    const result = await listTasks(DEFAULT_USER_ID, projectId, filters);
+                    mcpLogger.toolResult(name, true, timer());
+                    const tasks = result.data;
+                    let output = `# Tasks (${tasks.length})\n\n`;
+                    if (tasks.length === 0) {
+                        output += `No tasks found matching the filters.\n`;
+                    }
+                    else {
+                        // Group by type for better organization
+                        const epics = tasks.filter(t => t.type === 'epic');
+                        const regularTasks = tasks.filter(t => t.type === 'task');
+                        const subtasks = tasks.filter(t => t.type === 'subtask');
+                        const formatTask = (t) => {
+                            const statusEmoji = {
+                                backlog: '📋', ready: '🟢', in_progress: '🔄',
+                                blocked: '🚫', review: '👀', done: '✅', cancelled: '❌'
+                            };
+                            const emoji = statusEmoji[t.status] || '📝';
+                            let line = `- ${emoji} **${t.title}** (${t.id.slice(0, 8)}...)`;
+                            line += ` [${t.status}]`;
+                            if (t.priority !== 'medium')
+                                line += ` [${t.priority}]`;
+                            if (t.assigned_to)
+                                line += ` → ${t.assigned_to}`;
+                            return line;
+                        };
+                        if (epics.length > 0) {
+                            output += `## Epics\n`;
+                            epics.forEach(t => { output += formatTask(t) + '\n'; });
+                            output += '\n';
+                        }
+                        if (regularTasks.length > 0) {
+                            output += `## Tasks\n`;
+                            regularTasks.forEach(t => { output += formatTask(t) + '\n'; });
+                            output += '\n';
+                        }
+                        if (subtasks.length > 0) {
+                            output += `## Subtasks\n`;
+                            subtasks.forEach(t => { output += formatTask(t) + '\n'; });
+                        }
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_get': {
+                    const taskId = args?.task_id;
+                    const full = args?.full || false;
+                    const result = await getTask(DEFAULT_USER_ID, projectId, taskId, full);
+                    mcpLogger.toolResult(name, true, timer());
+                    let output = '';
+                    if (full) {
+                        const data = result.data;
+                        const task = data.task;
+                        output = `# ${task.title}\n\n`;
+                        output += `**ID:** ${task.id}\n`;
+                        output += `**Type:** ${task.type}\n`;
+                        output += `**Status:** ${task.status}\n`;
+                        output += `**Priority:** ${task.priority}\n`;
+                        if (task.assigned_to)
+                            output += `**Assigned To:** ${task.assigned_to}\n`;
+                        if (task.estimated_effort)
+                            output += `**Effort:** ${task.estimated_effort}\n`;
+                        const taskTags = parseJsonArray(task.tags);
+                        if (taskTags.length)
+                            output += `**Tags:** ${taskTags.join(', ')}\n`;
+                        if (task.description)
+                            output += `\n**Description:**\n${task.description}\n`;
+                        const fullCriteria = parseJsonArray(task.acceptance_criteria);
+                        if (fullCriteria.length) {
+                            output += `\n## Acceptance Criteria\n`;
+                            fullCriteria.forEach((c, i) => {
+                                output += `${i + 1}. ${c}\n`;
+                            });
+                        }
+                        if (data.parent) {
+                            output += `\n## Parent\n`;
+                            output += `- **${data.parent.title}** (${data.parent.id.slice(0, 8)}...) [${data.parent.status}]\n`;
+                        }
+                        if (data.subtasks?.length) {
+                            output += `\n## Subtasks (${data.subtasks.length})\n`;
+                            data.subtasks.forEach(s => {
+                                output += `- ${s.title} (${s.id.slice(0, 8)}...) [${s.status}]\n`;
+                            });
+                        }
+                        if (data.context?.length) {
+                            output += `\n## Context (${data.context.length})\n`;
+                            data.context.forEach(c => {
+                                output += `### ${c.context_type} (by ${c.added_by})\n`;
+                                output += `${c.content}\n\n`;
+                            });
+                        }
+                    }
+                    else {
+                        const task = result.data;
+                        output = `# ${task.title}\n\n`;
+                        output += `**ID:** ${task.id}\n`;
+                        output += `**Type:** ${task.type}\n`;
+                        output += `**Status:** ${task.status}\n`;
+                        output += `**Priority:** ${task.priority}\n`;
+                        if (task.description)
+                            output += `\n**Description:**\n${task.description}\n`;
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_claim': {
+                    const taskId = args?.task_id;
+                    const agentId = args?.agent_id;
+                    const lockDuration = args?.lock_duration_minutes || 30;
+                    const result = await claimTask(DEFAULT_USER_ID, projectId, taskId, agentId, lockDuration);
+                    mcpLogger.toolResult(name, true, timer());
+                    const data = result.data;
+                    let output = `# Task Claimed\n\n`;
+                    output += `**Task:** ${data.task.title}\n`;
+                    output += `**Claimed:** ${data.claimed ? '✅ Yes' : '❌ No'}\n`;
+                    output += `**Lock Expires:** ${data.lock_expires_at}\n`;
+                    output += `**Agent:** ${agentId}\n`;
+                    if (data.context?.length) {
+                        output += `\n## Previous Context\n`;
+                        data.context.forEach(c => {
+                            output += `### ${c.context_type}\n${c.content}\n\n`;
+                        });
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_release': {
+                    const taskId = args?.task_id;
+                    const agentId = args?.agent_id;
+                    const newStatus = args?.new_status;
+                    const workLog = args?.work_log;
+                    const result = await releaseTask(DEFAULT_USER_ID, projectId, taskId, agentId, newStatus, workLog);
+                    mcpLogger.toolResult(name, true, timer());
+                    const data = result.data;
+                    let output = `# Task Released\n\n`;
+                    output += `**Task:** ${data.task.title}\n`;
+                    output += `**Released:** ${data.released ? '✅ Yes' : '❌ No'}\n`;
+                    output += `**New Status:** ${data.task.status}\n`;
+                    if (workLog)
+                        output += `**Work Log:** ${workLog}\n`;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_update_status': {
+                    const taskId = args?.task_id;
+                    const status = args?.status;
+                    const agentId = args?.agent_id;
+                    const result = await updateTaskStatus(DEFAULT_USER_ID, projectId, taskId, status, agentId);
+                    mcpLogger.toolResult(name, true, timer());
+                    const task = result.data;
+                    let output = `# Status Updated\n\n`;
+                    output += `**Task:** ${task.title}\n`;
+                    output += `**New Status:** ${task.status}\n`;
+                    output += `**Updated At:** ${task.updated_at}\n`;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_add_context': {
+                    const taskId = args?.task_id;
+                    const contextType = args?.context_type;
+                    const content = args?.content;
+                    const addedBy = args?.added_by;
+                    const source = args?.source;
+                    const result = await addTaskContext(DEFAULT_USER_ID, projectId, taskId, contextType, content, addedBy, source);
+                    mcpLogger.toolResult(name, true, timer());
+                    const ctx = result.data;
+                    let output = `# Context Added\n\n`;
+                    output += `**ID:** ${ctx.id}\n`;
+                    output += `**Type:** ${ctx.context_type}\n`;
+                    output += `**Added By:** ${ctx.added_by}\n`;
+                    if (ctx.source)
+                        output += `**Source:** ${ctx.source}\n`;
+                    output += `\n**Content:**\n${ctx.content}\n`;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_summary': {
+                    const result = await getTaskSummary(DEFAULT_USER_ID, projectId);
+                    mcpLogger.toolResult(name, true, timer());
+                    const data = result.data;
+                    let output = `# Task Summary\n\n`;
+                    output += `## By Status\n`;
+                    const statusEmoji = {
+                        backlog: '📋', ready: '🟢', in_progress: '🔄',
+                        blocked: '🚫', review: '👀', done: '✅', cancelled: '❌'
+                    };
+                    Object.entries(data.by_status).forEach(([status, count]) => {
+                        const emoji = statusEmoji[status] || '📝';
+                        output += `- ${emoji} ${status}: **${count}**\n`;
+                    });
+                    output += `\n## By Type\n`;
+                    Object.entries(data.by_type).forEach(([type, count]) => {
+                        output += `- ${type}: **${count}**\n`;
+                    });
+                    output += `\n## Active Agents\n`;
+                    output += `**${data.active_agents}** agent(s) currently working on tasks\n`;
+                    if (data.recent_events?.length) {
+                        output += `\n## Recent Activity\n`;
+                        data.recent_events.slice(0, 5).forEach(e => {
+                            output += `- ${e.event_type}: ${e.task_title} (${new Date(e.created_at).toLocaleString()})\n`;
+                        });
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_heartbeat': {
+                    const taskId = args?.task_id;
+                    const agentId = args?.agent_id;
+                    const extendMinutes = args?.extend_minutes || 30;
+                    const result = await heartbeatTask(DEFAULT_USER_ID, projectId, taskId, agentId, extendMinutes);
+                    mcpLogger.toolResult(name, true, timer());
+                    const data = result.data;
+                    let output = `# Heartbeat\n\n`;
+                    output += `**Extended:** ${data.extended ? '✅ Yes' : '❌ No'}\n`;
+                    output += `**New Expiry:** ${data.new_expires_at}\n`;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                // =========================================================================
+                // ORCHESTRATION HANDLERS
+                // =========================================================================
+                case 'task_dispatch': {
+                    const epicId = args?.epic_id;
+                    const maxParallel = args?.max_parallel || 5;
+                    const dispatchable = await getDispatchableTasks(DEFAULT_USER_ID, projectId, epicId, maxParallel);
+                    mcpLogger.toolResult(name, true, timer());
+                    if (dispatchable.length === 0) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: '# No Tasks Ready for Dispatch\n\nAll tasks are either completed, blocked, or already claimed by other workers.',
+                                }],
+                        };
+                    }
+                    let output = `# Tasks Ready for Dispatch\n\n`;
+                    output += `**Count:** ${dispatchable.length} task(s) ready for parallel execution\n\n`;
+                    for (const item of dispatchable) {
+                        output += `---\n\n`;
+                        output += `## ${item.task.title}\n`;
+                        output += `**Task ID:** \`${item.task.id}\`\n`;
+                        output += `**Worker:** ${item.worker.name} (\`${item.worker.id}\`)\n`;
+                        output += `**Effort:** ${item.task.estimated_effort || 'Not estimated'}\n`;
+                        if (item.task.description) {
+                            output += `**Description:** ${item.task.description.slice(0, 200)}${item.task.description.length > 200 ? '...' : ''}\n`;
+                        }
+                        if (item.parentContext) {
+                            output += `**Epic:** ${item.parentContext.title}\n`;
+                        }
+                        output += `**Capabilities:** ${item.worker.capabilities.join(', ')}\n\n`;
+                    }
+                    output += `---\n\n`;
+                    output += `## Spawning Instructions\n\n`;
+                    output += `Use the Task tool to spawn parallel workers:\n\n`;
+                    output += `\`\`\`\n`;
+                    for (const item of dispatchable) {
+                        output += `Task(subagent_type="${item.worker.id}", prompt="Execute task ${item.task.id}: ${item.task.title}")\n`;
+                    }
+                    output += `\`\`\`\n`;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_execute': {
+                    const taskId = args?.task_id;
+                    const context = await getExecutionContext(DEFAULT_USER_ID, projectId, taskId);
+                    mcpLogger.toolResult(name, true, timer());
+                    let output = `# Execution Context for Worker\n\n`;
+                    output += `**Task:** ${context.task.title}\n`;
+                    output += `**Task ID:** \`${context.task.id}\`\n`;
+                    output += `**Worker Type:** ${context.worker.name} (\`${context.worker.id}\`)\n`;
+                    output += `**Status:** ${context.task.status}\n\n`;
+                    output += `## System Prompt for Worker\n\n`;
+                    output += `\`\`\`\n${context.systemPrompt}\`\`\`\n\n`;
+                    if (context.parentTask) {
+                        output += `## Parent Epic\n`;
+                        output += `- **${context.parentTask.title}** (\`${context.parentTask.id}\`)\n`;
+                        if (context.parentTask.description) {
+                            output += `- ${context.parentTask.description}\n`;
+                        }
+                        output += `\n`;
+                    }
+                    if (context.siblingTasks && context.siblingTasks.length > 0) {
+                        output += `## Sibling Tasks\n`;
+                        for (const sibling of context.siblingTasks) {
+                            const statusEmoji = { done: '✅', in_progress: '🔄', ready: '🟢', blocked: '🚫', backlog: '📋' }[sibling.status] || '📝';
+                            output += `- ${statusEmoji} ${sibling.title} [${sibling.status}]\n`;
+                        }
+                        output += `\n`;
+                    }
+                    output += `## Worker Capabilities\n`;
+                    output += context.worker.capabilities.map(c => `- ${c}`).join('\n') + '\n\n';
+                    output += `## Domain Patterns\n`;
+                    output += context.worker.domains.map(d => `- \`${d}\``).join('\n') + '\n';
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_resolve_dependencies': {
+                    const completedTaskId = args?.completed_task_id;
+                    const epicId = args?.epic_id;
+                    const newlyUnblocked = await resolveTaskDependencies(DEFAULT_USER_ID, projectId, completedTaskId, epicId);
+                    mcpLogger.toolResult(name, true, timer());
+                    if (newlyUnblocked.length === 0) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `# No New Tasks Unblocked\n\nCompletion of task \`${completedTaskId}\` did not unblock any waiting tasks.`,
+                                }],
+                        };
+                    }
+                    let output = `# Newly Unblocked Tasks\n\n`;
+                    output += `Completion of task \`${completedTaskId}\` has unblocked **${newlyUnblocked.length}** task(s):\n\n`;
+                    for (const task of newlyUnblocked) {
+                        const worker = matchTaskToWorker({
+                            title: task.title,
+                            description: task.description || undefined,
+                            domain: task.domain || undefined,
+                        });
+                        output += `- **${task.title}** (\`${task.id}\`) → ${worker.name}\n`;
+                    }
+                    output += `\n## Next Steps\n`;
+                    output += `These tasks are now ready for dispatch. Use \`task_dispatch\` to spawn workers.\n`;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_list_workers': {
+                    mcpLogger.toolResult(name, true, timer());
+                    let output = `# Available Expert Workers\n\n`;
+                    for (const [id, worker] of Object.entries(EXPERT_WORKERS)) {
+                        output += `## ${worker.name}\n`;
+                        output += `**ID:** \`${id}\`\n`;
+                        output += `**Description:** ${worker.description}\n\n`;
+                        output += `**Domain Patterns:**\n`;
+                        output += worker.domains.map(d => `- \`${d}\``).join('\n') + '\n\n';
+                        output += `**Capabilities:**\n`;
+                        output += worker.capabilities.map(c => `- ${c}`).join('\n') + '\n\n';
+                        output += `---\n\n`;
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                // =========================================================================
+                // CODEBASE MAPPING HANDLERS
+                // =========================================================================
+                case 'codebase_map': {
+                    const result = await apiRequest(`/api/v1/codebase/${projectId}/map`);
+                    mcpLogger.toolResult(name, true, timer());
+                    if (!result.success || typeof result === 'object' && 'error' in result) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `# No Codebase Map Found\n\nThe codebase map hasn't been generated yet. Use the file watcher or API to generate one.`,
+                                }],
+                        };
+                    }
+                    // The API returns text/markdown directly
+                    return {
+                        content: [{ type: 'text', text: result }],
+                    };
+                }
+                case 'codebase_find': {
+                    const query = args?.query;
+                    const searchType = args?.type || 'all';
+                    const exported = args?.exported;
+                    const limit = args?.limit || 20;
+                    const params = new URLSearchParams();
+                    params.set('q', query);
+                    params.set('type', searchType);
+                    if (exported !== undefined)
+                        params.set('exported', String(exported));
+                    params.set('limit', String(limit));
+                    const result = await apiRequest(`/api/v1/codebase/${projectId}/search?${params}`);
+                    mcpLogger.toolResult(name, true, timer());
+                    if (!result.success || !result.data) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `# Search Failed\n\nNo codebase index found. Generate a map first.`,
+                                }],
+                        };
+                    }
+                    let output = `# Search Results: "${query}"\n\n`;
+                    output += `Found **${result.data.count}** matches\n\n`;
+                    if (result.data.results.length === 0) {
+                        output += `No results found. Try a different query or check spelling.`;
+                    }
+                    else {
+                        output += `| Type | Name | Location | Context |\n`;
+                        output += `|------|------|----------|----------|\n`;
+                        for (const r of result.data.results) {
+                            const loc = r.line ? `${r.path}:${r.line}` : r.path;
+                            output += `| ${r.type} | ${r.name} | \`${loc}\` | ${r.context || r.role || ''} |\n`;
+                        }
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'codebase_context': {
+                    const target = args?.target;
+                    const result = await apiRequest(`/api/v1/codebase/${projectId}/context/${encodeURIComponent(target)}`);
+                    mcpLogger.toolResult(name, true, timer());
+                    if (!result.success || !result.data) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `# Not Found\n\nTarget "${target}" not found in codebase index.`,
+                                }],
+                        };
+                    }
+                    const data = result.data;
+                    let output = `# Context: ${target}\n\n`;
+                    if (data.file) {
+                        output += `## File Info\n`;
+                        output += `- **Path:** \`${data.file.path}\`\n`;
+                        output += `- **Role:** ${data.file.role}\n`;
+                        output += `- **Lines:** ${data.file.linesOfCode}\n\n`;
+                        if (data.file.symbols.length > 0) {
+                            output += `## Symbols (${data.file.symbols.length})\n`;
+                            for (const s of data.file.symbols.slice(0, 15)) {
+                                output += `- ${s.exported ? '📤' : '📦'} \`${s.name}\` (${s.type}) line ${s.line}\n`;
+                            }
+                            if (data.file.symbols.length > 15) {
+                                output += `- ... and ${data.file.symbols.length - 15} more\n`;
+                            }
+                            output += '\n';
+                        }
+                    }
+                    if (data.symbol) {
+                        output += `## Symbol: ${data.symbol.name}\n`;
+                        for (const loc of data.symbol.locations) {
+                            output += `- ${loc.exported ? '📤' : '📦'} \`${loc.file}:${loc.line}\` (${loc.type})\n`;
+                        }
+                        output += '\n';
+                    }
+                    if (data.callers && data.callers.length > 0) {
+                        output += `## Called By (${data.callers.length})\n`;
+                        output += data.callers.map(c => `- \`${c}\``).join('\n') + '\n\n';
+                    }
+                    if (data.callees && data.callees.length > 0) {
+                        output += `## Calls (${data.callees.length})\n`;
+                        output += data.callees.map(c => `- \`${c}\``).join('\n') + '\n\n';
+                    }
+                    if (data.dependents && data.dependents.length > 0) {
+                        output += `## Imported By (${data.dependents.length})\n`;
+                        output += data.dependents.map(d => `- \`${d}\``).join('\n') + '\n\n';
+                    }
+                    if (data.dependencies && data.dependencies.length > 0) {
+                        output += `## Imports (${data.dependencies.length})\n`;
+                        output += data.dependencies.map(d => `- \`${d}\``).join('\n') + '\n\n';
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'codebase_callgraph': {
+                    const functionName = args?.function_name;
+                    const depth = Math.min(args?.depth || 1, 3);
+                    const result = await apiRequest(`/api/v1/codebase/${projectId}/callgraph/${encodeURIComponent(functionName)}?depth=${depth}`);
+                    mcpLogger.toolResult(name, true, timer());
+                    if (!result.success || !result.data) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `# Call Graph Not Found\n\nFunction "${functionName}" not found in call graph.`,
+                                }],
+                        };
+                    }
+                    const data = result.data;
+                    let output = `# Call Graph: ${functionName}\n\n`;
+                    output += `**Depth:** ${data.depth}\n\n`;
+                    output += `## What ${functionName} Calls\n\n`;
+                    if (Object.keys(data.callees).length === 0) {
+                        output += `No outgoing calls found.\n\n`;
+                    }
+                    else {
+                        for (const [fn, calls] of Object.entries(data.callees)) {
+                            if (calls.length === 0)
+                                continue;
+                            output += `**${fn}** calls:\n`;
+                            output += calls.map(c => `  → ${c}`).join('\n') + '\n\n';
+                        }
+                    }
+                    output += `## What Calls ${functionName}\n\n`;
+                    if (Object.keys(data.callers).length === 0) {
+                        output += `No incoming calls found.\n\n`;
+                    }
+                    else {
+                        for (const [fn, callers] of Object.entries(data.callers)) {
+                            if (callers.length === 0)
+                                continue;
+                            output += `**${fn}** called by:\n`;
+                            output += callers.map(c => `  ← ${c}`).join('\n') + '\n\n';
+                        }
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            mcpLogger.error('TOOL', `${name} failed`, error);
+            mcpLogger.toolResult(name, false, timer());
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------------
+}