mcp-code-context 2.1.3 → 2.2.0

package/README.md

@@ -3,7 +3,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Tests](https://img.shields.io/badge/tests-passing-success.svg)]()
 [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)]()
-[![Version](https://img.shields.io/badge/version-2.1.1-blue.svg)]()
+[![Version](https://img.shields.io/badge/version-2.2.0-blue.svg)]()
 
 > MCP server that compresses any codebase into LLM-ready semantic context **and provides surgical code editing tools**. AST-based read & write for TypeScript, JavaScript, PHP, Dart & Python.
 
@@ -33,7 +33,7 @@ LLMs working with code face two bottlenecks:
 
 ## The Solution
 
-`mcp-code-context` provides **7 tools** — 3 for reading and 4 for writing — that operate at the **symbol level** (functions, classes, methods). Furthermore, tools support a `className` scope which correctly isolates identical symbol names in the same file (e.g. Flutter `build()` methods) to avoid reading or changing the wrong logic. Read tools extract structural skeletons. Write tools splice changes into the exact AST location.
+`mcp-code-context` provides **11 tools** — 5 for reading, 1 for cleanup, and 5 for writing — that operate at the **symbol level** (functions, classes, methods). Furthermore, tools support a `className` scope which correctly isolates identical symbol names in the same file (e.g. Flutter `build()` methods) to avoid reading or changing the wrong logic. Read tools extract structural skeletons. Write tools splice changes into the exact AST location.
 
 | File | Original | Compressed | Reduction |
 |------|----------|------------|-----------|
@@ -160,18 +160,42 @@ Find all files that depend on a given file.
 - `filePath` (required) — Path to the file being modified
 - `rootDir` (optional) — Repository root (auto-detected)
 
-#### 4. `rollback_file`
+#### 4. `read_file_lines`
+Read specific line ranges from a file without loading the entire content. More efficient than `read_file_surgical` for small fragments.
+- `filePath` (required) — Path to the source file
+- `startLine` (optional) — Starting line number (1-indexed)
+- `endLine` (optional) — Ending line number (1-indexed)
+- `aroundPattern` (optional) — Search pattern to find and return surrounding lines
+- `contextLines` (optional) — Number of lines before/after pattern (default: 5)
+
+#### 5. `search_code_pattern`
+Search for code patterns across multiple files with context. Respects `.gitignore` rules.
+- `rootDir` (required) — Repository root directory
+- `pattern` (required) — Regular expression pattern to search
+- `fileExtensions` (optional) — Array of extensions to search (e.g., `[".ts", ".dart"]`)
+- `excludeDirs` (optional) — Directories to exclude (default: `["node_modules", "dist", "build"]`)
+- `showContext` (optional) — Include surrounding lines (default: true)
+- `contextLines` (optional) — Number of context lines (default: 3)
+- `maxResults` (optional) — Maximum matches to return (default: 50)
+
+#### 6. `rollback_file`
 Surgically restore a file to a previous state from the automated backup system.
 - `filePath` (required) — Path to the file to restore
 - `steps` (optional) — Number of versions to go back (1-5, default: 1)
 
+#### 7. `clean_backups`
+Remove all backup files for a project to keep the working directory clean.
+- `projectRoot` (required) — Absolute path to the project root
+
+**Note:** Backups are stored centrally at `[project-root]/.mcp-backups/` to keep your project organized.
+
 ### Write Tools (Phase 1: Preview)
 
 All write tools follow a **Two-Phase Workflow**:
 1. **Call without token**: Returns a unified `diff` and a `confirmationToken`.
 2. **Call with token**: Set `confirm: true` and provide the token to apply the changes.
 
-#### 5. `write_file_surgical`
+#### 7. `write_file_surgical`
 Replace the full source code of a named symbol in a file.
 - `filePath` (required) — Path to the file
 - `symbolName` (required) — Symbol to replace
@@ -180,7 +204,7 @@ Replace the full source code of a named symbol in a file.
 - `confirm` (optional) — Set to `true` to apply
 - `className` (optional) — Scope the symbol to a specific class
 
-#### 5. `insert_symbol`
+#### 8. `insert_symbol`
 Insert new code at a precise location relative to an existing symbol.
 - `filePath` (required) — Path to the file
 - `code` (required) — Code to insert
@@ -189,7 +213,7 @@ Insert new code at a precise location relative to an existing symbol.
 - `className` (optional) — Scope the anchor to a specific class
 - `confirmationToken`, `confirm` (optional)
 
-#### 6. `rename_symbol`
+#### 9. `rename_symbol`
 Rename a symbol across the entire repository (definition + all usages).
 - `filePath` (required) — File where the symbol is defined
 - `oldName` (required) — Current name
@@ -197,7 +221,7 @@ Rename a symbol across the entire repository (definition + all usages).
 - `rootDir` (optional) — Repository root
 - `confirmationToken`, `confirm` (optional)
 
-#### 7. `remove_symbol`
+#### 10. `remove_symbol`
 Safely remove a symbol from a file with dependency checking.
 - `filePath` (required) — Path to the file
 - `symbolName` (required) — Symbol to remove

package/RELEASE_NOTES_v2.2.0.md

@@ -0,0 +1,286 @@
+# 🚀 Release v2.2.0 - Centralized Backup System + New Read Tools
+
+**Release Date:** April 22, 2026  
+**Type:** Minor Release (New Features + Improvements)
+
+---
+
+## 🎯 What's New
+
+### 1. 📖 **New Read Tools** (Token Efficiency Champions)
+
+#### `read_file_lines` - Surgical Line Reading
+Read specific line ranges or search around patterns without loading entire files.
+
+**Use Cases:**
+- Debug specific code blocks
+- View error context from stack traces
+- Inspect method implementations without full file overhead
+
+**Token Savings:** ~90% compared to reading full files
+
+**Examples:**
+```typescript
+// Read exact range
+read_file_lines({
+  filePath: "/project/src/utils.ts",
+  startLine: 120,
+  endLine: 135
+})
+
+// Search around pattern
+read_file_lines({
+  filePath: "/project/src/service.ts",
+  aroundPattern: "calculateTotal",
+  contextLines: 5
+})
+```
+
+#### `search_code_pattern` - Repository-Wide Pattern Search
+Find patterns across your codebase with context, respecting `.gitignore`.
+
+**Use Cases:**
+- Find all usages of a function
+- Locate TODO comments
+- Search for specific patterns with context
+
+**Token Savings:** ~85% compared to manual grep workflows
+
+**Examples:**
+```typescript
+search_code_pattern({
+  rootDir: "/project",
+  pattern: "widget\\.height",
+  fileExtensions: [".dart"],
+  showContext: true,
+  maxResults: 20
+})
+```
+
+---
+
+### 2. 🧹 **Centralized Backup System** (Major Improvement)
+
+**Problem Solved:** Backups were scattered throughout projects, polluting git status and creating multiple `.mcp-backups/` folders.
+
+**Solution:** ONE centralized backup directory at project root.
+
+#### Before (v2.1.x):
+```
+project/
+├── lib/
+│   ├── screens/
+│   │   └── .mcp-backups/  ❌
+│   └── services/
+│       └── .mcp-backups/  ❌
+└── src/
+    └── .mcp-backups/      ❌
+```
+
+#### After (v2.2.0):
+```
+project/
+├── .mcp-backups/          ✅ ONE directory
+│   ├── lib/
+│   │   ├── screens/
+│   │   └── services/
+│   └── src/
+├── lib/
+├── services/
+└── src/
+```
+
+**Benefits:**
+- ✅ Clean git status
+- ✅ Easy to clean all backups at once
+- ✅ Preserves internal folder structure
+- ✅ Backward compatible
+
+#### `clean_backups` - New Cleanup Tool
+Remove all backups with a single command.
+
+```typescript
+clean_backups({
+  projectRoot: "/path/to/project"
+})
+```
+
+---
+
+## 📊 Technical Improvements
+
+### Test Coverage
+- **148 tests passing** (100% success rate)
+  - 35 Dart compression tests
+  - 33 PHP compression tests
+  - 59 Surgical writing tests
+  - 7 New tools tests
+  - 7 Backup system tests
+  - 7 Integration tests
+
+### Performance
+- `read_file_lines`: 90% token reduction vs full file reads
+- `search_code_pattern`: 85% more efficient than manual grep
+- Centralized backups: 0 scattered directories
+
+### Reliability
+- Comprehensive error handling
+- Edge case coverage (deep nesting, non-existent paths)
+- Backward compatible with legacy backup locations
+
+---
+
+## 🛠️ All Tools (11 Total)
+
+### Read Tools (5)
+1. `get_semantic_repo_map` - Repository structure overview
+2. `read_file_surgical` - Extract specific symbols
+3. `analyze_impact` - Find dependencies
+4. **`read_file_lines`** - Read line ranges ⭐ NEW
+5. **`search_code_pattern`** - Search with context ⭐ NEW
+
+### Cleanup Tools (1)
+6. **`clean_backups`** - Remove all backups ⭐ NEW
+
+### Write Tools (5)
+7. `write_file_surgical` - Replace symbols
+8. `insert_symbol` - Insert code precisely
+9. `rename_symbol` - Rename across repository
+10. `remove_symbol` - Safe symbol removal
+11. `rollback_file` - Undo changes
+
+---
+
+## 📦 Installation
+
+### NPM (Recommended)
+```bash
+npm install -g mcp-code-context@2.2.0
+```
+
+### From Source
+```bash
+git clone https://github.com/achatainga/mcp-code-context.git
+cd mcp-code-context
+git checkout v2.2.0
+npm install
+npm run build
+```
+
+---
+
+## ⚙️ Configuration
+
+### Amazon Q / VS Code / Cursor
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "code-context": {
+      "command": "npx",
+      "args": ["-y", "mcp-code-context@2.2.0"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "code-context": {
+      "command": "npx",
+      "args": ["-y", "mcp-code-context@2.2.0"]
+    }
+  }
+}
+```
+
+---
+
+## 🔄 Migration from v2.1.x
+
+### Automatic Migration
+No action needed! The new backup system:
+- ✅ Automatically uses centralized location for new backups
+- ✅ Still reads legacy backup locations
+- ✅ No breaking changes
+
+### Optional Cleanup
+Clean old scattered backups:
+
+```bash
+# Find old backup directories
+find . -type d -name ".mcp-backups" -not -path "./.mcp-backups"
+
+# Remove them (after verifying)
+find . -type d -name ".mcp-backups" -not -path "./.mcp-backups" -exec rm -rf {} +
+```
+
+---
+
+## 🐛 Bug Fixes
+
+- Fixed backup directory pollution in git status
+- Improved error messages for non-existent paths
+- Better handling of deeply nested file structures
+
+---
+
+## 📚 Documentation
+
+- [README.md](README.md) - Complete tool documentation
+- [CHANGELOG.md](CHANGELOG.md) - Detailed change history
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
+- [llms.txt](llms.txt) - AI-optimized documentation
+
+---
+
+## 🙏 Acknowledgments
+
+This release was built based on real-world debugging experience with:
+- Flutter/Dart projects (DeTodo24 mobile app)
+- WordPress/PHP backends (dt24-home-engine)
+- Complex multi-repository architectures
+
+Special thanks to the community for feedback and testing.
+
+---
+
+## 📈 What's Next (v2.3.0)
+
+Planned features:
+- `extract_json_value` - Parse JSON responses efficiently
+- Enhanced `get_semantic_repo_map` with file limits
+- Support for more languages (Go, Rust, Java)
+- Performance optimizations for large repositories
+
+---
+
+## 🔗 Links
+
+- **GitHub:** https://github.com/achatainga/mcp-code-context
+- **NPM:** https://www.npmjs.com/package/mcp-code-context
+- **Issues:** https://github.com/achatainga/mcp-code-context/issues
+- **Discussions:** https://github.com/achatainga/mcp-code-context/discussions
+
+---
+
+## 📄 License
+
+MIT License - See [LICENSE](LICENSE) for details
+
+---
+
+**Full Changelog:** https://github.com/achatainga/mcp-code-context/compare/v2.1.3...v2.2.0
+
+---
+
+*Built with ❤️ for the AI-assisted development community*
+
+**Version:** 2.2.0  
+**Released:** April 22, 2026  
+**Tested:** 148/148 tests passing ✅

package/dist/src/index.d.ts

@@ -115,3 +115,39 @@ export declare function handleRollbackFile(args: Record<string, unknown>): Promi
         text: string;
     }[];
 }>;
+export declare function handleCleanBackups(args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleReadFileLines(args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function handleSearchCodePattern(args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/src/index.js

@@ -26,14 +26,16 @@ import { IgnoreManager } from "./utils/ignoreManager.js";
 import { compressFile, extractSymbol } from "./ast/semanticCompressor.js";
 import { replaceSymbol, insertCode, renameInFile, renameReferencesInFile, removeSymbolFromFile, WRITABLE_EXTENSIONS, } from "./ast/writers/symbolWriter.js";
 import { generateDiff, generateMultiFileDiff } from "./utils/diffEngine.js";
-import { createBackup, restoreBackup } from "./utils/backupManager.js";
+import { createBackup, restoreBackup, cleanAllBackups } from "./utils/backupManager.js";
 import { extractFallbackSymbols, findClosestSymbols } from "./utils/fuzzyMatch.js";
 import { confirmationCache } from "./utils/confirmationCache.js";
+import { readFileLines } from "./tools/readFileLines.js";
+import { searchCodePattern } from "./tools/searchCodePattern.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 // ─── Constants ──────────────────────────────────────────────────────
 const SERVER_NAME = "mcp-code-context";
-const SERVER_VERSION = "2.0.0";
+const SERVER_VERSION = "2.2.0";
 /** Extensions we consider source code for analysis */
 const SOURCE_EXTENSIONS = new Set([
     ".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs", ".cts", ".cjs",
@@ -136,6 +138,104 @@ const TOOLS = [
             required: ["filePath"],
         },
     },
+    {
+        name: "clean_backups",
+        description: "Removes all backup files for a project. Deletes the entire .mcp-backups directory " +
+            "at the project root, freeing up disk space and cleaning the working directory. " +
+            "Use this to clean up after completing a series of edits or when backups are no longer needed.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectRoot: {
+                    type: "string",
+                    description: "Absolute path to the project root directory. The .mcp-backups folder " +
+                        "at this location will be removed.",
+                },
+            },
+            required: ["projectRoot"],
+        },
+    },
+    {
+        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",
+            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",
+            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"],
+        },
+    },
     {
         name: "analyze_impact",
         description: "Analyzes the impact of modifying a given file by discovering all other " +
@@ -363,6 +463,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await handleRemoveSymbol(args);
             case "rollback_file":
                 return await handleRollbackFile(args);
+            case "clean_backups":
+                return await handleCleanBackups(args);
+            case "read_file_lines":
+                return await handleReadFileLines(args);
+            case "search_code_pattern":
+                return await handleSearchCodePattern(args);
             default:
                 return errorResponse(`Unknown tool: "${name}"`);
         }
@@ -1267,6 +1373,96 @@ export async function handleRollbackFile(args) {
             }],
     };
 }
+export async function handleCleanBackups(args) {
+    const projectRoot = args.projectRoot;
+    if (!projectRoot)
+        return errorResponse("Missing required parameter: projectRoot");
+    const resolvedPath = path.resolve(projectRoot);
+    if (!fs.existsSync(resolvedPath)) {
+        return errorResponse(`Project root not found: ${resolvedPath}`);
+    }
+    const success = cleanAllBackups(resolvedPath);
+    if (!success) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `// ℹ️ No backups found\n// No .mcp-backups directory exists at: ${resolvedPath}`,
+                }],
+        };
+    }
+    return {
+        content: [{
+                type: "text",
+                text: `// 🧹 Cleanup successful!\n// Removed all backups from: ${resolvedPath}/.mcp-backups\n// Your project is now clean.`,
+            }],
+    };
+}
+// ─── Tool: read_file_lines ──────────────────────────────────────────
+export async function handleReadFileLines(args) {
+    const result = readFileLines(args);
+    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",
+                text: header + content,
+            },
+        ],
+    };
+}
+// ─── Tool: search_code_pattern ──────────────────────────────────────
+export async function handleSearchCodePattern(args) {
+    const result = searchCodePattern(args);
+    if (!result.success) {
+        return errorResponse(result.error || "Unknown error searching code");
+    }
+    const { matches, totalMatches } = result;
+    if (!matches || matches.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `# Search Results\n\nNo matches found for pattern: "${args.pattern}"`,
+                },
+            ],
+        };
+    }
+    const lines = [
+        `# 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",
+                text: lines.join("\n"),
+            },
+        ],
+    };
+}
 function errorResponse(message) {
     return {
         content: [{ type: "text", text: `❌ ${message}` }],