Xray

🚀 XRAY MCP - 为AI助手提供渐进式代码智能

[XRAY MCP借助先进技术，为AI助手赋予强大的代码导航与分析能力，助力开发者更高效地理解和处理代码库。]

❌ 没有XRAY的情况

AI助手在理解代码库时会遇到困难，你可能会得到以下反馈：

• ❌ “我看不到你的代码结构”
• ❌ “我不知道这个函数依赖于什么”
• ❌ 没有影响分析的通用重构建议
• ❌ 不理解符号之间的关系

✅ 有XRAY的情况

XRAY为AI助手提供了代码导航能力。在你的提示语中添加 use XRAY tools：

分析UserService类，并告诉我如果我更改authenticate方法会导致哪些部分出错。use XRAY tools

查找所有调用validate_user的函数，并显示它们的依赖关系。use XRAY tools

XRAY提供了三个聚焦工具：

• 🗺️ Map (explore_repo) - 以符号骨架的形式查看项目结构
• 🔍 Find (find_symbol) - 通过模糊搜索定位函数和类
• 💥 Impact (what_breaks) - 查找符号的引用位置

🚀 快速开始

使用uv进行现代安装（推荐）

# 如果你没有安装uv，可以使用以下命令安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆并安装XRAY
git clone https://github.com/srijanshukla18/xray.git
cd xray
uv tool install .

使用uv进行自动化安装

为了最快完成设置，这个脚本可以自动化 uv 的安装过程。

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

生成配置

# 获取你的工具的配置
python mcp-config-generator.py cursor local_python
python mcp-config-generator.py claude docker  
python mcp-config-generator.py vscode source

✨ 主要特性

语言支持

XRAY使用 ast-grep，这是一个由tree-sitter驱动的结构搜索工具，可为以下语言提供准确的解析：

• Python - 函数、类、方法、异步函数
• JavaScript - 函数、类、箭头函数、导入
• TypeScript - 所有JavaScript特性，外加接口、类型别名
• Go - 函数、结构体、接口、方法

ast-grep确保了结构的准确性——它理解代码语法，而不仅仅是文本模式。

渐进式发现工作流程

1. Map - 从简单开始，然后深入探究

# 首先：获取整体概况（仅显示目录）
tree = explore_repo("/path/to/project")
# 返回：
# /path/to/project/
# ├── src/
# ├── tests/
# ├── docs/
# └── config/

# 然后：深入到感兴趣的区域并获取完整细节
tree = explore_repo("/path/to/project", focus_dirs=["src"], include_symbols=True)
# 返回：
# /path/to/project/
# └── src/
#     ├── auth.py
#     │   ├── class AuthService: # 处理用户认证
#     │   ├── def authenticate(username, password): # 验证用户凭证
#     │   └── def logout(session_id): # 结束用户会话
#     └── models.py
#         ├── class User(BaseModel): # 用户账户模型
#         └── ... 还有3个

# 或者：对于大型代码库，限制深度
tree = explore_repo("/path/to/project", max_depth=2, include_symbols=True)

2. Find - 定位特定符号

# 查找与“authenticate”匹配的符号（模糊搜索）
symbols = find_symbol("/path/to/project", "authenticate")
# 返回精确符号对象的列表，包含名称、类型、路径、行号

3. Impact - 查看会受到影响的部分

# 查找authenticate_user的使用位置
symbol = symbols[0]  # 从find_symbol获取
result = what_breaks(symbol)
# 返回：{"references": [...], "total_count": 12, 
#          "note": "根据文本搜索找到12个潜在引用..."}

架构

FastMCP Server (mcp_server.py)
    ↓
Core Engine (src/xray/core/)
    └── indexer.py      # 协调ast-grep进行结构分析
    ↓
ast-grep (external binary)
    └── Tree-sitter powered structural search

无状态设计 - 无需数据库，无需持久索引。每个操作都会运行全新的ast-grep查询，以确保实时准确性。

为什么选择ast-grep？

传统的grep搜索文本，而ast-grep搜索代码结构：

• grep：在函数名、变量、注释、字符串中查找“authenticate”
• ast-grep：仅查找 def authenticate() 或 function authenticate() 定义

这种结构方法提供了干净、准确的结果，这对于可靠的代码智能至关重要。

性能特点

• 启动：快速 - 启动ast-grep子进程
• 文件树：使用Python进行目录遍历
• 符号搜索：运行多个ast-grep模式，速度取决于代码库的大小
• 影响分析：在所有文件中进行基于名称的搜索
• 内存：最小化 - 无持久状态

