🔍 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

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

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

For macOS users with Homebrew:

{
  "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:

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:

# 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

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