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 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

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 --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

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)

CodeSeeker

CodeSeeker

🚀 Features

🔍 Core Search Tools

🔧 Search & Replace Tools

⚡ Advanced Features

📋 Prerequisites

1. Install ugrep

2. Install Node.js

🛠️ Installation

Clone and Build

Quick Test

⚙️ Configuration

Claude Desktop Integration

📖 Usage Examples

Basic Search

Boolean Search

Fuzzy Search

Search and Replace

Bulk Replace

Code Refactor

🔧 Tool Reference

Search Tools

basic_search

boolean_search

fuzzy_search

archive_search

code_structure_search

interactive_search

Replace Tools

search_and_replace

bulk_replace

code_refactor

Utility Tools

list_file_types

get_search_stats

🏗️ Development

Project Structure

Building

Testing the Server

🚨 Safety Features

Dry Run Mode

Automatic Backups

Error Handling

🐛 Troubleshooting

Common Issues

⚡ Performance Notes

🤝 Contributing

📄 License

🔗 Related Projects

📊 Tool Summary

Related Servers

302AI Sandbox MCP Server

MCP Server Starter

Cloudflare MCP Server Example

Windows CLI

Godot MCP

iTerm

SoftProbe MCP Server

BloodHound-MCP

DevRev MCP Server

Flutter MCP

`basic_search`

`boolean_search`

`fuzzy_search`

`archive_search`

`code_structure_search`

`interactive_search`

`search_and_replace`

`bulk_replace`

`code_refactor`

`list_file_types`

`get_search_stats`