mcp-code-context 3.5.2 → 3.6.0

package/CHANGELOG.md

@@ -1,6 +1,60 @@
 # Changelog
 
-## [3.5.2] - 2026-04-24
+## [3.6.0] - 2026-05-01
+
+### 🚀 PRODUCTION PLATFORM - Caching, Logging, Watching, Search & Testing
+
+**Major Update**: 144-hour engineering effort transforming mcp-code-context from a fragile in-memory tool into a production-ready platform.
+
+### Added
+
+#### Infrastructure
+- **Persistent WASM SQLite Cache** (`sql.js`) — <100ms cache hits, 10× faster on repeated reads. Debounced persistence (5s) prevents event loop blocking. OS temp cleanup recovery built-in.
+- **Structured Logging** (`pino`) — JSON to stderr (MCP-safe). Pretty-print in development, JSON in production. All `console.log/error` replaced.
+- **File Watcher** (`chokidar`) — Auto-invalidates cache on file changes. Configurable debounce (default 500ms). New MCP tools: `configure_file_watcher`, `get_file_watcher_status`.
+- **Fuzzy Search** (`fuse.js`) — Typo-tolerant search. Finds `authenticateUser` when searching `authUser`. Configurable threshold.
+- **Pagination** — `search_code_pattern` now defaults to 10 results (was 50) with `startIndex` parameter and result footer.
+
+#### Testing (74 tests, 100% passing)
+- **Vitest** test framework with V8 coverage
+- Unit tests: parsers, diff, fileLock, backupManager, phase9 optimization
+- Integration tests: full read→write→rollback cycle, multi-process safety
+- Performance tests: cache hit <100ms, search <2000ms
+- Stress tests: 20 concurrent locks, 10K line files, OOM protection
+
+#### Security Fixes (3 production stoppers resolved)
+- **STOPPER #1**: `sanitizeRegexPattern` UUID bug fixed (`\\$&` replacement)
+- **STOPPER #2**: Phase 2 re-acquires file lock before write (race condition eliminated)
+- **STOPPER #3**: `SecurityValidator` applied in Phase 2 (defense in depth)
+
+### Changed
+- **Token Optimization**: Phase 2 confirmation no longer repeats diff (50-80% token reduction)
+- **Auto-optimize output**: `get_semantic_repo_map` auto-disables symbols if >100 files or >1000 symbols
+- **Filesystem locks**: `proper-lockfile` replaces in-memory locks (multi-process safe)
+- **OS temp backups**: Backups moved from project root to `os.tmpdir()` (no hot-reload loops)
+- **Myers diff**: `diff-match-patch` replaces custom O(n×m) LCS (no OOM on large files)
+- **Centralized `walkDir`**: Extracted to `src/utils/fileWalker.ts` (eliminated 3× duplication)
+- **Pinned dependencies**: All `^` ranges replaced with exact versions for reproducible installs
+
+### Fixed
+- `analyzeImpact` regex patterns now use `safeRegex` (consistent ReDoS protection)
+- `BackupManager.getBackupRoot` uses async `fs.mkdir` (no sync blocking)
+- `validateRegexPattern` documented as best-effort (worker timeout is the real guarantee)
+
+### Performance
+- Cache hit: <100ms ✅
+- Parse file: <500ms ✅
+- Search (20 files): <2000ms ✅
+- Token savings: 50-80% ✅
+
+### Migration from v3.6.0
+- Zero breaking changes
+- New optional parameters: `fuzzyMatch`, `fuzzyThreshold`, `startIndex`, `maxDepth`, `includeSymbols`
+- New tools: `configure_file_watcher`, `get_file_watcher_status`, `get_cache_stats`, `clear_cache`
+
+---
+
+## [3.6.0] - 2026-04-24
 
 ### 🔒 PRODUCTION HARDENING - Security & Infrastructure Complete
 
@@ -30,7 +84,7 @@
 - **Security**: SecurityValidator enforced on all 13 handlers
 - **Architecture**: Middleware pipeline (RateLimiter → FileLock → Execute → AuditLog → Telemetry)
 - **Parsers**: Removed 300+ lines of duplicated replaceSymbol code
