mcp-code-context 2.5.1 → 3.0.4

package/docs/ARCHITECTURE.md

@@ -1,300 +0,0 @@
-# Architecture Overview
-
-## System Design
-
-`mcp-code-context` is a Model Context Protocol (MCP) server that provides semantic code analysis and surgical editing capabilities. The architecture follows a layered design with clear separation of concerns.
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      MCP Client                              │
-│              (Claude, Cursor, Amazon Q, etc.)                │
-└────────────────────────┬────────────────────────────────────┘
-                         │ JSON-RPC over stdio
-                         ▼
-┌─────────────────────────────────────────────────────────────┐
-│                   MCP Server (index.ts)                      │
-│  ┌──────────────────────────────────────────────────────┐   │
-│  │           Tool Registry & Dispatcher                  │   │
-│  └──────────────────────────────────────────────────────┘   │
-└────────────────────────┬────────────────────────────────────┘
-                         │
-         ┌───────────────┼───────────────┐
-         ▼               ▼               ▼
-┌────────────────┐ ┌────────────┐ ┌────────────┐
-│ Read Handlers  │ │   Write    │ │   Util     │
-│                │ │  Handlers  │ │  Handlers  │
-│ • repo_map     │ │ • surgical │ │ • rollback │
-│ • read_file    │ │ • insert   │ │ • cleanup  │
-│ • analyze      │ │ • rename   │ └────────────┘
-│ • search       │ │ • remove   │
-└────────┬───────┘ └─────┬──────┘
-         │               │
-         └───────┬───────┘
-                 ▼
-┌─────────────────────────────────────────────────────────────┐
-│                      Core Services                           │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
-│  │   AST    │  │  Cache   │  │Security  │  │  Backup  │   │
-│  │ Parsers  │  │   LRU    │  │Validation│  │  Manager │   │
-│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
-└─────────────────────────────────────────────────────────────┘
-         │               │               │               │
-         └───────────────┴───────────────┴───────────────┘
-                                 ▼
-                    ┌────────────────────────┐
-                    │     File System        │
-                    └────────────────────────┘
-```
-
-## Component Responsibilities
-
-### 1. MCP Server Layer (`index.ts`)
-
-**Responsibility**: Protocol handling and request routing
-
-- Initializes MCP server with stdio transport
-- Registers available tools
-- Routes requests to appropriate handlers
-- Minimal business logic (~150 lines)
-
-### 2. Handler Layer (`src/handlers/`)
-
-**Responsibility**: Tool implementation and orchestration
-
-#### Read Handlers (`readHandlers.ts`)
-- `get_semantic_repo_map`: Generate compressed repo overview
-- `read_file_surgical`: Extract specific symbols or full files
-- `analyze_impact`: Find file dependencies
-- `read_file_lines`: Read specific line ranges
-- `search_code_pattern`: Search patterns across repo
-
-#### Write Handlers (`writeHandlers.ts`)
-- `write_file_surgical`: Replace symbol code
-- `insert_symbol`: Insert code at precise locations
-- `rename_symbol`: Rename across repository
-- `remove_symbol`: Safe symbol deletion
-
-#### Util Handlers (`utilHandlers.ts`)
-- `rollback_file`: Restore from backup
-- `clean_backups`: Remove backup files
-
-### 3. Core Services Layer
-
-#### AST Parsers (`src/ast/`)
-- **TypeScript/JavaScript**: Uses `ts-morph` (real AST)
-- **PHP**: Uses `php-parser` (real AST)
-- **Dart**: Brace-counting + regex (pragmatic)
-- **Python**: Indentation-aware regex (pragmatic)
-
-**Design Decision**: Mix of real parsers and pragmatic approaches balances robustness with simplicity.
-
-#### Cache (`src/cache/astCache.ts`)
-- LRU cache for parsed ASTs
-- Automatic invalidation via file mtime
-- 90% performance improvement for repeated operations
-- Memory-bounded (configurable max size)
-
-#### Security (`src/utils/validation.ts`)
-- Path traversal prevention
-- ReDoS protection
-- Input sanitization
-- File size limits
-
-#### Backup Manager (`src/utils/backupManager.ts`)
-- Rolling 5-version backup system
-- Centralized `.mcp-backups/` directory
-- Automatic cleanup
-- Surgical rollback capability
-
-### 4. Utility Layer (`src/utils/`)
-
-- **constants.ts**: Centralized configuration
-- **normalization.ts**: CRLF/indentation handling
-- **validation.ts**: Security and input validation
-- **fuzzyMatch.ts**: Symbol name suggestions
-- **diffEngine.ts**: Unified diff generation
-- **confirmationCache.ts**: Two-phase write workflow
-
-## Data Flow
-
-### Read Operation Example: `read_file_surgical`
-
-```
-1. Client Request
-   ↓
-2. index.ts routes to readHandlers.handleReadFileSurgical()
-   ↓
-3. Validate file path (validation.ts)
-   ↓
-4. Check cache (astCache.ts)
-   ├─ Cache hit → Return cached result
-   └─ Cache miss → Continue
-   ↓
-5. Read file from disk
-   ↓
-6. Parse with appropriate AST parser
-   ↓
-7. Extract symbol
-   ↓
-8. Cache result
-   ↓
-9. Return to client
-```
-
-### Write Operation Example: `write_file_surgical`
-
-```
-PHASE 1 (Dry-Run):
-1. Client Request (no confirmation token)
-   ↓
-2. index.ts routes to writeHandlers.handleWriteFileSurgical()
-   ↓
-3. Validate inputs (validation.ts)
-   ↓
-4. Read file and parse
-   ↓
-5. Perform replacement in memory
-   ↓
-6. Generate diff (diffEngine.ts)
-   ↓
-7. Store in confirmation cache
-   ↓
-8. Return diff + confirmation token
-
-PHASE 2 (Apply):
-1. Client Request (with confirmation token + confirm: true)
-   ↓
-2. Retrieve from confirmation cache
-   ↓
-3. Create backup (backupManager.ts)
-   ↓
-4. Write to disk
-   ↓
-5. Invalidate cache
-   ↓
-6. Return success
-```
-
-## Security Model
-
-### Defense in Depth
-
-1. **Input Validation**: All user inputs validated before processing
-2. **Path Containment**: Paths must be within project root
-3. **ReDoS Protection**: Regex patterns validated for safety
-4. **File Size Limits**: Prevent memory exhaustion
-5. **Two-Phase Writes**: Mandatory preview before applying changes
-6. **Automatic Backups**: 5-version rolling backup system
-
-### Threat Mitigation
-
-| Threat | Mitigation |
-|--------|-----------|
-| Path Traversal | `validateFilePath()` checks for `..` and dangerous patterns |
-| ReDoS | `validateRegexPattern()` detects catastrophic backtracking |
-| Memory Exhaustion | File size limits + LRU cache with max size |
-| Data Loss | Automatic backups + two-phase confirmation |
-| Injection | Input sanitization + AST-based parsing |
-
-## Performance Optimizations
-
-### 1. LRU Cache
-- **Impact**: 90% faster for repeated operations
-- **Trade-off**: Memory usage (bounded by max size)
-
-### 2. Lazy Loading
-- AST parsers loaded on-demand
-- Reduces startup time
-
-### 3. Incremental Processing
-- `get_semantic_repo_map` limited to 500 files
-- Prevents timeout on large repositories
-
-### 4. Efficient Diff Generation
-- LCS algorithm for minimal diffs
-- Context lines configurable
-
-## Extensibility
-
-### Adding a New Language
-
-1. Create parser in `src/ast/` (e.g., `rustCompressor.ts`)
-2. Create writer in `src/ast/writers/` (e.g., `rustWriter.ts`)
-3. Add extension to `WRITABLE_EXTENSIONS` in `constants.ts`
-4. Update `symbolWriter.ts` to route to new writer
-5. Add tests in `tests/`
-
-### Adding a New Tool
-
-1. Create handler function in appropriate handler file
-2. Add tool definition to `TOOLS` array in `index.ts`
-3. Add route case in request handler
-4. Add tests in `tests/`
-
-## Testing Strategy
-
-### Unit Tests
-- Each handler tested in isolation
-- Mock file system operations
-- Test edge cases (missing files, invalid input, etc.)
-
-### Integration Tests
-- Full workflow tests (read → write → verify)
-- Multi-file operations (rename across repo)
-- Cache invalidation
-
-### Security Tests
-- Path traversal attempts
-- ReDoS patterns
-- Malformed input
-
-### Performance Tests
-- Large file handling
-- Cache hit rate
-- Memory usage under load
-
-## Deployment
-
-### NPM Package
-```bash
-npm install -g mcp-code-context
-```
-
-### MCP Client Configuration
-```json
-{
-  "mcpServers": {
-    "code-context": {
-      "command": "npx",
-      "args": ["-y", "mcp-code-context"]
-    }
-  }
-}
-```
-
-## Monitoring & Observability
-
-### Metrics (Future)
-- Tool invocation counts
-- Cache hit rates
-- Error rates by tool
-- Average response times
-
-### Logging
-- Errors logged to stderr
-- MCP protocol messages on stdout
-- Structured logging for debugging
-
-## Future Enhancements
-
-1. **Async I/O**: Migrate to `fs.promises` for non-blocking operations
-2. **Streaming**: Support large files via streaming
-3. **Tree-sitter**: Unified parser for all languages
-4. **LSP Integration**: Leverage Language Server Protocol for advanced features
-5. **Telemetry**: Optional usage analytics for improvement
-
-## References
-
-- [MCP Specification](https://modelcontextprotocol.io/)
-- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
-- [SOLID Principles](https://en.wikipedia.org/wiki/SOLID)

package/docs/architecture/ADR-001-modular-handlers.md

@@ -1,119 +0,0 @@
-# ADR-001: Modular Handler Architecture
-
-**Status:** Accepted  
-**Date:** 2026-04-23  
-**Decision Makers:** Core Team  
-
-## Context
-
-The original `src/index.ts` file grew to 1100+ lines, violating the Single Responsibility Principle and making the codebase difficult to maintain. The file contained:
-
-- MCP server initialization
-- 11 tool handler implementations
-- Utility functions (formatting, import resolution, project root finding)
-- Type definitions
-- Constants
-
-This created several problems:
-
-1. **High cognitive load**: Understanding any single tool required reading through 1100 lines
-2. **Merge conflicts**: Multiple developers editing the same file
-3. **Testing difficulty**: Unit testing individual handlers was cumbersome
-4. **Violation of SRP**: One file had too many responsibilities
-
-## Decision
-
-We will refactor `index.ts` into a modular architecture:
-
-```
-src/
-├─ handlers/
-│  ├─ readHandlers.ts    (get_semantic_repo_map, read_file_surgical, etc.)
-│  ├─ writeHandlers.ts   (write_file_surgical, insert_symbol, etc.)
-│  └─ utilHandlers.ts    (rollback_file, clean_backups)
-├─ utils/
-│  ├─ constants.ts       (centralized configuration)
-│  ├─ normalization.ts   (CRLF, indentation)
-│  └─ validation.ts      (security, input validation)
-├─ cache/
-│  └─ astCache.ts        (LRU cache for performance)
-└─ index.ts              (~150 lines, orchestration only)
-```
-
-### Key Principles
-
-1. **Separation of Concerns**: Each handler file focuses on one category of operations
-2. **DRY**: Shared logic extracted to utilities
-3. **Security First**: Validation centralized in `validation.ts`
-4. **Performance**: Cache layer added for repeated operations
-5. **Testability**: Each module can be unit tested independently
-
-## Consequences
-
-### Positive
-
-- **Maintainability**: Each file is <500 lines, easy to understand
-- **Testability**: Handlers can be tested in isolation
-- **Performance**: Cache reduces redundant parsing by 90%
-- **Security**: Centralized validation prevents vulnerabilities
-- **Extensibility**: Adding new tools is straightforward
-
-### Negative
-
-- **More files**: Developers need to navigate multiple files
-- **Import complexity**: More import statements
-- **Migration effort**: Existing code needs refactoring
-
-### Mitigation
-
-- Clear naming conventions make navigation intuitive
-- IDE features (Go to Definition) handle imports
-- Incremental migration with continuous testing
-
-## Alternatives Considered
-
-### 1. Keep monolithic index.ts
-
-**Pros**: No refactoring needed  
-**Cons**: Technical debt continues to grow  
-**Rejected**: Unsustainable long-term
-
-### 2. Microservices architecture
-
-**Pros**: Maximum separation  
-**Cons**: Over-engineering for a single MCP server  
-**Rejected**: Too complex for the problem
-
-### 3. Class-based handlers
-
-**Pros**: OOP encapsulation  
-**Cons**: Unnecessary abstraction for stateless handlers  
-**Rejected**: Functional approach is simpler
-
-## Implementation Plan
-
-1. ✅ Create utility modules (constants, normalization, validation)
-2. ✅ Create cache layer
-3. ✅ Extract handlers to separate files
-4. ⏳ Update index.ts to import and delegate
-5. ⏳ Run full test suite to ensure no regressions
-6. ⏳ Update documentation
-
-## Metrics
-
-**Before:**
-- index.ts: 1100 lines
-- Cyclomatic complexity: High
-- Test coverage: 70%
-
-**After (Target):**
-- index.ts: ~150 lines
-- Handler files: <500 lines each
-- Cyclomatic complexity: Low-Medium
-- Test coverage: >85%
-
-## References
-
-- [Single Responsibility Principle](https://en.wikipedia.org/wiki/Single-responsibility_principle)
-- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
-- [MCP Protocol Specification](https://modelcontextprotocol.io/)