# 🔍 Search Tools MCP Server

> ⚡ An intelligent Model Context Protocol (MCP) server that supercharges code analysis with advanced search capabilities and dependency mapping

## 🌟 Overview

The **Search Tools MCP Server** is a powerful toolkit that combines traditional code search with intelligent analysis algorithms. It leverages the **CodeRank** algorithm (inspired by PageRank) to identify the most critical modules in your codebase and provides sophisticated search capabilities that go beyond simple text matching.

## 🎯 Key Features

### 🔎 **Smart Search Capabilities**
- **Contextual Keyword Search**: Ripgrep-powered search with configurable context lines
- **Symbol Discovery**: Extract and analyze functions, classes, methods, and modules
- **Usage Tracking**: Find where symbols are used across your codebase
- **Priority-Ranked Results**: Search results ranked by code importance

### 🧠 **Intelligence & Analysis**
- **CodeRank Algorithm**: Identify the most critical modules using network analysis
- **Dependency Mapping**: Trace complex dependency chains and impact analysis
- **Hotspot Detection**: Find code areas that are both highly connected and frequently used
- **Refactoring Impact**: Analyze the potential impact of code changes

### 🎨 **Advanced Filtering**
- Symbol type filtering (functions, methods, classes)
- File inclusion/exclusion patterns
- External module dependency tracking
- Markdown documentation analysis

## 🛠️ Installation

### Prerequisites
- Python 3.13+
- `uv` package manager
- `kit` CLI tool (for symbol analysis)
- `ripgrep` (for fast text search)

### Setup
```bash
# Clone the repository
git clone <repository-url>
cd search-tools

# Install dependencies
uv sync
```

## ⚙️ Configuration

### Adding to Cursor/Windsurf

Add the following configuration to your `mcp.json` file:

```json
{
  "mcpServers": {
    "search-tools": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/search-tools",
        "main.py"
      ]
    }
  }
}
```

**For macOS users with Homebrew:**
```json
{
  "mcpServers": {
    "search-tools": {
      "command": "/Users/yourusername/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/search-tools/directory",
        "main.py"
      ]
    }
  }
}
```

### To add to claude code:
```bash
claude mcp add-json search-tools '{"type":"stdio","command":"/Users/yourusername/.local/bin/uv","args":[ "run", "--directory", "/path/to/your/search-tools/directory", "main.py"]}'
```

### 📍 Finding Your Paths

To find the correct paths for your system:

```bash
# Find uv location
which uv

# Get absolute path to search-tools directory  
pwd  # (run this from the search-tools directory)
```

## 🚀 Available Tools

### 🔍 `contextual_keyword_search`
Search for keywords with configurable context lines around matches.

**Parameters:**
- `keyword`: Search term (case insensitive)
- `working_directory`: Absolute path to search directory
- `num_context_lines`: Lines of context (default: 2)

### 🏗️ `get_repo_symbols`
Extract symbols (functions, classes, methods) from your codebase.

**Parameters:**
- `repo`: Repository path
- `working_directory`: Command execution directory
- `keep_types`: Filter by symbol types
- `file_must_contain/file_must_not_contain`: File filtering

### 📊 `get_symbol_usages`
Find where specific symbols are used throughout your codebase.

**Parameters:**
- `repo`: Repository path
- `symbol_name_or_substring`: Symbol to search for
- `working_directory`: Command execution directory
- `symbol_type`: Optional type filter

### 🎯 `coderank_analysis`
Analyze repository importance using the CodeRank algorithm.

**Parameters:**
- `repo_path`: Repository to analyze
- `external_modules`: Comma-separated external dependencies
- `top_n`: Number of top modules to return (default: 10)
- `analyze_markdown`: Include markdown files
- `output_format`: "summary", "detailed", or "json"

### 🔥 `find_code_hotspots`
Identify critical code areas combining connectivity and usage frequency.

**Parameters:**
- `repo_path`: Repository path
- `working_directory`: Command execution directory
- `min_connections`: Minimum import connections (default: 5)
- `include_external`: Include external dependencies
- `top_n`: Number of hotspots to return (default: 20)

### 🌐 `trace_dependency_impact`
Trace dependency chains and analyze refactoring impact.

**Parameters:**
- `repo_path`: Repository path
- `target_module`: Module to analyze
- `working_directory`: Command execution directory
- `analysis_type`: "dependency", "refactoring", or "both"
- `max_depth`: Maximum trace depth (default: 3)
- `change_type`: "modify", "split", "merge", or "remove"

### 🎪 `smart_code_search`
Enhanced search combining ripgrep with CodeRank prioritization.

**Parameters:**
- `keyword`: Search term (supports regex)
- `repo_path`: Repository path
- `working_directory`: Command execution directory
- `rank_results`: Sort by module importance
- `context_lines`: Context lines around matches (default: 3)
- `max_results`: Maximum results to return (default: 20)

## 🧪 Development & Testing

### Running the Server
```bash
# Development mode
uv run mcp dev main.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector python main.py
```

### 🔧 Dependencies
- **mcp[cli]**: Model Context Protocol framework
- **cased-kit**: Symbol analysis toolkit
- **networkx**: Graph analysis for CodeRank algorithm

## 🎨 Algorithm Details

### CodeRank Algorithm
The CodeRank algorithm treats your codebase as a directed graph where:
- **Nodes**: Python modules, classes, functions, methods
- **Edges**: Import relationships and dependencies
- **Weights**: Different weights for internal vs external dependencies

This creates a ranking system that identifies the most "central" and important parts of your codebase, similar to how PageRank identifies important web pages.

## 💡 Use Cases

- **🔍 Code Exploration**: Quickly understand large codebases
- **🏗️ Refactoring Planning**: Identify high-impact areas before changes
- **📚 Documentation**: Find the most important modules to document first
- **🐛 Bug Investigation**: Focus on critical code paths
- **👥 Code Review**: Prioritize review efforts on important modules

## 🤝 Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

## 📄 License

This project is open source. Please check the license file for details.

---

<div align="center">

**🔮 Powered by the CodeRank Algorithm & Model Context Protocol**

*Making code search intelligent, one repository at a time*

</div>