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編碼愉快！ 🚀