Ariadne

Ariadne

Ariadne's thread — a way out of the microservice maze.

Cross-service API dependency graph for Spring Boot + TypeScript microservice stacks. MCP stdio server for AI coding assistants (Claude Code, Cursor, Windsurf), with a CLI twin. Local SQLite + TF-IDF. Zero ML dependencies.

_{70-second deterministic terminal walkthrough. Reproduce it from docs/demo.tape.}

---

What it does

Indexes the contract layer — GraphQL mutations, REST endpoints, Kafka topics, frontend queries. Nothing else. That's why results fit an AI context window.

Ask Claude "where does createOrder live across the stack?" and query_chains returns:

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

The response is intentionally bounded for an AI context window. See the reproducible public-stack benchmark for measured retrieval, serialized token, and timing results against rg and grep.

Current public-stack benchmark (48 reviewed queries across Spring REST, GraphQL/TypeScript, Kafka, and FastAPI):

Backend	Top-1	Top-3	MRR	Warm query	Mean output
Ariadne	89.6%	95.8%	0.927	<0.4 ms	375 tokens
rg	37.5%	56.2%	0.510	~9 ms	591 tokens
grep	37.5%	56.2%	0.510	~9 ms	591 tokens

Full methodology and per-stack results · raw JSON evidence

This corpus is operation-name-heavy and measures deterministic contract lookup compatibility. It is not yet a natural-language relevance benchmark.

Reproduce the measurements with uv:

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

The first run that uses tiktoken downloads its encoding data and needs network access. The benchmark also calls the system git, rg, and grep commands.

Supports: GraphQL · Spring HTTP/Kafka/RestClient · Python FastAPI · TypeScript Apollo/fetch/axios · Cube.js.

---

Try it in 30 seconds (zero config)

pip install ariadne-mcp
ariadne-mcp demo

Clones spring-petclinic-microservices into ~/.cache/ariadne-mcp/demo, scans it, and prints the top cluster for owner — a real cross-service call chain. No config file, no workspace setup.

Did Ariadne find the chain you expected? Share one minute of structured feedback. Ariadne sends no usage data automatically; the form opens only when you choose to submit it.

---

Install on your own workspace

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

Restart Claude Code. install is idempotent — re-run after pulling new code, or let the assistant call rescan on a stale_warning.

Run an MCP server from a source checkout

Prepare the environment with the project's pinned uv version, then configure the MCP client to launch that environment's Python directly:

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

Use an absolute interpreter path in the MCP client configuration. Run the sync step after dependency changes; it is separate from the long-running server. --inexact preserves other installed dependency groups in a development checkout. If UV_PROJECT_ENVIRONMENT selects another environment, configure that environment's Python instead of .venv/bin/python.

With the project's pinned uv version, wrapping a long-running server in uv run keeps uv's shared package-cache lock held for the server's lifetime, which prevents normal uv cache prune. A direct Python launch avoids that lock. Separate stdio client connections can run separate server processes.

After your first real query, you can optionally send closed-ended usage feedback. No source, query, or usage data is transmitted by Ariadne itself.

---

Config

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

Scanners are inferred from each repo's top-level files (pom.xml / build.gradle / package.json / SDL). See docs/CONFIG.md for the detection table and override syntax.

---

Reproducible public samples

Each sample pins an upstream commit, scans real service source, runs one query, and verifies manually reviewed node IDs:

Example	Contract path
spring-petclinic	Spring REST gateway → service
one-platform	GraphQL/TypeScript services
kafka-microservices	Kafka producer → consumer
fastapi-microservices	Python FastAPI routes

Run one from a source checkout:

python examples/run.py kafka-microservices

---

Evaluate ranking

Keep a JSONL judgment list for queries that matter to your workspace:

{"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}

Run it against a built DB:

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

The command evaluates top-k hit rate and MRR using a stable internal candidate depth, and exits non-zero when a configured threshold fails. Add --feedback-db .ariadne/feedback.db to include local feedback reranking in the eval.

---

_{Architecture, MCP tools, scoring math, feedback boost → docs/ARCHITECTURE.md. Custom scanners (Go, Rust, anything) → docs/CUSTOM_SCANNERS.md. Maintainer adoption snapshots → docs/ADOPTION_METRICS.md.}

Business acceptance and ablation

The source-backed business suite covers all nine built-in scanners and the complete MCP query/expand/rate/rescan lifecycle, including a real stdio client. It uses synthetic contracts; private workspace sources and feedback stay local.

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

See quality experiment results for the fixed-input baseline, component ablations, output costs and remaining limitations. The server supports Python 3.10, 3.11, and 3.12. Runtime requirements are MCP Python SDK v1 (mcp>=1,<2) and PyYAML (PyYAML>=6,<7); tiktoken is an optional benchmark dependency. uv.lock pins the maintainer and CI environment and does not constrain dependencies resolved by package users.