{
"markdown": "# Ariadne\n\n\n\n[](LICENSE)\n[](https://modelcontextprotocol.io)\n[](https://glama.ai/mcp/servers/whyy9527/ariadne)\n[](https://github.com/punkpeye/awesome-mcp-servers#-developer-tools)\n\n> Ariadne's thread — a way out of the microservice maze.\n\nCross-service API dependency graph for Spring Boot + TypeScript\nmicroservice stacks. MCP stdio server for AI coding assistants\n(Claude Code, Cursor, Windsurf), with a CLI twin. Local SQLite + TF-IDF.\nZero ML dependencies.\n\n\n\n70-second deterministic terminal walkthrough. Reproduce it from\n[`docs/demo.tape`](docs/demo.tape).\n\n---\n\n## What it does\n\nIndexes the *contract layer* — GraphQL mutations, REST endpoints, Kafka\ntopics, frontend queries. Nothing else. That's why results fit an AI\ncontext window.\n\nAsk Claude *\"where does createOrder live across the stack?\"* and\n`query_chains` returns:\n\n```\nTop Cluster #1 [confidence: 0.91]\n Services: gateway, orders-svc, billing-svc, web\n - [web] Frontend Mutation: createOrder\n - [gateway] GraphQL Mutation: createOrder\n - [orders-svc] HTTP POST /orders: createOrder\n - [orders-svc] Kafka Topic: order-created\n - [billing-svc] Kafka Listener: order-created → chargeCustomer\n```\n\nThe response is intentionally bounded for an AI context window. See the\n[reproducible public-stack benchmark](BENCHMARKS.md) for measured retrieval,\nserialized token, and timing results against `rg` and `grep`.\n\nCurrent public-stack benchmark (48 reviewed queries across Spring REST,\nGraphQL/TypeScript, Kafka, and FastAPI):\n\n| Backend | Top-1 | Top-3 | MRR | Warm query | Mean output |\n|---|---:|---:|---:|---:|---:|\n| Ariadne | 64.6% | 70.8% | 0.677 | <0.3 ms | 157 tokens |\n| `rg` | 37.5% | 56.2% | 0.510 | ~9 ms | 591 tokens |\n| `grep` | 37.5% | 56.2% | 0.510 | ~9 ms | 591 tokens |\n\n[Full methodology and per-stack results](BENCHMARKS.md) ·\n[raw JSON evidence](benchmarks/results.json)\n\nThis corpus is operation-name-heavy and measures deterministic contract lookup\ncompatibility. It is not yet a natural-language relevance benchmark.\n\nSupports: GraphQL · Spring HTTP/Kafka/RestClient · Python FastAPI · TypeScript\nApollo/fetch/axios · Cube.js.\n\n---\n\n## Try it in 30 seconds (zero config)\n\n```bash\npip install ariadne-mcp\nariadne-mcp demo\n```\n\nClones [`spring-petclinic-microservices`][petclinic] into\n`~/.cache/ariadne-mcp/demo`, scans it, and prints the top cluster for\n`owner` — a real cross-service call chain. No config file, no workspace\nsetup.\n\nDid Ariadne find the chain you expected? Share one minute of\n[structured feedback][feedback-form]. Ariadne sends no usage data automatically;\nthe form opens only when you choose to submit it.\n\n[petclinic]: https://github.com/spring-petclinic/spring-petclinic-microservices\n[feedback-form]: https://github.com/whyy9527/ariadne/issues/new?template=usage-feedback.yml\n\n---\n\n## Install on your own workspace\n\n```bash\npip install ariadne-mcp\ncp \"$(python -c 'import ariadne_mcp, os; print(os.path.join(os.path.dirname(ariadne_mcp.__file__), \"ariadne.config.example.json\"))')\" ariadne.config.json\n# edit ariadne.config.json (list the repos you want indexed)\nariadne-mcp install ariadne.config.json ~/your-workspace\n```\n\nRestart Claude Code. `install` is idempotent — re-run after pulling new\ncode, or let the assistant call `rescan` on a `stale_warning`.\n\nAfter your first real query, you can optionally send\n[closed-ended usage feedback][feedback-form]. No source, query, or usage data is\ntransmitted by Ariadne itself.\n\n---\n\n## Config\n\n```json\n{ \"repos\": [\n { \"path\": \"../gateway\" },\n { \"path\": \"../orders-svc\" },\n { \"path\": \"../web\" }\n]}\n```\n\nScanners are inferred from each repo's top-level files\n(`pom.xml` / `build.gradle` / `package.json` / SDL). See\n[`docs/CONFIG.md`](docs/CONFIG.md) for the detection table and override\nsyntax.\n\n---\n\n## Reproducible public samples\n\nEach sample pins an upstream commit, scans real service source, runs one query,\nand verifies manually reviewed node IDs:\n\n| Example | Contract path |\n|---|---|\n| [`spring-petclinic`](examples/spring-petclinic/) | Spring REST gateway → service |\n| [`one-platform`](examples/one-platform/) | GraphQL/TypeScript services |\n| [`kafka-microservices`](examples/kafka-microservices/) | Kafka producer → consumer |\n| [`fastapi-microservices`](examples/fastapi-microservices/) | Python FastAPI routes |\n\nRun one from a source checkout:\n\n```bash\npython examples/run.py kafka-microservices\n```\n\n---\n\n## Evaluate ranking\n\nKeep a JSONL judgment list for queries that matter to your workspace:\n\n```jsonl\n{\"hint\":\"createOrder\",\"expected_node_ids\":[\"gateway::gql::m::createOrder\"],\"k\":3}\n{\"hint\":\"owner\",\"expected_node_ids\":[\"customers::http::GET /owners/{ownerId}\"],\"match\":\"any\",\"k\":5}\n```\n\nRun it against a built DB:\n\n```bash\nariadne-mcp --db .ariadne/ariadne.db eval eval/queries.jsonl --top 3 --min-hit-rate 0.8\n```\n\nThe command evaluates top-k hit rate and MRR using a stable internal candidate\ndepth, and exits non-zero when a configured threshold fails. Add\n`--feedback-db .ariadne/feedback.db` to include local feedback reranking in the\neval.\n\n---\n\nArchitecture, MCP tools, scoring math, feedback boost →\n[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Custom scanners (Go,\nRust, anything) → [`docs/CUSTOM_SCANNERS.md`](docs/CUSTOM_SCANNERS.md).\nMaintainer adoption snapshots → [`docs/ADOPTION_METRICS.md`](docs/ADOPTION_METRICS.md).\n",
"bytes": 5819,
"sha": "92037bb9c8a6e7229e8cd1a979433208bf55550294dd4234a1b083cd2e013908",
"repo_slug": "whyy9527/ariadne",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_whyy9527_ariadne_b0185d37/readme"
}