🚀 XRAY MCP - AIアシスタント向けの進化的コードインテリジェンス

❌ XRAYを使用しない場合

AIアシスタントはコードベースの理解に苦労します。以下のようなことが起こります：

• ❌ "コード構造が見えません"
• ❌ "この関数に依存しているものがわかりません"
• ❌ 影響分析のない一般的なリファクタリングのアドバイス
• ❌ シンボル間の関係を理解できません

✅ XRAYを使用する場合

XRAYはAIアシスタントにコードナビゲーション機能を提供します。プロンプトに use XRAY tools を追加します：

UserServiceクラスを分析し、authenticateメソッドを変更した場合に何が壊れるかを教えてください。use XRAY tools

validate_userを呼び出すすべての関数を見つけ、それらの依存関係を表示してください。use XRAY tools

XRAYは3つの重点的なツールを提供します：

• 🗺️ 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は構造的な正確性を保証します。コードの構文を理解し、単なるテキストパターンではなく、コードを解析します。

XRAYのワークフロー - 段階的な探索

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 (外部バイナリ)
    └── Tree-sitterをベースにした構造検索

ステートレス設計 - データベースや永続的なインデックスはありません。各操作はリアルタイムの正確性のために新しい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を使用してオンデマンドの構造解析を実行します。管理するデータベースや構築するインデックス、維持する状態はありません。各クエリは現在のコードに対して新しく実行されます。

なぜ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を使用してオンデマンドの構造解析を実行します。データベースや永続的なインデックスはありません。各操作は新しいast-grepクエリを実行し、リアルタイムの正確性を保証します。

始めるには

1. インストール: 最新のインストール方法については を参照してください
2. 地形を把握する: explore_repo("/path/to/project")
3. ターゲットを見つける: find_symbol("/path/to/project", "UserService")
4. 影響を評価する: what_breaks(symbol)

XRAYの理念

XRAYは、単純なテキスト検索と複雑なLSPサーバーの間のギャップを埋めます：

• grep以上 - コードの構文パターンにマッチし、単なるテキストではなく
• LSP以下 - 言語サーバーや複雑な設定は必要ありません
• AIに適している - コードの関係に関する構造化されたデータを提供します

テキスト検索だけではなく、AIアシスタントがコードベースをより効果的にナビゲートできるようにするシンプルなツールです。

アーキテクチャの選択理由

現在のXRAYの実装は、複数のコード分析手法を厳密に評価した結果です。以下に、検討したアーキテクチャと最終的な決定の理由をまとめます。

1. 単純なgrepベースの分析: 最初に、標準の grep を使用した基本的なアプローチを試しました。しかし、この方法はシンタックス構造と単なるテキストの出現を区別できず、信頼性の高いコードインテリジェンスには不十分でした。
2. Tree-Sitterの直接統合: tree-sitter の強力な解析機能を利用するために、直接統合を試みました。しかし、パーサーの生成やバインディング層でのエラーが多く、メンテナンスコストや学習曲線が高いため、断念しました。
3. Language Server Protocol (LSP): コード分析のためにLSPを検討しましたが、ユーザーに各言語のLSPをインストール、構成、管理させる必要があり、軽量でゼロ構成のユーザー体験の目標と矛盾するため、却下されました。
4. Combyベースの構造検索: Comby の構造検索と置換機能を試しましたが、ランタイムの不安定性や特異な動作があり、本番環境での信頼性が低いため、採用しませんでした。
5. ast-grepを核心エンジンとする: 最終的に、現在のアーキテクチャは ast-grep を中心に構築されています。このツールは構造認識、パフォーマンス、統合の容易さのバランスが最適です。内部的に tree-sitter を利用することで、直接の tree-sitter 統合やLSPのオーバーヘッドなしに、強力な構文認識コード分析を提供します。その信頼性と豊富な構造クエリ機能が、XRAYの核心エンジンとしての選択理由です。

XRAYの始め方 - uvを使用した最新のインストール方法

XRAYは、AIアシスタントがコードベースを理解するのを支援する最小限の依存関係のコードインテリジェンスシステムです。このガイドでは、最新の uv パッケージマネージャーを使用して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 から1行のインストーラーを使用します。これにより、すべてが自動的に処理されます。

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. 希望のツールとインストール方法でスクリプトを実行します。たとえば、インストールされた xray-mcp スクリプトを使用するClaude Desktopの設定を取得するには：

   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

macOSの場合は ~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "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の最大の特長の1つは、最小限の依存関係であることです。一連の言語サーバーをインストールする必要はありません。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. ドキュメントを読む: 詳細な例やAPIリファレンスについては README を参照してください

XRAYが最小限の依存関係アプローチを採用する理由

XRAYはシンプルで使いやすいように設計されています。以下を使用します：

• ast-grep: 強力で高速な単一バイナリツールによるコード分析
• Python: 堅牢な標準ライブラリとスクリプトの容易さ

このアプローチは、複数の言語サーバーを設定および管理する複雑さを回避しながら、正確な構造的なコードインテリジェンスを提供します。

uvを使用するメリット

• pipより10 - 100倍高速なインストール
• 仮想環境の煩わしさがない - uvがすべてを管理します
• 再現可能なインストール - uv.lockにより一貫性が保証されます
• 組み込みのPython管理 - 任意のPythonバージョンをインストールできます
• グローバルなツール管理 - pipxよりも高速

XRAYで快適なコーディングを！ 🚀