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:
sudo apt-get install ugrep
macOS (Homebrew):
brew install ugrep
Windows (Chocolatey):
choco install ugrep
From source:
git clone https://github.com/Genivia/ugrep.git
cd ugrep
./configure
make
sudo make install
Verify installation:
ugrep --version
# Should show version 7.4 or higher
2. Install Node.js
Ensure you have Node.js 18+ installed:
node --version
# Should show v18.0.0 or higher
🛠️ Installation
Clone and Build
git clone https://github.com/yourusername/codeseeker-mcp.git
cd codeseeker-mcp
npm install
npm run build
Quick Test
npm test
# Should show all tests passing
⚙️ 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
{
"mcpServers": {
"codeseeker": {
"command": "node",
"args": ["/absolute/path/to/codeseeker-mcp/build/index.js"]
}
}
}
Note: Replace /absolute/path/to/codeseeker-mcp with the actual path to your installation.
📖 Usage Examples
Basic Search
Search for "function" in JavaScript files:
- Pattern: function
- File Types: js,ts
- Path: ./src
- Case Sensitive: false
Boolean Search
Find TODO items that are urgent but not marked as later:
- Query: TODO AND urgent -NOT later
- File Types: cpp,h,js,py
Fuzzy Search
Find "function" with up to 2 character errors (matches "functoin", "functio", etc.):
- Pattern: function
- Max Errors: 2
- File Types: js,ts,py
Search and Replace
Replace old function names with new ones (safe preview first):
- Pattern: oldFunctionName
- Replacement: newFunctionName
- File Types: js,ts
- Dry Run: true (preview changes)
- Backup: true (create backups)
Bulk Replace
Multiple replacements in one operation:
- Replace "var " with "const "
- Replace "== " with "=== "
- File Types: js,ts
- Dry Run: true
Code Refactor
Refactor function names across a codebase:
- Structure Type: function
- Old Pattern: getUserData
- New Pattern: fetchUserData
- Language: typescript
- Dry Run: true
🔧 Tool Reference
Search Tools
basic_search
Standard pattern search with filtering options.
Parameters:
pattern(required): Search pattern or regexpath(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 excludecontextLines(optional): Lines of context around matchesmaxResults(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 formaxErrors(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 patternpath,maxResults: Same as basic searcharchiveTypes(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 forlanguage(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 patternpath(optional): Starting directory
Replace Tools
search_and_replace
Safe find and replace with preview.
Parameters:
pattern(required): Search pattern or regexreplacement(required): Replacement text (supports $1, $2 capture groups)path(optional): Directory to process (default: current directory)fileTypes(optional): File types to includecaseSensitive(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} objectspath,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 findnewPattern(required): Replacement patternlanguage(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
codeseeker-mcp/
├── src/
│ └── index.ts # Main server implementation
├── build/ # Compiled JavaScript output
├── package.json # Node.js dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── test.js # Test suite
├── README.md # This file
└── SETUP.md # Quick setup guide
Building
npm run build # Compile TypeScript
npm run dev # Watch mode for development
npm run inspector # Debug with MCP inspector
Testing the Server
# Test basic functionality
npm test
# Use MCP inspector for interactive testing
npm run inspector
# Test with Claude Desktop
# (Add to config and restart Claude Desktop)
🚨 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 --versionto 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 installto 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
maxResultsparameter - Replace operations process files efficiently with streaming
- Interactive mode requires a terminal and cannot run through MCP
🤝 Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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
| Tool | Purpose | Input | Output |
|---|---|---|---|
basic_search | Standard text search | Pattern + filters | Matches with context |
boolean_search | Logical search queries | Boolean expression | Filtered results |
fuzzy_search | Approximate matching | Pattern + error tolerance | Fuzzy matches |
archive_search | Search compressed files | Pattern + archive types | Archive contents |
code_structure_search | Find code elements | Structure type + language | Code definitions |
search_and_replace | Find and replace text | Pattern + replacement | Preview/changes |
bulk_replace | Multiple replacements | Array of operations | Batch results |
code_refactor | Refactor code structures | Old/new patterns + language | Refactored code |
interactive_search | Launch TUI mode | Initial pattern | Command to run |
list_file_types | Show supported types | None | Available extensions |
get_search_stats | Search metrics | Search parameters | Performance stats |
CodeSeeker - Intelligence in every search, precision in every change.
Total Tools Available: 11 (8 search + 3 replace)