Grafyx

Grafyx

AI コーディングアシスタント向けのリアルタイムなコードベース理解。

---

Grafyx とは？

AI コーディングツールは、アーキテクチャをまったく理解せずに生のファイルを読み込みます。つまり、何が何を呼び出すのか、どのクラスがどこを継承しているのか、モジュール同士がどうつながっているのかを把握できません。Grafyx は、Graph-sitter（tree-sitter を基盤に構築）を使ってコードベース全体を解析し、完全な関係グラフにすることで、この問題を解決します。さらに、Model Context Protocol（MCP）を通じて、あらゆる AI アシスタントにそのグラフを公開します。アシスタントは、呼び出しチェーンをたどり、依存関係をマッピングし、説明から関連コードを見つけ、規約を検出し、プロジェクトのアーキテクチャを理解できます。これらすべてをリアルタイムで行い、ファイルウォッチャーが編集に応じてグラフを最新の状態に保ちます。

---

クイックスタート

Claude Code

# Zero-install (recommended)
claude mcp add --scope user grafyx -- uvx --from grafyx-mcp grafyx

# Or install with pip first
pip install grafyx-mcp
claude mcp add --scope user grafyx -- grafyx

Cursor / Windsurf / Cline

MCP 設定ファイルに追加します。

• Cursor：.cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）
• Windsurf：~/.codeium/windsurf/mcp_config.json
• Cline：VS Code の Cline MCP 設定

{
  "mcpServers": {
    "grafyx": {
      "command": "uvx",
      "args": ["--from", "grafyx-mcp", "grafyx"]
    }
  }
}

VS Code（GitHub Copilot）

.vscode/mcp.json に追加します。

{
  "servers": {
    "grafyx": {
      "command": "uvx",
      "args": ["--from", "grafyx-mcp", "grafyx"]
    }
  }
}

uvx の代わりに pip を使っていますか？ コマンドを "command": "grafyx" に置き換えてください（引数は不要です）。

---

利用可能なツール

ツール	説明
get_project_skeleton	モジュールごとの統計情報を含む、プロジェクト全体の構造
get_function_context	関数に関するすべての情報：呼び出し元、呼び出し先、依存関係
get_file_context	ファイルの内容、インポート、依存関係
get_class_context	クラスのメソッド、継承、使用箇所
find_related_code	コードベース全体を対象にした自然言語検索
find_related_files	シンボルの照合により、機能に関連するファイルを検索
get_dependency_graph	影響分析：何が何に依存しているか
get_conventions	検出されたコーディングパターンと規約
get_call_graph	上流および下流の呼び出しチェーンをたどる
refresh_graph	コードベースを強制的に再解析
get_module_context	ディレクトリ／パッケージ内のシンボル（中間ズーム）
get_subclasses	基底クラスの継承ツリー
get_unused_symbols	デッドコードの検出
set_project	実行時に提供対象のプロジェクトを切り替え

---

仕組み

Your AI Assistant
       |
       | MCP Protocol (stdio)
       v
  +-----------+
  |  Grafyx   |  FastMCP server with 14 tools
  |  Server   |
  +-----------+
       |
  +-----------+     +-----------+     +-------------+
  |  Graph    |---->|  Search   |     | Convention  |
  |  Engine   |---->|  Engine   |     | Detector    |
  +-----------+     +-----------+     +-------------+
       |
       v
  +-----------+
  |  Graph-   |  Tree-sitter based parsing
  |  sitter   |
  +-----------+
       |
  +-----------+
  |  Watchdog |  File watcher for live updates
  +-----------+

1. 起動 -- Grafyx がプロジェクト内の言語を検出し、Graph-sitter を使ってすべてのソースファイルをセマンティックグラフに解析します。
2. 提供 -- FastMCP サーバーが stdio 経由で 14 個のツールを公開します。AI アシスタントは必要に応じてそれらを呼び出します。
3. ライブ更新 -- Watchdog がファイルの変更を監視します。保存すると、短いデバウンス後にグラフが自動的に再解析されます。

ML による拡張検索