-- **Version**: Synchronized all version strings to 3.5.2
+- **Version**: Synchronized all version strings to 3.6.0
 
 ### Performance
 - Streaming I/O for files >5MB (prevents memory exhaustion)
@@ -49,7 +103,7 @@
 - ✅ All security tests passing
 - ✅ All rate limiter tests passing
 - ✅ All file lock tests passing
-- ✅ All v3.5.2 feature tests passing
+- ✅ All v3.6.0 feature tests passing
 - ✅ TypeScript: 0 compilation errors
 - ✅ Build: Clean production dist
 

package/HIRE_ME.md

@@ -0,0 +1,234 @@
+# 💼 Hire Me - Freelance MCP & AI Development
+
+## About Me
+
+I'm **Alejandro Chataing**, creator of **mcp-code-context**, an MCP server with 2,000+ NPM package downloads that helps developers save 70-90% on LLM token costs through surgical code editing and AST-based compression.
+
+**Location**: Caracas, Venezuela 🇻🇪  
+**Timezone**: UTC-4 (AST / VET)  
+**Languages**: Spanish (native), English (fluent)
+
+---
+
+## 🎯 Core Expertise
+
+### MCP Protocol & AI Integration
+- **MCP Server Development**: Deep understanding of Model Context Protocol
+- **AI/LLM Integration**: Claude, GPT-4, Gemini, local models
+- **Context Optimization**: Token compression, semantic chunking, RAG
+- **Tool Development**: Custom MCP tools for specific workflows
+
+### Technical Skills
+- **Languages**: TypeScript, JavaScript, Python, PHP, Dart
+- **Frameworks**: Node.js, Express, Fastify
+- **AST Parsing**: Tree-sitter, Babel, custom parsers
+- **Databases**: PostgreSQL, MongoDB, Redis
+- **DevOps**: Docker, GitHub Actions, AWS
+- **AI/ML**: LangChain, OpenAI API, Anthropic API, Ollama
+
+---
+
+## 🛠️ Services
+
+### 🔹 MCP Server Development
+Build custom MCP servers tailored to your workflow:
+- Custom tools for your specific use case
+- Integration with internal APIs and databases
+- Performance optimization for large codebases
+- Security hardening and audit
+- Documentation and training
+
+**Rate**: $75/hour  
+**Typical Project**: $1,500-5,000  
+**Timeline**: 1-3 weeks
+
+**Example Projects**:
+- Custom code analysis tools
+- Database query assistants
+- API integration servers
+- Documentation generators
+- Testing automation tools
+
+---
+
+### 🔹 AI Integration Consulting
+Help your team integrate LLMs effectively:
+- Architecture design for AI-powered applications
+- Cost optimization strategies (reduce token usage by 70-90%)
+- Prompt engineering and fine-tuning
+- RAG (Retrieval-Augmented Generation) implementation
+- Agent orchestration and workflow design
+
+**Rate**: $100/hour  
+**Typical Project**: $2,000-10,000  
+**Timeline**: 2-6 weeks
+
+**Example Projects**:
+- AI-powered code review systems
+- Intelligent documentation assistants
+- Customer support automation
+- Internal knowledge base with AI search
+- Code generation pipelines
+
+---
+
+### 🔹 Code Review & Optimization
+Expert review of your MCP/AI codebase:
+- Security audit (path traversal, injection, ReDoS)
+- Performance optimization (memory, speed, token usage)
+- Best practices implementation
+- Documentation improvement
+- Test coverage analysis
+
+**Rate**: $50/hour  
+**Typical Project**: $500-2,000  
+**Timeline**: 3-7 days
+
+**Deliverables**:
+- Detailed audit report
+- Prioritized recommendations
+- Code examples for fixes
+- Implementation guidance
+
+---
+
+## 📂 Portfolio
+
+### mcp-code-context
+**The project that proves my expertise**
+
+- **GitHub**: [github.com/achatainga/mcp-code-context](https://github.com/achatainga/mcp-code-context)
+- **npm**: 2,000+ downloads/month
+- **Tech**: TypeScript, Tree-sitter WASM, MCP Protocol
+- **Impact**: Saves users 70-90% on LLM token costs
+
+**Key Features**:
+- Surgical code editing (replace one function without touching the rest)
+- AST-based compression (no regex hacks)
+- Two-phase confirmation workflow
+- Rolling backups (last 5 versions)
+- Zero native dependencies (100% WASM)
+
+**What this demonstrates**:
+- ✅ Deep understanding of MCP protocol
+- ✅ Production-grade TypeScript development
+- ✅ AST parsing and manipulation
+- ✅ Security-first design (two-phase workflow, backups)
+- ✅ Performance optimization (WASM, streaming)
+- ✅ Open source maintenance (1,000+ stars, active community)
+
+---
+
+## 🤝 How to Work With Me
+
+### 1. Initial Consultation (Free, 30 min)
+- Discuss your project goals
+- Assess technical feasibility
+- Provide rough estimate and timeline
+- Answer your questions
+
+**Book a call**: Email me at a.chataing.a@gmail.com
+
+---
+
+### 2. Proposal (1-2 days)
+- Detailed scope of work
+- Timeline with milestones
+- Fixed price or hourly estimate
+- Terms and conditions
+
+---
+
+### 3. Development (Agile)
+- Weekly check-ins (or more frequent if needed)
+- Incremental delivery (you see progress continuously)
+- Transparent communication (Slack, Discord, Email)
+- Code reviews at each milestone
+
+---
+
+### 4. Delivery & Support
+- Final code review
+- Complete documentation
+- Knowledge transfer session
+- 30 days of bug fixes included
+- Optional: Ongoing maintenance contract
+
+---
+
+## 💰 Pricing & Payment
+
+### Rates
+- **MCP Development**: $75/hour
+- **AI Consulting**: $100/hour
+- **Code Review**: $50/hour
+
+### Payment Terms
+- **Hourly Projects**: Weekly invoices, payment within 7 days
+- **Fixed-Price Projects**: 50% upfront, 50% on delivery
+- **Retainer**: Monthly prepayment for ongoing work
+
+### Accepted Payment Methods
+- **PayPal**: https://paypal.me/achatainga
+- **Binance (USDT)**: 0xa68d53f7853ce0175eb96aaad4a30c068ca96444
+
+---
+
+## 📅 Availability
+
+- **Current Capacity**: 20-30 hours/week for freelance projects
+- **Response Time**: Within 24 hours (usually faster)
+- **Timezone**: UTC-4 (flexible for meetings)
+- **Working Hours**: Flexible, can accommodate US/EU timezones
+
+---
+
+## 🌟 Why Work With Me?
+
+### Technical Excellence
+- **Proven Track Record**: mcp-code-context has 1,000+ stars and 10,000+ downloads
+- **Production Experience**: Built systems that handle real-world scale
+- **Security-First**: Every project includes security review
+- **Performance-Focused**: Optimize for speed and cost
+
+### Communication
+- **Fluent English**: Clear, professional communication
+- **Responsive**: Quick replies, regular updates
+- **Transparent**: No surprises, honest timelines
+- **Collaborative**: Your input shapes the solution
+
+### Value
+- **Cost-Effective**: Based in Venezuela, competitive rates without compromising quality
+- **Efficient**: Years of experience = faster delivery
+- **Reliable**: Meet deadlines, deliver what's promised
+- **Long-Term**: Build relationships, not just projects
+
+---
+
+## 📧 Contact
+
+**Email**: a.chataing.a@gmail.com  
+**GitHub**: [@achatainga](https://github.com/achatainga)  
+**Ko-fi**: [ko-fi.com/achatainga](https://ko-fi.com/achatainga)  
+**LinkedIn**: [linkedin.com](https://www.linkedin.com/in/alejandro-chataing-90205a1b1/)
+**Twitter/X**: [x.com/achatainga](https://x.com/achatainga)
+
+---
+
+## 🚀 Let's Build Something Amazing
+
+Whether you need:
+- A custom MCP server for your workflow
+- AI integration for your product
+- Code review and optimization
+- Consulting on LLM cost reduction
+
+I'm here to help. Let's talk about your project.
+
+**Email me**: a.chataing.a@gmail.com
+
+---
+
+*Looking for a developer who understands both the technical and economic constraints of AI development? You found the right person.*
+
+**Built with ❤️ from Caracas, Venezuela 🇻🇪**

package/INSTRUCTIONS.md

@@ -0,0 +1,274 @@
+# Instructions for AI Agents Using mcp-code-context
+
+## 🎯 Quick Start
+
+This MCP server provides **surgical code editing** with Tree-sitter AST parsing. Use it to read and modify code with precision.
+
+---
+
+## 📖 Essential Reading Workflow
+
+### 1. Start with Repository Map
+```
+@mcp-code-context/get_semantic_repo_map
+  directoryPath: /absolute/path/to/project
+  projectRoot: /absolute/path/to/project
+  format: xml
+```
+
+**Why**: Get architectural overview before diving into files. Saves 80% tokens vs reading raw files.
+
+### 2. Extract Specific Symbols
+```
+@mcp-code-context/read_file_surgical
+  filePath: /path/to/file.ts
+  projectRoot: /project/root
+  symbolName: functionName
+```
+
+**Why**: Read only what you need. If symbol not found, tool suggests available symbols.
+
+### 3. Check Impact Before Editing
+```
+@mcp-code-context/analyze_impact
+  filePath: /path/to/file.ts
+  projectRoot: /project/root
+```
+
+**Why**: Know which files depend on what you're about to change.
+
+---
+
+## ✏️ Essential Writing Workflow
+
+### Two-Phase Pattern (ALWAYS FOLLOW)
+
+**Phase 1: Preview**
+```
+@mcp-code-context/write_file_surgical
+  filePath: /path/to/file.ts
+  projectRoot: /project/root
+  symbolName: myFunction
+  newContent: "function myFunction() { return 42; }"
+```
+
+**Result**: Returns diff + confirmationToken
+
+**Phase 2: Apply**
+```
+@mcp-code-context/write_file_surgical
+  filePath: /path/to/file.ts
+  projectRoot: /project/root
+  symbolName: myFunction
+  newContent: "function myFunction() { return 42; }"
+  confirm: true
+  confirmationToken: "TOKEN_FROM_PHASE_1"
+```
+
+**Result**: ✅ Success. Changes applied to 1 file(s).
+
+---
+
+## 🚨 Critical Rules
+
+### 1. **ALWAYS Use projectRoot**
+Every tool requires `projectRoot` for security. Use the project's root directory.
+
+### 2. **NEVER Skip Phase 1**
+Always preview diffs before applying. Tokens are stored in memory and expire on server restart.
+
+### 3. **Use Surgical Tools, Not Full File Rewrites**
+❌ **Bad**: Read entire file, modify, write entire file  
+✅ **Good**: Use `write_file_surgical` to replace only the target symbol
+
+### 4. **Check Dependencies First**
+Before removing or renaming symbols, use `analyze_impact` to avoid breaking imports.
+
+### 5. **Provide Complete Symbol Code**
+When using `write_file_surgical`, include the full function/method signature + body:
+```typescript
+// ✅ GOOD
+newContent: "function hello(name: string): string {\n  return `Hello, ${name}`;\n}"
+
+// ❌ BAD (incomplete)
+newContent: "return `Hello, ${name}`;"
+```
+
+---
+
+## 🔍 Advanced Search
+
+### Pattern Search
+```
+@mcp-code-context/search_code_pattern
+  rootDir: /project/root
+  projectRoot: /project/root
+  pattern: "myFunction"
+  fileExtensions: [".ts", ".js"]
+  maxResults: 10
+```
+
+### Fuzzy Search (v3.6.0)
+```
+@mcp-code-context/search_code_pattern
+  rootDir: /project/root
+  projectRoot: /project/root
+  pattern: "authUser"
+  fuzzyMatch: true
+  fuzzyThreshold: 0.6
+  maxResults: 5
+```
+
+**Finds**: `authenticateUser`, `authorizeUser`, etc.
+
+---
+
+## 🛡️ Safety Features
+
+### Automatic Backups
+Every write creates a backup. Rollback if needed:
+```
+@mcp-code-context/rollback_file
+  filePath: /path/to/file.ts
+  projectRoot: /project/root
+```
+
+### Cache Management
+```
+@mcp-code-context/get_cache_stats
+  projectRoot: /project/root
+
+@mcp-code-context/clear_cache
+  projectRoot: /project/root
+```
+
+---
+
+## 💡 Pro Tips
+
+### 1. **Use className for Method Scoping**
+When a file has multiple classes with same method name:
+```
+@mcp-code-context/read_file_surgical
+  filePath: /path/to/file.ts
+  symbolName: render
+  className: MyComponent
+```
+
+### 2. **Batch Operations with rename_symbol**
+Rename across entire codebase in one operation:
+```
+@mcp-code-context/rename_symbol
+  filePath: /path/to/definition.ts
+  projectRoot: /project/root
+  oldName: oldFunction
+  newName: newFunction
+```
+
+### 3. **Insert New Code Precisely**
+```
+@mcp-code-context/insert_symbol
+  filePath: /path/to/file.ts
+  projectRoot: /project/root
+  code: "private newMethod() { }"
+  anchorSymbol: existingMethod
+  position: after
+```
+
+### 4. **Read Specific Lines Only**
+```
+@mcp-code-context/read_file_lines
+  filePath: /path/to/file.ts
+  projectRoot: /project/root
+  startLine: 100
+  endLine: 120
+```
+
+---
+
+## ⚠️ Common Mistakes
+
+### ❌ Mistake 1: Forgetting projectRoot
+```
+// WRONG
+@mcp-code-context/read_file_surgical
+  filePath: /path/to/file.ts
+```
+
+### ❌ Mistake 2: Skipping Phase 1
+```
+// WRONG - No preview
+@mcp-code-context/write_file_surgical
+  confirm: true
+  confirmationToken: "FAKE_TOKEN"
+```
+
+### ❌ Mistake 3: Incomplete Symbol Code
+```
+// WRONG - Missing function signature
+newContent: "{ return 42; }"
+```
+
+### ❌ Mistake 4: Not Checking Impact
+```
+// WRONG - Removing without checking dependencies
+@mcp-code-context/remove_symbol
+  symbolName: importantFunction
+  force: true
+```
+
+---
+
+## 📊 Performance Tips
+
+1. **Use get_semantic_repo_map first** - 80% token savings
+2. **Extract symbols, not full files** - 90% token savings
+3. **Use fuzzy search for discovery** - Finds similar patterns
+4. **Enable caching** - 10x faster repeated operations
+5. **Paginate search results** - Default 10 results, use `startIndex` for more
+
+---
+
+## 🎓 Example Workflow
+
+```
+1. Get repo map
+   → @mcp-code-context/get_semantic_repo_map
+
+2. Find target symbol
+   → @mcp-code-context/read_file_surgical
+   
+3. Check dependencies
+   → @mcp-code-context/analyze_impact
+   
+4. Preview changes (Phase 1)
+   → @mcp-code-context/write_file_surgical
+   
+5. Review diff, then apply (Phase 2)
+   → @mcp-code-context/write_file_surgical (with token)
+   
+6. Verify or rollback if needed
+   → @mcp-code-context/rollback_file
+```
+
+---
+
+## 🚀 v3.6.0 Features
+
+- ✅ **Fuzzy Search**: Find similar patterns with typo tolerance
+- ✅ **Pagination**: Default 10 results, use `startIndex` for more
+- ✅ **Token Optimization**: Phase 2 no longer repeats diff (97% savings)
+- ✅ **Auto-Optimize**: Large repos automatically disable symbols
+- ✅ **File Watcher**: Auto-invalidate cache on file changes
+- ✅ **Persistent Cache**: 10x faster with sql.js WASM SQLite
+
+---
+
+## 📚 Full Documentation
+
+See `llms.txt` for complete API reference and technical details.
+
+---
+
+**Version**: 3.6.0  
+**Last Updated**: May 1, 2026