Code-Index-MCP

# Architecture Update Summary - January 6, 2025 ## Overview Based on the comprehensive MCP vs Native performance test report, significant updates have been made to the project documentation and architecture to reflect critical issues discovered during testing. ## Key Findings from Performance Testing - **MCP Success Rate**: 17% (7 out of 42 tests) - **Native Success Rate**: 90% (37 out of 41 tests) - **Primary Issue**: 83% of MCP tests failed with "MCP tools not available in Task agent environment" ## Updates Made ### 1. ROADMAP.md Updates - **Added**: New critical priority section "MCP Sub-Agent Configuration Issues" - **Documented**: Performance test results showing 83% failure rate - **Created**: Immediate action items for fixing tool inheritance - **Updated**: Success metrics to include MCP-specific requirements - **Added**: Production recommendations favoring native tools until fixes are complete - **Reprioritized**: MCP infrastructure fixes before multi-repository enhancements ### 2. Structurizr DSL (workspace.dsl) Updates - **Added**: Claude Code internal components showing main agent vs task sub-agents - **Created**: New relationship showing broken MCP tool inheritance (83% failure) - **Added**: Index Discovery component marked as having issues - **Created**: New dynamic view "MCPFailureFlow" demonstrating the failure scenario - **Added**: Styling for broken components and relationships ### 3. New PlantUML Diagrams Created #### a. mcp_sub_agent_architecture.puml - Shows the Task agent spawning process - Documents where tool inheritance breaks - Highlights the 83% failure rate issue - Proposes fixes for configuration passing #### b. mcp_configuration_flow.puml - Documents .mcp.json processing flow - Shows environment variable propagation issues - Illustrates why sub-agents lose MCP access - Includes proposed configuration fixes #### c. index_path_resolution.puml - Maps all possible index locations - Shows priority order for path checking - Documents Docker vs native path issues - Explains why test repositories fail to be found ### 4. Updated PlantUML Diagrams #### enhanced_dispatcher.puml - Added Index Discovery and Path Translator components - Documented current issues from test results - Added performance statistics notes - Shows BM25 bypass success rates ## Alignment with README.md Next Steps The updates properly acknowledge that while the README mentions "Multi-Repository and Smart Plugin Loading Enhancement" as the next priority, the critical MCP infrastructure issues must be resolved first: 1. **First Priority**: Fix MCP sub-agent tool inheritance (blocking 83% of operations) 2. **Second Priority**: Implement robust index discovery across environments 3. **Third Priority**: Then proceed with multi-repository enhancements ## Critical Architecture Changes Documented ### 1. Sub-Agent Tool Inheritance - Problem: Task agents don't inherit MCP configuration - Impact: 83% failure rate in production scenarios - Solution: Pass configuration and environment to sub-agents ### 2. Index Discovery Enhancement - Problem: Indexes only searched in one location - Impact: Test repositories have 0% success rate (Rust) - Solution: Multi-path search with fallback logic ### 3. Path Resolution - Problem: Docker and native environments have different paths - Impact: Indexes created in one environment fail in another - Solution: Path translation and environment detection ### 4. Error Handling - Problem: Generic "tools not available" messages - Impact: Difficult to debug in production - Solution: Detailed error messages with context ## Recommendations Going Forward 1. **Immediate Actions**: - Implement MCP configuration inheritance for sub-agents - Add multi-path index discovery logic - Create pre-flight validation system 2. **Testing Requirements**: - Validate MCP tool availability before operations - Test across Docker and native environments - Ensure cross-environment index portability 3. **Documentation Needs**: - Create troubleshooting guide for MCP issues - Document sub-agent configuration requirements - Provide clear migration path for existing users This comprehensive update ensures the architecture documentation accurately reflects the current state of the system and provides a clear path forward for resolving the critical issues discovered during performance testing.