Skip to main content
Glama
srijanshukla18

XRAY MCP

by srijanshukla18
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

XRAY MCP - Progressive Code Intelligence for AI Assistants

Python MCP ast-grep

❌ Without XRAY

AI assistants struggle with codebase understanding. You get:

  • ❌ "I can't see your code structure"

  • ❌ "I don't know what depends on this function"

  • ❌ Generic refactoring advice without impact analysis

  • ❌ No understanding of symbol relationships

Related MCP server: Paparats MCP

✅ With XRAY

XRAY gives AI assistants code navigation capabilities. Add use XRAY tools to your prompt:

Analyze the UserService class and show me what would break if I change the authenticate method. use XRAY tools
Find all functions that call validate_user and show their dependencies. use XRAY tools

XRAY provides three focused tools:

  • 🗺️ Map (explore_repo) - See project structure with symbol skeletons

  • 🔍 Find (find_symbol) - Locate functions and classes with fuzzy search

  • 💥 Impact (what_breaks) - Find where a symbol is referenced

🚀 Quick Install

Modern Install with uv (Recommended)

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install XRAY
git clone https://github.com/srijanshukla18/xray.git
cd xray
uv tool install .

Automated Install with uv

For the quickest setup, this script automates the uv installation process.

curl -fsSL https://raw.githubusercontent.com/srijanshukla18/xray/main/install.sh | bash

Generate Config

# Get config for your tool
python mcp-config-generator.py cursor local_python
python mcp-config-generator.py claude docker  
python mcp-config-generator.py vscode source

Language Support

XRAY uses ast-grep, a tree-sitter powered structural search tool, providing accurate parsing for:

  • Python - Functions, classes, methods, async functions

  • JavaScript - Functions, classes, arrow functions, imports

  • TypeScript - All JavaScript features plus interfaces, type aliases

  • Go - Functions, structs, interfaces, methods

ast-grep ensures structural accuracy - it understands code syntax, not just text patterns.

The XRAY Workflow - Progressive Discovery

1. Map - Start Simple, Then Zoom In

# First: Get the big picture (directories only)
tree = explore_repo("/path/to/project")
# Returns:
# /path/to/project/
# ├── src/
# ├── tests/
# ├── docs/
# └── config/

# Then: Zoom into areas of interest with full details
tree = explore_repo("/path/to/project", focus_dirs=["src"], include_symbols=True)
# Returns:
# /path/to/project/
# └── src/
#     ├── auth.py
#     │   ├── class AuthService: # Handles user authentication
#     │   ├── def authenticate(username, password): # Validates user credentials
#     │   └── def logout(session_id): # Ends user session
#     └── models.py
#         ├── class User(BaseModel): # User account model
#         └── ... and 3 more

# Or: Limit depth for large codebases
tree = explore_repo("/path/to/project", max_depth=2, include_symbols=True)

2. Find - Locate Specific Symbols

# Find symbols matching "authenticate" (fuzzy search)
symbols = find_symbol("/path/to/project", "authenticate")
# Returns list of exact symbol objects with name, type, path, line numbers

3. Impact - See What Would Break

# Find where authenticate_user is used
symbol = symbols[0]  # From find_symbol
result = what_breaks(symbol)
# Returns: {"references": [...], "total_count": 12, 
#          "note": "Found 12 potential references based on text search..."}

Architecture

FastMCP Server (mcp_server.py)
    ↓
Core Engine (src/xray/core/)
    └── indexer.py      # Orchestrates ast-grep for structural analysis
    ↓
ast-grep (external binary)
    └── Tree-sitter powered structural search

Stateless design - No database, no persistent index. Each operation runs fresh ast-grep queries for real-time accuracy.

Why ast-grep?

Traditional grep searches text. ast-grep searches code structure:

  • grep: Finds "authenticate" in function names, variables, comments, strings

  • ast-grep: Finds only def authenticate() or function authenticate() definitions

This structural approach provides clean, accurate results essential for reliable code intelligence.

