mcp-adr-analysis-server

# Getting Started: Workflow & Development Guidance This guide shows you how to use the new **workflow guidance** and **development guidance** tools to get intelligent recommendations for your specific project goals. ## 🎯 Overview The MCP ADR Analysis Server now includes two powerful meta-tools that act as intelligent assistants: - **`get_workflow_guidance`** - Recommends optimal tool sequences based on your goals - **`get_development_guidance`** - Translates architectural decisions into specific coding tasks These tools solve the "tool discovery" problem and ensure you follow best practices to achieve your goals efficiently. ## 🚀 Quick Start ### Step 1: Get Workflow Guidance Start by describing what you want to accomplish: **Tool Call:** ``` get_workflow_guidance ``` **Parameters:** ```json { "goal": "analyze new project and set up architectural documentation", "projectContext": "new_project", "availableAssets": ["codebase"], "timeframe": "thorough_review", "primaryConcerns": ["maintainability", "scalability"] } ``` **What You Get:** - 📋 **Recommended Tool Sequence** - Step-by-step workflow - 🔄 **Alternative Approaches** - Different paths based on constraints - ⏱️ **Timeline Estimates** - Realistic time expectations - 📊 **Success Metrics** - How to measure progress - 💡 **Pro Tips** - Best practices and common pitfalls ### Step 2: Get Development Guidance Once you have architectural decisions, get specific implementation guidance: **Tool Call:** ``` get_development_guidance ``` **Parameters:** ```json { "developmentPhase": "implementation", "adrsToImplement": ["ADR-001: REST API Design", "ADR-002: Database Schema"], "technologyStack": ["TypeScript", "Node.js", "PostgreSQL"], "teamContext": { "size": "small_team", "experienceLevel": "mixed" }, "focusAreas": ["API design", "testing strategy"] } ``` **What You Get:** - 🏗️ **Implementation Roadmap** - Phase-by-phase development plan - 📋 **Specific Coding Tasks** - ADRs translated to actionable tasks - 🧪 **Testing Strategy** - Comprehensive testing approach - 📊 **Quality Gates** - Success criteria and checkpoints - 🚀 **Deployment Guidance** - Environment and deployment strategy ## 📋 Common Scenarios ### Scenario 1: New Project Analysis **Goal**: Analyze a new React TypeScript project and set up architectural documentation. ```json { "goal": "analyze new project and set up architectural documentation", "projectContext": "new_project", "availableAssets": ["codebase"], "timeframe": "thorough_review" } ``` **Expected Workflow**: 1. `analyze_project_ecosystem` → Discover technology stack 2. `get_architectural_context` → Generate architectural insights + ADR setup 3. `suggest_adrs` → Get ADR recommendations 4. `generate_adr_from_decision` → Create specific ADRs 5. `get_development_guidance` → Get implementation roadmap ### Scenario 2: Legacy System Modernization **Goal**: Modernize a legacy codebase with proper architectural documentation. ```json { "goal": "modernize legacy system with architectural documentation", "projectContext": "legacy_codebase", "availableAssets": ["codebase", "documentation"], "timeframe": "comprehensive_audit", "primaryConcerns": ["technical_debt", "maintainability", "security"] } ``` **Expected Workflow**: 1. `analyze_project_ecosystem` → Understand current state 2. `get_architectural_context` → Assess architectural maturity 3. `suggest_adrs` → Identify modernization decisions 4. `generate_rules` → Extract current patterns 5. `get_development_guidance` → Create modernization roadmap ### Scenario 3: Security Audit & Compliance **Goal**: Perform security audit and implement data protection measures. ```json { "goal": "security audit and data protection implementation", "projectContext": "existing_without_adrs", "primaryConcerns": ["security", "compliance"], "timeframe": "comprehensive_audit" } ``` **Expected Workflow**: 1. `analyze_content_security` → Identify sensitive data 2. `generate_content_masking` → Create masking strategy 3. `configure_custom_patterns` → Set up security patterns 4. `validate_content_masking` → Verify protection 5. `get_development_guidance` → Implement security measures ### Scenario 4: PRD to Implementation **Goal**: Convert a Product Requirements Document to a working implementation. ```json { "goal": "convert PRD to implementation plan", "projectContext": "greenfield", "availableAssets": ["PRD.md"], "timeframe": "thorough_review" } ``` **Expected Workflow**: 1. `generate_adrs_from_prd` → Convert PRD to ADRs 2. `generate_adr_todo` (phase: "both", linkAdrs: true) → Create TDD implementation tasks 3. `get_development_guidance` → Get detailed development plan 4. `compare_adr_progress` → Validate implementation quality and detect mock patterns 5. `analyze_deployment_progress` → Track implementation ## 🔧 Development Guidance Deep Dive The `get_development_guidance` tool provides phase-specific guidance: ### Planning Phase ```json { "developmentPhase": "planning", "technologyStack": ["TypeScript", "React", "Node.js"], "teamContext": {"size": "small_team", "experienceLevel": "mixed"} } ``` **Focus**: Project structure, tooling setup, development workflow ### Implementation Phase ```json { "developmentPhase": "implementation", "adrsToImplement": ["ADR-001: API Design"], "focusAreas": ["API design", "database schema"] } ``` **Focus**: Specific coding tasks, design patterns, implementation strategies ### Testing Phase ```json { "developmentPhase": "testing", "focusAreas": ["unit testing", "integration testing", "e2e testing"] } ``` **Focus**: Testing strategies, quality gates, automation setup ### Deployment Phase ```json { "developmentPhase": "deployment", "focusAreas": ["CI/CD pipeline", "environment setup", "monitoring"] } ``` **Focus**: Deployment strategies, environment configuration, monitoring setup ### Validation & Quality Assurance Phase ```json { "developmentPhase": "validation", "focusAreas": ["mock detection", "ADR compliance", "production readiness"] } ``` **Focus**: Implementation validation, mock vs production detection, ADR goal compliance ## 🧪 Enhanced TDD and Validation Workflow The MCP server now includes sophisticated validation capabilities to ensure high-quality implementations: ### New Validation-Focused Scenarios #### Scenario 5: TDD Implementation with Validation **Goal**: Implement ADRs using test-driven development with comprehensive validation. ```json { "goal": "implement ADRs using TDD with quality validation", "projectContext": "existing_with_adrs", "availableAssets": ["codebase", "ADRs"], "timeframe": "thorough_review", "primaryConcerns": ["code_quality", "test_coverage", "production_readiness"] } ``` **Expected Workflow**: 1. `generate_adr_todo` (phase: "test") → Generate test specifications 2. Implement mock tests based on specifications 3. `generate_adr_todo` (phase: "production") → Generate implementation tasks 4. Implement production code to pass tests 5. `compare_adr_progress` (strictMode: true) → Validate against ADR goals and detect mock patterns 6. `get_development_guidance` → Refine implementation based on validation results #### Scenario 6: Quality Assurance and Mock Detection **Goal**: Validate existing implementations and detect mock code masquerading as production. ```json { "goal": "validate implementation quality and detect mock patterns", "projectContext": "existing_with_adrs", "availableAssets": ["codebase", "ADRs", "todo.md"], "primaryConcerns": ["production_readiness", "ADR_compliance"] } ``` **Expected Workflow**: 1. `compare_adr_progress` (deepCodeAnalysis: true) → Comprehensive validation 2. `generate_rules` → Extract architectural rules 3. `validate_rules` → Check rule compliance 4. `get_development_guidance` → Create remediation plan for issues found ### Key Validation Parameters When using workflow guidance, consider these validation-specific parameters: ```json { "validationRequirements": { "mockDetection": true, "adrCompliance": true, "functionalValidation": true, "strictMode": true }, "qualityGates": ["test_coverage", "error_handling", "integration_tests"], "productionCriteria": ["real_database_connections", "proper_error_handling", "input_validation"] } ``` ## 💡 Pro Tips ### 1. Start with Workflow Guidance Always begin with `get_workflow_guidance` to get the optimal tool sequence for your specific situation. ### 2. Be Specific with Goals The more specific your goal description, the better the recommendations: - ❌ "analyze project" - ✅ "analyze React TypeScript project for security vulnerabilities and performance optimization" ### 3. Provide Context Include your team context and constraints for tailored recommendations: ```json { "teamContext": { "size": "solo", "experienceLevel": "junior" }, "timeline": "2 weeks to MVP" } ``` ### 4. Use Focus Areas Specify focus areas to get targeted guidance: ```json { "focusAreas": ["API design", "testing strategy", "deployment pipeline"] } ``` ### 5. Iterate and Refine Use the guidance as a starting point and refine based on your specific findings and constraints. ### 6. Always Validate Implementation Quality Include validation steps in every workflow: ```json { "includeValidation": true, "validationLevel": "strict", "mockDetection": true, "adrCompliance": true } ``` ### 7. Use TDD Approach for New Implementations For new ADR implementations, always use the two-phase TDD approach: - **Phase 1**: Generate test specifications with `generate_adr_todo` (phase: "test") - **Phase 2**: Generate implementation tasks with `generate_adr_todo` (phase: "production") - **Validation**: Use `compare_adr_progress` to ensure production readiness ### 8. Prevent Mock Code in Production Always run `compare_adr_progress` with `strictMode: true` to prevent common issues: - Mock implementations being considered production-ready - Missing error handling and input validation - Inadequate integration testing - Configuration issues that prevent real deployment ## 🎯 Success Metrics Track your progress using the success metrics provided by the tools: - **Immediate Indicators**: Quick wins and early signals - **Progress Milestones**: Key checkpoints in your workflow - **Final Outcomes**: Ultimate success criteria for your goals ## 🔄 Integration with Other Tools The workflow and development guidance tools work seamlessly with all other MCP tools: - **Analysis Tools**: `analyze_project_ecosystem`, `get_architectural_context` - **ADR Tools**: `suggest_adrs`, `generate_adr_from_decision`, `discover_existing_adrs` - **TDD Tools**: `generate_adr_todo` (enhanced with phase-based approach) - **Validation Tools**: `compare_adr_progress`, `generate_rules`, `validate_rules` - **Quality Tools**: `analyze_content_security`, `generate_content_masking` - **Utility Tools**: `check_ai_execution_status`, `manage_cache` ## 🚀 Next Steps 1. **Try the workflow guidance** with your current project 2. **Follow the recommended tool sequence** 3. **Use development guidance** to implement architectural decisions 4. **Track progress** using the provided success metrics 5. **Iterate and improve** based on your results The workflow and development guidance tools transform the MCP server into a complete development lifecycle assistant that guides you from architectural planning all the way through to working code!