mcp-code-context 2.1.3 → 2.2.0

package/src/index.ts

@@ -40,16 +40,18 @@ import {
   type InsertPosition,
 } from "./ast/writers/symbolWriter.js";
 import { generateDiff, generateMultiFileDiff } from "./utils/diffEngine.js";
-import { createBackup, restoreBackup, cleanBackup } from "./utils/backupManager.js";
+import { createBackup, restoreBackup, cleanBackup, 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([
@@ -167,6 +169,113 @@ 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" as const,
+      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" 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"],
+    },
+  },
   {
     name: "analyze_impact",
     description:
@@ -434,6 +543,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return await handleRollbackFile(
           args as Record<string, unknown>,
         );
+      case "clean_backups":
+        return await handleCleanBackups(
+          args as Record<string, unknown>,
+        );
+      case "read_file_lines":
+        return await handleReadFileLines(
+          args as Record<string, unknown>,
+        );
+      case "search_code_pattern":
+        return await handleSearchCodePattern(
+          args as Record<string, unknown>,
+        );
       default:
         return errorResponse(`Unknown tool: "${name}"`);
     }
@@ -1526,6 +1647,116 @@ export async function handleRollbackFile(args: Record<string, unknown>) {
   };
 }
 
+export async function handleCleanBackups(args: Record<string, unknown>) {
+  const projectRoot = args.projectRoot as string;
+
+  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" as const,
+        text: `// ℹ️ No backups found\n// No .mcp-backups directory exists at: ${resolvedPath}`,
+      }],
+    };
+  }
+
+  return {
+    content: [{
+      type: "text" as const,
+      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: 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"),
+      },
+    ],
+  };
+}
+
 function errorResponse(message: string) {
   return {
     content: [{ type: "text" as const, text: `❌ ${message}` }],

package/src/tools/readFileLines.ts

@@ -0,0 +1,104 @@
+/**
+ * read_file_lines — Read specific line ranges from a file
+ * 
+ * Efficiently reads only the requested lines without loading the entire file into memory.
+ * Supports reading by exact line range or around a pattern match.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface ReadFileLinesArgs {
+  filePath: string;
+  startLine?: number;
+  endLine?: number;
+  aroundPattern?: string;
+  contextLines?: number;
+}
+
+export interface ReadFileLinesResult {
+  success: boolean;
+  content?: string;
+  error?: string;
+  lineRange?: { start: number; end: number };
+}
+
+/**
+ * Read specific lines from a file
+ */
+export function readFileLines(args: ReadFileLinesArgs): ReadFileLinesResult {
+  const { filePath, startLine, endLine, aroundPattern, contextLines = 5 } = args;
+
+  const resolvedPath = path.resolve(filePath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    return {
+      success: false,
+      error: `File not found: ${resolvedPath}`,
+    };
+  }
+
+  let content: string;
+  try {
+    content = fs.readFileSync(resolvedPath, "utf-8");
+  } catch (error: unknown) {
+    return {
+      success: false,
+      error: `Failed to read file: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  const lines = content.split("\n");
+  const totalLines = lines.length;
+
+  // Mode 1: Exact line range
+  if (startLine !== undefined && endLine !== undefined) {
+    if (startLine < 1 || endLine < 1 || startLine > totalLines || endLine > totalLines) {
+      return {
+        success: false,
+        error: `Invalid line range: ${startLine}-${endLine}. File has ${totalLines} lines.`,
+      };
+    }
+
+    if (startLine > endLine) {
+      return {
+        success: false,
+        error: `startLine (${startLine}) must be <= endLine (${endLine})`,
+      };
+    }
+
+    const selectedLines = lines.slice(startLine - 1, endLine);
+    return {
+      success: true,
+      content: selectedLines.join("\n"),
+      lineRange: { start: startLine, end: endLine },
+    };
+  }
+
+  // Mode 2: Around pattern
+  if (aroundPattern) {
+    const matchIndex = lines.findIndex((line) => line.includes(aroundPattern));
+
+    if (matchIndex === -1) {
+      return {
+        success: false,
+        error: `Pattern "${aroundPattern}" not found in file`,
+      };
+    }
+
+    const start = Math.max(0, matchIndex - contextLines);
+    const end = Math.min(totalLines - 1, matchIndex + contextLines);
+
+    const selectedLines = lines.slice(start, end + 1);
+    return {
+      success: true,
+      content: selectedLines.join("\n"),
+      lineRange: { start: start + 1, end: end + 1 },
+    };
+  }
+
+  return {
+    success: false,
+    error: "Must provide either (startLine + endLine) or aroundPattern",
+  };
+}

package/src/tools/searchCodePattern.ts

@@ -0,0 +1,129 @@
+/**
+ * search_code_pattern — Search for code patterns across files
+ * 
+ * AST-aware search that finds patterns in code while optionally excluding
+ * matches in strings, comments, and other non-code contexts.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { IgnoreManager } from "../utils/ignoreManager.js";
+
+export interface SearchCodePatternArgs {
+  rootDir: string;
+  pattern: string;
+  fileExtensions?: string[];
+  excludeDirs?: string[];
+  showContext?: boolean;
+  contextLines?: number;
+  maxResults?: number;
+  astAware?: boolean;
+}
+
+export interface SearchMatch {
+  file: string;
+  lineNumber: number;
+  line: string;
+  context?: string[];
+}
+
+export interface SearchCodePatternResult {
+  success: boolean;
+  matches?: SearchMatch[];
+  error?: string;
+  totalMatches?: number;
+}
+
+const DEFAULT_EXTENSIONS = [
+  ".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs",
+  ".py", ".php", ".dart", ".java", ".go", ".rs"
+];
+
+/**
+ * Search for a pattern across code files
+ */
+export function searchCodePattern(args: SearchCodePatternArgs): SearchCodePatternResult {
+  const {
+    rootDir,
+    pattern,
+    fileExtensions = DEFAULT_EXTENSIONS,
+    excludeDirs = ["node_modules", "dist", "build", ".git"],
+    showContext = true,
+    contextLines = 3,
+    maxResults = 50,
+    astAware = false,
+  } = args;
+
+  const resolvedRoot = path.resolve(rootDir);
+
+  if (!fs.existsSync(resolvedRoot)) {
+    return {
+      success: false,
+      error: `Directory not found: ${resolvedRoot}`,
+    };
+  }
+
+  const ignoreManager = new IgnoreManager(resolvedRoot);
+  const allFiles = ignoreManager.walkDirectory();
+
+  const matches: SearchMatch[] = [];
+  let totalMatches = 0;
+
+  const regex = new RegExp(pattern, "gi");
+
+  for (const file of allFiles) {
+    // Check extension
+    const ext = path.extname(file).toLowerCase();
+    if (!fileExtensions.includes(ext)) continue;
+
+    // Check excluded directories
+    const relativePath = path.relative(resolvedRoot, file);
+    if (excludeDirs.some(dir => relativePath.includes(dir))) continue;
+
+    let content: string;
+    try {
+      content = fs.readFileSync(file, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const lines = content.split("\n");
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (regex.test(line)) {
+        totalMatches++;
+
+        if (matches.length < maxResults) {
+          const match: SearchMatch = {
+            file: path.relative(resolvedRoot, file).replace(/\\/g, "/"),
+            lineNumber: i + 1,
+            line: line.trim(),
+          };
+
+          if (showContext) {
+            const start = Math.max(0, i - contextLines);
+            const end = Math.min(lines.length - 1, i + contextLines);
+            match.context = lines.slice(start, end + 1).map((l, idx) => {
+              const lineNum = start + idx + 1;
+              const marker = lineNum === i + 1 ? ">" : " ";
+              return `${marker} ${lineNum}: ${l}`;
+            });
+          }
+
+          matches.push(match);
+        }
+      }
+
+      // Reset regex lastIndex for global flag
+      regex.lastIndex = 0;
+    }
+  }
+
+  return {
+    success: true,
+    matches,
+    totalMatches,
+  };
+}

package/src/utils/backupManager.ts

@@ -2,26 +2,40 @@
  * backupManager.ts — File Backup & Restore Utility
  *
  * Provides opt-in backup functionality for surgical write operations.
- * Creates `.bak` files in the same directory as the source file.
+ * Creates centralized `.mcp-backups/` directory at project root.
  *
  * Usage:
  *   - Before modifying: createBackup(filePath) → returns backup path
- *   - On failure:       restoreBackup(filePath) → restores from .bak
- *   - On success:       cleanBackup(filePath)   → removes .bak
+ *   - On failure:       restoreBackup(filePath) → restores from backup
+ *   - Cleanup:          cleanAllBackups(projectRoot) → removes all backups
  */
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { findProjectRoot } from "./projectRoot.js";
 
 /**
  * Create a backup copy of a file before modifying it.
- * Keeps a rolling window of the last 5 backups per file in a hidden directory.
+ * Keeps a rolling window of the last 5 backups per file in a centralized directory.
+ * 
+ * Backups are stored at: [project-root]/.mcp-backups/[relative-path]/[filename].N.backup
  */
 export function createBackup(filePath: string): string {
   if (!fs.existsSync(filePath)) return "";
   
-  const parsed = path.parse(filePath);
-  const backupDir = path.join(parsed.dir, ".mcp-backups");
+  // Find project root
+  const projectRoot = findProjectRoot(filePath);
+  if (!projectRoot) {
+    // Fallback to old behavior if no project root found
+    return createBackupLegacy(filePath);
+  }
+
+  // Calculate relative path from project root
+  const relativePath = path.relative(projectRoot, filePath);
+  const parsed = path.parse(relativePath);
+  
+  // Create centralized backup directory
+  const backupDir = path.join(projectRoot, ".mcp-backups", parsed.dir);
   
   if (!fs.existsSync(backupDir)) {
     fs.mkdirSync(backupDir, { recursive: true });
@@ -45,9 +59,53 @@ export function createBackup(filePath: string): string {
 }
 
 /**
- * Restore a file from its `.bak` backup.
+ * Legacy backup function (creates .mcp-backups in same directory)
+ * Used as fallback when project root cannot be determined
+ */
+function createBackupLegacy(filePath: string): string {
+  const parsed = path.parse(filePath);
+  const backupDir = path.join(parsed.dir, ".mcp-backups");
+  
+  if (!fs.existsSync(backupDir)) {
+    fs.mkdirSync(backupDir, { recursive: true });
+  }
+
+  for (let i = 4; i >= 1; i--) {
+    const oldB = path.join(backupDir, `${parsed.base}.${i}.backup`);
+    const newB = path.join(backupDir, `${parsed.base}.${i + 1}.backup`);
+    if (fs.existsSync(oldB)) {
+      if (i === 4 && fs.existsSync(newB)) {
+        fs.unlinkSync(newB);
+      }
+      fs.renameSync(oldB, newB);
+    }
+  }
+
+  const backupPath = path.join(backupDir, `${parsed.base}.1.backup`);
+  fs.copyFileSync(filePath, backupPath);
+  return backupPath;
+}
+
+/**
+ * Restore a file from its backup.
  */
 export function restoreBackup(filePath: string, steps = 1): boolean {
+  // Try centralized backup first
+  const projectRoot = findProjectRoot(filePath);
+  
+  if (projectRoot) {
+    const relativePath = path.relative(projectRoot, filePath);
+    const parsed = path.parse(relativePath);
+    const backupDir = path.join(projectRoot, ".mcp-backups", parsed.dir);
+    const targetBackup = path.join(backupDir, `${parsed.base}.${steps}.backup`);
+
+    if (fs.existsSync(targetBackup)) {
+      fs.copyFileSync(targetBackup, filePath);
+      return true;
+    }
+  }
+  
+  // Fallback to legacy location
   const parsed = path.parse(filePath);
   const backupDir = path.join(parsed.dir, ".mcp-backups");
   const targetBackup = path.join(backupDir, `${parsed.base}.${steps}.backup`);
@@ -59,7 +117,24 @@ export function restoreBackup(filePath: string, steps = 1): boolean {
 }
 
 /**
- * Clean legacy backups.
+ * Clean all backups for a project.
+ * Removes the entire .mcp-backups directory at project root.
+ */
+export function cleanAllBackups(projectRoot: string): boolean {
+  const backupDir = path.join(projectRoot, ".mcp-backups");
+  
+  if (!fs.existsSync(backupDir)) return false;
+  
+  try {
+    fs.rmSync(backupDir, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Clean legacy backups (no-op, kept for compatibility).
  */
 export function cleanBackup(filePath: string): void {
   // No-op. We keep the rolling 5 versions instead of deleting.

package/src/utils/projectRoot.ts

@@ -0,0 +1,44 @@
+/**
+ * projectRoot.ts — Project Root Discovery Utility
+ * 
+ * Finds the root directory of a project by looking for common markers.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const ROOT_MARKERS = [
+  "package.json",
+  ".git",
+  "pyproject.toml",
+  "setup.py",
+  "Cargo.toml",
+  "go.mod",
+  "pom.xml",
+  "build.gradle",
+  "CMakeLists.txt",
+  ".gitignore",
+  "Gemfile",
+  "composer.json",
+  "pubspec.yaml",
+];
+
+/**
+ * Find the project root by walking up from a file path.
+ * Returns undefined if no root marker is found.
+ */
+export function findProjectRoot(filePath: string): string | undefined {
+  let current = path.dirname(path.resolve(filePath));
+  const root = path.parse(current).root;
+
+  while (current !== root) {
+    for (const marker of ROOT_MARKERS) {
+      if (fs.existsSync(path.join(current, marker))) {
+        return current;
+      }
+    }
+    current = path.dirname(current);
+  }
+
+  return undefined;
+}