MCP 服务器

Search Tools MCP Server

Enables intelligent code analysis and search across repositories using the CodeRank algorithm (inspired by PageRank) to identify critical modules, trace dependencies, find code hotspots, and perform context-aware keyword searches with importance-ranked results.

README

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