Performance Characteristics

  • Startup: Fast - launches ast-grep subprocess

  • File tree: Python directory traversal

  • Symbol search: Runs multiple ast-grep patterns, speed depends on codebase size

  • Impact analysis: Name-based search across all files

  • Memory: Minimal - no persistent state

What Makes This Practical

  1. Progressive Discovery - Start with directories, add symbols only where needed

  2. Smart Caching - Symbol extraction cached per git commit for instant re-runs

  3. Flexible Focus - Use focus_dirs to zoom into specific parts of large codebases

  4. Enhanced Symbols - See function signatures and docstrings, not just names

  5. Based on tree-sitter - ast-grep provides accurate structural analysis

XRAY helps AI assistants avoid information overload while providing deep code intelligence where needed.

Stateless Design

XRAY performs on-demand structural analysis using ast-grep. There's no database to manage, no index to build, and no state to maintain. Each query runs fresh against your current code.

Getting Started

  1. Install: See getting_started.md for modern installation

  2. Map the terrain: explore_repo("/path/to/project")

  3. Find your target: find_symbol("/path/to/project", "UserService")

  4. Assess impact: what_breaks(symbol)

The XRAY Philosophy

XRAY bridges the gap between simple text search and complex LSP servers:

  • More than grep - Matches code syntax patterns, not just text

  • Less than LSP - No language servers or complex setup

  • Practical for AI - Provides structured data about code relationships

A simple tool that helps AI assistants navigate codebases more effectively than text search alone.

Architectural Journey & Design Rationale

The current implementation of XRAY is the result of a rigorous evaluation of multiple code analysis methodologies. My journey involved prototyping and assessing several distinct approaches, each with its own set of trade-offs. Below is a summary of the considered architectures and the rationale for my final decision.

  1. Naive Grep-Based Analysis: I initially explored a baseline approach using standard grep for symbol identification. While expedient, this method proved fundamentally inadequate due to its inability to differentiate between syntactical constructs and simple text occurrences (e.g., comments, strings, variable names). The high signal-to-noise ratio rendered it impractical for reliable code intelligence.

  2. Tree-Sitter Native Integration: A direct integration with tree-sitter was evaluated to leverage its powerful parsing capabilities. However, this path was fraught with significant implementation complexities, including intractable errors within the parser generation and binding layers. The maintenance overhead and steep learning curve for custom grammar development were deemed prohibitive for a lean, multi-language tool.

  3. Language Server Protocol (LSP): I considered leveraging the Language Server Protocol for its comprehensive, standardized approach to code analysis. This was ultimately rejected due to the excessive operational burden it would impose on the end-user, requiring them to install, configure, and manage separate LSPs for each language in their environment. This friction conflicted with my goal of a lightweight, zero-configuration user experience.

  4. Comby-Based Structural Search: Comby was explored for its structural search and replacement capabilities. Despite its promising feature set, I encountered significant runtime instability and idiosyncratic behavior that undermined its reliability for mission-critical code analysis. The tool's performance and consistency did not meet my stringent requirements for a production-ready system.

  5. ast-grep as the Core Engine: My final and current architecture is centered on ast-grep. This tool provides the optimal balance of structural awareness, performance, and ease of integration. By leveraging tree-sitter internally, it offers robust, syntactically-aware code analysis without the complexities of direct tree-sitter integration or the overhead of LSPs. Its reliability and rich feature set for structural querying made it the unequivocal choice for XRAY's core engine.

Getting Started with XRAY - Modern Installation with uv

XRAY is a minimal-dependency code intelligence system that enhances AI assistants' understanding of codebases. This guide shows how to install and use XRAY with the modern uv package manager.

Prerequisites

  • Python 3.10 or later

  • uv - Fast Python package manager

Installing uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

Installation Options

Option 1: Automated Install (Easiest)

For the quickest setup, use the one-line installer from the README.md. This will handle everything for you.

curl -fsSL https://raw.githubusercontent.com/srijanshukla18/xray/main/install.sh | bash

Option 2: Quick Try with uvx (Recommended for Testing)

