mcp-adr-analysis-server

# Validated Patterns Implementation Guide ## Overview This document describes the implementation of Validated Patterns for consistent, reproducible deployments across multiple platforms. The system was created to address inconsistencies in bootstrap tools by adopting industry best practices from OpenShift, Kubernetes, Docker, Node.js, Python, MCP, and A2A ecosystems. ## Architecture ### Core Components 1. **Pattern Definitions** (`src/utils/validated-pattern-definitions.ts`) - Comprehensive patterns for 7 platform types - Each pattern includes: - Bill of Materials (dependencies, configurations, secrets, infrastructure) - Deployment phases with commands and validation - Health checks and monitoring - Environment-specific overrides - Metadata and references 2. **Platform Detection** (`src/utils/platform-detector.ts`) - Automatic detection of platform types - Confidence scoring based on project files - Evidence collection and recommendations - Support for multi-platform (hybrid) projects 3. **Pattern Memory System** (Integrated with Memory Entity Manager) - Stores applied patterns for reuse - Tracks deployment history and learnings - Enables pattern evolution based on real-world experience ## Supported Platforms ### 1. OpenShift Validated Pattern **Source**: https://play.validatedpatterns.io/ **Key Features**: - GitOps-based deployment with ArgoCD - Hierarchical values system (global → cluster group → application) - Helm chart integration - HashiCorp Vault for secrets management **Detection Indicators**: - `.openshift/` directory - `openshift-gitops-operator` references - `oc` CLI commands ### 2. Kubernetes Deployment Pattern **Source**: Kubernetes Best Practices 2025 **Key Features**: - Declarative YAML manifests - Rolling update and blue/green strategies - Helm charts for templating - Liveness and readiness probes **Detection Indicators**: - `k8s/` or `kubernetes/` directories - `kustomization.yaml` - `kubectl` commands - Kubernetes resource kinds (Deployment, Service, etc.) ### 3. Docker Containerization Pattern **Source**: Docker Best Practices **Key Features**: - Multi-stage builds for optimization - Non-root user execution - Read-only filesystems - Security scanning with `docker scan` - Layer caching optimization **Detection Indicators**: - `Dockerfile` - `docker-compose.yml` - `.dockerignore` ### 4. Node.js Application Pattern **Source**: Node.js Deployment Best Practices **Key Features**: - npm/yarn/pnpm package management - PM2 process management - Environment-specific configurations - Health endpoints **Detection Indicators**: - `package.json` - `node_modules/` - `ecosystem.config.js` (PM2) ### 5. Python Application Pattern **Source**: Python Packaging User Guide **Key Features**: - Virtual environment isolation - pip/pipenv/poetry dependency management - Gunicorn/Uvicorn WSGI/ASGI servers - Containerization support **Detection Indicators**: - `requirements.txt` - `setup.py` - `pyproject.toml` - `Pipfile` ### 6. Model Context Protocol (MCP) Server Pattern **Source**: MCP Best Practices **Key Features**: - STDIO and HTTP transport support - Tool/Resource/Prompt definitions - Schema validation with MCP Inspector - Security best practices (HTTPS, OAuth) - Docker packaging **Detection Indicators**: - `@modelcontextprotocol/sdk` dependency - MCP server implementation patterns - Tool/resource registration ### 7. Agent-to-Agent (A2A) Protocol Pattern **Source**: A2A Protocol Specification (Linux Foundation) **Key Features**: - Agent capability discovery via "Agent Card" - OAuth 2.0 authentication - Task-oriented communication - Multi-modal support (audio, video) - JSON-RPC 2.0 over HTTPS **Detection Indicators**: - `@a2aproject/sdk` dependency - `agent-card.json` - A2A protocol references ## Pattern Structure Each validated pattern follows this consistent structure: ```typescript interface ValidatedPattern { // Identification id: string; name: string; version: string; platformType: PlatformType; // Bill of Materials billOfMaterials: { dependencies: Dependency[]; configurations: Configuration[]; secrets: SecretRequirement[]; infrastructure: InfrastructureRequirement[]; }; // Deployment Lifecycle deploymentPhases: DeploymentPhase[]; // Validation validationChecks: ValidationCheck[]; healthChecks: HealthCheck[]; // Environment Overrides environmentOverrides: EnvironmentOverride[]; // Metadata metadata: { source: string; lastUpdated: string; maintainer: string; tags: string[]; references: string[]; }; } ``` ## How It Works ### 1. Platform Detection ```typescript import { detectPlatforms } from './src/utils/platform-detector.js'; const result = await detectPlatforms('/path/to/project'); // Result includes: // - detectedPlatforms: Array of platforms with confidence scores // - primaryPlatform: The most confident platform type // - confidence: Overall detection confidence (0-1) // - evidence: Files and patterns that led to detection // - recommendations: Suggested next steps ``` ### 2. Pattern Selection ```typescript import { getPattern } from './src/utils/validated-pattern-definitions.js'; const pattern = getPattern(result.primaryPlatform); // Pattern contains: // - All dependencies required // - Configuration files needed // - Deployment phases to execute // - Validation checks to run // - Environment-specific overrides ``` ### 3. Pattern Application The pattern application framework (to be integrated with existing bootstrap system): 1. **Validates Prerequisites**: Checks that all required dependencies are installed 2. **Creates Configuration Files**: Generates missing configuration files from templates 3. **Executes Deployment Phases**: Runs commands in proper order 4. **Validates Results**: Runs validation checks after deployment 5. **Monitors Health**: Sets up health checks for ongoing monitoring 6. **Stores Pattern in Memory**: Saves for future reuse ### 4. Memory-Based Consistency The system uses the Memory Entity Manager to: - **Store Applied Patterns**: Track which patterns were used for each project - **Learn from Deployments**: Capture successes and failures - **Evolve Patterns**: Update patterns based on real-world experience - **Provide Recommendations**: Suggest patterns based on similar projects ## Integration with Bootstrap Validation Loop The validated patterns system integrates with the existing `BootstrapValidationLoop`: 1. **Pattern Detection Phase**: Before generating bootstrap scripts, detect platform type 2. **Pattern-Based Script Generation**: Use pattern's deployment phases to generate scripts 3. **Pattern-Specific Validation**: Apply pattern's validation checks 4. **Pattern Learning**: Store deployment learnings back to pattern memory ## Benefits ### Consistency - Same deployment approach every time for a given platform - No more guessing or ad-hoc scripts ### Reproducibility - Patterns are versioned and documented - Can recreate deployments from pattern definitions ### Best Practices - Based on industry-standard approaches - Regularly updated with latest recommendations ### Multi-Platform Support - Single system handles 7+ platform types - Hybrid patterns for multi-platform projects ### Self-Learning - Patterns evolve based on deployment experience - Memory system captures institutional knowledge ## Next Steps 1. **Complete Pattern Application Framework**: Implement the framework that applies patterns 2. **Integrate with Bootstrap System**: Update `bootstrap-validation-loop-tool.ts` to use patterns 3. **Add Pattern Memory Persistence**: Extend memory system to store pattern applications 4. **Create Pattern CLI**: Add CLI commands for pattern management 5. **Document Pattern Customization**: Guide for creating custom patterns ## Research Sources This implementation is based on research from: ### OpenShift - https://play.validatedpatterns.io/vp-workshop/main/5_validatedpatterns/creatingPatterns.html ### Kubernetes - https://kubernetes.io/docs/concepts/configuration/overview/ - https://komodor.com/learn/14-kubernetes-best-practices-you-must-know-in-2025/ - https://www.groundcover.com/blog/kubernetes-deployment-strategies ### Docker - https://docs.docker.com/build/building/best-practices/ - https://www.sysdig.com/learn-cloud-native/dockerfile-best-practices - https://betterstack.com/community/guides/scaling-docker/docker-build-best-practices/ ### Node.js - https://www.apriorit.com/dev-blog/how-to-build-microservices-with-node-js - https://blog.logrocket.com/building-microservices-node-js/ - https://www.harness.io/blog/how-to-build-and-deploy-a-node-js-microservice-with-harness ### Python - https://packaging.python.org/en/latest/discussions/deploying-python-applications/ - https://www.fullstackpython.com/deployment.html - https://www.aiamigos.org/python-deployment-best-practices-a-comprehensive-guide/ ### MCP - https://modelcontextprotocol.info/docs/best-practices/ - https://github.com/cyanheads/model-context-protocol-resources/blob/main/guides/mcp-server-development-guide.md - https://www.marktechpost.com/2025/07/23/7-mcp-server-best-practices-for-scalable-ai-integrations-in-2025/ ### A2A - https://a2aprotocol.ai/ - https://github.com/a2aproject/A2A - https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project - https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/ ## Contributing To add a new platform pattern: 1. Research industry best practices for the platform 2. Define the pattern in `validated-pattern-definitions.ts` 3. Add detection indicators in `platform-detector.ts` 4. Document the pattern in this guide 5. Test with real projects 6. Submit for review ## Conclusion The Validated Patterns system provides a consistent, reproducible, and self-learning approach to deployment across multiple platforms. By following industry best practices and maintaining pattern memory, the system ensures deployments are reliable and evolve over time.