Xray

🚀 XRAY MCP - Progressive Code Intelligence for AI Assistants

XRAY MCP offers progressive code intelligence for AI assistants, enabling them to better understand codebases and provide more accurate analysis and suggestions.

❌ Without XRAY

AI assistants face difficulties in understanding codebases. You may encounter the following issues:

• ❌ "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 equips AI assistants with code navigation capabilities. Simply 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) - Visualize the project structure with symbol skeletons
• 🔍 Find (find_symbol) - Locate functions and classes using fuzzy search
• 💥 Impact (what_breaks) - Identify where a symbol is referenced

🚀 Quick Start

📦 Installation

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, use this script to automate 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

💻 Usage Examples

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..."}

📚 Documentation

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.

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, while 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

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)

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

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

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

# 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

# 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

Using the MCP Config Generator (Recommended)

cd /path/to/xray
python mcp-config-generator.py claude installed_script
python mcp-config-generator.py vscode local_python

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

Manual Configuration (Advanced)

Claude CLI (Claude Code)

claude mcp add xray xray-mcp -s local
claude mcp list | grep xray

Claude Desktop

{
  "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

XRAY uses:

• ast-grep: A single, fast binary for structural code analysis.
• Python: For the server and core logic.

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

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

Find all functions containing "hello". use XRAY tools

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

Usage Examples

# 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

export PATH="$HOME/.cargo/bin:$PATH"

Permission denied

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

Python version issues

python --version
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

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

Debug Mode

export XRAY_DEBUG=1

What's Next?

1. Index your first repository: "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)
3. Read the documentation: README

Why XRAY Uses a Minimal Dependency Approach

XRAY relies on:

• ast-grep: A powerful and fast single-binary tool for code analysis.
• Python: For its robust standard library and ease of scripting.

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! 🚀