✅ 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

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

{
  "tool": "review_existing_adrs",
  "parameters": {
    "adrDirectory": "./adrs",
    "complianceFramework": "madr",
    "analysisDepth": "standard"
  }
}

Comprehensive ADR Analysis with Code Validation

{
  "tool": "review_existing_adrs",
  "parameters": {
    "adrDirectory": "./adrs",
    "includeTreeSitter": true,
    "complianceFramework": "madr",
    "analysisDepth": "comprehensive",
    "projectPath": ".",
    "generateRecommendations": true,
    "validateImplementation": true,
    "checkConsistency": true
  }
}

Quick Compliance Check

{
  "tool": "review_existing_adrs",
  "parameters": {
    "adrDirectory": "./adrs",
    "complianceFramework": "nygard",
    "analysisDepth": "basic",
    "generateRecommendations": false
  }
}

Response Format

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

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

{
  "tool": "compare_adr_progress",
  "parameters": {
    "todoPath": "TODO.md",
    "adrDirectory": "./adrs",
    "includeMetrics": true
  }
}

Comprehensive Progress Analysis

{
  "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

{
  "tool": "compare_adr_progress",
  "parameters": {
    "adrDirectory": "./adrs",
    "projectPath": ".",
    "trackingMode": "implementations",
    "includeMetrics": true
  }
}

Response Format

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

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

{
  "tool": "deployment_readiness",
  "parameters": {
    "operation": "validate",
    "projectPath": ".",
    "environment": "production"
  }
}

Comprehensive Security Audit

{
  "tool": "deployment_readiness",
  "parameters": {
    "operation": "security_audit",
    "projectPath": ".",
    "environment": "production",
    "securityValidation": true,
    "enableTreeSitterAnalysis": true,
    "complianceValidation": true
  }
}

Performance-Focused Check

{
  "tool": "deployment_readiness",
  "parameters": {
    "operation": "performance_check",
    "projectPath": ".",
    "environment": "production",
    "performanceValidation": true,
    "customChecks": ["memory_usage", "cpu_optimization", "database_queries"]
  }
}

Blocking Issues Only

{
  "tool": "deployment_readiness",
  "parameters": {
    "operation": "validate",
    "projectPath": ".",
    "environment": "production",
    "blockingIssuesOnly": true,
    "securityValidation": true
  }
}

Response Format

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

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

{
  "tool": "validate_adr_bootstrap",
  "parameters": {
    "adrDirectory": "./adrs",
    "complianceFramework": "madr"
  }
}

Comprehensive Bootstrap Analysis

{
  "tool": "validate_adr_bootstrap",
  "parameters": {
    "adrDirectory": "./adrs",
    "complianceFramework": "madr",
    "organizationStandards": "standards/adr-standards.json",
    "enableTreeSitterAnalysis": true,
    "securityValidation": true,
    "templateValidation": true,
    "processValidation": true
  }
}

Response Format

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

# 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

// 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

{
  "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

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

{
  "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 - Project analysis for validation context
• Generation Tools - Content generation with validation
• Security Tools - Security-focused validation
• Troubleshooting - Validation troubleshooting

---

Need help with validation tools? → Deployment Readiness Guide or File an Issue