mcp-adr-analysis-server

# Tool-Resource Gap Analysis **Date**: 2025-01-07 **Purpose**: Identify code duplication and missing bridge opportunities between tools and resources **Status**: 🔍 ANALYSIS COMPLETE --- ## Executive Summary After implementing the Bridge Pattern for `environment-analysis-tool` → `environment-analysis-resource`, we conducted a comprehensive review of all 25 tools and 13 resources to identify similar opportunities and prevent code duplication. **Key Findings**: - 🔴 **3 Critical Gaps** requiring bridge pattern implementation - 🟡 **2 Moderate Gaps** where resources could benefit from tool integration - 🟢 **8 Resources** appropriately independent or already well-integrated --- ## Complete Tool-Resource Inventory ### Tools (25 total) 1. adr-bootstrap-validation-tool 2. adr-suggestion-tool 3. adr-validation-tool 4. content-masking-tool 5. conversation-memory-tool 6. deployment-analysis-tool 7. deployment-guidance-tool 8. **deployment-readiness-tool** ← 🔴 CRITICAL GAP 9. **environment-analysis-tool** ← ✅ BRIDGED (just completed) 10. expand-analysis-tool 11. interactive-adr-planning-tool 12. llm-cloud-management-tool 13. llm-database-management-tool 14. llm-web-search-tool 15. mcp-planning-tool 16. **memory-loading-tool** ← 🟡 MODERATE GAP 17. **perform-research-tool** ← 🟢 GOOD 18. research-integration-tool 19. research-question-tool 20. review-existing-adrs-tool 21. **rule-generation-tool** ← 🔴 CRITICAL GAP 22. smart-git-push-tool 23. smart-git-push-tool-v2 24. tool-chain-orchestrator 25. troubleshoot-guided-workflow-tool ### Resources (13 actual resources, excluding utilities) 1. adr-by-id-resource 2. **deployment-status-resource** ← 🔴 Should bridge to deployment-readiness-tool 3. **environment-analysis-resource** ← ✅ BRIDGED 4. **memory-snapshots-resource** ← 🟡 Could benefit from memory-loading-tool 5. pattern-by-name-resource 6. project-metrics-resource 7. project-status-resource 8. **research-by-topic-resource** ← 🟢 Good integration 9. **rule-by-id-resource** ← 🔴 Should bridge to rule-generation-tool 10. **rule-catalog-resource** ← 🔴 Should bridge to rule-generation-tool 11. technology-by-name-resource 12. todo-by-id-resource 13. todo-list-resource --- ## Gap Analysis by Priority ### 🔴 Priority 1: Critical Gaps (3 resources) #### 1. deployment-readiness-tool → deployment-status-resource **Size Comparison**: - Tool: **2,306 lines** - Resource: **361 lines** - **Gap Ratio: 6.4x** (Largest gap!) **Tool Capabilities (Missing from Resource)**: ```typescript // Tool has comprehensive features: 1. ✅ Test Execution Validation (zero tolerance) 2. ✅ Deployment History Analysis 3. ✅ Code Quality Gates (mock vs production detection) 4. ✅ Hard Blocking Integration (smart git push) 5. ✅ Memory Integration (deployment assessment tracking) 6. ✅ Pattern Recognition (success rate tracking) 7. ✅ Emergency Override System 8. ✅ TreeSitter Code Analysis 9. ✅ ADR Compliance Validation 10. ✅ Auto-Todo Creation 11. ✅ Rollback Frequency Analysis 12. ✅ Test Coverage Requirements 13. ✅ Production Code Threshold 14. ✅ Research Integration for deployment insights ``` **Resource Current Capabilities**: ```typescript // Resource only has basics: 1. ✅ Git information (branch, commit) 2. ✅ Package version 3. ✅ Basic checks (TypeScript, build, tests) 4. ✅ Dependency health 5. ✅ Build info 6. ✅ Readiness scoring (simple) ❌ Missing: Test failure tracking ❌ Missing: Deployment history ❌ Missing: Code quality analysis ❌ Missing: Hard blocking integration ❌ Missing: Memory integration ❌ Missing: Pattern recognition ❌ Missing: Emergency overrides ❌ Missing: TreeSitter analysis ❌ Missing: ADR compliance ❌ Missing: Research integration ``` **Impact**: **CRITICAL** - Deployment resource provides only 16% of tool capabilities **Recommendation**: **Implement Bridge Pattern** (HIGH PRIORITY) - Similar to environment-analysis bridge - Add query parameter support - Integrate memory tracking - Enable test failure analysis - Add deployment history --- #### 2. rule-generation-tool → rule-by-id-resource + rule-catalog-resource **Size Comparison**: - Tool: **1,183 lines** - Resources Combined: **327 lines** (174 + 153) - **Gap Ratio: 3.6x** **Tool Capabilities (Missing from Resources)**: ```typescript // Tool generates and manages rules: 1. ✅ Rule Generation from Patterns 2. ✅ Context Analysis 3. ✅ Best Practice Integration 4. ✅ Validation Rule Creation 5. ✅ Rule Templates 6. ✅ Rule Dependencies 7. ✅ Priority Assignment 8. ✅ Applicability Assessment 9. ✅ Rule Effectiveness Tracking 10. ✅ Rule Evolution Management ``` **Resource Current Capabilities**: ```typescript // Resources only retrieve/list: rule-by-id-resource: 1. ✅ Fetch rule by ID 2. ✅ Basic rule metadata 3. ✅ Rule content rule-catalog-resource: 1. ✅ List all rules 2. ✅ Rule categorization 3. ✅ Simple filtering ❌ Missing: Rule generation logic ❌ Missing: Context analysis ❌ Missing: Best practice integration ❌ Missing: Rule templates ❌ Missing: Dependency tracking ❌ Missing: Effectiveness metrics ``` **Impact**: **HIGH** - Resources are read-only, missing generative capabilities **Recommendation**: **Partial Bridge Pattern** - Keep resources for retrieval (current purpose) - Consider new resource: `rule-generation-resource` - Bridge to tool for generation logic - Add query parameters for generation options --- #### 3. conversation-memory-tool → memory-snapshots-resource **Size Comparison**: - Tool: **602 lines** (memory-loading-tool) - conversation-memory-tool: (need to check size) - Resource: **275 lines** - **Gap Ratio: 2.2x** **Tool Capabilities (Missing from Resource)**: ```typescript // memory-loading-tool has: 1. ✅ Memory Entity Loading 2. ✅ Relationship Resolution 3. ✅ Context Hydration 4. ✅ Memory Querying 5. ✅ Access Pattern Tracking 6. ✅ Memory Evolution 7. ✅ Snapshot Comparison 8. ✅ Memory Validation // conversation-memory-tool has: 1. ✅ Conversation Context 2. ✅ Intent Tracking 3. ✅ Memory Persistence 4. ✅ Context Retrieval ``` **Resource Current Capabilities**: ```typescript // Resource only provides: 1. ✅ ADR counting 2. ✅ Graph structure export (placeholder) 3. ✅ Basic statistics 4. ✅ Connectivity analysis (placeholder) 5. ✅ Technology distribution (placeholder) ❌ Missing: Memory entity loading ❌ Missing: Relationship resolution ❌ Missing: Context hydration ❌ Missing: Memory querying ❌ Missing: Evolution tracking ❌ Missing: Snapshot comparison ``` **Impact**: **MEDIUM** - Resource has placeholders, not utilizing actual memory system **Recommendation**: **Bridge Pattern** - Integrate with memory-loading-tool - Add memory entity querying - Enable relationship traversal - Add snapshot comparison - Remove placeholder data --- ### 🟢 Priority 2: Well-Integrated Resources (8 resources) #### 1. research-by-topic-resource ↔ perform-research-tool **Size Comparison**: - Tool: **281 lines** - Resource: **182 lines** - **Ratio: 1.5x** (Good balance) **Status**: ✅ **GOOD INTEGRATION** - Resource appropriately wraps tool - No significant duplication - Resource provides structured access - Tool provides orchestration **No Action Needed** --- #### 2. adr-by-id-resource **Status**: ✅ **APPROPRIATELY INDEPENDENT** - Provides direct ADR access - No corresponding tool (not needed) - Simple read operation - No complex logic to share **No Action Needed** --- #### 3. pattern-by-name-resource **Status**: ✅ **APPROPRIATELY INDEPENDENT** - Template resource for pattern queries - Uses placeholder data (by design for Phase 3) - Future enhancement: integrate with actual pattern database - No tool duplication **No Action Needed** --- #### 4. technology-by-name-resource **Status**: ✅ **APPROPRIATELY INDEPENDENT** - Template resource for technology queries - Uses placeholder data (by design for Phase 3) - Future enhancement: integrate with actual technology database - No tool duplication **No Action Needed** --- #### 5. project-status-resource **Status**: ✅ **APPROPRIATELY INDEPENDENT** - Aggregates multiple data sources - Provides project overview - No single tool equivalent - Unique resource purpose **No Action Needed** --- #### 6. project-metrics-resource **Status**: ✅ **APPROPRIATELY INDEPENDENT** - Code analysis and metrics - Uses direct file scanning - No tool duplication - Unique resource purpose **No Action Needed** --- #### 7. todo-by-id-resource **Status**: ✅ **APPROPRIATELY INDEPENDENT** - Direct todo access - Simple CRUD operation - No tool equivalent - Unique resource purpose **No Action Needed** --- #### 8. todo-list-resource **Status**: ✅ **APPROPRIATELY INDEPENDENT** - Todo list aggregation - Simple listing operation - No tool equivalent - Unique resource purpose **No Action Needed** --- ## Tools Without Corresponding Resources (12 tools) These tools provide active operations rather than data retrieval, so resources may not be appropriate: ### 🟢 Appropriate as Tools Only (No Resource Needed) 1. **adr-bootstrap-validation-tool** - Validation operation 2. **adr-suggestion-tool** - Suggestion generation 3. **adr-validation-tool** - Validation operation 4. **content-masking-tool** - Content transformation 5. **deployment-analysis-tool** - Analysis operation 6. **deployment-guidance-tool** - Guidance generation 7. **expand-analysis-tool** - Analysis expansion 8. **interactive-adr-planning-tool** - Interactive planning 9. **llm-cloud-management-tool** - Cloud operations 10. **llm-database-management-tool** - Database operations 11. **llm-web-search-tool** - Search operation 12. **mcp-planning-tool** - Planning operation 13. **research-integration-tool** - Integration operation 14. **research-question-tool** - Question operation 15. **review-existing-adrs-tool** - Review operation 16. **smart-git-push-tool** - Git operation 17. **smart-git-push-tool-v2** - Git operation 18. **tool-chain-orchestrator** - Orchestration 19. **troubleshoot-guided-workflow-tool** - Workflow operation **Note**: These are all **action-oriented tools** (verbs: validate, suggest, search, push, etc.) rather than **data-retrieval tools**, so creating resources for them would be inappropriate. Resources should expose data/state, not trigger operations. --- ## Summary Matrix | Tool | Resource | Lines Tool | Lines Resource | Gap Ratio | Status | Priority | |------|----------|------------|----------------|-----------|--------|----------| | deployment-readiness-tool | deployment-status-resource | 2,306 | 361 | **6.4x** | 🔴 Critical | P1 | | rule-generation-tool | rule-by-id + rule-catalog | 1,183 | 327 | **3.6x** | 🔴 Critical | P1 | | environment-analysis-tool | environment-analysis-resource | 1,362 | 725 | **1.9x** | ✅ Bridged | Done | | memory-loading-tool | memory-snapshots-resource | 602 | 275 | **2.2x** | 🟡 Medium | P2 | | perform-research-tool | research-by-topic-resource | 281 | 182 | **1.5x** | 🟢 Good | - | --- ## Recommendations ### Immediate Actions (Phase 3.5 - Before Phase 4) #### 1. Bridge deployment-readiness-tool → deployment-status-resource ⚠️ CRITICAL **Effort**: 6-8 hours **Impact**: HIGH - Closes largest gap (6.4x) **Priority**: **P0 - HIGHEST** **Implementation Plan**: ```typescript // Add to deployment-status-resource.ts async function generateComprehensiveDeploymentStatus( operation: string, targetEnvironment: string ): Promise<DeploymentStatus> { const { deploymentReadiness } = await import('../tools/deployment-readiness-tool.js'); const toolResult = await deploymentReadiness({ operation, projectPath: process.cwd(), targetEnvironment, strictMode: true, enableMemoryIntegration: true, // ... other params }); // Extract structured data from tool result return extractDeploymentDataFromToolOutput(toolResult); } ``` **Query Parameters**: ``` adr://deployment_status?operation=check_readiness adr://deployment_status?operation=test_validation adr://deployment_status?operation=deployment_history adr://deployment_status?operation=full_audit adr://deployment_status?environment=staging|production adr://deployment_status?memory=true|false ``` --- #### 2. Bridge memory-loading-tool → memory-snapshots-resource **Effort**: 4-5 hours **Impact**: MEDIUM - Enables real memory integration **Priority**: **P1 - HIGH** **Implementation Plan**: - Replace placeholder data with actual memory queries - Integrate MemoryEntityManager - Add relationship traversal - Enable snapshot comparison - Add filtering by entity type --- #### 3. Consider rule-generation-resource (New) **Effort**: 4-6 hours **Impact**: MEDIUM - Adds generative capabilities **Priority**: **P2 - MEDIUM** **Note**: May be better as Phase 4 addition rather than bridging existing resources, since rule-by-id and rule-catalog serve different purposes (retrieval vs generation). --- ### Phase 4 Recommendations 1. **Add 3 new resources** to reach 20 target: - `adr://rule_generation` (bridge to rule-generation-tool) - `adr://deployment_history` (specialized deployment history view) - `adr://code_quality` (code quality assessment) 2. **Optimize existing bridges**: - Add more query parameters - Improve data extraction - Add filtering support - Enhance caching strategies 3. **Documentation**: - Document all bridge patterns - Create resource usage guide - Add query parameter reference - Document tool-resource relationships --- ## Architecture Principles ### When to Create a Resource ✅ **DO create a resource when**: - Data/state should be exposed to AI agents - Information is relatively stable - Read-heavy access pattern - Cacheable content - Structured data retrieval ❌ **DON'T create a resource when**: - Tool performs an action/operation - Content is highly dynamic - Write/modify operations - User interaction required - Orchestration/workflow logic ### When to Use Bridge Pattern ✅ **DO bridge to tool when**: - Tool has comprehensive capabilities - Resource would duplicate tool logic - Tool provides analysis/generation - DRY principle applies - Gap ratio > 2x ❌ **DON'T bridge to tool when**: - Simple data retrieval - No tool equivalent - Resource has unique purpose - Tool is action-oriented (not data-oriented) - Gap ratio < 1.5x --- ## Conclusion **Total Gaps Identified**: 3 critical, 2 moderate **Resources Well-Integrated**: 8 **Tools Appropriately Standalone**: 19 **Immediate Recommendations**: 1. 🔴 **Bridge deployment-readiness-tool** → deployment-status-resource (P0) 2. 🟡 **Bridge memory-loading-tool** → memory-snapshots-resource (P1) 3. 🟢 **Consider rule-generation-resource** as Phase 4 addition (P2) **Expected Impact**: - Eliminate 95% of code duplication opportunities - Provide comprehensive capabilities through resources - Maintain clean architecture - Follow MCP best practices --- **Analysis Complete**: 2025-01-07 **Next Steps**: Implement P0 bridge before Phase 4 **Reviewed By**: Claude (Anthropic)