Run XRAY directly without installation using uvx:

# Clone the repository
git clone https://github.com/srijanshukla18/xray.git
cd xray

# Run XRAY directly with uvx
uvx --from . xray-mcp

Option 3: Install as a Tool (Recommended for Regular Use)

Install XRAY as a persistent tool:

# Clone and install
git clone https://github.com/srijanshukla18/xray.git
cd xray

# Install with uv
uv tool install .

# Now you can run xray-mcp from anywhere
xray-mcp

Option 4: Development Installation

For contributing or modifying XRAY:

# Clone the repository
git clone https://github.com/srijanshukla18/xray.git
cd xray

# Create and activate virtual environment with uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode
uv pip install -e .

# Run the server
python -m xray.mcp_server

Configure Your AI Assistant

After installation, configure your AI assistant to use XRAY:

Using the MCP Config Generator (Recommended)

For easier configuration, use the mcp-config-generator.py script located in the XRAY repository. This script can generate the correct JSON configuration for various AI assistants and installation methods.

To use it:

  1. Navigate to the XRAY repository root:

    cd /path/to/xray

  2. Run the script with your desired tool and installation method. For example, to get the configuration for Claude Desktop with an installed xray-mcp script:

    python mcp-config-generator.py claude installed_script

    Or for VS Code with a local Python installation:

    python mcp-config-generator.py vscode local_python

    The script will print the JSON configuration and instructions on where to add it.

    Available tools: cursor, claude, vscode Available methods: local_python, docker, source, installed_script (method availability varies by tool)

Manual Configuration (Advanced)

If you prefer to configure manually, here are examples for common AI assistants:

Claude CLI (Claude Code)

For Claude CLI users, simply run:

claude mcp add xray xray-mcp -s local

Then verify it's connected:

claude mcp list | grep xray

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "xray": {
      "command": "uvx",
      "args": ["--from", "/path/to/xray", "xray-mcp"]
    }
  }
}

Or if installed as a tool:

{
  "mcpServers": {
    "xray": {
      "command": "xray-mcp"
    }
  }
}

Cursor

Settings → Cursor Settings → MCP → Add new global MCP server:

{
  "mcpServers": {
    "xray": {
      "command": "xray-mcp"
    }
  }
}

Minimal Dependencies

One of XRAY's best features is its minimal dependency profile. You don't need to install a suite of language servers. XRAY uses:

  • ast-grep: A single, fast binary for structural code analysis.

  • Python: For the server and core logic.

This means you can start using XRAY immediately after installation with no complex setup!

Verify Installation

1. Check XRAY is accessible

# If installed as tool
xray-mcp --version

# If using uvx
uvx --from /path/to/xray xray-mcp --version

2. Test basic functionality

Create a test file test_xray.py:

def hello_world():
    print("Hello from XRAY test!")

def calculate_sum(a, b):
    return a + b

class Calculator:
    def multiply(self, x, y):
        return x * y

3. In your AI assistant, test these commands:

Build the index for the current directory. use XRAY tools

Expected: Success message with files indexed

Find all functions containing "hello". use XRAY tools

Expected: Should find hello_world function

What would break if I change the multiply method? use XRAY tools

Expected: Impact analysis showing any dependencies

Usage Examples

Once configured, use XRAY by adding "use XRAY tools" to your prompts:

# Index a codebase
"Index the src/ directory for analysis. use XRAY tools"

# Find symbols
"Find all classes that contain 'User' in their name. use XRAY tools"

# Impact analysis
"What breaks if I change the authenticate method in UserService? use XRAY tools"

# Dependency tracking
"What does the PaymentProcessor class depend on? use XRAY tools"

# Location queries
"What function is defined at line 125 in main.py? use XRAY tools"

Troubleshooting

uv not found

Make sure uv is in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.cargo/bin:$PATH"

Permission denied

On macOS/Linux, you might need to make the script executable:

chmod +x ~/.local/bin/xray-mcp

Python version issues

XRAY requires Python 3.10+. Check your version:

python --version