Grafyx の find_related_code は、ONNX 経由で fastembed を使用して CPU 上で実行される、事前学習済みのコード埋め込みモデル（デフォルト： jinaai/jina-embeddings-v2-base-code、Apache-2.0、1 億 6,100 万パラメーター）を使用します。モデルは初回使用時にダウンロードされ、ローカルにキャッシュされます。GPU もデーモンもクラウド呼び出しも不要です。

0.2.1 以降、fastembed は必須依存関係となっているため、デフォルトのインストールにエンコーダーが含まれます。追加のインストールは不要です。

ベンチマーク（0.2.0、FastAPI と Django を対象とした docstring→関数のクエリ 278 件）：

エンコーダー	nDCG@10	MRR@10	p50 レイテンシー
jina-v2（デフォルト）	0.787	0.741	約 1.5 秒
coderankembed	0.663	0.623	約 1.3 秒
tokens-only（fastembed なし）	0.335	0.297	約 0.9 秒

デフォルトのエンコーダーは、プレーンなソーストークン検索と比べて検索品質を 2 倍以上に高めます（nDCG@10 が 135％向上）。

詳細な内訳とクエリごとの JSONL： docs/benchmarks/0.2.0/。

GRAFYX_ENCODER 環境変数でエンコーダーを切り替えられます。

• jina-v2（デフォルト） — Apache-2.0、fastembed ネイティブ、約 150 MB。精度に優れており、切り替える特別な理由がない限り推奨です。
• coderankembed — MIT、1 億 3,700 万パラメーター、ONNX-int8、約 140 MB。レイテンシーは低くなりますが、評価では jina-v2 より nDCG@10 が約 12 ポイント低くなります。Bilal7Dev/grafyx-coderankembed-onnx で公開されています。

numpy のみで動作する MLP（合計約 5 MB の重み、wheel に同梱）：

• M1 関連性ランカー — 呼び出し元の数、名前の一致、エクスポートなどの構造的シグナルを用いて、エンコーダーの上位候補を再ランキングする 33 特徴量の MLP です。
• M3 ソーストークンフィルター — 全文検索からノイズとなるトークン（インポート、文字列、マジックメソッド）を抑制します。
• M4 シンボル重要度 — 呼び出し元の数、エクスポート、構造的シグナルに基づいてシンボルに重み付けします。
• 意味不明な文字列の検出器 — インデックスに到達する前に、不自然なクエリをブロックする文字バイグラム MLP です。

FastAPI、Django、Home Assistant を対象とした再現可能なベンチマークは benchmarks/ に含まれています（python -m scripts.run_all）。

---

対応言語

言語	拡張子
Python	.py、.pyi
TypeScript	.ts、.tsx
JavaScript	.js、.jsx

言語は自動検出されます。手動で指定するには：

grafyx --languages python,typescript

---

オプション

grafyx [OPTIONS]

  --project PATH       Project to analyze (default: current directory)
  --languages LANGS    Comma-separated languages (default: auto-detect)
  --ignore PATTERNS    Additional directories to ignore
  --no-watch           Disable file watching
  --verbose, -v        Debug logging
  --version            Show version

デフォルトで無視されるもの：node_modules、.git、__pycache__、.venv、venv、.env、dist、build、.tox、.mypy_cache、.pytest_cache、.ruff_cache、egg-info、.eggs、.next、.nuxt、coverage、.coverage、.nyc_output

---

マルチエージェントのサポート

Grafyx はエージェントチームに対応しています。単一の Grafyx インスタンスで、同じプロジェクトに接続しているすべてのエージェントにサービスを提供します。エージェントがコードを変更すると、ファイルウォッチャーがグラフを自動的に更新するため、ほかのエージェントもすぐに変更を確認できます。

---

コントリビューション

git clone https://github.com/bilal07karadeniz/Grafyx.git
cd Grafyx
pip install -e ".[dev]"
pytest

---

トラブルシューティング

Windows：Graph-sitter の実行には Linux が必要です。WSL を使用し、MCP クライアントが wsl 経由で起動するように設定してください。

{
  "mcpServers": {
    "grafyx": {
      "command": "wsl",
      "args": ["-e", "bash", "-c", "source ~/your-venv/bin/activate && grafyx"]
    }
  }
}

---

ライセンス

MIT — 詳細は LICENSE を参照してください。