CodeSeeker-MCP

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)