# If needed, install Python 3.10+ with uv
uv python install 3.10

MCP connection issues

  1. Check XRAY is running: xray-mcp --test

  2. Verify your MCP config JSON is valid

  3. Restart your AI assistant after config changes

Advanced Configuration

Custom Database Location

Set the XRAY_DB_PATH environment variable:

export XRAY_DB_PATH="$HOME/.xray/databases"

Debug Mode

Enable debug logging:

export XRAY_DEBUG=1

What's Next?

  1. Index your first repository: In your AI assistant, ask it to "Build the index for my project. use XRAY tools"

  2. Explore the tools:

    • build_index - Visual file tree of your repository

    • find_symbol - Fuzzy search for functions, classes, and methods

    • what_breaks - Find what code depends on a symbol (reverse dependencies)

    • what_depends - Find what a symbol depends on (calls and imports)

    Note: Results may include matches from comments or strings. The AI assistant will intelligently filter based on context.

  3. Read the documentation: Check out the README for detailed examples and API reference

Why XRAY Uses a Minimal Dependency Approach

XRAY is designed for simplicity and ease of use. It relies on:

  • ast-grep: A powerful and fast single-binary tool for code analysis.

  • Python: For its robust standard library and ease of scripting.

This approach avoids the complexity of setting up and managing multiple language servers, while still providing accurate, structural code intelligence.

Benefits of Using uv

  • 10-100x faster than pip for installations

  • No virtual environment hassles - uv manages everything

  • Reproducible installs - uv.lock ensures consistency

  • Built-in Python management - install any Python version

  • Global tool management - like pipx but faster

Happy coding with XRAY! 🚀

Available Tools

4 tools
explore_repoA

🗺️ STEP 1: Map the codebase structure - start simple, then zoom in!

PROGRESSIVE DISCOVERY WORKFLOW:

  1. First call: explore_repo("/path/to/project") - See directory structure only

  2. Zoom in: explore_repo("/path/to/project", focus_dirs=["src"], include_symbols=True)

  3. Go deeper: explore_repo("/path/to/project", max_depth=3, include_symbols=True)

INPUTS:

  • root_path: The ABSOLUTE path to the project (e.g., "/Users/john/myproject") NOT relative paths like "./myproject" or "~/myproject"

  • max_depth: How deep to traverse directories (None = unlimited, accepts int or string)

  • include_symbols: Show function/class signatures with docs (False = dirs only, accepts bool or string)

  • focus_dirs: List of top-level directories to focus on (e.g., ["src", "lib"])

  • max_symbols_per_file: Max symbols to show per file when include_symbols=True (accepts int or string)

EXAMPLE 1 - Initial exploration (directory only): explore_repo("/Users/john/project")

Returns:

/Users/john/project/

├── src/

├── tests/

├── docs/

└── README.md

EXAMPLE 2 - Zoom into src/ with symbols: explore_repo("/Users/john/project", focus_dirs=["src"], include_symbols=True)

Returns:

/Users/john/project/

└── src/

├── auth.py

│ ├── class AuthService: # Handles user authentication

│ ├── def authenticate(username, password): # Validates credentials

│ └── def logout(session_id): # Ends user session

└── models.py

├── class User(BaseModel): # User account model

└── ... and 3 more

EXAMPLE 3 - Limited depth exploration: explore_repo("/Users/john/project", max_depth=1, include_symbols=True)

Shows only top-level dirs and files with their symbols

💡 PRO TIP: Start with include_symbols=False to see structure, then set it to True for areas you want to examine in detail. This prevents information overload!

⚡ PERFORMANCE: Symbol extraction is cached per git commit - subsequent calls are instant!

WHAT TO DO NEXT:

  • If you found interesting directories, zoom in with focus_dirs

  • If you see relevant files, use find_symbol() to locate specific functions

