import { z } from 'zod'; import { FileManager } from '../utils/file-manager.js'; import { RequirementsData } from '../types.js'; import { EARSGenerator } from '../utils/ears-generator.js'; import { VisualFormatter } from '../utils/visual-formatter.js'; const createRequirementsSchema = z.object({ action: z.literal('create'), projectPath: z.string().min(1, 'projectPath is required and must be absolute'), title: z.string().min(1, 'title is required'), description: z.string().min(1, 'description is required'), userStories: z.array(z.string()), functionalRequirements: z.array(z.string()), nonFunctionalRequirements: z.object({ performance: z.array(z.string()).optional(), security: z.array(z.string()).optional(), usability: z.array(z.string()).optional(), reliability: z.array(z.string()).optional() }) }); const createBatchRequirementsSchema = z.object({ action: z.literal('createBatch'), projectPath: z.string().min(1, 'projectPath is required and must be absolute'), requirements: z.array(z.object({ title: z.string(), description: z.string(), userStories: z.array(z.string()), functionalRequirements: z.array(z.string()), nonFunctionalRequirements: z.object({ performance: z.array(z.string()).optional(), security: z.array(z.string()).optional(), usability: z.array(z.string()).optional(), reliability: z.array(z.string()).optional() }) })) }); const updateRequirementsSchema = z.object({ action: z.literal('update'), projectPath: z.string().min(1, 'projectPath is required and must be absolute'), content: z.string().min(1, 'content is required') }); const validateRequirementsSchema = z.object({ action: z.literal('validate'), projectPath: z.string().min(1, 'projectPath is required and must be absolute') }); const enhanceEarsSchema = z.object({ action: z.literal('enhance-ears'), projectPath: z.string().min(1, 'projectPath is required and must be absolute') }); const requirementsSchema = z.union([ createRequirementsSchema, createBatchRequirementsSchema, updateRequirementsSchema, validateRequirementsSchema, enhanceEarsSchema ]); export async function handleSpecRequirements(args: any) { try { const validatedArgs = requirementsSchema.parse(args); const { action, projectPath } = validatedArgs; const fileManager = new FileManager(projectPath); switch (action) { case 'create': { const { title, description, userStories, functionalRequirements, nonFunctionalRequirements } = validatedArgs; const requirementsContent = generateRequirementsFromParams({ title, description, userStories, functionalRequirements, nonFunctionalRequirements: { performance: nonFunctionalRequirements.performance || [], security: nonFunctionalRequirements.security || [], usability: nonFunctionalRequirements.usability || [], reliability: nonFunctionalRequirements.reliability || [] } }); await fileManager.writeFile('requirements.md', requirementsContent); return { content: [{ type: "text", text: `✅ Requirements created successfully!\n\nTitle: ${title}\nDescription: ${description}\nUser Stories: ${userStories.length}\nFunctional Requirements: ${functionalRequirements.length}` }] }; } case 'createBatch': { const { requirements } = validatedArgs; // Combine all requirements into a single file const combinedContent = requirements.map((req, index) => generateRequirementsFromParams(req) ).join('\n\n---\n\n'); await fileManager.writeFile('requirements.md', combinedContent); return { content: [{ type: "text", text: `✅ Batch requirements created successfully!\n\nCombined ${requirements.length} requirement sets into requirements.md` }] }; } case 'update': { const { content } = validatedArgs; await fileManager.writeFile('requirements.md', content); return { content: [{ type: "text", text: `✅ Requirements updated successfully!` }] }; } case 'validate': { try { const content = await fileManager.readFile('requirements.md'); const validation = validateEARSFormat(content); return { content: [{ type: "text", text: validation.isValid ? `✅ Requirements validation passed!\n\nEARS format compliance: ${validation.compliance}%` : `❌ Requirements validation failed!\n\nErrors:\n${validation.errors.join('\n')}` }] }; } catch (error) { return { content: [{ type: "text", text: "❌ No requirements.md file found to validate" }] }; } } case 'enhance-ears': { try { const content = await fileManager.readFile('requirements.md'); // Extract functional requirements from content const functionalRequirements = extractFunctionalRequirements(content); // Generate EARS suggestions const earsSection = EARSGenerator.generateEARSSection(functionalRequirements); // Append EARS section to existing content const enhancedContent = content + '\n\n' + earsSection; // Write back to file await fileManager.writeFile('requirements.md', enhancedContent); return { content: [{ type: "text", text: `✅ EARS suggestions added successfully!\n\nEnhanced ${functionalRequirements.length} requirements with EARS format suggestions.` }] }; } catch (error) { return { content: [{ type: "text", text: "❌ No requirements.md file found to enhance" }] }; } } default: throw new Error(`Unknown action: ${action}`); } } catch (error: any) { return { content: [{ type: "text", text: `❌ Error in spec-requirements: ${error.message}` }] }; } } function generateRequirementsFromParams(params: RequirementsData): string { const { title, description, userStories, functionalRequirements, nonFunctionalRequirements } = params; let result = `# ${title}\n\n`; // Overview section result += VisualFormatter.createBoxHeader('OVERVIEW', '📋') + '\n\n'; result += `${description}\n\n`; // User Stories section result += VisualFormatter.createBoxHeader('USER STORIES', '👥') + '\n\n'; const userStoryItems = userStories.map((story, index) => ({ title: `US-${String(index + 1).padStart(2, '0')}: ${story}`, items: [] })); result += VisualFormatter.createHierarchicalList(userStoryItems) + '\n'; // Functional Requirements section result += VisualFormatter.createBoxHeader('FUNCTIONAL REQUIREMENTS', '⚙️') + '\n\n'; const functionalItems = functionalRequirements.map((req, index) => ({ title: `FR-${String(index + 1).padStart(2, '0')}: ${req}`, items: [] })); result += VisualFormatter.createHierarchicalList(functionalItems) + '\n'; // Non-Functional Requirements section result += VisualFormatter.createBoxHeader('NON-FUNCTIONAL REQUIREMENTS', '🔧') + '\n\n'; const nonFunctionalItems = [ { title: '🚀 Performance', items: nonFunctionalRequirements.performance || ['To be defined'] }, { title: '🔒 Security', items: nonFunctionalRequirements.security || ['To be defined'] }, { title: '📱 Usability', items: nonFunctionalRequirements.usability || ['To be defined'] }, { title: '🛡️ Reliability', items: nonFunctionalRequirements.reliability || ['To be defined'] } ]; result += VisualFormatter.createHierarchicalList(nonFunctionalItems) + '\n'; result += '\n' + VisualFormatter.createSectionSeparator() + '\n'; result += '*Generated using spec-mcp-tools*'; return result; } function extractFunctionalRequirements(content: string): string[] { const lines = content.split('\n'); const requirements: string[] = []; let inFunctionalSection = false; for (const line of lines) { const trimmed = line.trim(); // Check if we're in the functional requirements section if (trimmed.includes('## ⚙️ Functional Requirements') || trimmed.includes('## Functional Requirements')) { inFunctionalSection = true; continue; } // Check if we've moved to another section if (trimmed.startsWith('## ') && !trimmed.includes('Functional Requirements')) { inFunctionalSection = false; continue; } // Extract requirements from functional section if (inFunctionalSection && trimmed.startsWith('- ')) { const requirement = trimmed.substring(2).trim(); if (requirement) { requirements.push(requirement); } } } return requirements; } function validateEARSFormat(content: string): { isValid: boolean; errors: string[]; compliance: number } { const errors: string[] = []; const lines = content.split('\n'); let totalRequirements = 0; let validRequirements = 0; for (const line of lines) { const trimmed = line.trim(); if (trimmed.startsWith('- ')) { totalRequirements++; // Check for EARS patterns if (trimmed.match(/WHEN.*THEN.*SHALL/i) || trimmed.match(/GIVEN.*WHEN.*THEN.*SHALL/i) || trimmed.match(/WHERE.*IF.*THEN.*SHALL/i)) { validRequirements++; } else { errors.push(`Non-EARS format: ${trimmed}`); } } } const compliance = totalRequirements > 0 ? Math.round((validRequirements / totalRequirements) * 100) : 100; return { isValid: errors.length === 0, errors, compliance }; } // Export the tool function export const specRequirementsTool = { name: "spec-requirements", description: "Create and manage requirements.md with EARS format", inputSchema: { type: "object", properties: { action: { type: "string", enum: ["create", "createBatch", "update", "validate", "enhance-ears"], description: "Action: create from parameters, create multiple requirements (batch), update existing, validate format, or enhance with EARS suggestions" }, projectPath: { type: "string", description: "Absolute path to the project directory (must be full path, not relative)" }, title: { type: "string", description: "Requirements title (for single create)" }, description: { type: "string", description: "Project description/introduction (for single create)" }, userStories: { type: "array", items: { type: "string" }, description: "Array of user stories (for single create)" }, functionalRequirements: { type: "array", items: { type: "string" }, description: "Array of functional requirements in EARS format (for single create)" }, nonFunctionalRequirements: { type: "object", description: "Non-functional requirements by category (for single create)", properties: { performance: { type: "array", items: { type: "string" } }, security: { type: "array", items: { type: "string" } }, usability: { type: "array", items: { type: "string" } }, reliability: { type: "array", items: { type: "string" } } } }, requirements: { type: "array", items: { type: "object", properties: { title: { type: "string", description: "Requirements title" }, description: { type: "string", description: "Project description" }, userStories: { type: "array", items: { type: "string" }, description: "User stories" }, functionalRequirements: { type: "array", items: { type: "string" }, description: "Functional requirements" }, nonFunctionalRequirements: { type: "object", description: "Non-functional requirements", properties: { performance: { type: "array", items: { type: "string" } }, security: { type: "array", items: { type: "string" } }, usability: { type: "array", items: { type: "string" } }, reliability: { type: "array", items: { type: "string" } } } } }, required: ["title"] }, description: "Array of requirements to create (for createBatch)" }, content: { type: "string", description: "Updated content (for update)" } }, required: ["action", "projectPath"] }, handler: handleSpecRequirements };