MCP Server: Code Search, Read & PR Analysis

A Python-based Model Context Protocol (MCP) server that enables LLMs to interact with codebases through search, read, and PR analysis capabilities.

Features

Local Operations:

• 🔍 Search: Find files by name (glob) or content (grep) in local repositories
• 📖 Read: Safely read file contents with path traversal protection

GitHub Integration:

• 🔄 PR Analysis: Fetch and analyze GitHub Pull Request diffs
• 🔎 GitHub Search: Search for files by name in any GitHub repository
• 📄 GitHub Read: Read file contents directly from GitHub repositories
• 🔬 Code Grep: Search code content across GitHub repositories

Security & Performance:

• 🔒 Security: Automatic filtering of sensitive files (.env, credentials, keys)
• ⚡ Performance: Uses native tools (ripgrep, git grep) for fast searches

Quick Start

# Install dependencies
uv sync

# Run the server
uv run python -m mcp_server

# Run tests
uv run pytest -v

Installation & Setup

For detailed instructions on running the server and installing it in VS Code, see run.md.

Project Structure

src/mcp_server/
├── server.py          # Main MCP server entrypoint (6 tools)
├── tools/
│   ├── search.py      # Local file search (glob/grep)
│   ├── read.py        # Local safe file reading
│   └── github.py      # GitHub integration (PR, search, read, grep)
tests/                 # Comprehensive test suite (40 tests)

Available Tools

Local File Operations

1. search_files

Search for files by name pattern or content in local repository.

Parameters:

• query (string): Search pattern (file pattern for glob, regex for grep)
• search_type (string): Either "glob" or "grep"
• path (string, optional): Root directory to search (defaults to current directory)

2. read_file

Read local file contents with security validation.

Parameters:

• file_path (string): Path to the file to read

Security:

• Validates paths to prevent traversal attacks
• Blocks sensitive files (.env, credentials, keys)

GitHub Operations

3. get_pr_diff

Fetch GitHub Pull Request diffs.

Parameters:

• repo (string): Repository in format "owner/repo"
• pr_number (integer): Pull request number

4. search_github_files

Search for files by name in a GitHub repository.

Parameters:

• repo (string): Repository in format "owner/repo"
• query (string): Filename or path pattern to search for
• path (string, optional): Path prefix to search within (e.g., "src/")

5. read_github_file

Read file contents directly from a GitHub repository.

Parameters:

• repo (string): Repository in format "owner/repo"
• file_path (string): Path to the file in the repository
• branch (string, optional): Branch name (defaults to "main")

6. grep_github_repo

Search for code content in a GitHub repository (grep-like).

Parameters:

• repo (string): Repository in format "owner/repo"
• query (string): Code content to search for
• path (string, optional): Path prefix to search within

Note: GitHub operations require GITHUB_TOKEN environment variable for private repos and to avoid rate limits.

Development

# Install in development mode
uv pip install -e .

# Run tests with coverage
uv run pytest -v

# Lint code
uv run ruff check .

# Format code
uv run ruff format .

Configuration

See run.md for VS Code and Claude Desktop configuration examples.

Security

• All file operations validate paths to prevent directory traversal
• Sensitive files are automatically filtered from search results
• GitHub tokens should be stored securely (use environment variables)
• Server operates in stateless mode

Requirements

• Python 3.12+
• uv package manager
• Optional: ripgrep (for faster grep searches)
• Optional: GitHub token (for GitHub operations)

Documentation

• run.md - Detailed setup and installation guide
• doc.md - Original project specifications
• CLAUDE.md - Claude Code specific guidance

License

See LICENSE file for details.