mcp-adr-analysis-server

# ✅ Validation Tools Reference **Complete reference for MCP ADR Analysis Server validation, progress tracking, and quality assurance tools.** --- ## 📋 Quick Reference | Tool | Purpose | Key Parameters | Output | | ------------------------ | --------------------------------- | ------------------------------------- | ------------------------------------- | | `review_existing_adrs` | ADR compliance and gap analysis | `adrDirectory`, `complianceFramework` | Compliance scores and recommendations | | `compare_adr_progress` | Track implementation progress | `todoPath`, `adrDirectory` | Progress metrics and status | | `deployment_readiness` | Validate deployment readiness | `operation`, `projectPath` | Readiness assessment and blockers | | `validate_adr_bootstrap` | Validate ADR setup and compliance | `adrDirectory`, `complianceFramework` | Bootstrap validation report | --- ## 📋 review_existing_adrs **Purpose**: Comprehensive analysis of existing ADRs for compliance, completeness, and quality assessment. ### Parameters ```typescript interface ReviewExistingAdrsParams { adrDirectory: string; // Required: Path to ADR directory includeTreeSitter?: boolean; // Enable code analysis for implementation validation complianceFramework?: 'madr' | 'nygard' | 'alexandrian' | 'custom'; analysisDepth?: 'basic' | 'standard' | 'comprehensive'; projectPath?: string; // Project path for code analysis generateRecommendations?: boolean; // Generate improvement recommendations validateImplementation?: boolean; // Check if decisions are implemented checkConsistency?: boolean; // Validate consistency across ADRs } ``` ### Usage Examples #### Basic ADR Review ```json { "tool": "review_existing_adrs", "parameters": { "adrDirectory": "./adrs", "complianceFramework": "madr", "analysisDepth": "standard" } } ``` #### Comprehensive ADR Analysis with Code Validation ```json { "tool": "review_existing_adrs", "parameters": { "adrDirectory": "./adrs", "includeTreeSitter": true, "complianceFramework": "madr", "analysisDepth": "comprehensive", "projectPath": ".", "generateRecommendations": true, "validateImplementation": true, "checkConsistency": true } } ``` #### Quick Compliance Check ```json { "tool": "review_existing_adrs", "parameters": { "adrDirectory": "./adrs", "complianceFramework": "nygard", "analysisDepth": "basic", "generateRecommendations": false } } ``` ### Response Format ```typescript interface AdrReviewAnalysis { summary: { totalAdrs: number; complianceScore: number; // 0-100 overall compliance completenessScore: number; // 0-100 completeness score qualityScore: number; // 0-100 quality score implementationScore?: number; // 0-100 implementation score }; adrAnalysis: Array<{ file: string; title: string; status: string; compliance: { score: number; issues: string[]; recommendations: string[]; missingElements: string[]; }; implementation?: { implemented: boolean; evidence: string[]; gaps: string[]; codeReferences: string[]; }; quality: { readability: number; completeness: number; consistency: number; maintainability: number; }; }>; gaps: { missingDecisions: string[]; undocumentedPatterns: string[]; implementationGaps: string[]; consistencyIssues: string[]; }; recommendations: { newAdrs: string[]; improvements: string[]; processChanges: string[]; toolingEnhancements: string[]; }; trendAnalysis?: { decisionVelocity: number; qualityTrend: 'improving' | 'stable' | 'declining'; commonIssues: string[]; }; } ``` ### Compliance Frameworks #### MADR (Markdown ADR) Framework - **Title**: Clear, descriptive title - **Status**: Current status (proposed, accepted, deprecated, etc.) - **Context**: Background and problem description - **Decision**: The architectural decision made - **Consequences**: Positive and negative outcomes #### Nygard Framework - **Title**: Decision title - **Status**: Decision status - **Context**: Forces and constraints - **Decision**: The decision made - **Consequences**: Results and trade-offs #### Custom Framework - User-defined sections and requirements - Organization-specific compliance rules - Custom validation criteria --- ## 📊 compare_adr_progress **Purpose**: Track and compare implementation progress of architectural decisions against planned tasks. ### Parameters ```typescript interface CompareAdrProgressParams { todoPath?: string; // Path to TODO file adrDirectory: string; // Required: Path to ADR directory projectPath?: string; // Project path for implementation analysis timeframe?: string; // Analysis timeframe (e.g., "last_30_days") includeMetrics?: boolean; // Include detailed metrics generateReport?: boolean; // Generate progress report trackingMode?: 'tasks' | 'implementations' | 'both'; } ``` ### Usage Examples #### Basic Progress Tracking ```json { "tool": "compare_adr_progress", "parameters": { "todoPath": "TODO.md", "adrDirectory": "./adrs", "includeMetrics": true } } ``` #### Comprehensive Progress Analysis ```json { "tool": "compare_adr_progress", "parameters": { "todoPath": "IMPLEMENTATION_TODO.md", "adrDirectory": "./adrs", "projectPath": ".", "timeframe": "last_60_days", "includeMetrics": true, "generateReport": true, "trackingMode": "both" } } ``` #### Implementation-Only Tracking ```json { "tool": "compare_adr_progress", "parameters": { "adrDirectory": "./adrs", "projectPath": ".", "trackingMode": "implementations", "includeMetrics": true } } ``` ### Response Format ```typescript interface AdrProgressComparison { summary: { totalAdrs: number; implementedAdrs: number; inProgressAdrs: number; plannedAdrs: number; overallProgress: number; // 0-100 percentage }; taskProgress: { totalTasks: number; completedTasks: number; inProgressTasks: number; blockedTasks: number; taskCompletionRate: number; }; adrDetails: Array<{ adr: string; status: 'implemented' | 'in_progress' | 'planned' | 'blocked'; progress: number; // 0-100 percentage tasks: Array<{ description: string; status: 'completed' | 'in_progress' | 'pending' | 'blocked'; assignee?: string; dueDate?: string; }>; implementationEvidence: string[]; blockers: string[]; estimatedCompletion?: string; }>; metrics: { velocityTrend: 'increasing' | 'stable' | 'decreasing'; averageImplementationTime: number; // days riskFactors: string[]; recommendations: string[]; }; timeline: { milestones: Array<{ date: string; description: string; status: 'completed' | 'upcoming' | 'at_risk'; }>; projectedCompletion: string; }; } ``` --- ## 🚀 deployment_readiness **Purpose**: Comprehensive validation of deployment readiness including code quality, security, and operational requirements. ### Parameters ```typescript interface DeploymentReadinessParams { operation: 'validate' | 'security_audit' | 'performance_check' | 'compliance_check'; projectPath?: string; // Project path for analysis environment?: 'development' | 'staging' | 'production'; securityValidation?: boolean; // Include security validation performanceValidation?: boolean; // Include performance checks complianceValidation?: boolean; // Include compliance validation enableTreeSitterAnalysis?: boolean; // Enable code analysis customChecks?: string[]; // Custom validation checks blockingIssuesOnly?: boolean; // Only report blocking issues } ``` ### Usage Examples #### Basic Deployment Validation ```json { "tool": "deployment_readiness", "parameters": { "operation": "validate", "projectPath": ".", "environment": "production" } } ``` #### Comprehensive Security Audit ```json { "tool": "deployment_readiness", "parameters": { "operation": "security_audit", "projectPath": ".", "environment": "production", "securityValidation": true, "enableTreeSitterAnalysis": true, "complianceValidation": true } } ``` #### Performance-Focused Check ```json { "tool": "deployment_readiness", "parameters": { "operation": "performance_check", "projectPath": ".", "environment": "production", "performanceValidation": true, "customChecks": ["memory_usage", "cpu_optimization", "database_queries"] } } ``` #### Blocking Issues Only ```json { "tool": "deployment_readiness", "parameters": { "operation": "validate", "projectPath": ".", "environment": "production", "blockingIssuesOnly": true, "securityValidation": true } } ``` ### Response Format ```typescript interface DeploymentReadinessResponse { readinessScore: number; // 0-100 overall readiness isReady: boolean; // Ready for deployment environment: string; validation: { security: { score: number; issues: Array<{ severity: 'low' | 'medium' | 'high' | 'critical'; description: string; recommendation: string; blocking: boolean; }>; passed: boolean; }; performance: { score: number; metrics: { loadTime: number; memoryUsage: number; cpuUsage: number; }; issues: string[]; passed: boolean; }; compliance: { score: number; frameworks: Record<string, boolean>; violations: string[]; passed: boolean; }; codeQuality: { score: number; coverage: number; complexity: number; issues: string[]; passed: boolean; }; }; blockers: Array<{ category: string; description: string; severity: 'high' | 'critical'; resolution: string; estimatedEffort: string; }>; recommendations: { immediate: string[]; shortTerm: string[]; longTerm: string[]; }; deployment: { estimatedRisk: 'low' | 'medium' | 'high' | 'critical'; recommendedActions: string[]; rollbackPlan: string[]; }; } ``` --- ## 🔧 validate_adr_bootstrap **Purpose**: Validate ADR setup, structure, and compliance with organizational standards. ### Parameters ```typescript interface ValidateAdrBootstrapParams { adrDirectory: string; // Required: Path to ADR directory complianceFramework?: 'madr' | 'nygard' | 'custom'; organizationStandards?: string; // Path to organization standards enableTreeSitterAnalysis?: boolean; // Enable code analysis securityValidation?: boolean; // Include security validation templateValidation?: boolean; // Validate ADR templates processValidation?: boolean; // Validate ADR process compliance } ``` ### Usage Examples #### Basic Bootstrap Validation ```json { "tool": "validate_adr_bootstrap", "parameters": { "adrDirectory": "./adrs", "complianceFramework": "madr" } } ``` #### Comprehensive Bootstrap Analysis ```json { "tool": "validate_adr_bootstrap", "parameters": { "adrDirectory": "./adrs", "complianceFramework": "madr", "organizationStandards": "standards/adr-standards.json", "enableTreeSitterAnalysis": true, "securityValidation": true, "templateValidation": true, "processValidation": true } } ``` ### Response Format ```typescript interface AdrBootstrapValidation { isValid: boolean; validationScore: number; // 0-100 overall score structure: { directoryExists: boolean; templateExists: boolean; indexExists: boolean; namingConvention: boolean; organizationCompliant: boolean; }; templates: { valid: boolean; framework: string; completeness: number; issues: string[]; }; process: { workflowDefined: boolean; reviewProcess: boolean; approvalProcess: boolean; stakeholderMapping: boolean; }; security: { accessControls: boolean; sensitiveDataHandling: boolean; auditTrail: boolean; }; recommendations: { setup: string[]; process: string[]; tooling: string[]; training: string[]; }; nextSteps: string[]; } ``` --- ## 🔄 Advanced Validation Workflows ### Continuous Validation Pipeline ```yaml # Continuous ADR validation workflow validation_pipeline: triggers: - adr_changes - code_changes - scheduled_weekly stages: - name: 'adr_review' tool: 'review_existing_adrs' config: analysisDepth: 'comprehensive' includeTreeSitter: true - name: 'progress_tracking' tool: 'compare_adr_progress' config: includeMetrics: true trackingMode: 'both' - name: 'deployment_readiness' tool: 'deployment_readiness' config: operation: 'validate' securityValidation: true - name: 'bootstrap_validation' tool: 'validate_adr_bootstrap' config: processValidation: true ``` ### Quality Gates Integration ```typescript // Quality gate configuration interface QualityGate { name: string; threshold: number; blocking: boolean; tool: string; parameters: Record<string, any>; } const qualityGates: QualityGate[] = [ { name: 'ADR Compliance', threshold: 80, blocking: true, tool: 'review_existing_adrs', parameters: { complianceFramework: 'madr', analysisDepth: 'comprehensive', }, }, { name: 'Implementation Progress', threshold: 70, blocking: false, tool: 'compare_adr_progress', parameters: { trackingMode: 'implementations', }, }, { name: 'Deployment Readiness', threshold: 90, blocking: true, tool: 'deployment_readiness', parameters: { operation: 'validate', securityValidation: true, }, }, ]; ``` ### Automated Reporting ```json { "reporting_config": { "frequency": "weekly", "recipients": ["architecture-team", "engineering-leads"], "format": "dashboard", "metrics": [ "adr_compliance_trend", "implementation_velocity", "deployment_readiness_score", "quality_gate_status" ], "alerts": { "compliance_drop": "immediate", "blocked_deployments": "immediate", "quality_gate_failures": "daily_digest" } } } ``` --- ## 📈 Validation Metrics and Analytics ### Key Performance Indicators ```typescript interface ValidationKPIs { adrQuality: { averageComplianceScore: number; qualityTrend: 'improving' | 'stable' | 'declining'; completenessRate: number; }; implementationVelocity: { averageImplementationTime: number; // days velocityTrend: 'increasing' | 'stable' | 'decreasing'; blockerFrequency: number; }; deploymentReadiness: { averageReadinessScore: number; deploymentSuccessRate: number; criticalIssueFrequency: number; }; processMaturity: { bootstrapComplianceScore: number; processAdherence: number; toolingEffectiveness: number; }; } ``` ### Trend Analysis ```json { "trend_analysis": { "timeframe": "last_6_months", "metrics": { "adr_creation_rate": { "current": 2.5, "previous": 1.8, "trend": "increasing" }, "compliance_score": { "current": 85, "previous": 78, "trend": "improving" }, "implementation_rate": { "current": 72, "previous": 68, "trend": "stable" } } } } ``` --- ## 🔗 Related Documentation - **[Analysis Tools](analysis-tools.md)** - Project analysis for validation context - **[Generation Tools](generation-tools.md)** - Content generation with validation - **[Security Tools](security-tools.md)** - Security-focused validation - **[Troubleshooting](.../how-to-guides/troubleshooting.md)** - Validation troubleshooting --- **Need help with validation tools?** → **[Deployment Readiness Guide](.../how-to-guides/deployment-readiness.md)** or **[File an Issue](https://github.com/tosin2013/mcp-adr-analysis-server/issues)**