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.

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

~500 tokens round-trip. The equivalent grep -r createOrder across four repos returns 40+ matches across DTOs, tests, and configs at ~2000 tokens, with the contract layer buried.

Supports: GraphQL · Spring HTTP/Kafka/RestClient · 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.

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.

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.

Try it on a public sample

examples/spring-petclinic/ — clone the public spring-petclinic-microservices sample, drop in the config, scan, query. Reproducible end-to-end in under a minute.

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.}