ParametersJSON Schema
NameRequiredDescriptionDefault
root_pathYes
max_depthNo
include_symbolsNo
focus_dirsNo
max_symbols_per_fileNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.9/5.0
Behavior5/5

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 and excels. It explains the tool's progressive workflow, caching behavior ('Symbol extraction is cached per git commit - subsequent calls are instant!'), performance implications, and output format through detailed examples. It also clarifies path requirements ('ABSOLUTE path... NOT relative paths') and default behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (workflow, inputs, examples, tips, next steps) and uses emojis for visual organization. While slightly verbose, every sentence adds value: the workflow guides usage, examples illustrate outputs, tips optimize performance, and next steps connect to sibling tools. It could be more concise but remains highly effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is exceptionally complete for a tool with 5 parameters, 0% schema coverage, no annotations, but an output schema. It covers purpose, usage workflow, parameter details, behavioral traits (caching, performance), examples with output formats, and integration with sibling tools. The presence of an output schema means return values don't need explanation, and the description fills all other gaps comprehensively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Given 0% schema description coverage, the description fully compensates by providing comprehensive parameter semantics. Each of the 5 parameters is clearly explained with purpose, constraints, and examples: root_path (absolute vs. relative), max_depth (unlimited vs. limited), include_symbols (dirs only vs. with symbols), focus_dirs (top-level directories to filter), and max_symbols_per_file (limit when symbols shown). The examples demonstrate practical usage of all parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Map the codebase structure - start simple, then zoom in!' It specifies the verb ('explore', 'map') and resource ('repo', 'codebase structure'), and distinguishes it from sibling tools by focusing on structural discovery rather than symbol searching (find_symbol), interface reading (read_interface), or breakage analysis (what_breaks).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when and how to use this tool versus alternatives. It outlines a 'PROGRESSIVE DISCOVERY WORKFLOW' with three steps, advises starting with 'include_symbols=False' to avoid overload, and directs users to 'use find_symbol() to locate specific functions' after exploration. It clearly differentiates from sibling tools by positioning explore_repo as the entry point for structural mapping.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_symbolA

🔍 STEP 2: Find specific functions, classes, or methods in the codebase.

USE THIS AFTER explore_repo() when you need to locate a specific piece of code. Uses fuzzy matching - you don't need the exact name!

INPUTS:

  • root_path: Same ABSOLUTE path used in explore_repo

  • query: What you're looking for (fuzzy search works!) Examples: "auth", "user service", "validate", "parseJSON"

EXAMPLE INPUTS: find_symbol("/Users/john/awesome-project", "authenticate") find_symbol("/Users/john/awesome-project", "user model") # Fuzzy matches "UserModel"

EXAMPLE OUTPUT: [ { "name": "authenticate_user", "type": "function", "path": "/Users/john/awesome-project/src/auth.py", "start_line": 45, "end_line": 67 }, { "name": "AuthService", "type": "class", "path": "/Users/john/awesome-project/src/services.py", "start_line": 12, "end_line": 89 } ]

RETURNS: List of symbol objects (dictionaries). Save these objects - you'll pass them to what_breaks()! Empty list if no matches found.

WHAT TO DO NEXT: Pick a symbol from the results and pass THE ENTIRE SYMBOL OBJECT to what_breaks() to see where it's used in the codebase.

ParametersJSON Schema
NameRequiredDescriptionDefault
root_pathYes
queryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and adds valuable behavioral context: it explains the fuzzy matching capability, returns a list of symbol objects or empty list if no matches, and specifies that results should be saved for use with what_breaks(). It doesn't cover permissions or rate limits, but provides clear operational details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections (description, usage, inputs, examples, returns, next steps) and front-loaded purpose. Slightly verbose due to detailed examples and instructions, but every sentence adds value for tool invocation and workflow integration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 parameters with 0% schema coverage, no annotations, but an output schema exists, the description is complete: it covers purpose, usage, parameters with semantics, example inputs/outputs, return behavior, and integration with sibling tools (explore_repo and what_breaks), leaving no gaps for agent operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate fully. It does so by explaining both parameters: root_path ('Same ABSOLUTE path used in explore_repo') and query ('What you're looking for (fuzzy search works!)') with examples and formatting guidance, adding meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Find specific functions, classes, or methods in the codebase' with 'fuzzy matching'. It distinguishes from siblings like explore_repo (which it follows) and what_breaks (which it precedes), making the verb+resource+scope specific and differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: 'USE THIS AFTER explore_repo() when you need to locate a specific piece of code.' It names the sibling tool explore_repo as a prerequisite and indicates when to use this tool (for fuzzy searching after exploration), with no misleading or missing exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_interfaceA

