Ariadne

Ariadne

アリアドネの糸 — マイクロサービスの迷宮から抜け出す道しるべです。

Spring Boot + TypeScript のマイクロサービススタック向け、サービス間 API 依存関係グラフです。AI コーディングアシスタント （Claude Code、Cursor、Windsurf）向けの MCP stdio サーバーで、 CLI 版も備えています。ローカルの SQLite + TF-IDF を使用します。 ML 依存関係はゼロです。

_{70 秒の再現可能なターミナルウォークスルーです。 docs/demo.tape から再現できます。}

---

できること

契約レイヤー — GraphQL ミューテーション、REST エンドポイント、Kafka トピック、フロントエンドクエリをインデックス化します。それ以外は扱いません。 そのため、結果が AI のコンテキストウィンドウに収まります。

Claude に 「スタック全体で createOrder はどこにありますか？」 と尋ねると、 query_chains は次を返します。

Top Cluster #1  [confidence: 0.91]
  Services: gateway, orders-svc, billing-svc, web
  - [web]          Frontend Mutation: createOrder
  - [gateway]      GraphQL Mutation:  createOrder
  - [orders-svc]   HTTP POST /orders: createOrder
  - [orders-svc]   Kafka Topic:       order-created
  - [billing-svc]  Kafka Listener:    order-created → chargeCustomer

応答は、AI のコンテキストウィンドウに収まるよう意図的に制限されています。 rg および grep と比較した検索結果、シリアライズ後のトークン数、実行時間の測定結果については、 再現可能な公開スタックベンチマークをご覧ください。

現在の公開スタックベンチマーク（Spring REST、 GraphQL/TypeScript、Kafka、FastAPI にまたがるレビュー済みのクエリ 48 件）：

バックエンド	Top-1	Top-3	MRR	ウォームクエリ	平均出力
Ariadne	89.6%	95.8%	0.927	<0.4 ms	375 トークン
rg	37.5%	56.2%	0.510	~9 ms	591 トークン
grep	37.5%	56.2%	0.510	~9 ms	591 トークン

手法とスタックごとの結果の全容 · 生の JSON エビデンス

このコーパスは操作名が多く含まれており、決定論的な契約検索の互換性を測定します。 自然言語での関連性ベンチマークにはまだなっていません。

uv を使って測定結果を再現できます。

uv run --locked --extra benchmark python benchmarks/run.py

tiktoken を使用する初回実行では、エンコーディングデータをダウンロードするため、ネットワークアクセスが必要です。 ベンチマークでは、システムの git、rg、grep コマンドも呼び出します。

対応対象：GraphQL · Spring HTTP/Kafka/RestClient · Python FastAPI · TypeScript Apollo/fetch/axios · Cube.js。

---

30 秒で試す（設定不要）

pip install ariadne-mcp
ariadne-mcp demo

spring-petclinic-microservices を ~/.cache/ariadne-mcp/demo にクローンし、スキャンして、 owner に関する最上位のクラスター（実際のサービス間呼び出しチェーン）を表示します。 設定ファイルも、ワークスペースのセットアップも不要です。

Ariadne は期待したチェーンを見つけましたか？ 1 分で終わる 構造化フィードバックをお寄せください。Ariadne が使用状況データを自動送信することはありません。 フォームは、送信を選択した場合にのみ開きます。

---

自分のワークスペースにインストールする

pip install ariadne-mcp
cp "$(python -c 'import ariadne_mcp, os; print(os.path.join(os.path.dirname(ariadne_mcp.__file__), "ariadne.config.example.json"))')" ariadne.config.json
# edit ariadne.config.json (list the repos you want indexed)
ariadne-mcp install ariadne.config.json ~/your-workspace

Claude Code を再起動してください。install は冪等です。新しいコードをプルした後に再実行するか、 stale_warning が発生したときにアシスタントから rescan を呼び出してください。

ソースチェックアウトから MCP サーバーを実行する

プロジェクトで固定されている uv バージョンを使って環境を準備し、MCP クライアントがその環境の Python を直接起動するように設定します。

cd /path/to/ariadne
uv sync --locked --no-dev --inexact
.venv/bin/python -m ariadne_mcp.server \
  --db /path/to/workspace/.ariadne/ariadne.db \
  --fb /path/to/workspace/.ariadne/feedback.db

