🔍 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+
uvpackage managerkitCLI 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 directorynum_context_lines: Lines of context (default: 2)
🏗️ get_repo_symbols
Extract symbols (functions, classes, methods) from your codebase.
Parameters:
repo: Repository pathworking_directory: Command execution directorykeep_types: Filter by symbol typesfile_must_contain/file_must_not_contain: File filtering
📊 get_symbol_usages
Find where specific symbols are used throughout your codebase.
Parameters:
repo: Repository pathsymbol_name_or_substring: Symbol to search forworking_directory: Command execution directorysymbol_type: Optional type filter
🎯 coderank_analysis
Analyze repository importance using the CodeRank algorithm.
Parameters:
repo_path: Repository to analyzeexternal_modules: Comma-separated external dependenciestop_n: Number of top modules to return (default: 10)analyze_markdown: Include markdown filesoutput_format: "summary", "detailed", or "json"
🔥 find_code_hotspots
Identify critical code areas combining connectivity and usage frequency.
Parameters:
repo_path: Repository pathworking_directory: Command execution directorymin_connections: Minimum import connections (default: 5)include_external: Include external dependenciestop_n: Number of hotspots to return (default: 20)
🌐 trace_dependency_impact
Trace dependency chains and analyze refactoring impact.
Parameters:
repo_path: Repository pathtarget_module: Module to analyzeworking_directory: Command execution directoryanalysis_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 pathworking_directory: Command execution directoryrank_results: Sort by module importancecontext_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.
🔮 Powered by the CodeRank Algorithm & Model Context Protocol
Making code search intelligent, one repository at a time