@specforge/mcp 1.1.0

package/dist/tools/index.js

@@ -0,0 +1,1622 @@
+/**
+ * MCP Tools Registry
+ *
+ * This module defines and exports all available MCP tools.
+ * All operations from Epics 3-10 are registered here with proper JSON Schema definitions.
+ *
+ * Tool categories:
+ * - Core Operations: Project, Specification, Epic, Ticket, Dependency
+ * - Context & AI: Implementation context, actionable tickets, critical path
+ * - Workflow: Work sessions, progress reporting
+ * - Testing: Test results, validation
+ * - Discovery: Report and resolve discoveries
+ * - Status: Status reports, summaries, analytics
+ * - Search: Search, find by file/tag, find related
+ * - Git: Link commits and PRs, get linked items
+ */
+import { ValidationError, ApiError, validateToolArgs, formatMCPError, transformError, } from '../validation/index.js';
+/**
+ * Get list of all available tools
+ *
+ * This returns the tool definitions that will be sent to the AI client
+ * in response to ListTools requests.
+ *
+ * @returns Array of tool definitions
+ */
+export function getTools() {
+    return [
+        // ========================================================================
+        // Core Operations - Projects (Epic 3)
+        // ========================================================================
+        {
+            name: 'list_projects',
+            description: 'List all projects accessible to the current user',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: 'get_project',
+            description: 'Get details of a specific project including summary counts',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    projectId: {
+                        type: 'string',
+                        description: 'The ID of the project to retrieve',
+                    },
+                },
+                required: ['projectId'],
+            },
+        },
+        // ========================================================================
+        // Core Operations - Specifications (Epic 3)
+        // ========================================================================
+        {
+            name: 'list_specifications',
+            description: 'List specifications for a project with optional status filter',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    projectId: {
+                        type: 'string',
+                        description: 'The ID of the project',
+                    },
+                    status: {
+                        type: 'array',
+                        items: {
+                            type: 'string',
+                            enum: ['draft', 'planning', 'ready', 'in_progress', 'completed'],
+                        },
+                        description: 'Filter by status (optional)',
+                    },
+                },
+                required: ['projectId'],
+            },
+        },
+        {
+            name: 'get_specification',
+            description: 'Get full specification with goals, requirements, constraints, and guardrails',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    specificationId: {
+                        type: 'string',
+                        description: 'The ID of the specification to retrieve',
+                    },
+                },
+                required: ['specificationId'],
+            },
+        },
+        // ========================================================================
+        // Core Operations - Epics (Epic 3)
+        // ========================================================================
+        {
+            name: 'list_epics',
+            description: 'List epics for a specification with optional status filter',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    specificationId: {
+                        type: 'string',
+                        description: 'The ID of the specification',
+                    },
+                    status: {
+                        type: 'string',
+                        enum: ['todo', 'in_progress', 'completed'],
+                        description: 'Filter by status (optional)',
+                    },
+                },
+                required: ['specificationId'],
+            },
+        },
+        {
+            name: 'get_epic',
+            description: 'Get epic with scope, goals, acceptance criteria, and ticket summary',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    epicId: {
+                        type: 'string',
+                        description: 'The ID of the epic to retrieve',
+                    },
+                },
+                required: ['epicId'],
+            },
+        },
+        // ========================================================================
+        // Core Operations - Tickets (Epic 3)
+        // ========================================================================
+        {
+            name: 'list_tickets',
+            description: 'List tickets for an epic with optional status filter',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    epicId: {
+                        type: 'string',
+                        description: 'The ID of the epic',
+                    },
+                    status: {
+                        type: 'array',
+                        items: {
+                            type: 'string',
+                            enum: ['todo', 'queue', 'in_progress', 'blocked', 'done'],
+                        },
+                        description: 'Filter by status (optional)',
+                    },
+                },
+                required: ['epicId'],
+            },
+        },
+        {
+            name: 'get_ticket',
+            description: 'Get full ticket details including implementation steps, acceptance criteria, and dependencies',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket to retrieve',
+                    },
+                },
+                required: ['ticketId'],
+            },
+        },
+        // ========================================================================
+        // Core Operations - Dependencies (Epic 3)
+        // ========================================================================
+        {
+            name: 'get_ticket_dependencies',
+            description: 'Get dependency information for a ticket - what it blocks and what blocks it',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                },
+                required: ['ticketId'],
+            },
+        },
+        // ========================================================================
+        // Context & AI Tools (Epic 4)
+        // ========================================================================
+        {
+            name: 'get_implementation_context',
+            description: 'Get full implementation context for a ticket including spec, epic, dependencies, and patterns',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                },
+                required: ['ticketId'],
+            },
+        },
+        {
+            name: 'get_next_actionable_tickets',
+            description: 'Get tickets that can be worked on now (all dependencies satisfied)',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    specificationId: {
+                        type: 'string',
+                        description: 'The ID of the specification',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Maximum number of tickets to return (default: 5)',
+                    },
+                },
+                required: ['specificationId'],
+            },
+        },
+        {
+            name: 'get_blocked_tickets',
+            description: 'Get tickets that are blocked with reasons why',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    specificationId: {
+                        type: 'string',
+                        description: 'The ID of the specification',
+                    },
+                },
+                required: ['specificationId'],
+            },
+        },
+        {
+            name: 'get_critical_path',
+            description: 'Get the critical path (longest dependency chain) for a specification',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    specificationId: {
+                        type: 'string',
+                        description: 'The ID of the specification',
+                    },
+                },
+                required: ['specificationId'],
+            },
+        },
+        {
+            name: 'get_patterns',
+            description: 'Extract tech stack, code patterns, and naming conventions from specification',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    specificationId: {
+                        type: 'string',
+                        description: 'The ID of the specification',
+                    },
+                },
+                required: ['specificationId'],
+            },
+        },
+        // ========================================================================
+        // Workflow & Tracking (Epic 5)
+        // ========================================================================
+        {
+            name: 'start_work_session',
+            description: 'Start working on a ticket - validates dependencies are satisfied',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket to start',
+                    },
+                },
+                required: ['ticketId'],
+            },
+        },
+        {
+            name: 'complete_work_session',
+            description: 'Mark a ticket as complete with summary and results',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                    summary: {
+                        type: 'string',
+                        description: 'Summary of work completed',
+                    },
+                    filesModified: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of files modified',
+                    },
+                    filesCreated: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of files created',
+                    },
+                },
+                required: ['ticketId', 'summary'],
+            },
+        },
+        {
+            name: 'report_progress',
+            description: 'Report incremental progress on a ticket',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                    progress: {
+                        type: 'number',
+                        minimum: 0,
+                        maximum: 100,
+                        description: 'Progress percentage (0-100)',
+                    },
+                    message: {
+                        type: 'string',
+                        description: 'Progress message',
+                    },
+                },
+                required: ['ticketId', 'progress'],
+            },
+        },
+        {
+            name: 'get_work_summary',
+            description: 'Get summary of completed work with optional scope filtering',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    scope: {
+                        type: 'string',
+                        enum: ['epic', 'specification', 'project', 'user'],
+                        description: 'Scope of the summary',
+                    },
+                    scopeId: {
+                        type: 'string',
+                        description: 'ID of the scoped entity (epicId, specificationId, or projectId)',
+                    },
+                    startDate: {
+                        type: 'string',
+                        description: 'Start date filter (ISO 8601)',
+                    },
+                    endDate: {
+                        type: 'string',
+                        description: 'End date filter (ISO 8601)',
+                    },
+                },
+                required: ['scope'],
+            },
+        },
+        // ========================================================================
+        // Testing Tools (Epic 6)
+        // ========================================================================
+        {
+            name: 'report_test_results',
+            description: 'Report test results for a ticket',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                    passed: {
+                        type: 'boolean',
+                        description: 'Whether the tests passed',
+                    },
+                    testType: {
+                        type: 'string',
+                        enum: ['unit', 'integration', 'e2e', 'manual'],
+                        description: 'Type of test',
+                    },
+                    summary: {
+                        type: 'string',
+                        description: 'Summary of test results',
+                    },
+                    output: {
+                        type: 'string',
+                        description: 'Test output (will be truncated if too long)',
+                    },
+                },
+                required: ['ticketId', 'passed', 'testType'],
+            },
+        },
+        {
+            name: 'get_ticket_test_status',
+            description: 'Get test status and history for a ticket',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                },
+                required: ['ticketId'],
+            },
+        },
+        {
+            name: 'validate_ticket_completion',
+            description: 'Validate that a ticket is ready to be marked complete',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                },
+                required: ['ticketId'],
+            },
+        },
+        // ========================================================================
+        // Discovery Tools (Epic 7)
+        // ========================================================================
+        {
+            name: 'report_discovery',
+            description: 'Report a discovery (new requirement, bug, or improvement) found during implementation',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket where discovery was made',
+                    },
+                    type: {
+                        type: 'string',
+                        enum: ['bug', 'requirement', 'improvement', 'question'],
+                        description: 'Type of discovery',
+                    },
+                    title: {
+                        type: 'string',
+                        description: 'Short title for the discovery',
+                    },
+                    description: {
+                        type: 'string',
+                        description: 'Detailed description',
+                    },
+                    priority: {
+                        type: 'string',
+                        enum: ['low', 'medium', 'high', 'critical'],
+                        description: 'Priority level',
+                    },
+                },
+                required: ['ticketId', 'type', 'title'],
+            },
+        },
+        {
+            name: 'get_pending_discoveries',
+            description: 'Get pending discoveries that need resolution',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    specificationId: {
+                        type: 'string',
+                        description: 'Filter by specification (optional)',
+                    },
+                    projectId: {
+                        type: 'string',
+                        description: 'Filter by project (optional)',
+                    },
+                },
+                required: [],
+            },
+        },
+        {
+            name: 'resolve_discovery',
+            description: 'Resolve a discovery as created (new ticket) or dismissed',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    discoveryId: {
+                        type: 'string',
+                        description: 'The ID of the discovery',
+                    },
+                    resolution: {
+                        type: 'string',
+                        enum: ['created', 'dismissed'],
+                        description: 'Resolution type',
+                    },
+                    createdTicketId: {
+                        type: 'string',
+                        description: 'ID of created ticket (if resolution is "created")',
+                    },
+                    notes: {
+                        type: 'string',
+                        description: 'Resolution notes',
+                    },
+                },
+                required: ['discoveryId', 'resolution'],
+            },
+        },
+        // ========================================================================
+        // Status & Analytics Tools (Epic 8)
+        // ========================================================================
+        {
+            name: 'get_specification_status',
+            description: 'Get detailed status for a specification including progress, time tracking, and blockers',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    specificationId: {
+                        type: 'string',
+                        description: 'The ID of the specification',
+                    },
+                },
+                required: ['specificationId'],
+            },
+        },
+        {
+            name: 'get_epic_status',
+            description: 'Get detailed status for an epic including progress and actionable tickets',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    epicId: {
+                        type: 'string',
+                        description: 'The ID of the epic',
+                    },
+                },
+                required: ['epicId'],
+            },
+        },
+        {
+            name: 'get_implementation_summary',
+            description: 'Get cross-specification implementation summary with velocity metrics',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    projectId: {
+                        type: 'string',
+                        description: 'Filter by project (optional)',
+                    },
+                },
+                required: [],
+            },
+        },
+        {
+            name: 'get_time_report',
+            description: 'Get time tracking report with estimated vs actual analysis',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    scope: {
+                        type: 'string',
+                        enum: ['epic', 'specification', 'project'],
+                        description: 'Scope of the report',
+                    },
+                    scopeId: {
+                        type: 'string',
+                        description: 'ID of the scoped entity',
+                    },
+                },
+                required: ['scope', 'scopeId'],
+            },
+        },
+        {
+            name: 'get_blockers_report',
+            description: 'Get report of all blockers with duration and grouping',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    specificationId: {
+                        type: 'string',
+                        description: 'Filter by specification (optional)',
+                    },
+                    projectId: {
+                        type: 'string',
+                        description: 'Filter by project (optional)',
+                    },
+                },
+                required: [],
+            },
+        },
+        // ========================================================================
+        // Search Tools (Epic 9)
+        // ========================================================================
+        {
+            name: 'search_tickets',
+            description: 'Full-text search across tickets with relevance ranking',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: 'Search query',
+                    },
+                    specificationId: {
+                        type: 'string',
+                        description: 'Limit search to specification (optional)',
+                    },
+                    projectId: {
+                        type: 'string',
+                        description: 'Limit search to project (optional)',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Maximum results (default: 20)',
+                    },
+                    offset: {
+                        type: 'number',
+                        description: 'Pagination offset (default: 0)',
+                    },
+                },
+                required: ['query'],
+            },
+        },
+        {
+            name: 'find_tickets_by_file',
+            description: 'Find tickets that modify or create specific files (supports glob patterns)',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    filePath: {
+                        type: 'string',
+                        description: 'File path or glob pattern (e.g., "src/components/*.tsx")',
+                    },
+                    specificationId: {
+                        type: 'string',
+                        description: 'Limit search to specification (optional)',
+                    },
+                    projectId: {
+                        type: 'string',
+                        description: 'Limit search to project (optional)',
+                    },
+                },
+                required: ['filePath'],
+            },
+        },
+        {
+            name: 'find_tickets_by_tag',
+            description: 'Find tickets by tags with AND/OR logic',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Tags to search for',
+                    },
+                    matchAll: {
+                        type: 'boolean',
+                        description: 'If true, match all tags (AND). If false, match any (OR). Default: false',
+                    },
+                    specificationId: {
+                        type: 'string',
+                        description: 'Limit search to specification (optional)',
+                    },
+                    projectId: {
+                        type: 'string',
+                        description: 'Limit search to project (optional)',
+                    },
+                },
+                required: ['tags'],
+            },
+        },
+        {
+            name: 'find_related_tickets',
+            description: 'Find tickets related to a given ticket based on files, tags, and tech stack',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Maximum results (default: 10)',
+                    },
+                },
+                required: ['ticketId'],
+            },
+        },
+        // ========================================================================
+        // Git Integration Tools (Epic 10)
+        // ========================================================================
+        {
+            name: 'link_commit',
+            description: 'Associate a git commit with a ticket',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                    sha: {
+                        type: 'string',
+                        description: 'Full 40-character commit SHA',
+                    },
+                    message: {
+                        type: 'string',
+                        description: 'Commit message',
+                    },
+                    author: {
+                        type: 'string',
+                        description: 'Commit author',
+                    },
+                    repoUrl: {
+                        type: 'string',
+                        description: 'Repository URL for generating commit link',
+                    },
+                },
+                required: ['ticketId', 'sha'],
+            },
+        },
+        {
+            name: 'link_pull_request',
+            description: 'Associate a pull request with a ticket',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                    prNumber: {
+                        type: 'number',
+                        description: 'PR number (provide this or prUrl)',
+                    },
+                    prUrl: {
+                        type: 'string',
+                        description: 'Full PR URL (GitHub, GitLab, or Bitbucket)',
+                    },
+                    title: {
+                        type: 'string',
+                        description: 'PR title',
+                    },
+                    author: {
+                        type: 'string',
+                        description: 'PR author',
+                    },
+                    repoUrl: {
+                        type: 'string',
+                        description: 'Repository URL (required if using prNumber)',
+                    },
+                },
+                required: ['ticketId'],
+            },
+        },
+        {
+            name: 'get_ticket_commits',
+            description: 'Get all commits linked to a ticket',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Maximum results (default: 20)',
+                    },
+                    offset: {
+                        type: 'number',
+                        description: 'Pagination offset (default: 0)',
+                    },
+                },
+                required: ['ticketId'],
+            },
+        },
+        {
+            name: 'get_ticket_prs',
+            description: 'Get all pull requests linked to a ticket',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ticketId: {
+                        type: 'string',
+                        description: 'The ID of the ticket',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Maximum results (default: 20)',
+                    },
+                    offset: {
+                        type: 'number',
+                        description: 'Pagination offset (default: 0)',
+                    },
+                },
+                required: ['ticketId'],
+            },
+        },
+        // ========================================================================
+        // Creation Operations
+        // ========================================================================
+        {
+            name: 'create_specification',
+            description: 'Create a new specification with optional nested epics and tickets for bulk creation',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    projectId: {
+                        type: 'string',
+                        description: 'The ID of the project to create the specification in',
+                    },
+                    title: {
+                        type: 'string',
+                        description: 'Specification title',
+                    },
+                    description: {
+                        type: 'string',
+                        description: 'Brief description (2-3 sentences)',
+                    },
+                    content: {
+                        type: 'string',
+                        description: 'Full markdown content',
+                    },
+                    specificationTypeId: {
+                        type: 'string',
+                        description: 'Specification type ID (uses default if not provided)',
+                    },
+                    background: {
+                        type: 'string',
+                        description: 'Problem context and why this exists',
+                    },
+                    scope: {
+                        type: 'string',
+                        description: "What's in/out of scope",
+                    },
+                    goals: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Business/user/technical objectives',
+                    },
+                    requirements: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Functional requirements',
+                    },
+                    acceptanceCriteria: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Success criteria',
+                    },
+                    techStack: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Technologies to use',
+                    },
+                    priority: {
+                        type: 'string',
+                        enum: ['high', 'medium', 'low'],
+                        description: 'Priority level',
+                    },
+                    tags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Categorization tags',
+                    },
+                    estimatedHours: {
+                        type: 'number',
+                        description: 'Total estimated effort in hours',
+                    },
+                    epics: {
+                        type: 'array',
+                        description: 'Nested epics to create (bulk creation)',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                title: { type: 'string' },
+                                description: { type: 'string' },
+                                objective: { type: 'string' },
+                                tickets: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            title: { type: 'string' },
+                                            description: { type: 'string' },
+                                            acceptanceCriteria: { type: 'array', items: { type: 'string' } },
+                                            estimatedHours: { type: 'number' },
+                                        },
+                                        required: ['title'],
+                                    },
+                                },
+                            },
+                            required: ['title', 'description', 'objective'],
+                        },
+                    },
+                },
+                required: ['projectId', 'title'],
+            },
+        },
+        {
+            name: 'create_epic',
+            description: 'Create a new epic in a specification with optional nested tickets for bulk creation',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    specificationId: {
+                        type: 'string',
+                        description: 'The ID of the specification',
+                    },
+                    title: {
+                        type: 'string',
+                        description: 'Epic title',
+                    },
+                    description: {
+                        type: 'string',
+                        description: 'Detailed description',
+                    },
+                    objective: {
+                        type: 'string',
+                        description: 'What this epic achieves',
+                    },
+                    epicNumber: {
+                        type: 'number',
+                        description: 'Epic number (auto-incremented if not provided)',
+                    },
+                    content: {
+                        type: 'string',
+                        description: 'Full epic content (markdown)',
+                    },
+                    scope: {
+                        type: 'string',
+                        description: "What's in/out of scope for this epic",
+                    },
+                    goals: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Epic-specific goals',
+                    },
+                    acceptanceCriteria: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Epic-level success criteria',
+                    },
+                    priority: {
+                        type: 'string',
+                        enum: ['high', 'medium', 'low'],
+                        description: 'Priority level',
+                    },
+                    tags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Categorization tags',
+                    },
+                    estimatedHours: {
+                        type: 'number',
+                        description: 'Total estimated hours for epic',
+                    },
+                    tickets: {
+                        type: 'array',
+                        description: 'Nested tickets to create (bulk creation)',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                title: { type: 'string' },
+                                description: { type: 'string' },
+                                acceptanceCriteria: { type: 'array', items: { type: 'string' } },
+                                estimatedHours: { type: 'number' },
+                                complexity: { type: 'string', enum: ['small', 'medium', 'large', 'xlarge'] },
+                            },
+                            required: ['title'],
+                        },
+                    },
+                },
+                required: ['specificationId', 'title', 'description', 'objective'],
+            },
+        },
+        {
+            name: 'create_ticket',
+            description: 'Create a new ticket in an epic',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    epicId: {
+                        type: 'string',
+                        description: 'The ID of the epic',
+                    },
+                    title: {
+                        type: 'string',
+                        description: 'Ticket title',
+                    },
+                    ticketNumber: {
+                        type: 'number',
+                        description: 'Ticket number (auto-incremented if not provided)',
+                    },
+                    description: {
+                        type: 'string',
+                        description: 'Ticket description',
+                    },
+                    implementation: {
+                        type: 'object',
+                        description: 'Detailed implementation steps (JSON)',
+                    },
+                    technicalDetails: {
+                        type: 'object',
+                        description: 'Technical details like stack, endpoints (JSON)',
+                    },
+                    acceptanceCriteria: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Success criteria',
+                    },
+                    priority: {
+                        type: 'string',
+                        enum: ['high', 'medium', 'low'],
+                        description: 'Priority level',
+                    },
+                    complexity: {
+                        type: 'string',
+                        enum: ['small', 'medium', 'large', 'xlarge'],
+                        description: 'Size/complexity indicator',
+                    },
+                    tags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Categorization tags',
+                    },
+                    estimatedHours: {
+                        type: 'number',
+                        description: 'Estimated effort in hours',
+                    },
+                    dependsOn: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Array of ticket IDs this ticket depends on',
+                    },
+                },
+                required: ['epicId', 'title'],
+            },
+        },
+        {
+            name: 'import_specification',
+            description: 'Import a markdown file as a complete specification with AI-powered parsing. Parses epics from ## headers and tickets from ### headers.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    projectId: {
+                        type: 'string',
+                        description: 'The ID of the project to import into',
+                    },
+                    content: {
+                        type: 'string',
+                        description: 'Raw markdown content to parse and import',
+                    },
+                    title: {
+                        type: 'string',
+                        description: 'Override the parsed title (optional)',
+                    },
+                    specificationTypeId: {
+                        type: 'string',
+                        description: 'Specification type ID (uses default if not provided)',
+                    },
+                },
+                required: ['projectId', 'content'],
+            },
+        },
+    ];
+}
+/**
+ * Retry configuration for transient failures
+ */
+const RETRY_CONFIG = {
+    maxRetries: 3,
+    initialDelayMs: 500,
+    maxDelayMs: 5000,
+    backoffMultiplier: 2,
+};
+/**
+ * Transient error patterns that should trigger retry
+ */
+const TRANSIENT_ERROR_PATTERNS = [
+    /ETIMEDOUT/i,
+    /ECONNRESET/i,
+    /ECONNREFUSED/i,
+    /socket hang up/i,
+    /network error/i,
+    /too many requests/i,
+    /rate limit/i,
+    /5\d{2}/, // 5xx status codes
+];
+/**
+ * Check if an error is transient and should be retried
+ */
+function isTransientError(error) {
+    return TRANSIENT_ERROR_PATTERNS.some(pattern => pattern.test(error.message));
+}
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Execute a function with retry logic for transient failures
+ */
+async function withRetry(fn, toolName, debug) {
+    let lastError = null;
+    let delay = RETRY_CONFIG.initialDelayMs;
+    for (let attempt = 1; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt < RETRY_CONFIG.maxRetries && isTransientError(lastError)) {
+                if (debug) {
+                    console.error(`[DEBUG] Tool ${toolName} attempt ${attempt} failed with transient error, retrying in ${delay}ms:`, lastError.message);
+                }
+                await sleep(delay);
+                delay = Math.min(delay * RETRY_CONFIG.backoffMultiplier, RETRY_CONFIG.maxDelayMs);
+            }
+            else {
+                break;
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Create tool handlers that call the API with proper request formatting
+ *
+ * Each handler:
+ * - Validates required arguments
+ * - Formats the request for the API
+ * - Parses and transforms the response
+ * - Handles errors appropriately
+ *
+ * @param apiClient - The API client to use for making requests
+ * @returns Record of tool handlers keyed by tool name
+ */
+export function createToolHandlers(apiClient) {
+    return {
+        // ========================================================================
+        // Core Operations - Projects
+        // ========================================================================
+        list_projects: async (_client, _args) => {
+            return await apiClient.call('list_projects', {});
+        },
+        get_project: async (_client, args) => {
+            validateRequired(args, 'projectId');
+            return await apiClient.call('get_project', {
+                projectId: args.projectId,
+            });
+        },
+        // ========================================================================
+        // Core Operations - Specifications
+        // ========================================================================
+        list_specifications: async (_client, args) => {
+            validateRequired(args, 'projectId');
+            return await apiClient.call('list_specifications', {
+                projectId: args.projectId,
+                status: args.status,
+            });
+        },
+        get_specification: async (_client, args) => {
+            validateRequired(args, 'specificationId');
+            return await apiClient.call('get_specification', {
+                specificationId: args.specificationId,
+            });
+        },
+        // ========================================================================
+        // Core Operations - Epics
+        // ========================================================================
+        list_epics: async (_client, args) => {
+            validateRequired(args, 'specificationId');
+            return await apiClient.call('list_epics', {
+                specificationId: args.specificationId,
+                status: args.status,
+            });
+        },
+        get_epic: async (_client, args) => {
+            validateRequired(args, 'epicId');
+            return await apiClient.call('get_epic', {
+                epicId: args.epicId,
+            });
+        },
+        // ========================================================================
+        // Core Operations - Tickets
+        // ========================================================================
+        list_tickets: async (_client, args) => {
+            validateRequired(args, 'epicId');
+            return await apiClient.call('list_tickets', {
+                epicId: args.epicId,
+                status: args.status,
+            });
+        },
+        get_ticket: async (_client, args) => {
+            validateRequired(args, 'ticketId');
+            return await apiClient.call('get_ticket', {
+                ticketId: args.ticketId,
+            });
+        },
+        // ========================================================================
+        // Core Operations - Dependencies
+        // ========================================================================
+        get_ticket_dependencies: async (_client, args) => {
+            validateRequired(args, 'ticketId');
+            return await apiClient.call('get_ticket_dependencies', {
+                ticketId: args.ticketId,
+            });
+        },
+        // ========================================================================
+        // Context & AI Tools
+        // ========================================================================
+        get_implementation_context: async (_client, args) => {
+            validateRequired(args, 'ticketId');
+            return await apiClient.call('get_implementation_context', {
+                ticketId: args.ticketId,
+            });
+        },
+        get_next_actionable_tickets: async (_client, args) => {
+            validateRequired(args, 'specificationId');
+            return await apiClient.call('get_next_actionable_tickets', {
+                specificationId: args.specificationId,
+                limit: args.limit ?? 5,
+            });
+        },
+        get_blocked_tickets: async (_client, args) => {
+            validateRequired(args, 'specificationId');
+            return await apiClient.call('get_blocked_tickets', {
+                specificationId: args.specificationId,
+            });
+        },
+        get_critical_path: async (_client, args) => {
+            validateRequired(args, 'specificationId');
+            return await apiClient.call('get_critical_path', {
+                specificationId: args.specificationId,
+            });
+        },
+        get_patterns: async (_client, args) => {
+            validateRequired(args, 'specificationId');
+            return await apiClient.call('get_patterns', {
+                specificationId: args.specificationId,
+            });
+        },
+        // ========================================================================
+        // Workflow & Tracking
+        // ========================================================================
+        start_work_session: async (_client, args) => {
+            validateRequired(args, 'ticketId');
+            return await apiClient.call('start_work_session', {
+                ticketId: args.ticketId,
+            });
+        },
+        complete_work_session: async (_client, args) => {
+            validateRequired(args, 'ticketId', 'summary');
+            return await apiClient.call('complete_work_session', {
+                ticketId: args.ticketId,
+                summary: args.summary,
+                filesModified: args.filesModified,
+                filesCreated: args.filesCreated,
+            });
+        },
+        report_progress: async (_client, args) => {
+            validateRequired(args, 'ticketId', 'progress');
+            validateRange(args.progress, 'progress', 0, 100);
+            return await apiClient.call('report_progress', {
+                ticketId: args.ticketId,
+                progress: args.progress,
+                message: args.message,
+            });
+        },
+        get_work_summary: async (_client, args) => {
+            validateRequired(args, 'scope');
+            return await apiClient.call('get_work_summary', {
+                scope: args.scope,
+                scopeId: args.scopeId,
+                startDate: args.startDate,
+                endDate: args.endDate,
+            });
+        },
+        // ========================================================================
+        // Testing Tools
+        // ========================================================================
+        report_test_results: async (_client, args) => {
+            validateRequired(args, 'ticketId', 'passed', 'testType');
+            return await apiClient.call('report_test_results', {
+                ticketId: args.ticketId,
+                passed: args.passed,
+                testType: args.testType,
+                summary: args.summary,
+                output: args.output,
+            });
+        },
+        get_ticket_test_status: async (_client, args) => {
+            validateRequired(args, 'ticketId');
+            return await apiClient.call('get_ticket_test_status', {
+                ticketId: args.ticketId,
+            });
+        },
+        validate_ticket_completion: async (_client, args) => {
+            validateRequired(args, 'ticketId');
+            return await apiClient.call('validate_ticket_completion', {
+                ticketId: args.ticketId,
+            });
+        },
+        // ========================================================================
+        // Discovery Tools
+        // ========================================================================
+        report_discovery: async (_client, args) => {
+            validateRequired(args, 'ticketId', 'type', 'title');
+            return await apiClient.call('report_discovery', {
+                ticketId: args.ticketId,
+                type: args.type,
+                title: args.title,
+                description: args.description,
+                priority: args.priority,
+            });
+        },
+        get_pending_discoveries: async (_client, args) => {
+            return await apiClient.call('get_pending_discoveries', {
+                specificationId: args.specificationId,
+                projectId: args.projectId,
+            });
+        },
+        resolve_discovery: async (_client, args) => {
+            validateRequired(args, 'discoveryId', 'resolution');
+            return await apiClient.call('resolve_discovery', {
+                discoveryId: args.discoveryId,
+                resolution: args.resolution,
+                createdTicketId: args.createdTicketId,
+                notes: args.notes,
+            });
+        },
+        // ========================================================================
+        // Status & Analytics Tools
+        // ========================================================================
+        get_specification_status: async (_client, args) => {
+            validateRequired(args, 'specificationId');
+            return await apiClient.call('get_specification_status', {
+                specificationId: args.specificationId,
+            });
+        },
+        get_epic_status: async (_client, args) => {
+            validateRequired(args, 'epicId');
+            return await apiClient.call('get_epic_status', {
+                epicId: args.epicId,
+            });
+        },
+        get_implementation_summary: async (_client, args) => {
+            return await apiClient.call('get_implementation_summary', {
+                projectId: args.projectId,
+            });
+        },
+        get_time_report: async (_client, args) => {
+            validateRequired(args, 'scope', 'scopeId');
+            return await apiClient.call('get_time_report', {
+                scope: args.scope,
+                scopeId: args.scopeId,
+            });
+        },
+        get_blockers_report: async (_client, args) => {
+            return await apiClient.call('get_blockers_report', {
+                specificationId: args.specificationId,
+                projectId: args.projectId,
+            });
+        },
+        // ========================================================================
+        // Search Tools
+        // ========================================================================
+        search_tickets: async (_client, args) => {
+            validateRequired(args, 'query');
+            return await apiClient.call('search_tickets', {
+                query: args.query,
+                specificationId: args.specificationId,
+                projectId: args.projectId,
+                limit: args.limit ?? 20,
+                offset: args.offset ?? 0,
+            });
+        },
+        find_tickets_by_file: async (_client, args) => {
+            validateRequired(args, 'filePath');
+            return await apiClient.call('find_tickets_by_file', {
+                filePath: args.filePath,
+                specificationId: args.specificationId,
+                projectId: args.projectId,
+            });
+        },
+        find_tickets_by_tag: async (_client, args) => {
+            validateRequired(args, 'tags');
+            return await apiClient.call('find_tickets_by_tag', {
+                tags: args.tags,
+                matchAll: args.matchAll ?? false,
+                specificationId: args.specificationId,
+                projectId: args.projectId,
+            });
+        },
+        find_related_tickets: async (_client, args) => {
+            validateRequired(args, 'ticketId');
+            return await apiClient.call('find_related_tickets', {
+                ticketId: args.ticketId,
+                limit: args.limit ?? 10,
+            });
+        },
+        // ========================================================================
+        // Git Integration Tools
+        // ========================================================================
+        link_commit: async (_client, args) => {
+            validateRequired(args, 'ticketId', 'sha');
+            validateSha(args.sha);
+            return await apiClient.call('link_commit', {
+                ticketId: args.ticketId,
+                sha: args.sha,
+                message: args.message,
+                author: args.author,
+                repoUrl: args.repoUrl,
+            });
+        },
+        link_pull_request: async (_client, args) => {
+            validateRequired(args, 'ticketId');
+            if (!args.prNumber && !args.prUrl) {
+                throw new Error('Either prNumber or prUrl must be provided');
+            }
+            return await apiClient.call('link_pull_request', {
+                ticketId: args.ticketId,
+                prNumber: args.prNumber,
+                prUrl: args.prUrl,
+                title: args.title,
+                author: args.author,
+                repoUrl: args.repoUrl,
+            });
+        },
+        get_ticket_commits: async (_client, args) => {
+            validateRequired(args, 'ticketId');
+            return await apiClient.call('get_ticket_commits', {
+                ticketId: args.ticketId,
+                limit: args.limit ?? 20,
+                offset: args.offset ?? 0,
+            });
+        },
+        get_ticket_prs: async (_client, args) => {
+            validateRequired(args, 'ticketId');
+            return await apiClient.call('get_ticket_prs', {
+                ticketId: args.ticketId,
+                limit: args.limit ?? 20,
+                offset: args.offset ?? 0,
+            });
+        },
+        // ========================================================================
+        // Creation Operations
+        // ========================================================================
+        create_specification: async (_client, args) => {
+            validateRequired(args, 'projectId', 'title');
+            return await apiClient.call('create_specification', {
+                projectId: args.projectId,
+                title: args.title,
+                description: args.description,
+                content: args.content,
+                specificationTypeId: args.specificationTypeId,
+                background: args.background,
+                scope: args.scope,
+                goals: args.goals,
+                requirements: args.requirements,
+                acceptanceCriteria: args.acceptanceCriteria,
+                techStack: args.techStack,
+                priority: args.priority,
+                tags: args.tags,
+                estimatedHours: args.estimatedHours,
+                epics: args.epics,
+            });
+        },
+        create_epic: async (_client, args) => {
+            validateRequired(args, 'specificationId', 'title', 'description', 'objective');
+            return await apiClient.call('create_epic', {
+                specificationId: args.specificationId,
+                title: args.title,
+                description: args.description,
+                objective: args.objective,
+                epicNumber: args.epicNumber,
+                content: args.content,
+                scope: args.scope,
+                goals: args.goals,
+                acceptanceCriteria: args.acceptanceCriteria,
+                priority: args.priority,
+                tags: args.tags,
+                estimatedHours: args.estimatedHours,
+                order: args.order,
+                tickets: args.tickets,
+            });
+        },
+        create_ticket: async (_client, args) => {
+            validateRequired(args, 'epicId', 'title');
+            return await apiClient.call('create_ticket', {
+                epicId: args.epicId,
+                title: args.title,
+                ticketNumber: args.ticketNumber,
+                description: args.description,
+                implementation: args.implementation,
+                technicalDetails: args.technicalDetails,
+                acceptanceCriteria: args.acceptanceCriteria,
+                priority: args.priority,
+                complexity: args.complexity,
+                tags: args.tags,
+                estimatedHours: args.estimatedHours,
+                order: args.order,
+                dependsOn: args.dependsOn,
+            });
+        },
+        import_specification: async (_client, args) => {
+            validateRequired(args, 'projectId', 'content');
+            return await apiClient.call('import_specification', {
+                projectId: args.projectId,
+                content: args.content,
+                title: args.title,
+                specificationTypeId: args.specificationTypeId,
+            });
+        },
+    };
+}
+/**
+ * Validate that required arguments are present
+ * @throws Error if any required argument is missing
+ */
+function validateRequired(args, ...required) {
+    for (const field of required) {
+        if (args[field] === undefined || args[field] === null || args[field] === '') {
+            throw new Error(`Missing required argument: ${field}`);
+        }
+    }
+}
+/**
+ * Validate that a number is within a range
+ * @throws Error if the value is out of range
+ */
+function validateRange(value, field, min, max) {
+    if (typeof value !== 'number' || value < min || value > max) {
+        throw new Error(`${field} must be between ${min} and ${max}`);
+    }
+}
+/**
+ * Validate SHA format (40 hexadecimal characters)
+ * @throws Error if the SHA is invalid
+ */
+function validateSha(sha) {
+    if (!/^[0-9a-f]{40}$/i.test(sha)) {
+        throw new Error('sha must be a 40-character hexadecimal string');
+    }
+}
+// Create a cached instance of tool handlers
+let cachedHandlers = null;
+/**
+ * Handle a tool call by routing to the appropriate handler
+ *
+ * @param apiClient - The API client to use for making requests
+ * @param toolName - Name of the tool being called
+ * @param args - Arguments passed to the tool
+ * @param debug - Whether to enable debug logging
+ * @returns Promise resolving to the tool result
+ */
+export async function handleToolCall(apiClient, toolName, args, debug = false) {
+    const startTime = Date.now();
+    // Create handlers if not cached
+    if (!cachedHandlers) {
+        cachedHandlers = createToolHandlers(apiClient);
+    }
+    // Get the handler for this tool
+    const handler = cachedHandlers[toolName];
+    if (!handler) {
+        throw new Error(`Unknown tool: ${toolName}`);
+    }
+    if (debug) {
+        console.error(`[DEBUG] Calling tool: ${toolName}`, {
+            args: JSON.stringify(args),
+        });
+    }
+    try {
+        // Run comprehensive validation before executing
+        validateToolArgs(toolName, args);
+        // Execute with retry logic
+        const result = await withRetry(() => handler(apiClient, args), toolName, debug);
+        const duration = Date.now() - startTime;
+        if (debug) {
+            console.error(`[DEBUG] Tool ${toolName} completed in ${duration}ms`);
+        }
+        return result;
+    }
+    catch (error) {
+        const duration = Date.now() - startTime;
+        // Transform error for proper handling
+        const transformedError = transformError(error);
+        const message = transformedError.message;
+        if (debug) {
+            console.error(`[DEBUG] Tool ${toolName} failed after ${duration}ms:`, message);
+            if (transformedError instanceof ValidationError) {
+                console.error(`[DEBUG] Validation field: ${transformedError.field}, code: ${transformedError.code}`);
+            }
+        }
+        // Rethrow with context
+        if (transformedError instanceof ValidationError) {
+            throw transformedError;
+        }
+        if (transformedError instanceof ApiError) {
+            throw transformedError;
+        }
+        throw new Error(`Tool ${toolName} failed: ${message}`);
+    }
+}
+/**
+ * Handle a tool call and return MCP-formatted response
+ * This wraps handleToolCall with proper error formatting for MCP protocol
+ *
+ * @param apiClient - The API client to use for making requests
+ * @param toolName - Name of the tool being called
+ * @param args - Arguments passed to the tool
+ * @param debug - Whether to enable debug logging
+ * @returns Promise resolving to either the result or an MCP error response
+ */
+export async function handleToolCallSafe(apiClient, toolName, args, debug = false) {
+    try {
+        return await handleToolCall(apiClient, toolName, args, debug);
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        return formatMCPError(err);
+    }
+}
+// Re-export validation utilities for use by other modules
+export { ValidationError, ApiError, validateToolArgs, formatMCPError, transformError, } from '../validation/index.js';
+//# sourceMappingURL=index.js.map