MCP クライアントの設定では、絶対パスのインタープリターを使用してください。依存関係を変更した後は同期手順を実行してください。この手順は、長時間実行するサーバーとは別のものです。--inexact を指定すると、開発用チェックアウトでインストール済みの他の依存関係グループが保持されます。 UV_PROJECT_ENVIRONMENT で別の環境が選択されている場合は、.venv/bin/python ではなく、その環境の Python を設定してください。

プロジェクトで固定されている uv バージョンでは、長時間実行するサーバーを uv run でラップすると、uv の共有パッケージキャッシュのロックがサーバーの実行中ずっと保持されるため、通常の uv cache prune ができなくなります。Python を直接起動すれば、このロックを回避できます。 stdio クライアント接続ごとに、個別のサーバープロセスを実行できます。

最初の実際のクエリの後、任意で 選択式の利用状況フィードバックを送信できます。Ariadne 自体がソース、クエリ、利用状況のデータを送信することはありません。

---

設定

{ "repos": [
    { "path": "../gateway" },
    { "path": "../orders-svc" },
    { "path": "../web" }
]}

スキャナーは、各リポジトリのトップレベルファイル （pom.xml / build.gradle / package.json / SDL）から推定されます。検出テーブルと上書き構文については docs/CONFIG.md を参照してください。

---

再現可能な公開サンプル

各サンプルでは、上流のコミットを固定し、実際のサービスソースをスキャンして、1 つのクエリを実行し、手動でレビューしたノード ID を検証します。

例	コントラクトパス
spring-petclinic	Spring REST ゲートウェイ → サービス
one-platform	GraphQL/TypeScript サービス
kafka-microservices	Kafka プロデューサー → コンシューマー
fastapi-microservices	Python FastAPI ルート

ソースチェックアウトから、次のようにいずれかを実行します。

python examples/run.py kafka-microservices

---

ランキングを評価する

ワークスペースで重要なクエリについて、JSONL 形式の判定リストを保持します。

{"hint":"createOrder","expected_node_ids":["gateway::gql::m::createOrder"],"k":3}
{"hint":"owner","expected_node_ids":["customers::http::GET /owners/{ownerId}"],"match":"any","k":5}

ビルド済み DB に対して実行します。

ariadne-mcp --db .ariadne/ariadne.db eval eval/queries.jsonl --top 3 --min-hit-rate 0.8

このコマンドは、安定した内部候補深度を使って top-k ヒット率と MRR を評価し、設定したしきい値を下回ると 0 以外の終了コードを返します。評価にローカルのフィードバックによる再ランキングを含めるには、--feedback-db .ariadne/feedback.db を追加してください。

---

_{アーキテクチャ、MCP ツール、スコアリング計算、フィードバックブースト → docs/ARCHITECTURE.md。カスタムスキャナー（Go、 Rust など）→ docs/CUSTOM_SCANNERS.md。 メンテナーによる導入状況のスナップショット → docs/ADOPTION_METRICS.md。}

ビジネス受け入れテストとアブレーション

ソースに基づくビジネススイートは、9 つすべての組み込みスキャナーと、実際の stdio クライアントを含む MCP のクエリ／展開／評価／再スキャンのライフサイクル全体を対象としています。合成コントラクトを使用し、プライベートなワークスペースのソースとフィードバックはローカルに保持されます。

uv sync --locked --extra benchmark --group dev
uv run --locked --extra benchmark --group dev python -m pytest tests/ -q
uv run --locked --extra benchmark python benchmarks/ablation.py \
  --output benchmarks/.work/ablation.json

固定入力のベースライン、コンポーネントのアブレーション、出力コスト、残る制限事項については、品質実験の結果を参照してください。サーバーは Python 3.10、3.11、3.12 をサポートしています。実行時の要件は MCP Python SDK v1（mcp>=1,<2）と PyYAML（PyYAML>=6,<7）です。tiktoken は任意のベンチマーク依存関係です。uv.lock はメンテナーと CI の環境を固定するものであり、パッケージ利用者が解決する依存関係を制約するものではありません。