实用性体现

1. 渐进式发现 - 从目录开始，仅在需要的地方添加符号
2. 智能缓存 - 每个git提交的符号提取都会被缓存，以便即时重新运行
3. 灵活聚焦 - 使用 focus_dirs 深入大型代码库的特定部分
4. 增强符号 - 查看函数签名和文档字符串，而不仅仅是名称
5. 基于tree-sitter - ast-grep提供准确的结构分析

XRAY帮助AI助手避免信息过载，同时在需要的地方提供深入的代码智能。

无状态设计

XRAY使用ast-grep进行按需结构分析。无需管理数据库，无需构建索引，也无需维护状态。每个查询都会针对你当前的代码运行全新的查询。

XRAY的设计理念

XRAY弥合了简单文本搜索和复杂LSP服务器之间的差距：

• 比grep更强大 - 匹配代码语法模式，而不仅仅是文本
• 比LSP更轻量 - 无需语言服务器或复杂的设置
• 对AI实用 - 提供有关代码关系的结构化数据

这是一个简单的工具，可帮助AI助手比单纯的文本搜索更有效地导航代码库。

架构演变与设计依据

XRAY的当前实现是对多种代码分析方法进行严格评估的结果。我的探索过程涉及对几种不同方法进行原型设计和评估，每种方法都有其自身的权衡。以下是所考虑的架构以及最终决策的依据总结。

1. 基于朴素grep的分析：我最初探索了使用标准 grep 进行符号识别的基线方法。虽然这种方法快捷，但由于它无法区分语法结构和简单的文本出现（例如，注释、字符串、变量名），证明其根本不足。高噪声比使其无法用于可靠的代码智能。
2. Tree-sitter原生集成：评估了直接与 tree-sitter 集成以利用其强大的解析能力。然而，这条路径充满了重大的实现复杂性，包括解析器生成和绑定层中的棘手错误。对于一个轻量级、多语言的工具来说，维护开销和自定义语法开发的陡峭学习曲线被认为是不可行的。
3. 语言服务器协议（LSP）：考虑利用语言服务器协议进行全面、标准化的代码分析。最终拒绝了这个方案，因为它会给最终用户带来过多的操作负担，要求他们为环境中的每种语言安装、配置和管理单独的LSP。这种摩擦与我提供轻量级、零配置用户体验的目标相冲突。
4. 基于Comby的结构搜索：探索了 Comby 的结构搜索和替换功能。尽管它有很有前景的功能集，但我遇到了严重的运行时不稳定性和特殊行为，这破坏了它在关键代码分析中的可靠性。该工具的性能和一致性不符合我对生产就绪系统的严格要求。
5. 以ast-grep为核心引擎：我最终的当前架构以 ast-grep 为中心。这个工具在结构感知、性能和易于集成之间提供了最佳平衡。通过在内部利用 tree-sitter，它提供了强大的、语法感知的代码分析，而无需直接集成 tree-sitter 的复杂性或LSP的开销。其可靠性和丰富的结构查询功能使其成为XRAY核心引擎的明确选择。

📦 安装指南

前提条件

• Python 3.10或更高版本
• uv - 快速Python包管理器

安装uv

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

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

# 或者使用pip安装
pip install uv

安装选项

选项1：自动化安装（最简单）

为了最快完成设置，使用 README.md 中的单行安装程序。这将为你处理一切。

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

选项2：使用uvx快速试用（推荐用于测试）

使用 uvx 直接运行XRAY，无需安装：

# 克隆仓库
git clone https://github.com/srijanshukla18/xray.git
cd xray

# 使用uvx直接运行XRAY
uvx --from . xray-mcp

选项3：作为工具安装（推荐用于常规使用）

将XRAY安装为持久工具：

# 克隆并安装
git clone https://github.com/srijanshukla18/xray.git
cd xray

# 使用uv安装
uv tool install .

# 现在你可以在任何地方运行xray-mcp
xray-mcp

选项4：开发安装

如果你想为XRAY做出贡献或进行修改：

# 克隆仓库
git clone https://github.com/srijanshukla18/xray.git
cd xray

# 使用uv创建并激活虚拟环境
uv venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate

# 以可编辑模式安装
uv pip install -e .

# 运行服务器
python -m xray.mcp_server

📚 详细文档

配置你的AI助手

安装完成后，配置你的AI助手以使用XRAY：

使用MCP配置生成器（推荐）

