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 XRAY gives AI assistants code navigation capabilities. Add use XRAY tools to your prompt: XRAY provides three focused tools: - 🗺️ Map (explorerepo) - S
Add this skill
npx mdskills install srijanshukla18/xrayWell-documented MCP server providing structural code analysis through ast-grep with clear workflows
1# XRAY MCP - Progressive Code Intelligence for AI Assistants23[](https://python.org) [](https://modelcontextprotocol.io) [](https://ast-grep.github.io)45## ❌ Without XRAY67AI assistants struggle with codebase understanding. You get:89- ❌ "I can't see your code structure"10- ❌ "I don't know what depends on this function"11- ❌ Generic refactoring advice without impact analysis12- ❌ No understanding of symbol relationships1314## ✅ With XRAY1516XRAY gives AI assistants code navigation capabilities. Add `use XRAY tools` to your prompt:1718```txt19Analyze the UserService class and show me what would break if I change the authenticate method. use XRAY tools20```2122```txt23Find all functions that call validate_user and show their dependencies. use XRAY tools24```2526XRAY provides three focused tools:2728- 🗺️ **Map** (`explore_repo`) - See project structure with symbol skeletons29- 🔍 **Find** (`find_symbol`) - Locate functions and classes with fuzzy search30- 💥 **Impact** (`what_breaks`) - Find where a symbol is referenced3132## 🚀 Quick Install3334### Modern Install with uv (Recommended)3536```bash37# Install uv if you don't have it38curl -LsSf https://astral.sh/uv/install.sh | sh3940# Clone and install XRAY41git clone https://github.com/srijanshukla18/xray.git42cd xray43uv tool install .44```4546### Automated Install with uv4748For the quickest setup, this script automates the `uv` installation process.4950```bash51curl -fsSL https://raw.githubusercontent.com/srijanshukla18/xray/main/install.sh | bash52```5354### Generate Config5556```bash57# Get config for your tool58python mcp-config-generator.py cursor local_python59python mcp-config-generator.py claude docker60python mcp-config-generator.py vscode source61```6263## Language Support6465XRAY uses [ast-grep](https://ast-grep.github.io), a tree-sitter powered structural search tool, providing accurate parsing for:66- **Python** - Functions, classes, methods, async functions67- **JavaScript** - Functions, classes, arrow functions, imports68- **TypeScript** - All JavaScript features plus interfaces, type aliases69- **Go** - Functions, structs, interfaces, methods7071ast-grep ensures structural accuracy - it understands code syntax, not just text patterns.7273## The XRAY Workflow - Progressive Discovery7475### 1. Map - Start Simple, Then Zoom In76```python77# First: Get the big picture (directories only)78tree = explore_repo("/path/to/project")79# Returns:80# /path/to/project/81# ├── src/82# ├── tests/83# ├── docs/84# └── config/8586# Then: Zoom into areas of interest with full details87tree = explore_repo("/path/to/project", focus_dirs=["src"], include_symbols=True)88# Returns:89# /path/to/project/90# └── src/91# ├── auth.py92# │ ├── class AuthService: # Handles user authentication93# │ ├── def authenticate(username, password): # Validates user credentials94# │ └── def logout(session_id): # Ends user session95# └── models.py96# ├── class User(BaseModel): # User account model97# └── ... and 3 more9899# Or: Limit depth for large codebases100tree = explore_repo("/path/to/project", max_depth=2, include_symbols=True)101```102103### 2. Find - Locate Specific Symbols104```python105# Find symbols matching "authenticate" (fuzzy search)106symbols = find_symbol("/path/to/project", "authenticate")107# Returns list of exact symbol objects with name, type, path, line numbers108```109110### 3. Impact - See What Would Break111```python112# Find where authenticate_user is used113symbol = symbols[0] # From find_symbol114result = what_breaks(symbol)115# Returns: {"references": [...], "total_count": 12,116# "note": "Found 12 potential references based on text search..."}117```118119120## Architecture121122```123FastMCP Server (mcp_server.py)124 ↓125Core Engine (src/xray/core/)126 └── indexer.py # Orchestrates ast-grep for structural analysis127 ↓128ast-grep (external binary)129 └── Tree-sitter powered structural search130```131132**Stateless design** - No database, no persistent index. Each operation runs fresh ast-grep queries for real-time accuracy.133134## Why ast-grep?135136Traditional grep searches text. ast-grep searches code structure:137138- **grep**: Finds "authenticate" in function names, variables, comments, strings139- **ast-grep**: Finds only `def authenticate()` or `function authenticate()` definitions140141This structural approach provides clean, accurate results essential for reliable code intelligence.142143## Performance Characteristics144145- **Startup**: Fast - launches ast-grep subprocess146- **File tree**: Python directory traversal147- **Symbol search**: Runs multiple ast-grep patterns, speed depends on codebase size148- **Impact analysis**: Name-based search across all files149- **Memory**: Minimal - no persistent state150151## What Makes This Practical1521531. **Progressive Discovery** - Start with directories, add symbols only where needed1542. **Smart Caching** - Symbol extraction cached per git commit for instant re-runs1553. **Flexible Focus** - Use `focus_dirs` to zoom into specific parts of large codebases1564. **Enhanced Symbols** - See function signatures and docstrings, not just names1575. **Based on tree-sitter** - ast-grep provides accurate structural analysis158159XRAY helps AI assistants avoid information overload while providing deep code intelligence where needed.160161## Stateless Design162163XRAY 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.164165## Getting Started1661671. **Install**: See [`getting_started.md`](getting_started.md) for modern installation1682. **Map the terrain**: `explore_repo("/path/to/project")`1693. **Find your target**: `find_symbol("/path/to/project", "UserService")`1704. **Assess impact**: `what_breaks(symbol)`171172## The XRAY Philosophy173174XRAY bridges the gap between simple text search and complex LSP servers:175176- **More than grep** - Matches code syntax patterns, not just text177- **Less than LSP** - No language servers or complex setup178- **Practical for AI** - Provides structured data about code relationships179180A simple tool that helps AI assistants navigate codebases more effectively than text search alone.181182## Architectural Journey & Design Rationale183184The 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.1851861. **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.1871882. **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.1891903. **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.1911924. **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.1931945. **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.195196---197198# Getting Started with XRAY - Modern Installation with uv199200XRAY 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.201202## Prerequisites203204- Python 3.10 or later205- [uv](https://docs.astral.sh/uv/) - Fast Python package manager206207### Installing uv208209```bash210# macOS/Linux211curl -LsSf https://astral.sh/uv/install.sh | sh212213# Windows214powershell -c "irm https://astral.sh/uv/install.ps1 | iex"215216# Or with pip217pip install uv218```219220## Installation Options221222### Option 1: Automated Install (Easiest)223224For the quickest setup, use the one-line installer from the `README.md`. This will handle everything for you.225226```bash227curl -fsSL https://raw.githubusercontent.com/srijanshukla18/xray/main/install.sh | bash228```229230### Option 2: Quick Try with uvx (Recommended for Testing)231232Run XRAY directly without installation using `uvx`:233234```bash235# Clone the repository236git clone https://github.com/srijanshukla18/xray.git237cd xray238239# Run XRAY directly with uvx240uvx --from . xray-mcp241```242243### Option 3: Install as a Tool (Recommended for Regular Use)244245Install XRAY as a persistent tool:246247```bash248# Clone and install249git clone https://github.com/srijanshukla18/xray.git250cd xray251252# Install with uv253uv tool install .254255# Now you can run xray-mcp from anywhere256xray-mcp257```258259### Option 4: Development Installation260261For contributing or modifying XRAY:262263```bash264# Clone the repository265git clone https://github.com/srijanshukla18/xray.git266cd xray267268# Create and activate virtual environment with uv269uv venv270source .venv/bin/activate # On Windows: .venv\Scripts\activate271272# Install in editable mode273uv pip install -e .274275# Run the server276python -m xray.mcp_server277```278279## Configure Your AI Assistant280281After installation, configure your AI assistant to use XRAY:282283### Using the MCP Config Generator (Recommended)284285For 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.286287To use it:2882891. Navigate to the XRAY repository root:290 ```bash291 cd /path/to/xray292 ```2932. 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:294 ```bash295 python mcp-config-generator.py claude installed_script296 ```297 Or for VS Code with a local Python installation:298 ```bash299 python mcp-config-generator.py vscode local_python300 ```301 The script will print the JSON configuration and instructions on where to add it.302303 Available tools: `cursor`, `claude`, `vscode`304 Available methods: `local_python`, `docker`, `source`, `installed_script` (method availability varies by tool)305306### Manual Configuration (Advanced)307308If you prefer to configure manually, here are examples for common AI assistants:309310#### Claude CLI (Claude Code)311312For Claude CLI users, simply run:313314```bash315claude mcp add xray xray-mcp -s local316```317318Then verify it's connected:319320```bash321claude mcp list | grep xray322```323324#### Claude Desktop325326Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):327328```json329{330 "mcpServers": {331 "xray": {332 "command": "uvx",333 "args": ["--from", "/path/to/xray", "xray-mcp"]334 }335 }336}337```338339Or if installed as a tool:340341```json342{343 "mcpServers": {344 "xray": {345 "command": "xray-mcp"346 }347 }348}349```350351#### Cursor352353Settings → Cursor Settings → MCP → Add new global MCP server:354355```json356{357 "mcpServers": {358 "xray": {359 "command": "xray-mcp"360 }361 }362}363```364365## Minimal Dependencies366367One of XRAY's best features is its minimal dependency profile. You don't need to install a suite of language servers. XRAY uses:368369- **ast-grep**: A single, fast binary for structural code analysis.370- **Python**: For the server and core logic.371372This means you can start using XRAY immediately after installation with no complex setup!373374## Verify Installation375376### 1. Check XRAY is accessible377378```bash379# If installed as tool380xray-mcp --version381382# If using uvx383uvx --from /path/to/xray xray-mcp --version384```385386### 2. Test basic functionality387388Create a test file `test_xray.py`:389390```python391def hello_world():392 print("Hello from XRAY test!")393394def calculate_sum(a, b):395 return a + b396397class Calculator:398 def multiply(self, x, y):399 return x * y400```401402### 3. In your AI assistant, test these commands:403404```405Build the index for the current directory. use XRAY tools406```407408Expected: Success message with files indexed409410```411Find all functions containing "hello". use XRAY tools412```413414Expected: Should find `hello_world` function415416```417What would break if I change the multiply method? use XRAY tools418```419420Expected: Impact analysis showing any dependencies421422## Usage Examples423424Once configured, use XRAY by adding "use XRAY tools" to your prompts:425426```427# Index a codebase428"Index the src/ directory for analysis. use XRAY tools"429430# Find symbols431"Find all classes that contain 'User' in their name. use XRAY tools"432433# Impact analysis434"What breaks if I change the authenticate method in UserService? use XRAY tools"435436# Dependency tracking437"What does the PaymentProcessor class depend on? use XRAY tools"438439# Location queries440"What function is defined at line 125 in main.py? use XRAY tools"441```442443## Troubleshooting444445### uv not found446447Make sure uv is in your PATH:448449```bash450# Add to ~/.bashrc or ~/.zshrc451export PATH="$HOME/.cargo/bin:$PATH"452```453454### Permission denied455456On macOS/Linux, you might need to make the script executable:457458```bash459chmod +x ~/.local/bin/xray-mcp460```461462### Python version issues463464XRAY requires Python 3.10+. Check your version:465466```bash467python --version468469# If needed, install Python 3.10+ with uv470uv python install 3.10471```472473### MCP connection issues4744751. Check XRAY is running: `xray-mcp --test`4762. Verify your MCP config JSON is valid4773. Restart your AI assistant after config changes478479## Advanced Configuration480481### Custom Database Location482483Set the `XRAY_DB_PATH` environment variable:484485```bash486export XRAY_DB_PATH="$HOME/.xray/databases"487```488489### Debug Mode490491Enable debug logging:492493```bash494export XRAY_DEBUG=1495```496497## What's Next?4984991. **Index your first repository**: In your AI assistant, ask it to "Build the index for my project. use XRAY tools"5005012. **Explore the tools**:502 - `build_index` - Visual file tree of your repository503 - `find_symbol` - Fuzzy search for functions, classes, and methods504 - `what_breaks` - Find what code depends on a symbol (reverse dependencies)505 - `what_depends` - Find what a symbol depends on (calls and imports)506507 Note: Results may include matches from comments or strings. The AI assistant will intelligently filter based on context.5085093. **Read the documentation**: Check out the [README](README.md) for detailed examples and API reference510511## Why XRAY Uses a Minimal Dependency Approach512513XRAY is designed for simplicity and ease of use. It relies on:514515- **ast-grep**: A powerful and fast single-binary tool for code analysis.516- **Python**: For its robust standard library and ease of scripting.517518This approach avoids the complexity of setting up and managing multiple language servers, while still providing accurate, structural code intelligence.519520## Benefits of Using uv521522- **10-100x faster** than pip for installations523- **No virtual environment hassles** - uv manages everything524- **Reproducible installs** - uv.lock ensures consistency525- **Built-in Python management** - install any Python version526- **Global tool management** - like pipx but faster527528Happy coding with XRAY! 🚀529
Full transparency — inspect the skill content before installing.