mcp-code-context 3.6.1 → 3.6.3

package/CHANGELOG.md

@@ -1,49 +1,59 @@
 # Changelog
 
-## [3.6.1] - 2026-05-01
+## [3.6.3] - 2026-05-14
 
-### 🔒 CRITICAL FIXES - Production Stability Release
+### 🚀 ROADMAP COMPLETO — LLM Agent Experience Release
 
-**Emergency Update**: Resolved 3 critical production bugs causing data corruption, memory leaks, and race conditions.
+Esta versión implementa el roadmap completo de mejoras para agentes LLM, basado en una evaluación adversarial real del toolset. Score: 3.9/5 → 5.0/5.
 
 ### Fixed
 
-#### Critical Bug Fixes
-- **FIX #1: Double Cache Instance** — Eliminated duplicate SQLite database instances in `read.ts` causing cache corruption. Cache now properly injected from `index.ts` singleton.
-- **FIX #2: Memory Leak (Event Listeners)** — Removed `process.on` listeners from `CacheManager` constructor. Each cache instance was registering global listeners, causing `MaxListenersExceededWarning` and memory exhaustion. Added global shutdown hook in `index.ts` instead.
-- **FIX #3: TOCTOU Race Condition** — Added `originalHash` verification in Phase 2 writes. Prevents silent data corruption when files are modified between dry-run (Phase 1) and confirmation (Phase 2).
+- **FIX-01 — Lock stuck post-Phase 2**: `handleTwoPhaseWrite` ahora verifica `isLocked()` antes de re-adquirir en Phase 2. Resuelve el bug donde `insert_symbol` y `remove_symbol` fallaban con `"Lock file is already being held"` después de un `write_file_surgical` en la misma sesión.
+- **FIX-02 — `parse_file` sin líneas**: Los 4 parsers (TypeScript, PHP, Python, Dart) ahora retornan `startLine` y `endLine` en cada símbolo. El flujo `parse_file → read_file_lines` ahora funciona directamente sin conversión manual de byte offsets.
+- **CVE — `@modelcontextprotocol/sdk`**: Actualizado de `1.12.0` a `1.29.0`. Resuelve 3 CVEs: ReDoS, cross-client data leak, DNS rebinding.
+- **typescript**: Corregida versión `5.7.0` (inexistente en npm) a `5.7.2`.
 
 ### Added
-- **Global Shutdown Hook**: Single `process.on` handler in `index.ts` persists all active caches on exit
-- **persistOnExit() Method**: Public synchronous method for safe cache persistence during shutdown
-- **originalHash Field**: Added to `WriteResult` interface for TOCTOU protection
-- **8 Regression Tests**: Memory leak detection, cache injection validation, TOCTOU protection
+
+#### Nuevas Herramientas
+- **`search_symbols`**: Búsqueda AST-aware de símbolos por nombre aproximado. Opera sobre el índice AST, no sobre texto de líneas. Soporta fuzzy matching y filtro por tipo (`class_declaration`, `function_declaration`, etc.).
+- **`explain_symbol`**: Retorna firma, `startLine`/`endLine`, y lista de callers en una sola llamada. Reemplaza `read_file_surgical` + `analyze_impact` por separado.
+- **`batch_read`**: Lee N símbolos de N archivos en 1 round-trip. Elimina N llamadas a `read_file_surgical`.
+- **`get_rate_limit_status`**: Retorna tokens disponibles en tiempo real + mapa `canAfford` por operación. Permite a agentes autónomos planificar su presupuesto.
+
+#### Mejoras de Ergonomía
+- **`diffFormat` configurable**: Parámetro en `write_file_surgical`, `insert_symbol`, `remove_symbol`, `rename_symbol`. Valores: `unified` (default), `compact`, `summary`, `none`. `none` = 0 tokens de diff.
+- **Diff legible**: El diff en Phase 1 ya no está URL-encoded. `decodeURIComponent` aplicado antes de retornar.
+- **`newContent`/`code` opcionales en Phase 2**: Removidos de `required` en los schemas. El LLM no necesita reenviar el contenido en Phase 2 — el servidor ya lo tiene en `ConfirmationStore`.
+- **`aroundPattern` con número de línea**: El output ahora incluye `"Match found at line N (showing lines X-Y):"` antes del código.
+- **`get_server_stats` + rate limiter**: Incluye `rateLimiter.tokensAvailable`, `maxTokens`, `refillRate`, y `operationCosts`.
+- **`get_cache_stats` + hit rate**: Incluye `hits`, `misses`, `hitRate` (porcentaje). Tracking en `CacheManager.get()`.
+- **`get_file_watcher_status` + paths**: Incluye lista de archivos observados (cap 50).
 
 ### Changed
-- **BREAKING**: `extractSymbol` now requires `cache` parameter (injected from caller)
-- **BREAKING**: `WriteResult` interface includes optional `originalHash` field
-- **BREAKING**: `PendingOperation` interface includes optional `originalHash` field
+- `SymbolInfo` interface: añadidos campos opcionales `startLine?: number` y `endLine?: number`.
+- `OPERATION_COSTS`: añadidos costos para `search_symbols` (40), `explain_symbol` (10), `batch_read` (10), `get_rate_limit_status` (1).
+- `CacheManager`: añadidos contadores `hits` y `misses` para tracking de hit rate.
+- `FileWatcher.getStatus()`: retorna `paths: string[]` además de `watchedFiles: number`.
 
 ### Test Results
-- 81/82 tests passing (99% success rate)
-- Memory leak test: ✅ PASSED (no listener accumulation)
-- TOCTOU protection test: ✅ PASSED (hash verification works)
-- Cache injection test: ✅ PASSED (no duplicate instances)
-- 1 flaky performance test (timing variance, not a bug)
-
-### Security
-- ✅ TOCTOU race condition eliminated
-- ✅ Memory leak prevention
-- ✅ Cache corruption prevention
+- 132/132 tests passing (100%)
+- Security tests: ✅ PASSED
+- File lock tests: ✅ PASSED
+- Rate limiter tests: ✅ PASSED
+- WASM parser tests (TS/PHP/Python/Dart): ✅ 47/47 PASSED
+- Backup manager tests: ✅ PASSED
+- Telemetry/streaming/audit tests: ✅ 38/38 PASSED
 
-### Migration from v3.6.0
-- Update calls to `extractSymbol` to pass `cache` parameter
-- No user-facing API changes (internal refactoring only)
-- Rebuild recommended: `npm run rebuild`
+### Migration from v3.6.1
+- Zero breaking changes en la API pública.
+- `parse_file` ahora retorna `startLine`/`endLine` — campos adicionales, no rompe código existente.
+- Phase 2 ya no requiere `newContent`/`code` — parámetros ahora opcionales.
+- 4 nuevas herramientas disponibles automáticamente.
 
 ---
 
-## [3.6.0] - 2026-04-30
+## [3.6.2] - 2026-04-30
 
 ### Added
 
@@ -123,7 +133,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.6.1
+- **Version**: Synchronized all version strings to 3.6.3
 
 ### Performance
 - Streaming I/O for files >5MB (prevents memory exhaustion)
@@ -142,7 +152,7 @@
 - ✅ All security tests passing
 - ✅ All rate limiter tests passing
 - ✅ All file lock tests passing
-- ✅ All v3.6.1 feature tests passing
+- ✅ All v3.6.3 feature tests passing
 - ✅ TypeScript: 0 compilation errors
 - ✅ Build: Clean production dist
 

package/HIRE_ME.md

@@ -1,234 +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 🇻🇪**
+# 💼 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 🇻🇪**