mcp-code-context 2.2.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-code-context",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Powerful MCP server for LLM-ready semantic code context and surgical AST-aware editing. Supports TypeScript, JavaScript, PHP, Dart, and Python.",
   "type": "module",
   "main": "dist/src/index.js",
@@ -11,7 +11,7 @@
     "build": "tsc",
     "start": "node dist/src/index.js",
     "dev": "tsc && node dist/src/index.js",
-    "test": "npm run build && node dist/tests/test-dart.js && node dist/tests/test-php.js && node dist/tests/writers/test-write-smoke.js && node dist/tests/test-new-tools.js && node dist/tests/test-backup-system.js",
+    "test": "npm run build && node dist/tests/test-dart.js && node dist/tests/test-php.js && node dist/tests/writers/test-write-smoke.js && node dist/tests/test-new-tools.js && node dist/tests/test-backup-system.js && node dist/tests/test-rename-limitations.js",
     "clean": "rimraf dist",
     "rebuild": "npm run clean && npm run build"
   },
@@ -44,12 +44,12 @@
     "@modelcontextprotocol/sdk": "^1.12.0",
     "ignore": "^6.0.2",
     "php-parser": "^3.5.1",
-    "ts-morph": "^24.0.0"
+    "ts-morph": "^24.0.0",
+    "typescript": "^5.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.7.0"
+    "rimraf": "^6.0.1"
   },
   "engines": {
     "node": ">=18.0.0"

package/AGENT_INSTRUCTIONS.md

@@ -1,135 +0,0 @@
-# Smart Code Analysis & Editing Tools
-**Available tools for efficient code analysis, context management, and surgical code modification.**
-
-## Read Tools
-
-### 1. `get_semantic_repo_map` — Architectural Map
-**When to use**: At the start of a session, before a major refactor, or when you need to understand a new codebase or directory structure.
-**NEVER use**: For reading specific implementations — this tool extracts ONLY structural signatures (classes, functions), not the code bodies.
-```ts
-get_semantic_repo_map(directoryPath: "/path/to/project/src", format: "markdown")
-```
-
-### 2. `read_file_surgical` — Surgical Reading
-**When to use**: When you need a specific method, class, or symbol. ALWAYS prefer this over reading the entire file (like `fsRead`) if the symbol name is known.
-**NEVER use**: For reading complete files if you only need a single function or symbol.
-```ts
-read_file_surgical(filePath: "/path/to/file.ts", symbolName: "ClassName")
-read_file_surgical(filePath: "/path/to/file.dart", symbolName: "WidgetName")
-// Omitting symbolName will read the entire file
-read_file_surgical(filePath: "/path/to/file.php")
-```
-- If the symbol is not found, the tool returns a **structured JSON error** with `available_symbols` and `suggestions` (e.g., if a `className` scope is missing but the symbol exists in a class).
-- **Pro-tip**: Use the suggestions to fix your next tool call (e.g., adding the correct `className`).
-
-### 3. `analyze_impact` — Blast Radius Detection
-**When to use**: ALWAYS before modifying a file that might be imported or depended upon by other parts of the system.
-**NEVER use**: Ignore or skip this step when refactoring shared services, utilities, or core components.
-**Features**: Detects imports across ecosystems (e.g., `use Namespace\Class` in PHP, `import` in JS/TS/Dart/Python).
-```ts
-analyze_impact(filePath: "/path/to/project/src/services/MyService.ts")
-analyze_impact(filePath: "/path/to/project/src/Services/GeoIPService.php")
-analyze_impact(filePath: "/path/to/detodo24_mobile/lib/services/tracking_service.dart")
-```
-
----
-
-## Write Tools
-
-### Mandatory Two-Phase Write Workflow (v2.1.1+)
-
-All write tools (`write_file_surgical`, `insert_symbol`, `rename_symbol`, `remove_symbol`) now enforce a safety-first confirmation flow.
-
-**Phase 1: Dry-Run / Preview**
-Call the tool with your proposed changes. You will receive:
-1. A unified `diff` of the proposed changes.
-2. A `confirmationToken`.
-
-**Phase 2: Confirmation**
-To apply the changes, call the SAME tool again with:
-1. `confirmationToken`: The token from Phase 1.
-2. `confirm: true`.
-
----
-
-### 4. `write_file_surgical` — Surgical Symbol Replacement
-**When to use**: Replace a specific function, method, class, or interface.
-**Phase 1 (Preview)**:
-```ts
-write_file_surgical(filePath: "/path/to/file.ts", symbolName: "processOrder", newContent: "...")
-```
-**Phase 2 (Apply)**:
-```ts
-write_file_surgical(filePath: "/path/to/file.ts", symbolName: "processOrder", confirmationToken: "TOKEN_FROM_P1", confirm: true)
-```
-
-### 5. `insert_symbol` — Precise Code Insertion
-**When to use**: Adding new members relative to an existing anchor symbol.
-**Phase 1 (Preview)**:
-```ts
-insert_symbol(filePath: "/path/to/file.dart", code: "void clear() { ... }", anchorSymbol: "getUser", position: "after")
-```
-**Phase 2 (Apply)**:
-```ts
-insert_symbol(filePath: "/path/to/file.dart", code: "void clear() { ... }", confirmationToken: "TOKEN_FROM_P1", confirm: true)
-```
-
-### 6. `rename_symbol` — Repository-Wide Rename
-**When to use**: Atomic identifier renaming across the entire project.
-**Phase 1 (Preview)**:
-```ts
-rename_symbol(filePath: "/path/to/UserService.ts", oldName: "UserService", newName: "AccountService")
-```
-**Phase 2 (Apply)**:
-```ts
-rename_symbol(filePath: "/path/to/UserService.ts", oldName: "UserService", newName: "AccountService", confirmationToken: "TOKEN_FROM_P1", confirm: true)
-```
-
-### 7. `remove_symbol` — Safe Symbol Deletion
-**When to use**: Removing code with dependency checking.
-**Phase 1 (Preview)**:
-```ts
-remove_symbol(filePath: "/path/to/file.ts", symbolName: "deprecatedHelper")
-```
-**Phase 2 (Apply)**:
-```ts
-remove_symbol(filePath: "/path/to/file.ts", symbolName: "deprecatedHelper", confirmationToken: "TOKEN_FROM_P1", confirm: true)
-```
-- **Safety**: Safe removal check happens in Phase 1. If dependents exist, use `force: true` in your next Phase 1 call to override.
-
-### 8. `rollback_file` — Surgical Restoration
-**When to use**: If an applied change introduces an unexpected error or side effect.
-**Safety**: The server automatically keeps the last 5 versions in `.mcp-backups/`.
-```ts
-rollback_file(filePath: "/path/to/file.ts", steps: 1)
-```
-
-### 7. `remove_symbol` — Safe Symbol Deletion
-**When to use**: When removing a function, method, or class from a file.
-**Safety**: By default, checks for dependents and **refuses** to remove if other files reference it.
-```ts
-// Safe removal (checks dependents first)
-remove_symbol(filePath: "/path/to/file.ts", symbolName: "deprecatedHelper")
-// Force removal (skip dependency check)
-remove_symbol(filePath: "/path/to/file.php", symbolName: "oldMethod", force: true)
-```
-
----
-
-## Mandatory Workflow
-1. **New Session / Unknown Context** → Use `get_semantic_repo_map` on the relevant directory to understand the structure.
-2. **Read Code** → Use `read_file_surgical` with a `symbolName` whenever possible.
-3. **Handle Missing Symbols** → If you get a JSON error, use the `suggestions` to refine your `symbolName` or `className`.
-4. **Before Modifying** → Use `analyze_impact` if the file is a shared module or component.
-5. **Modify Code (Phase 1)** → Use write tools to generate a `diff` and `confirmationToken`.
-6. **Verify Diff** → Read the diff carefully. If incorrect, correct your prompt and start Phase 1 again.
-7. **Apply (Phase 2)** → Call the same write tool with the token and `confirm: true`.
-8. **Verify Result** → Ensure nothing broke. Use `rollback_file` if needed.
-
-## Supported Languages (Read + Write)
-| Language | Read | Write | Engine |
-|----------|------|-------|--------|
-| TypeScript / JavaScript | ✅ | ✅ | AST (ts-morph) |
-| PHP | ✅ | ✅ | AST (php-parser) |
-| Dart | ✅ | ✅ | Brace-counting + regex |
-| Python | ✅ | ✅ | Indentation-based |

package/DEPLOYMENT_INSTRUCTIONS.md

@@ -1,110 +0,0 @@
-# Deployment Instructions for v2.1.3
-
-## ✅ Completed Steps
-1. ✅ Code fixes implemented and tested
-2. ✅ Version bumped to 2.1.3 in package.json
-3. ✅ CHANGELOG.md updated
-4. ✅ TROUBLESHOOTING.md updated
-5. ✅ llms.txt updated
-6. ✅ Test suite created and passing (11/11 tests)
-7. ✅ Git commit created with semantic message
-8. ✅ Git tag v2.1.3 created with release notes
-9. ✅ Pushed to GitHub (main branch + tag)
-
-## 🚀 Next Steps (Manual)
-
-### 1. Publish to npm
-You need to be logged in to npm. Run:
-
-```bash
-cd C:\code\antigravity-mcp-context
-
-# Login to npm (if not already)
-npm login
-
-# Publish the package
-npm publish
-
-# Verify publication
-npm view mcp-code-context@2.1.3
-```
-
-### 2. Create GitHub Release
-Go to: https://github.com/achatainga/mcp-code-context/releases/new
-
-- **Tag**: Select `v2.1.3` (already pushed)
-- **Title**: `v2.1.3 - Windows CRLF & Parameter Brace Fixes`
-- **Description**: Copy content from `RELEASE_NOTES_v2.1.3.md`
-- **Attach files**: None needed (npm package is the artifact)
-- Click **Publish release**
-
-### 3. Verify Installation
-Test that users can install the new version:
-
-```bash
-# Global install
-npm install -g mcp-code-context@2.1.3
-
-# Verify version
-npx mcp-code-context --version  # Should show 2.1.3
-
-# Test with MCP client (Claude Desktop, Amazon Q, etc.)
-# Update config to use @2.1.3 and restart client
-```
-
-### 4. Announce (Optional)
-Consider announcing on:
-- GitHub Discussions
-- Twitter/X
-- Reddit (r/LocalLLaMA, r/ClaudeAI)
-- Discord communities
-
-## 📋 Verification Checklist
-
-Before announcing:
-- [ ] npm package published successfully
-- [ ] GitHub release created
-- [ ] Can install via `npm install -g mcp-code-context@2.1.3`
-- [ ] Version shows correctly in `package.json`
-- [ ] Tag visible on GitHub releases page
-- [ ] CHANGELOG.md shows v2.1.3 entry
-- [ ] Tests passing on CI (if configured)
-
-## 🐛 Rollback Plan (If Needed)
-
-If critical issues are discovered:
-
-```bash
-# Unpublish from npm (within 72 hours)
-npm unpublish mcp-code-context@2.1.3
-
-# Delete GitHub release
-# Go to releases page and delete v2.1.3
-
-# Delete git tag
-git tag -d v2.1.3
-git push origin :refs/tags/v2.1.3
-
-# Revert commit
-git revert f0bfcfe
-git push origin main
-```
-
-## 📊 Monitoring
-
-After release, monitor:
-- npm download stats: https://npm-stat.com/charts.html?package=mcp-code-context
-- GitHub issues for bug reports
-- GitHub stars/forks for adoption
-
-## 🎉 Success Criteria
-- No critical bugs reported within 48 hours
-- Windows users confirm CRLF issues resolved
-- Download count increases
-- Positive feedback from users
-
----
-
-**Current Status**: Ready for npm publish and GitHub release creation
-**Blocked By**: npm authentication required
-**Next Action**: Run `npm login` then `npm publish`

package/MEJORAS_PROPUESTAS.md

@@ -1,324 +0,0 @@
-# 🚀 Antigravity MCP - Mejoras Propuestas
-
-## 📋 Resumen
-
-Basado en la experiencia real de debugging en DeTodo24, se identificaron limitaciones en las herramientas AST actuales y se proponen 2 nuevas herramientas para mejorar la eficiencia.
-
----
-
-## ✅ Nuevas Herramientas Implementadas
-
-### 1. `read_file_lines` ⭐ **ALTA PRIORIDAD**
-
-**Ubicación:** `src/tools/readFileLines.ts`
-
-**Propósito:** Leer rangos específicos de líneas sin cargar el archivo completo.
-
-**Casos de uso:**
-- Ver líneas 120-135 de un archivo
-- Ver ±5 líneas alrededor de un patrón (ej: "HeroBannerWidget")
-- Debugging rápido sin consumir tokens del archivo completo
-
-**Ahorro estimado:** 90% vs `read_file_surgical` para fragmentos pequeños
-
-**Ejemplo de uso:**
-```typescript
-// Modo 1: Rango exacto
-read_file_lines({
-  filePath: "/path/to/file.dart",
-  startLine: 120,
-  endLine: 135
-})
-
-// Modo 2: Alrededor de patrón
-read_file_lines({
-  filePath: "/path/to/file.dart",
-  aroundPattern: "HeroBannerWidget",
-  contextLines: 5
-})
-```
-
----
-
-### 2. `search_code_pattern` ⭐ **ALTA PRIORIDAD**
-
-**Ubicación:** `src/tools/searchCodePattern.ts`
-
-**Propósito:** Buscar patrones de código en múltiples archivos con contexto.
-
-**Casos de uso:**
-- Buscar todas las ocurrencias de "widget.height"
-- Encontrar logs específicos (ej: "🎯 [BUILDER]")
-- Buscar imports o referencias a símbolos
-
-**Ahorro estimado:** 85% vs grep manual + análisis
-
-**Ejemplo de uso:**
-```typescript
-search_code_pattern({
-  rootDir: "/project",
-  pattern: "widget\\.height",
-  fileExtensions: [".dart", ".ts"],
-  showContext: true,
-  contextLines: 3,
-  maxResults: 20
-})
-```
-
----
-
-## 🔧 Pasos para Integración
-
-### 1. Agregar definiciones de herramientas en `src/index.ts`
-
-Insertar en el array `TOOLS` (después de `rollback_file`):
-
-```typescript
-{
-  name: "read_file_lines",
-  description:
-    "Reads specific line ranges from a file without loading the entire content. " +
-    "Supports reading by exact line range (startLine/endLine) or around a pattern match. " +
-    "More efficient than read_file_surgical when you only need a small fragment of code. " +
-    "Perfect for debugging, viewing specific code blocks, or extracting context around errors.",
-  inputSchema: {
-    type: "object" as const,
-    properties: {
-      filePath: {
-        type: "string",
-        description: "Absolute path to the source file to read.",
-      },
-      startLine: {
-        type: "number",
-        description: "Starting line number (1-indexed). Required if using exact range mode.",
-      },
-      endLine: {
-        type: "number",
-        description: "Ending line number (1-indexed). Required if using exact range mode.",
-      },
-      aroundPattern: {
-        type: "string",
-        description:
-          "Search pattern to find in the file. Returns lines around the first match. " +
-          "Use this mode when you don't know the exact line numbers.",
-      },
-      contextLines: {
-        type: "number",
-        description:
-          "Number of lines to include before and after the pattern match. " +
-          "Defaults to 5. Only used with aroundPattern mode.",
-      },
-    },
-    required: ["filePath"],
-  },
-},
-{
-  name: "search_code_pattern",
-  description:
-    "Searches for code patterns across multiple files in a repository. " +
-    "Returns matches with file paths, line numbers, and optional context lines. " +
-    "Respects .gitignore rules and allows filtering by file extensions. " +
-    "More efficient than manual grep when you need structured results with context.",
-  inputSchema: {
-    type: "object" as const,
-    properties: {
-      rootDir: {
-        type: "string",
-        description: "Absolute path to the repository root directory to search.",
-      },
-      pattern: {
-        type: "string",
-        description:
-          "Regular expression pattern to search for. Use proper regex escaping " +
-          "(e.g., 'widget\\\\.height' to match 'widget.height').",
-      },
-      fileExtensions: {
-        type: "array",
-        items: { type: "string" },
-        description:
-          "Array of file extensions to search (e.g., ['.ts', '.dart', '.py']). " +
-          "Defaults to common code extensions if omitted.",
-      },
-      excludeDirs: {
-        type: "array",
-        items: { type: "string" },
-        description:
-          "Array of directory names to exclude (e.g., ['node_modules', 'dist']). " +
-          "Defaults to common build/dependency directories.",
-      },
-      showContext: {
-        type: "boolean",
-        description: "If true, includes surrounding lines for each match. Defaults to true.",
-      },
-      contextLines: {
-        type: "number",
-        description: "Number of context lines before/after each match. Defaults to 3.",
-      },
-      maxResults: {
-        type: "number",
-        description: "Maximum number of matches to return. Defaults to 50.",
-      },
-    },
-    required: ["rootDir", "pattern"],
-  },
-},
-```
-
-### 2. Agregar imports en `src/index.ts`
-
-Después de los imports existentes:
-
-```typescript
-import { readFileLines } from "./tools/readFileLines.js";
-import { searchCodePattern } from "./tools/searchCodePattern.js";
-```
-
-### 3. Agregar handlers en el switch del dispatcher
-
-En la función `server.setRequestHandler(CallToolRequestSchema, ...)`, agregar:
-
-```typescript
-case "read_file_lines":
-  return await handleReadFileLines(args as Record<string, unknown>);
-case "search_code_pattern":
-  return await handleSearchCodePattern(args as Record<string, unknown>);
-```
-
-### 4. Implementar los handlers
-
-Agregar al final del archivo (antes de `// ─── Bootstrap`):
-
-```typescript
-// ─── Tool: read_file_lines ──────────────────────────────────────────
-
-export async function handleReadFileLines(args: Record<string, unknown>) {
-  const result = readFileLines(args as any);
-
-  if (!result.success) {
-    return errorResponse(result.error || "Unknown error reading file lines");
-  }
-
-  const { content, lineRange } = result;
-  const header = lineRange
-    ? `// Lines ${lineRange.start}-${lineRange.end}\n// File: ${args.filePath}\n\n`
-    : `// File: ${args.filePath}\n\n`;
-
-  return {
-    content: [
-      {
-        type: "text" as const,
-        text: header + content,
-      },
-    ],
-  };
-}
-
-// ─── Tool: search_code_pattern ──────────────────────────────────────
-
-export async function handleSearchCodePattern(args: Record<string, unknown>) {
-  const result = searchCodePattern(args as any);
-
-  if (!result.success) {
-    return errorResponse(result.error || "Unknown error searching code");
-  }
-
-  const { matches, totalMatches } = result;
-
-  if (!matches || matches.length === 0) {
-    return {
-      content: [
-        {
-          type: "text" as const,
-          text: `# Search Results\n\nNo matches found for pattern: "${args.pattern}"`,
-        },
-      ],
-    };
-  }
-
-  const lines: string[] = [
-    `# Search Results`,
-    ``,
-    `**Pattern:** \`${args.pattern}\``,
-    `**Root:** \`${args.rootDir}\``,
-    `**Matches:** ${totalMatches} (showing ${matches.length})`,
-    ``,
-  ];
-
-  for (const match of matches) {
-    lines.push(`## \`${match.file}\` (line ${match.lineNumber})`);
-    lines.push(``);
-
-    if (match.context) {
-      lines.push("```");
-      lines.push(...match.context);
-      lines.push("```");
-    } else {
-      lines.push(`\`\`\`\n${match.line}\n\`\`\``);
-    }
-
-    lines.push(``);
-  }
-
-  return {
-    content: [
-      {
-        type: "text" as const,
-        text: lines.join("\n"),
-      },
-    ],
-  };
-}
-```
-
-### 5. Compilar y probar
-
-```bash
-cd C:\code\antigravity-mcp-context
-npm run build
-```
-
-### 6. Actualizar versión
-
-En `src/index.ts`, cambiar:
-```typescript
-const SERVER_VERSION = "2.2.0"; // Era "2.0.0"
-```
-
----
-
-## 📊 Comparación de Eficiencia
-
-| Tarea | Herramienta Actual | Nueva Herramienta | Ahorro |
-|-------|-------------------|-------------------|--------|
-| Ver líneas 120-135 | `read_file_surgical` (2500 tokens) | `read_file_lines` (200 tokens) | 92% |
-| Buscar patrón en 50 archivos | `grep` manual + análisis | `search_code_pattern` | 85% |
-| Ver contexto de error | Leer archivo completo | `read_file_lines` con `aroundPattern` | 90% |
-
----
-
-## 🎯 Beneficios Clave
-
-1. **Menor consumo de tokens:** 60-90% de ahorro en operaciones de lectura
-2. **Debugging más rápido:** Acceso directo a fragmentos específicos
-3. **Búsqueda estructurada:** Resultados con contexto automático
-4. **Compatibilidad total:** Se integra con herramientas AST existentes
-
----
-
-## 📝 Notas de Implementación
-
-- ✅ `.mcp-backups/` ya está en `.gitignore` (línea 31)
-- ✅ Ambas herramientas respetan `.gitignore` usando `IgnoreManager`
-- ✅ Manejo de errores consistente con herramientas existentes
-- ✅ TypeScript types completos
-
----
-
-## 🚀 Próximos Pasos
-
-1. Integrar las herramientas siguiendo los pasos anteriores
-2. Compilar y probar con `npm run build`
-3. Recargar Amazon Q para detectar las nuevas herramientas
-4. Documentar en CHANGELOG.md
-
-**Tiempo estimado de integración:** 15-20 minutos

package/RELEASE_NOTES_v2.1.3.md

@@ -1,78 +0,0 @@
-# Release v2.1.3 - Windows CRLF & Parameter Brace Fixes
-
-## 🎯 Overview
-This release completely resolves false brace imbalance errors on Windows systems and fixes a critical bug with Dart method parameters containing braces.
-
-## ✨ What's Fixed
-
-### Windows CRLF Support (Complete Resolution)
-- ✅ All Dart writer functions now normalize `\r\n` to `\n` before processing
-- ✅ No more false "unbalanced braces" errors on Windows files
-- ✅ Consistent behavior across Windows, macOS, and Linux
-- ✅ Helper functions (`hasBraceBalance`, `reindentCode`) also normalize line endings
-
-### Method Parameter Brace Handling
-- ✅ Fixed critical bug where braces in method parameters (e.g., `{int? cart}`) were incorrectly counted as method body braces
-- ✅ `findMatchingBraceStateAware` now tracks closing parenthesis to identify method body start
-- ✅ Correctly handles Dart named parameters, optional parameters, and destructuring syntax
-
-## 🧪 Testing
-- **11 new test cases** covering:
-  - CRLF line endings
-  - Mixed CRLF/LF line endings
-  - Methods with braces in parameters
-  - All write operations (replace, insert, rename, remove)
-- **100% test pass rate** on Windows 11
-
-## 📝 Changes
-
-### Modified Files
-- `src/ast/writers/dartWriter.ts` - Core CRLF normalization and parameter brace detection
-- `package.json` - Version bump to 2.1.3
-- `CHANGELOG.md` - Detailed release notes
-- `TROUBLESHOOTING.md` - Marked CRLF issue as resolved
-- `llms.txt` - Updated for LLM consumption
-
-### New Files
-- `tests/writers/test-crlf-handling.ts` - Comprehensive CRLF test suite
-
-## 🔄 Migration Guide
-No breaking changes. Simply update:
-
-```bash
-npm install -g mcp-code-context@2.1.3
-```
-
-Or in your MCP client config:
-```json
-{
-  "mcpServers": {
-    "code-context": {
-      "command": "npx",
-      "args": ["-y", "mcp-code-context@2.1.3"]
-    }
-  }
-}
-```
-
-## 🐛 Bug Reports Resolved
-- Windows CRLF false positive errors
-- Parameter brace detection in Dart methods
-- Mixed line ending handling
-
-## 📊 Impact
-- **Platforms affected**: Windows (primary), all platforms benefit from improved robustness
-- **Languages affected**: Dart (primary fix), all languages benefit from CRLF normalization
-- **Backward compatible**: Yes, no breaking changes
-
-## 🙏 Credits
-Special thanks to the Amazon Q Developer user who reported the Windows CRLF bug with detailed reproduction steps.
-
-## 📚 Documentation
-- [CHANGELOG.md](./CHANGELOG.md) - Full version history
-- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) - Known issues and solutions
-- [README.md](./README.md) - Complete usage guide
-
----
-
-**Full Changelog**: https://github.com/achatainga/mcp-code-context/compare/v2.1.2...v2.1.3