# CodeSeeker

**Advanced code search and transformation for AI assistants**

A comprehensive Model Context Protocol (MCP) server that combines the power of [ugrep](https://github.com/Genivia/ugrep) and [ast-grep](https://github.com/ast-grep/ast-grep) philosophies to deliver intelligent search and replace capabilities for modern development workflows.

<a href="https://glama.ai/mcp/servers/@mixelpixx/CodeSeeker-MCP">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@mixelpixx/CodeSeeker-MCP/badge" alt="CodeSeeker-MCP MCP server" />
</a>

## 🚀 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:**
```bash
sudo apt-get install ugrep
```

**macOS (Homebrew):**
```bash
brew install ugrep
```

**Windows (Chocolatey):**
```bash
choco install ugrep
```

**From source:**
```bash
git clone https://github.com/Genivia/ugrep.git
cd ugrep
./configure
make
sudo make install
```

**Verify installation:**
```bash
ugrep --version
# Should show version 7.4 or higher
```

### 2. Install Node.js
Ensure you have Node.js 18+ installed:
```bash
node --version
# Should show v18.0.0 or higher
```

## 🛠️ Installation

### Clone and Build
```bash
git clone https://github.com/yourusername/codeseeker-mcp.git
cd codeseeker-mcp
npm install
npm run build
```

### Quick Test
```bash
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`

```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
```bash
npm run build           # Compile TypeScript
npm run dev            # Watch mode for development
npm run inspector      # Debug with MCP inspector
```

### Testing the Server
```bash
# 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

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](LICENSE) file for details.

## 🔗 Related Projects

- [ugrep](https://github.com/Genivia/ugrep) - The ultra-fast grep replacement
- [ast-grep](https://github.com/ast-grep/ast-grep) - AST-based code search and rewrite tool  
- [Model Context Protocol](https://modelcontextprotocol.io/) - Open standard for AI-data connections
- [Claude Desktop](https://claude.ai/) - 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)