Enables fetching and analyzing Pull Request diffs, searching for files by name or content across repositories, and reading file contents directly from GitHub repositories
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Code Search, Read & PR Analysis search for error handling patterns in the utils directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Python-based Model Context Protocol (MCP) server that enables LLMs to interact with codebases through search, read, and PR analysis capabilities.
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
Related MCP server: Code Search MCP
# Install dependencies
uv sync
# Run the server
uv run python -m mcp_server
# Run tests
uv run pytest -vFor detailed instructions on running the server and installing it in VS Code, see run.md.
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)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)
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)
Fetch GitHub Pull Request diffs.
Parameters:
repo (string): Repository in format "owner/repo"
pr_number (integer): Pull request number
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/")
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")
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.
# 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 .See run.md for VS Code and Claude Desktop configuration examples.
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
Python 3.12+
uv package manager
Optional: ripgrep (for faster grep searches)
Optional: GitHub token (for GitHub operations)
run.md - Detailed setup and installation guide
doc.md - Original project specifications
CLAUDE.md - Claude Code specific guidance
See LICENSE file for details.
Fetch and analyze Pull Request changes from GitHub
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository in format 'owner/repo' | |
| pr_number | Yes | Pull request number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'analyze' but doesn't specify what that entails (e.g., diff format, summary, or raw data), nor does it cover permissions, rate limits, or error handling. This leaves significant gaps in understanding how the tool behaves beyond basic fetching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose, making it easy to scan and understand quickly, which is ideal for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (involving GitHub API interactions and analysis), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what 'analyze' means, the return format, or error scenarios, leaving the agent with insufficient context for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, clearly documenting both parameters ('repo' and 'pr_number') with formats. The description adds no additional semantic context beyond implying these are needed for GitHub PRs, so it meets the baseline of 3 without compensating for or enhancing the schema's information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch and analyze') and resource ('Pull Request changes from GitHub'), making the purpose understandable. However, it doesn't differentiate this tool from sibling tools like 'read_github_file' or 'search_github_files' that might also interact with GitHub content, leaving some ambiguity about its specific niche.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing GitHub access), exclusions (e.g., not for commits or issues), or compare it to siblings like 'grep_github_repo' or 'search_github_files', leaving the agent to infer usage context independently.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for code content in a GitHub repository (grep-like search)
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository in format 'owner/repo' | |
| query | Yes | Code content to search for | |
| path | No | Optional path prefix to search within |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'grep-like search', which implies text-based pattern matching, but doesn't specify details like case sensitivity, regex support, search scope (e.g., all branches), rate limits, authentication needs, or output format. For a search tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence: 'Search for code content in a GitHub repository (grep-like search)'. It is front-loaded with the core purpose and includes a clarifying parenthetical. There is no wasted verbiage, making it highly concise and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for a search tool. It doesn't explain what the tool returns (e.g., matches, line numbers, file paths) or behavioral aspects like error handling. With sibling tools present, it also fails to clarify differentiation. For a tool with three parameters and no structured output information, more context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, clearly documenting all three parameters (repo, query, path). The description adds minimal value beyond the schema, only implying that 'query' is for 'code content' and 'repo' is a 'GitHub repository'. It doesn't provide additional context like query syntax examples or path usage nuances, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for code content in a GitHub repository (grep-like search)'. It specifies the verb ('search'), resource ('code content'), and context ('GitHub repository'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'search_files' or 'search_github_files', which might offer similar functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'search_files' and 'search_github_files' available, there is no indication of how this tool differs (e.g., grep-like vs. file-based search). No context, exclusions, or prerequisites are mentioned, leaving the agent to guess based on the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the full contents of a file from the local filesystem
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute or relative path to the file to read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description lacks behavioral details such as file size limits, encoding handling, error conditions (e.g., missing files or permissions), or performance implications, leaving significant gaps in understanding how the tool behaves beyond its basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words, clearly conveying the core purpose efficiently without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is too minimal. It fails to address critical context like return format (e.g., string or binary), error handling, or limitations, making it incomplete for safe and effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter 'file_path' is fully documented in the schema. The description does not add any extra meaning or examples beyond what the schema provides, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Read'), the target resource ('full contents of a file'), and the source ('local filesystem'), distinguishing it from sibling tools like read_github_file (remote) or search_files (partial content).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implicitly suggests usage for reading entire local files, but does not explicitly state when to use alternatives like search_files for partial content or read_github_file for remote files, missing explicit exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the contents of a file from a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository in format 'owner/repo' | |
| file_path | Yes | Path to the file in the repository | |
| branch | No | Branch name (defaults to 'main') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool reads file contents but doesn't mention authentication requirements, rate limits, error handling (e.g., for missing files or private repos), or output format (e.g., raw text or structured data). This leaves significant gaps for a tool interacting with an external API like GitHub.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, straightforward sentence that efficiently conveys the core functionality without any fluff. It's front-loaded and wastes no words, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of interacting with GitHub (which involves authentication, API limits, and potential errors) and the lack of annotations and output schema, the description is insufficient. It doesn't cover behavioral aspects like what happens on failure or the structure of returned data, leaving the agent under-informed for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with clear descriptions for all parameters (repo, file_path, branch). The description adds no additional semantic context beyond what the schema provides, such as examples or edge cases. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and resource ('contents of a file from a GitHub repository'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from siblings like 'read_file' or 'search_github_files', which might have overlapping functionality, so it doesn't reach a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'read_file' (which might be for local files) or 'search_github_files' (which might search multiple files). There's no mention of prerequisites, constraints, or typical use cases, leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for files by name pattern (glob) or content (grep) in local codebase
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (file pattern for glob, regex for grep) | |
| search_type | Yes | Type of search to perform | |
| path | No | Root path to search within (defaults to current directory) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the search types (glob and grep) but doesn't cover critical aspects like performance implications, error handling, output format, or whether it's read-only or has side effects. For a search tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary details. Every word earns its place by specifying the action, methods, and scope, making it highly concise and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose and scope but lacks details on behavior, output, and usage nuances. Without annotations or output schema, more context on what results to expect would improve completeness, but it meets a minimum viable level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value by hinting at parameter usage ('file pattern for glob, regex for grep'), but this is largely redundant with the schema. Baseline 3 is appropriate as the schema does the heavy lifting, but the description doesn't significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for files by name pattern (glob) or content (grep) in local codebase.' It specifies the verb ('search'), resource ('files'), and scope ('local codebase'), distinguishing it from sibling tools like search_github_files. However, it doesn't explicitly differentiate from grep_github_repo beyond the 'local' scope, which is slightly less specific than ideal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning 'local codebase,' suggesting it's for local searches versus GitHub-based siblings. However, it lacks explicit guidance on when to use this tool over alternatives like grep_github_repo or search_github_files, and doesn't specify prerequisites or exclusions. The context is clear but not detailed enough for optimal agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for files in a GitHub repository by name or path pattern
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository in format 'owner/repo' | |
| query | Yes | Filename or path pattern to search for | |
| path | No | Optional path prefix to search within (e.g., 'src/') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states what the tool does, not how it behaves. It doesn't disclose whether this is a read-only operation, what permissions are required, whether it uses GitHub API rate limits, what the return format looks like, or any pagination behavior for large result sets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized for a search tool and front-loads the essential information without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the search returns (file paths, contents, metadata), how results are formatted, whether there are limitations on repository size or search depth, or how to interpret search patterns. The agent would need to guess about the tool's behavior and output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema - it mentions 'name or path pattern' which aligns with the 'query' parameter but provides no extra context about syntax, wildcards, or search behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'search' and resource 'files in a GitHub repository', specifying the search criteria 'by name or path pattern'. It distinguishes from generic file search by specifying GitHub repository context, though it doesn't explicitly differentiate from sibling tools like 'search_files' or 'grep_github_repo'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'grep_github_repo' or 'search_files'. It mentions the search criteria but doesn't indicate appropriate contexts, prerequisites, or exclusions for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_pr_diffgrep_github_reporead_fileread_github_filesearch_filessearch_github_filesScored across 6 tools
Most tools have distinct purposes, but there is some overlap between grep_github_repo (search for code content) and search_github_files (search for files by name/path), which could cause confusion about which to use for GitHub content searches. The local vs. GitHub separation is clear, but the search functionality has minor ambiguity.
All tool names follow a consistent snake_case pattern with clear verb_noun structure (e.g., get_pr_diff, read_file, search_files). The naming is predictable and readable throughout the set, with no deviations in style or convention.
With 6 tools, the server is well-scoped for its purpose of code search, reading, and PR analysis. Each tool serves a specific function, and the count is appropriate without being too thin or bloated, fitting typical expectations for this domain.
The toolset covers core operations for code search and reading across local and GitHub contexts, with PR analysis included. A minor gap is the lack of tools for creating or modifying code (e.g., write operations), but for a read/search-focused server, the surface is largely complete and supports key workflows.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Codebase intelligence for AI agents ā dead code, blast radius, ownership.