为了更轻松地进行配置，使用XRAY仓库中的 mcp-config-generator.py 脚本。这个脚本可以为各种AI助手和安装方法生成正确的JSON配置。 要使用它：

1. 导航到XRAY仓库的根目录：

cd /path/to/xray

2. 使用你想要的工具和安装方法运行脚本。例如，要获取Claude Desktop使用已安装的 xray-mcp 脚本的配置：

python mcp-config-generator.py claude installed_script

或者为使用本地Python安装的VS Code获取配置：

python mcp-config-generator.py vscode local_python

脚本将打印JSON配置和添加位置的说明。

可用工具：cursor, claude, vscode 可用方法：local_python, docker, source, installed_script（方法可用性因工具而异）

手动配置（高级）

如果你更喜欢手动配置，以下是常见AI助手的示例：

Claude CLI（Claude Code）

对于Claude CLI用户，只需运行：

claude mcp add xray xray-mcp -s local

然后验证是否已连接：

claude mcp list | grep xray

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

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

或者如果作为工具安装：

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

Cursor

设置 → Cursor设置 → MCP → 添加新的全局MCP服务器：

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

最小依赖

XRAY的最佳特性之一是其最小的依赖配置文件。你无需安装一套语言服务器。XRAY使用：

• ast-grep：一个单一、快速的二进制文件，用于结构代码分析。
• Python：用于服务器和核心逻辑。

这意味着你在安装后可以立即开始使用XRAY，无需复杂的设置！

验证安装

1. 检查XRAY是否可访问

# 如果作为工具安装
xray-mcp --version

# 如果使用uvx
uvx --from /path/to/xray xray-mcp --version

2. 测试基本功能

创建一个测试文件 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. 在你的AI助手中，测试以下命令：

Build the index for the current directory. use XRAY tools

预期：显示包含已索引文件的成功消息

Find all functions containing "hello". use XRAY tools

预期：应找到 hello_world 函数

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

预期：显示影响分析，展示任何依赖关系

💻 使用示例

配置完成后，在你的提示语中添加 "use XRAY tools" 来使用XRAY：

# 为代码库建立索引
"Index the src/ directory for analysis. use XRAY tools"

# 查找符号
"Find all classes that contain 'User' in their name. use XRAY tools"

# 影响分析
"What breaks if I change the authenticate method in UserService? use XRAY tools"

# 依赖跟踪
"What does the PaymentProcessor class depend on? use XRAY tools"

# 位置查询
"What function is defined at line 125 in main.py? use XRAY tools"

🔧 技术细节

故障排除

uv未找到

确保uv在你的PATH中：

# 添加到~/.bashrc或~/.zshrc
export PATH="$HOME/.cargo/bin:$PATH"

权限被拒绝

在macOS/Linux上，你可能需要使脚本可执行：

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

Python版本问题

XRAY需要Python 3.10+。检查你的版本：

python --version

# 如果需要，使用uv安装Python 3.10+
uv python install 3.10

MCP连接问题

1. 检查XRAY是否正在运行：xray-mcp --test
2. 验证你的MCP配置JSON是否有效
3. 在更改配置后重启你的AI助手

高级配置

自定义数据库位置

设置 XRAY_DB_PATH 环境变量：

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

调试模式

启用调试日志记录：

export XRAY_DEBUG=1

下一步计划

1. 为你的第一个仓库建立索引：在你的AI助手中，要求它 "Build the index for my project. use XRAY tools"

2. 探索工具：

   • build_index - 查看你的仓库的可视化文件树
   • find_symbol - 对函数、类和方法进行模糊搜索
   • what_breaks - 查找依赖于某个符号的代码（反向依赖）
   • what_depends - 查找某个符号依赖的内容（调用和导入）

   注意：结果可能包括来自注释或字符串的匹配项。AI助手将根据上下文进行智能过滤。

3. 阅读文档：查看 README 以获取详细示例和API参考

为什么XRAY采用最小依赖方法

XRAY的设计旨在简单易用。它依赖于：

• ast-grep：一个强大而快速的单二进制工具，用于代码分析。
• Python：因其强大的标准库和易于脚本编写。

这种方法避免了设置和管理多个语言服务器的复杂性，同时仍然提供准确的结构代码智能。

使用uv的好处

• 安装速度比pip快10 - 100倍
• 无需处理虚拟环境的麻烦 - uv会管理一切
• 可重现的安装 - uv.lock确保一致性
• 内置Python管理 - 安装任何Python版本
• 全局工具管理 - 像pipx一样，但更快

祝你使用XRAY编码愉快！ 🚀