📖 READ INTERFACE: Get a high-level overview of a file without reading implementation.

Returns function signatures, class definitions, and docstrings. Perfect for understanding how to USE a module without reading the whole thing.

INPUTS:

  • root_path: The ABSOLUTE path to the project root

  • file_path: The path to the specific file you want to read (can be relative to root)

EXAMPLE: read_interface("/Users/john/project", "src/auth.py")

ParametersJSON Schema
NameRequiredDescriptionDefault
root_pathYes
file_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

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 describes what the tool returns (interface elements) and its non-destructive nature (implied by 'read'), but doesn't cover aspects like error handling, performance characteristics, or authentication needs. The description adds useful context about the tool's scope but lacks comprehensive behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, returns, usage context, inputs, example) and uses emojis for visual organization. While slightly longer than minimal, every sentence adds value. The information is front-loaded with the core purpose stated first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 parameters, no annotations, but has output schema), the description provides good coverage. It explains the purpose, parameters, and includes an example. Since an output schema exists, it doesn't need to detail return values. The main gap is lack of behavioral details like error cases or limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage for 2 parameters, the description compensates well by explaining both parameters in the INPUTS section: 'root_path' as 'The ABSOLUTE path to the project root' and 'file_path' as 'The path to the specific file you want to read (can be relative to root)'. It also provides a concrete example that clarifies usage. This adds significant meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('Get a high-level overview', 'understanding how to USE') and distinguishes it from siblings by focusing on extracting interface information rather than exploring, finding symbols, or analyzing breaks. It explicitly mentions what it returns (function signatures, class definitions, docstrings) and what it doesn't do ('without reading implementation').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when to use this tool ('Perfect for understanding how to USE a module without reading the whole thing'), which implicitly suggests alternatives like reading the full file. However, it doesn't explicitly mention when not to use it or name specific sibling tools as alternatives, though the context is sufficient for differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

what_breaksA

💥 STEP 3: See what code might break if you change this symbol.

USE THIS AFTER find_symbol() to understand the impact of changing a function/class.

IMPROVEMENTS:

  • Uses structural search (ast-grep) to find ACTUAL code references (ignoring comments/strings).

  • Returns 2 lines of context around each match.

INPUT:

  • exact_symbol: Pass THE ENTIRE SYMBOL OBJECT from find_symbol(), not just the name! Must be a dictionary with AT LEAST 'name' and 'path' keys.

EXAMPLE INPUT:

First, get a symbol from find_symbol():

symbols = find_symbol("/Users/john/project", "authenticate") symbol = symbols[0] # Pick the first result

Then pass THE WHOLE SYMBOL OBJECT:

what_breaks(symbol)

EXAMPLE OUTPUT: { "references": [ { "file": "/Users/john/project/src/api.py", "line": 23, "text": " # Authenticate the user user = authenticate_user(username, password) if not user:", "type": "code" } ], "total_count": 1, "strategy": "structural", "note": "Found 1 references using structural search." }

