mcp-github-project-manager

Instructions

Implementation Reference

• src/infrastructure/tools/ai-tasks/CreateTraceabilityMatrixTool.ts:40-115 (handler)

  The primary handler function that executes the tool's core logic: creates mock PRD, converts tasks, calls RequirementsTraceabilityService.createTraceabilityMatrix, validates completeness, and formats the output.

  async function executeCreateTraceabilityMatrix(args: CreateTraceabilityMatrixArgs): Promise<MCPResponse> {
    const traceabilityService = new RequirementsTraceabilityService();
  
    try {
      // Create mock PRD from content
      const mockPRD = {
        id: `prd-${args.projectId}`,
        title: `PRD for ${args.projectId}`,
        overview: args.prdContent.substring(0, 500),
        objectives: extractObjectivesFromContent(args.prdContent),
        successMetrics: extractSuccessMetricsFromContent(args.prdContent),
        features: args.features,
        author: 'system',
        createdAt: new Date().toISOString(),
        updatedAt: new Date().toISOString(),
        aiGenerated: true,
        aiMetadata: {
          generatedBy: 'create-traceability-matrix',
          generatedAt: new Date().toISOString(),
          prompt: 'Extract PRD elements for traceability matrix',
          confidence: 0.8,
          version: '1.0.0'
        }
      };
  
      // Convert input tasks to AITask format
      const aiTasks = args.tasks.map(task => ({
        ...task,
        priority: task.priority as TaskPriority,
        complexity: task.complexity as TaskComplexity,
        status: TaskStatus.PENDING,
        dependencies: [],
        acceptanceCriteria: [],
        tags: [],
        aiGenerated: true,
        subtasks: [],
        createdAt: new Date().toISOString(),
        updatedAt: new Date().toISOString()
      }));
  
      // Create comprehensive traceability matrix
      const traceabilityMatrix = traceabilityService.createTraceabilityMatrix(
        args.projectId,
        mockPRD as any,
        args.features as any,
        aiTasks
      );
  
      // Validate completeness if requested
      let validation;
      if (args.validateCompleteness) {
        validation = validateTraceabilityCompleteness(traceabilityMatrix);
      }
  
      // Format response
      const summary = formatTraceabilityMatrixSummary(traceabilityMatrix, validation, args);
  
      return ToolResultFormatter.formatSuccess('create_traceability_matrix', {
        summary,
        traceabilityMatrix,
        validation,
        coverage: traceabilityMatrix.coverage,
        totalRequirements: traceabilityMatrix.businessRequirements.length,
        totalFeatures: traceabilityMatrix.features.length,
        totalUseCases: traceabilityMatrix.useCases.length,
        totalTasks: traceabilityMatrix.tasks.length
      });
  
    } catch (error) {
      process.stderr.write(`Error in create_traceability_matrix tool: ${error}\n`);
      return ToolResultFormatter.formatSuccess('create_traceability_matrix', {
        error: `Failed to create traceability matrix: ${error instanceof Error ? error.message : 'Unknown error'}`,
        success: false
      });
    }
  }

• src/infrastructure/tools/ai-tasks/CreateTraceabilityMatrixTool.ts:9-33 (schema)

  Zod schema defining the input structure and validation for the create_traceability_matrix tool, including projectId, prdContent, features, tasks, and various boolean flags.

  const createTraceabilityMatrixSchema = z.object({
    projectId: z.string().describe('ID of the project to create traceability matrix for'),
    prdContent: z.string().min(100).describe('PRD content to extract business requirements from'),
    features: z.array(z.object({
      id: z.string(),
      title: z.string(),
      description: z.string(),
      priority: z.enum(['critical', 'high', 'medium', 'low']),
      userStories: z.array(z.string()),
      acceptanceCriteria: z.array(z.string()),
      estimatedComplexity: z.number().min(1).max(10)
    })).describe('List of features to include in traceability'),
    tasks: z.array(z.object({
      id: z.string(),
      title: z.string(),
      description: z.string(),
      complexity: z.number().min(1).max(10),
      estimatedHours: z.number(),
      priority: z.enum(['critical', 'high', 'medium', 'low'])
    })).describe('List of tasks to include in traceability'),
    includeUseCases: z.boolean().default(true).describe('Whether to generate use cases from features'),
    includeTraceabilityLinks: z.boolean().default(true).describe('Whether to generate traceability links'),
    includeCoverageAnalysis: z.boolean().default(true).describe('Whether to include coverage analysis'),
    validateCompleteness: z.boolean().default(true).describe('Whether to validate traceability completeness')
  });

• src/infrastructure/tools/ToolRegistry.ts:276-276 (registration)

  Registration of the createTraceabilityMatrixTool in the central ToolRegistry singleton during initialization of built-in AI task management tools.

  this.registerTool(createTraceabilityMatrixTool);

• src/index.ts:462-463 (registration)

  Dispatch case in the main MCP server tool handler switch statement that routes calls to the create_traceability_matrix tool to its execution function.

  case "create_traceability_matrix":
    return await executeCreateTraceabilityMatrix(args);

• src/services/RequirementsTraceabilityService.ts:283-326 (helper)

  Core helper method in RequirementsTraceabilityService that builds the traceability matrix by extracting requirements from PRD, generating use cases, enhancing tasks with traceability info, creating links, and calculating coverage metrics.

  createTraceabilityMatrix(
    projectId: string,
    prd: PRDDocument,
    features: FeatureRequirement[],
    tasks: AITask[]
  ): TraceabilityMatrix {
    // Extract business requirements from PRD
    const businessRequirements = this.extractBusinessRequirementsFromPRD(prd);
  
    // Generate use cases from features
    const useCases = features.flatMap(feature =>
      this.generateUseCasesFromFeature(feature, businessRequirements)
    );
  
    // Enhance tasks with traceability
    const enhancedTasks = this.enhanceTasksWithTraceability(
      tasks, useCases, features, businessRequirements, prd.id
    );
  
    // Create traceability links
    const traceabilityLinks = this.generateTraceabilityLinks(
      businessRequirements, features, useCases, enhancedTasks
    );
  
    // Calculate coverage
    const coverage = this.calculateCoverage(
      businessRequirements, features, useCases, enhancedTasks
    );
  
    return {
      id: `tm-${projectId}-${Date.now()}`,
      projectId,
      prdId: prd.id,
      businessRequirements,
      features: features as EnhancedFeatureRequirement[], // Type assertion for now
      useCases,
      tasks: enhancedTasks,
      traceabilityLinks,
      coverage,
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      version: '1.0.0'
    };
  }