XRAY MCP - Progressive Code Intelligence for AI Assistants

❌ 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

✅ 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)