SACL MCP Server

# 📋 SACL Enhancement Implementation Plan ## 🎯 **Objective** Transform SACL MCP Server from file-watching based updates to explicit agent-controlled updates, while adding comprehensive code relationship analysis for context-aware retrieval. ## 🚀 **Overview of Changes** ### **Problems to Solve:** 1. ❌ FileWatcher doesn't work reliably in Docker containers 2. ❌ Missing code relationship analysis (imports, inheritance, calls) 3. ❌ Query results lack contextual information about related components 4. ❌ No explicit update mechanism for AI agents ### **Solutions to Implement:** 1. ✅ Replace FileWatcher with explicit agent-controlled updates 2. ✅ Add comprehensive relationship analysis and storage 3. ✅ Enhance query results with related component context 4. ✅ Add new MCP tools for file updates and relationship queries --- ## 🔄 **Phase 1: Remove FileWatcher & Design Explicit Updates** **Status: ✅ COMPLETED** **Duration: 1-2 days** **Priority: HIGH** ### **1.1 Files to Modify** - [x] `src/core/SACLProcessor.ts` - Remove file watching setup - [x] `src/utils/FileWatcher.ts` - Delete entire file - [x] `src/mcp/SACLMCPServer.ts` - Remove FileWatcher references - [x] `package.json` - Remove chokidar dependency ### **1.2 Architecture Changes** - [x] Remove `private fileWatcher?: FileWatcher` from SACLProcessor - [x] Remove `setupFileWatching()` method - [x] Remove `handleFileChange()` method - [x] Remove file watching from `initialize()` method - [x] Update cleanup to not stop file watcher ### **1.3 New Update Architecture Design** ```typescript // New workflow: AI Agent modifies code → Calls update_file() → SACL re-analyzes → Updates graph // Methods added: - updateFile(filePath: string, changeType: 'created'|'modified'|'deleted') - updateFiles(files: FileUpdate[]) - validateFilePath(filePath: string) ``` ### **1.4 Acceptance Criteria** - [x] No references to FileWatcher in codebase - [x] Server starts without file watching - [x] Docker container runs without file monitoring - [x] Prepared for explicit update methods --- ## 🔗 **Phase 2: Design Code Relationship Analysis System** **Status: ✅ COMPLETED** **Duration: 2-3 days** **Priority: HIGH** ### **2.1 Define Relationship Types** - [x] Create `src/types/relationships.ts` with relationship interfaces - [x] Define ImportRelation, ExportRelation, CallRelation, InheritanceRelation - [x] Define CodeRelationships aggregate interface - [x] Define RelatedComponent and RelationshipGraph types ### **2.2 Relationship Type Definitions** ```typescript interface ImportRelation { from: string; // File that imports to: string; // File being imported symbols: string[]; // What's being imported importType: 'default' | 'named' | 'namespace' | 'dynamic'; lineNumber?: number; } interface CallRelation { from: string; // Calling function/file to: string; // Called function object?: string; // Object/service being called lineNumber?: number; callType: 'direct' | 'method' | 'constructor'; } interface InheritanceRelation { from: string; // Child class to: string; // Parent class/interface type: 'extends' | 'implements' | 'mixin'; lineNumber?: number; } interface ExportRelation { from: string; // File that exports symbol: string; // What's being exported exportType: 'default' | 'named' | 'namespace'; lineNumber?: number; } ``` ### **2.3 Graph Storage Schema Design** - [x] Define Graphiti node types: File, Class, Function, Interface, Module - [x] Define Graphiti edge types: imports, exports, calls, extends, implements, uses - [x] Design relationship properties and metadata - [x] Plan relationship traversal algorithms ### **2.4 Acceptance Criteria** - [x] Complete relationship type definitions - [x] Clear graph schema for Graphiti storage - [x] Documented relationship detection strategy - [x] Multi-language support plan --- ## 🔍 **Phase 3: Enhance CodeAnalyzer with Relationship Extraction** **Status: ✅ COMPLETED** **Duration: 3-4 days** **Priority: HIGH** ### **3.1 Core Analysis Methods** - [x] Add `extractRelationships(content: string, filePath: string): CodeRelationships` - [x] Add `analyzeImports(ast: any, filePath: string): ImportRelation[]` - [x] Add `analyzeFunctionCalls(ast: any, filePath: string): CallRelation[]` - [x] Add `analyzeClassInheritance(ast: any, filePath: string): InheritanceRelation[]` - [x] Add `analyzeExports(ast: any, filePath: string): ExportRelation[]` ### **3.2 JavaScript/TypeScript Analysis (Primary)** - [x] Enhance Babel AST traversal for import detection - [x] Add function call detection in AST - [x] Add class inheritance detection - [x] Add export detection (default, named, namespace) - [x] Handle dynamic imports and require() calls ### **3.3 Python Analysis (Secondary)** - [x] Add Python import detection with regex - [x] Add class inheritance detection for Python - [x] Add function call heuristics - [x] Handle from X import Y statements ### **3.4 Generic Language Support (Fallback)** - [x] Create regex-based import detection - [x] Create heuristic function call detection - [x] Create basic inheritance pattern matching - [x] Support Java, C++, C#, Go, Rust basics ### **3.5 Integration with Existing Analysis** - [x] Update `analyzeFile()` to include relationship extraction - [x] Add relationships to CodeRepresentation interface - [x] Update structural features to include relationship metrics - [x] Maintain backward compatibility ### **3.6 Acceptance Criteria** - [x] Accurate import/export detection for JS/TS - [x] Function call detection with AST - [x] Class inheritance detection - [x] Python support for major patterns - [x] Fallback support for other languages - [x] Integration with existing CodeAnalyzer --- ## 📊 **Phase 4: Update Graphiti Integration for Relationship Storage** **Status: ✅ COMPLETED** **Duration: 2-3 days** **Priority: HIGH** ### **4.1 Enhanced GraphitiClient Methods** - [x] Add `storeRelationship(from: string, to: string, type: string, details: any)` - [x] Add `getRelatedComponents(filePath: string, maxDepth: number): RelatedComponent[]` - [x] Add `traverseRelationships(startFile: string, relationTypes: string[]): GraphPath[]` - [x] Add `updateFileRelationships(filePath: string, relationships: CodeRelationships)` - [x] Add `deleteFileRelationships(filePath: string)` ### **4.2 Relationship Storage Format** - [x] Design episode format for relationships - [x] Create relationship metadata structure - [x] Plan relationship indexing strategy - [x] Design relationship query patterns ### **4.3 Graph Traversal Algorithms** - [x] Implement breadth-first relationship traversal - [x] Add relationship strength calculation - [x] Create related component ranking - [x] Add circular dependency detection ### **4.4 Enhanced Code Storage** - [x] Update `storeCodeRepresentation()` to include relationships - [x] Modify episode creation to store relationship data - [x] Update search to consider relationships - [x] Add relationship-based similarity scoring ### **4.5 Acceptance Criteria** - [x] Relationships stored as Graphiti edges - [x] Efficient relationship traversal - [x] Related component retrieval - [x] Integration with existing storage --- ## 🎯 **Phase 5: Enhance Query System for Context-Aware Retrieval** **Status: ✅ COMPLETED** **Duration: 3-4 days** **Priority: HIGH** ### **5.1 Enhanced SACLReranker** - [x] Add `includeRelatedContext(results: RetrievalResult[]): EnhancedResult[]` - [x] Add `calculateRelationshipRelevance(primary: string, related: string): number` - [x] Add `generateContextExplanation(result: RetrievalResult, context: RelatedComponent[]): string` - [x] Update `rerank()` to include relationship context ### **5.2 Context Selection Logic** - [x] Implement relationship weight calculation - [x] Add context relevance scoring - [x] Create relationship path analysis - [x] Add context size limiting (max 5-10 related components) ### **5.3 Enhanced Result Structure** - [x] Create `EnhancedRetrievalResult` interface - [x] Add `relatedComponents` field - [x] Add `relationshipMap` field - [x] Add `contextExplanation` field - [x] Add `dependencyChain` field ### **5.4 Context Explanation Generation** - [x] Create relationship description templates - [x] Add LLM-powered context explanation - [x] Generate dependency chain descriptions - [x] Create relationship visualizations (text-based) ### **5.5 Acceptance Criteria** - [x] Query results include related components - [x] Clear context explanations - [x] Relationship relevance scoring - [x] Performance acceptable for context inclusion --- ## 🛠️ **Phase 6: Add New MCP Tools** **Status: ✅ COMPLETED** **Duration: 2-3 days** **Priority: MEDIUM** ### **6.1 New MCP Tool: update_file** - [x] Add tool definition to `listTools()` - [x] Implement `handleUpdateFile()` method - [x] Add file validation and error handling - [x] Update single file relationships - [x] Return update status and metrics ### **6.2 New MCP Tool: update_files** - [x] Add tool definition for batch updates - [x] Implement `handleUpdateFiles()` method - [x] Add batch processing logic - [x] Optimize for large file sets - [x] Maintain relationship consistency ### **6.3 New MCP Tool: get_relationships** - [x] Add tool definition for relationship queries - [x] Implement `handleGetRelationships()` method - [x] Add relationship filtering options - [x] Create relationship visualization - [x] Add dependency analysis ### **6.4 New MCP Tool: get_file_context** - [x] Add tool for file context queries - [x] Implement `handleGetFileContext()` method - [x] Show related components for specific file - [x] Display dependency chains - [x] Explain relationship types ### **6.5 Enhanced Existing Tools** - [x] Update `query_code` to return enhanced results - [x] Update `get_bias_analysis` to include relationship context - [x] Update `analyze_repository` to show relationship stats - [x] Add relationship metrics to `get_system_stats` ### **6.6 Acceptance Criteria** - [x] All new MCP tools functional - [x] Enhanced existing tool responses - [x] Clear error handling and validation - [x] Comprehensive tool documentation --- ## 📚 **Phase 7: Update Documentation & Testing** **Status: ✅ COMPLETED** **Duration: 1-2 days** **Priority: MEDIUM** ### **7.1 Documentation Updates** - [x] Update `README.md` with new user flow - [x] Document new MCP tools and enhanced results - [x] Add relationship analysis documentation - [x] Update Docker setup instructions - [x] Add troubleshooting guide ### **7.2 Code Documentation** - [x] Add JSDoc comments to all new methods - [x] Document relationship type definitions - [x] Add code examples for relationship analysis - [x] Document performance considerations ### **7.3 Example Updates** - [x] Create example enhanced query results - [x] Add relationship analysis examples - [x] Update user workflow examples - [x] Add context-aware retrieval demos ### **7.4 Architecture Documentation** - [x] Update architecture diagrams - [x] Document relationship analysis pipeline - [x] Add data flow diagrams - [x] Document performance characteristics ### **7.5 Acceptance Criteria** - [x] Complete documentation for all changes - [x] Clear examples and usage patterns - [x] Updated architecture documentation - [x] User guide for new features --- ## 📈 **Implementation Schedule** ### **Week 1: Foundation (Phases 1-2)** - **Days 1-2**: Phase 1 - Remove FileWatcher - **Days 3-5**: Phase 2 - Design relationship system ### **Week 2: Core Implementation (Phases 3-4)** - **Days 1-4**: Phase 3 - Enhance CodeAnalyzer - **Days 5-7**: Phase 4 - Update Graphiti integration ### **Week 3: Query Enhancement (Phase 5)** - **Days 1-4**: Phase 5 - Context-aware retrieval - **Days 5-7**: Testing and refinement ### **Week 4: Tools & Documentation (Phases 6-7)** - **Days 1-3**: Phase 6 - New MCP tools - **Days 4-5**: Phase 7 - Documentation updates --- ## 🎯 **Success Criteria** ### **Functional Requirements** - [ ] ✅ No FileWatcher dependency - [ ] ✅ Agent-controlled updates work reliably in Docker - [ ] ✅ Relationship analysis for JS/TS/Python - [ ] ✅ Context-aware query results with related components - [ ] ✅ Knowledge graph stores and retrieves relationships - [ ] ✅ New MCP tools functional and documented ### **Quality Requirements** - [ ] ✅ Docker container compatibility maintained - [ ] ✅ Performance acceptable for large codebases (>1000 files) - [ ] ✅ Accurate relationship detection (>90% precision) - [ ] ✅ Clear context explanations and relationship descriptions - [ ] ✅ Comprehensive documentation and examples - [ ] ✅ Backward compatibility with existing functionality ### **Performance Targets** - [ ] ✅ Single file update: <5 seconds - [ ] ✅ Relationship traversal: <2 seconds for 3-depth - [ ] ✅ Context-aware query: <10 seconds for complex queries - [ ] ✅ Memory usage: <2GB for 1000+ file repositories --- ## 🔄 **Progress Tracking** | Phase | Status | Start Date | End Date | Notes | |-------|--------|------------|----------|-------| | Phase 1: Remove FileWatcher | ✅ Completed | - | - | FileWatcher removed, explicit updates implemented | | Phase 2: Design Relationships | ✅ Completed | - | - | Comprehensive relationship types defined | | Phase 3: Enhance CodeAnalyzer | ✅ Completed | - | - | JS/TS/Python relationship extraction added | | Phase 4: Update Graphiti | ✅ Completed | - | - | Relationship storage and retrieval implemented | | Phase 5: Context-Aware Queries | ✅ Completed | - | - | Enhanced results with relationship context | | Phase 6: New MCP Tools | ✅ Completed | - | - | 5 new MCP tools implemented with relationship context | | Phase 7: Documentation | 🔲 Pending | - | - | - | --- ## 📝 **Implementation Notes** ### **Key Decisions Made:** - Remove FileWatcher completely for Docker compatibility - Focus on JavaScript/TypeScript with Python secondary support - Use explicit agent-controlled updates instead of automatic monitoring - Store relationships as Graphiti graph edges for efficient traversal - Include 3-5 related components in query results for optimal context ### **Risks and Mitigation:** - **Risk**: Performance impact of relationship analysis **Mitigation**: Implement caching and limit traversal depth - **Risk**: Complexity of multi-language support **Mitigation**: Start with JS/TS, add others incrementally - **Risk**: Large graph storage requirements **Mitigation**: Implement relationship pruning and archiving ### **Future Enhancements:** - Real-time collaboration features - Visual relationship graphs - Advanced dependency analysis - Integration with LSP servers - AI-powered relationship suggestions This implementation plan provides a complete roadmap for transforming SACL into a comprehensive, relationship-aware code intelligence platform.