CodeSeeker

Advanced code search and transformation for AI assistants

A comprehensive Model Context Protocol (MCP) server that combines the power of ugrep and ast-grep philosophies to deliver intelligent search and replace capabilities for modern development workflows.

🚀 Features

CodeSeeker provides AI assistants with complete search AND replace capabilities:

🔍 Core Search Tools

• Basic Search: Standard pattern matching with file type filtering and context

• Boolean Search: Google-like search with AND, OR, NOT operators

• Fuzzy Search: Approximate pattern matching allowing character errors

• Archive Search: Search inside compressed files and archives (zip, tar, 7z, etc.)

• Interactive Search: Launch ugrep's TUI for real-time search

• Code Structure Search: Find functions, classes, methods, imports, and variables

🔧 Search & Replace Tools

• Search and Replace: Safe find & replace with dry-run preview and automatic backups

• Bulk Replace: Multiple search/replace operations in a single command

• Code Refactor: Language-aware refactoring for code structures across multiple languages

⚡ Advanced Features

• JSON Output: Structured results perfect for AI processing

• File Type Filtering: Search specific programming languages or document types

• Context Lines: Show surrounding lines for better understanding

• Search Statistics: Get detailed metrics about search operations

• Archive Support: Search nested archives without extraction

• Safety First: Dry-run mode by default with automatic backup creation

• Language Awareness: Smart patterns for JavaScript, TypeScript, Python, Java, C++

📋 Prerequisites

1. Install ugrep

Ubuntu/Debian:

macOS (Homebrew):

Windows (Chocolatey):

From source:

Verify installation:

2. Install Node.js

Ensure you have Node.js 18+ installed:

🛠️ Installation

Clone and Build

Quick Test

⚙️ Configuration

Claude Desktop Integration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Note: Replace /absolute/path/to/codeseeker-mcp with the actual path to your installation.

📖 Usage Examples

Basic Search

Boolean Search

Fuzzy Search

Search and Replace

Bulk Replace

Code Refactor

🔧 Tool Reference

Search Tools

basic_search

Standard pattern search with filtering options.

Parameters:

• pattern (required): Search pattern or regex

• path (optional): Directory to search (default: current directory)

• caseSensitive (optional): Case-sensitive search (default: false)

• fileTypes (optional): Comma-separated file types (e.g., "js,py,cpp")

• excludeTypes (optional): File types to exclude

• contextLines (optional): Lines of context around matches

• maxResults (optional): Maximum results (default: 100)

boolean_search

Google-like search with boolean operators.

Parameters:

• query (required): Boolean query (supports AND, OR, NOT, parentheses)

• path, fileTypes, maxResults: Same as basic search

Example queries:

• "error AND (critical OR fatal)"

• "TODO AND urgent -NOT completed"

• "function OR method -NOT test"

fuzzy_search

Approximate pattern matching.

Parameters:

• pattern (required): Pattern to search for

• maxErrors (optional): Character errors allowed 1-9 (default: 2)

• path, fileTypes, maxResults: Same as basic search

archive_search

Search compressed files and archives.

Parameters:

• pattern (required): Search pattern

• path, maxResults: Same as basic search

• archiveTypes (optional): Archive types to search

code_structure_search

Find specific code structures.

Parameters:

• structureType (required): Type to search for (function, class, method, import, variable)

• name (optional): Specific name to search for

• language (required): Programming language (js, ts, py, java, cpp)

• path, maxResults: Same as basic search

interactive_search

Launch interactive TUI mode.

Parameters:

• initialPattern (optional): Starting search pattern

• path (optional): Starting directory

Replace Tools

search_and_replace

Safe find and replace with preview.

Parameters:

• pattern (required): Search pattern or regex

• replacement (required): Replacement text (supports $1, $2 capture groups)

• path (optional): Directory to process (default: current directory)

• fileTypes (optional): File types to include

• caseSensitive (optional): Case-sensitive search (default: false)

• dryRun (optional): Preview mode (default: true)

• maxFiles (optional): Maximum files to process (default: 50)

• backup (optional): Create backups (default: true)

bulk_replace

Multiple search/replace operations.

Parameters:

• replacements (required): Array of {pattern, replacement, description} objects

• path, fileTypes, caseSensitive, dryRun, backup: Same as search_and_replace

code_refactor

Language-aware code refactoring.

Parameters:

• structureType (required): Code structure type (function, class, variable, import)

• oldPattern (required): Pattern to find

• newPattern (required): Replacement pattern

• language (required): Programming language (js, ts, py, java, cpp)

• path, dryRun, backup: Same as search_and_replace

Utility Tools

list_file_types

Get all supported file types for filtering.

get_search_stats

Get detailed search statistics and performance metrics.

🏗️ Development

Project Structure

Building

Testing the Server

🚨 Safety Features

Dry Run Mode

All replace operations default to dry-run mode for safety:

• Preview changes before applying

• See exactly what will be modified

• No accidental overwrites

Automatic Backups

When making changes:

• Backup files created automatically with timestamps

• Original files preserved

• Easy rollback if needed

Error Handling

• Comprehensive error messages

• Graceful failure handling

• File permission checking

🐛 Troubleshooting

Common Issues

"ugrep not found"

• Ensure ugrep is installed and in your PATH

• Run ugrep --version to verify installation

"Permission denied"

• Make sure the build/index.js file is executable

• Run chmod +x build/index.js (on Unix systems)

"Module not found errors"

• Run npm install to install dependencies

• Ensure you're using Node.js 18 or higher

"Claude Desktop not showing tools"

• Verify the configuration file path is correct

• Restart Claude Desktop after configuration changes

• Check Claude Desktop logs for connection errors

"No files found to process"

• Check that the path exists and contains matching files

• Verify file type filters are correct

• Ensure ugrep can access the specified directories

⚡ Performance Notes

• ugrep is extremely fast, often outperforming other grep tools

• JSON output adds minimal overhead

• Archive searching may be slower depending on compression

• Large result sets are limited by maxResults parameter

• Replace operations process files efficiently with streaming

• Interactive mode requires a terminal and cannot run through MCP

🤝 Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📄 License

MIT License - see the LICENSE file for details.

🔗 Related Projects

• ugrep - The ultra-fast grep replacement

• ast-grep - AST-based code search and rewrite tool

• Model Context Protocol - Open standard for AI-data connections

• Claude Desktop - AI assistant with MCP support

📊 Tool Summary

CodeSeeker - Intelligence in every search, precision in every change.

Total Tools Available: 11 (8 search + 3 replace)