https://github.com/whyy9527/ariadne
Ariadne's thread — a way out of the microservice maze. Local cross-service semantic chain hinter for microservices (GraphQL/HTTP/Kafka/frontend)
https://github.com/whyy9527/ariadne
code-navigation developer-tools mcp microservices
Last synced: 3 months ago
JSON representation
Ariadne's thread — a way out of the microservice maze. Local cross-service semantic chain hinter for microservices (GraphQL/HTTP/Kafka/frontend)
- Host: GitHub
- URL: https://github.com/whyy9527/ariadne
- Owner: whyy9527
- License: mit
- Created: 2026-04-14T07:32:09.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-14T09:06:18.000Z (3 months ago)
- Last Synced: 2026-04-14T10:15:48.347Z (3 months ago)
- Topics: code-navigation, developer-tools, mcp, microservices
- Language: Python
- Homepage:
- Size: 52.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Ariadne
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://glama.ai/mcp/servers/whyy9527/ariadne)
[](https://github.com/punkpeye/awesome-mcp-servers#-developer-tools)
> 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)
```bash
pip install ariadne-mcp
ariadne-mcp demo
```
Clones [`spring-petclinic-microservices`][petclinic] 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.
[petclinic]: https://github.com/spring-petclinic/spring-petclinic-microservices
---
## Install on your own workspace
```bash
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
```json
{ "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`](docs/CONFIG.md) for the detection table and override
syntax.
---
## Try it on a public sample
[`examples/spring-petclinic/`](examples/spring-petclinic/) — clone the
public `spring-petclinic-microservices` sample, drop in the config,
scan, query. Reproducible end-to-end in under a minute.
---
Architecture, MCP tools, scoring math, feedback boost →
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Custom scanners (Go,
Rust, anything) → [`docs/CUSTOM_SCANNERS.md`](docs/CUSTOM_SCANNERS.md).