ParametersJSON Schema
NameRequiredDescriptionDefault
exact_symbolYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior4/5

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 effectively describes key behaviors: it performs structural search using ast-grep, ignores comments and strings, returns 2 lines of context around each match, and outputs a structured result with references and metadata. However, it doesn't mention potential limitations like performance or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, usage, improvements, input, examples), but it includes an extensive example input and output that could be condensed. Most sentences earn their place by providing essential information, though the examples are detailed and might be overly verbose for a concise description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (structural code analysis), no annotations, and an output schema that covers return values, the description is complete enough. It explains the tool's purpose, usage context, behavioral traits, parameter requirements, and provides illustrative examples, compensating well for the lack of structured metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds significant meaning beyond the schema by explaining that 'exact_symbol' must be 'THE ENTIRE SYMBOL OBJECT from find_symbol(), not just the name!' and specifying it 'Must be a dictionary with AT LEAST 'name' and 'path' keys.' This clarifies the parameter's purpose and constraints that aren't in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'See what code might break if you change this symbol.' It specifies the verb ('see what code might break') and resource ('this symbol'), and distinguishes it from sibling tools by explicitly mentioning it should be used 'AFTER find_symbol()' and contrasting with 'structural search' versus other approaches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool: 'USE THIS AFTER find_symbol() to understand the impact of changing a function/class.' It also specifies an alternative approach by noting it 'Uses structural search (ast-grep) to find ACTUAL code references (ignoring comments/strings),' implying a distinction from other search methods.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv1.0.0
    • Changedexplore_repo7 fields changed
      • removedInput schema / properties / focus_dirs / title
        Removed value: -"Focus Dirs"
      • removedInput schema / properties / include_symbols / title
        Removed value: -"Include Symbols"
      • removedInput schema / properties / max_depth / title
        Removed value: -"Max Depth"
      • removedInput schema / properties / max_symbols_per_file / title
        Removed value: -"Max Symbols Per File"
      • removedInput schema / properties / root_path / title
        Removed value: -"Root Path"
      • removedOutput schema / properties / result / title
        Removed value: -"Result"
      • removedOutput schema / title
        Removed value: -"_WrappedResult"
    • Changedfind_symbol4 fields changed
      • removedInput schema / properties / query / title
        Removed value: -"Query"
      • removedInput schema / properties / root_path / title
        Removed value: -"Root Path"
      • removedOutput schema / properties / result / title
        Removed value: -"Result"
      • removedOutput schema / title
        Removed value: -"_WrappedResult"
    • Addedread_interface
    • Changedwhat_breaks1 field changed
      • removedInput schema / properties / exact_symbol / title
        Removed value: -"Exact Symbol"
  2. 3 tool updates
    • First observedexplore_repo
    • First observedfind_symbol
    • First observedwhat_breaks
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0
Disambiguation5/5

Each tool has a distinct, non-overlapping purpose in the code exploration workflow: explore_repo maps structure, find_symbol locates specific symbols, read_interface provides file overviews, and what_breaks analyzes dependencies. The tools are clearly sequenced and complementary, with no ambiguity in their roles.

Naming Consistency4/5

Three tools use snake_case with descriptive verbs (explore_repo, find_symbol, read_interface), while what_breaks uses snake_case but with a less conventional verb phrase. The naming is mostly consistent and readable, with only minor deviation in style for what_breaks.

Tool Count5/5

Four tools is well-scoped for a code exploration server, covering the essential workflow from mapping structure to analyzing impacts. Each tool earns its place without redundancy, and the count aligns with the progressive discovery approach described.

Completeness5/5

The tool set provides complete coverage for codebase exploration: explore_repo for initial mapping, find_symbol for searching, read_interface for understanding files, and what_breaks for impact analysis. There are no obvious gaps, and the tools support a full workflow from discovery to dependency checking.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Paparats MCP

    IBazylchuk
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides AI coding assistants with deep, semantic understanding of local codebases via AST-aware chunking, cross-repo symbol graphs, and architectural memory, enabling context-aware code search and dependency tracing.
    10
    MIT

  • code-intel

    nairraf
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides semantic code search and code insights via a knowledge graph, enabling AI to understand, navigate, and modify complex projects with deep dependency and architecture analysis.
    MIT

  • mcp-codebase-intelligence

    g-tiwari
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides a semantic understanding of your codebase by parsing with tree-sitter and building a graph of symbols and dependencies. Enables AI assistants to navigate code, analyze changes, and discover architecture using 18 tools with minimal context overhead.
    22
    1
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/srijanshukla18/xray'

If you have feedback or need assistance with the MCP directory API, please join our Discord server