ariadne
Ariadne is a cross-service API dependency graph and semantic code navigation tool for microservice architectures. It exposes four core tools:
query_chains— Search for cross-service API chains using a business term or endpoint name (e.g."createOrder"). Returns ranked clusters of related GraphQL operations, HTTP endpoints, Kafka topics, and frontend queries across all indexed services.expand_node— Trace one-hop relationships from a known node (e.g. a Kafka topic, REST endpoint, or GraphQL mutation) to discover directly connected components with similarity scores.ariadne_help— Retrieve setup and usage guidance, including how to index microservices or troubleshoot empty results. Requires no database access.log_feedback— Record thumbs-up/thumbs-down feedback on results, stored locally infeedback.dbto gradually improve cluster rankings over time.
It supports GraphQL, Spring (Java/Kotlin), TypeScript, and cube.js codebases; operates offline via static analysis; and integrates with MCP-compatible tools like Claude Code and Cursor.
Scans GraphQL SDL files to extract Query, Mutation, Subscription, and Type definitions for cross-service API dependency analysis and semantic code navigation.
Analyzes Kotlin code with Spring framework annotations to identify HTTP endpoints, Kafka topics, and backend client calls for microservice API dependency analysis.
Analyzes Spring framework code to identify HTTP endpoints via @RestController annotations, Kafka topics via @KafkaListener and application.yaml configurations, and backend client calls via RestClient/RestTemplate.
Scans TypeScript files to extract frontend GraphQL queries/mutations from gql template literals and REST API calls from axiosRequest/fetch statements for cross-service feature mapping.
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 → chargeCustomerThe 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 | 64.6% | 70.8% | 0.677 | <0.3 ms | 157 tokens |
| 37.5% | 56.2% | 0.510 | ~9 ms | 591 tokens |
| 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.
Supports: GraphQL · Spring HTTP/Kafka/RestClient · Python FastAPI · TypeScript Apollo/fetch/axios · Cube.js.
Related MCP server: TempoGraph
Try it in 30 seconds (zero config)
pip install ariadne-mcp
ariadne-mcp demoClones 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-workspaceRestart Claude Code. install is idempotent — re-run after pulling new
code, or let the assistant call rescan on a stale_warning.
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 REST gateway → service | |
GraphQL/TypeScript services | |
Kafka producer → consumer | |
Python FastAPI routes |
Run one from a source checkout:
python examples/run.py kafka-microservicesEvaluate 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.8The 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.
Available Tools
5 toolsexpand_nodeA
One-hop neighbours of a known node (endpoint / Kafka topic / GraphQL operation / frontend call), with similarity scores and file paths. Read-only; no writes except an implicit positive feedback row if called within 10 min of a matching query_chains. Returns up to 3 matched source nodes × up to 10 neighbours (edges with score ≥ 0.08), plus a stale_warning field — call rescan if non-null.
Use AFTER query_chains when you already have a concrete node name and want to trace one hop further. Use query_chains (not this) when starting from a business term or when you don't yet know a node name. Partial, case-insensitive match against node id and raw_name; ambiguous inputs return multiple source groups.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Node id or raw name (endpoint method, Kafka topic, GraphQL operation, frontend call). Case-insensitive substring match against both id and raw_name. Prefer exact names copied from a prior query_chains result to avoid ambiguity; short strings (e.g. 'get') will match many nodes and only the first 3 are expanded. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: 'Read-only; no writes except an implicit positive feedback row if called within 10 min of a matching query_chains. Returns up to 3 matched source nodes × up to 10 neighbours (edges with score ≥ 0.08), plus a `stale_warning` field — call `rescan` if non-null.' This covers safety (read-only with one exception), output structure, and side effects, though it could mention error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and well-structured, with the first sentence stating the core purpose and subsequent sentences providing usage guidelines and behavioral details. Every sentence adds value, though it could be slightly more front-loaded by moving key behavioral traits earlier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description does a good job of covering the tool's complexity. It explains purpose, usage, behavior, and output structure. However, it could be more complete by explicitly mentioning the tool's return format (e.g., JSON structure) or potential error cases, which would help an AI agent better handle responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description adds valuable context beyond the schema: it explains that 'Partial, case-insensitive match against node id and raw_name; ambiguous inputs return multiple source groups,' and clarifies the relationship to 'query_chains' results. This enhances understanding of how the parameter is used, though it doesn't introduce new parameter-specific details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'One-hop neighbours of a known node... with similarity scores and file paths.' It specifies the verb ('expand') and resource ('node'), and distinguishes it from sibling 'query_chains' by noting it's for tracing 'one hop further' after having a concrete node name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use AFTER query_chains when you already have a concrete node name and want to trace one hop further. Use query_chains (not this) when starting from a business term or when you don't yet know a node name.' It clearly defines when to use this tool versus the alternative 'query_chains'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
query_chainsA
Query cross-service chains by business term or endpoint name. Returns candidate clusters of related GraphQL operations, HTTP endpoints, Kafka topics, and frontend queries across all services indexed by the local Ariadne DB. Use this when you need to understand which APIs, topics, or frontend operations are involved in a business feature.
| Name | Required | Description | Default |
|---|---|---|---|
| hint | Yes | Business term or endpoint name (e.g. 'createOrder', 'userProfile', 'subscription') | |
| top_n | No | Number of clusters to return (default 3) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what the tool does (queries and returns clusters) and the scope ('across all services indexed by the local Ariadne DB'), but lacks details on permissions, rate limits, error handling, or response format. For a query tool with no annotations, this is adequate but has gaps in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with two sentences that efficiently convey purpose and usage guidelines without unnecessary details. Every sentence adds value, making it concise and well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (querying cross-service chains) and lack of annotations and output schema, the description is moderately complete. It covers purpose and usage well but misses behavioral details like response format, pagination, or error cases. For a tool with no output schema, more information on return values would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters well-documented in the schema. The description adds minimal value beyond the schema by mentioning 'business term or endpoint name' for 'hint' and implying clustering for results, but doesn't provide additional syntax or format details. Baseline 3 is appropriate as the schema handles most parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('query', 'returns') and resources ('cross-service chains', 'candidate clusters of related GraphQL operations, HTTP endpoints, Kafka topics, and frontend queries'). It distinguishes this tool from siblings by specifying it queries by 'business term or endpoint name' and returns clusters across services, unlike expand_node, rate_result, rescan, or show_help.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use this when you need to understand which APIs, topics, or frontend operations are involved in a business feature.' This provides clear context for usage versus alternatives, though it doesn't name specific sibling tools, the guidance is sufficient for distinguishing use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
rate_resultA
Record whether Ariadne results were useful. Call this after using query_chains or expand_node to log feedback for future improvement. If node_ids is omitted after a recent query_chains call, Ariadne infers node_ids from hint + cluster_rank. Feedback is stored locally in feedback.db and survives DB rebuilds.
| Name | Required | Description | Default |
|---|---|---|---|
| hint | Yes | The hint used in query_chains or the node name used in expand_node | |
| accepted | Yes | true if results helped locate files or understand the chain; false if irrelevant or misleading | |
| node_ids | No | Node IDs from the result that were actually useful | |
| cluster_rank | No | Which cluster was referenced (1-based). Use 0 for expand_node results. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It reveals that feedback is stored locally in feedback.db and survives DB rebuilds, and explains inference behavior. No side effects or permission needs are mentioned, but overall transparent enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with purpose and usage, then provides details about inference and storage. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity and no output schema, the description is complete enough. It explains behavior, parameters, and storage. Minor gap: no return value description, but not critical for a feedback tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning: explains that node_ids can be inferred from hint and cluster_rank if omitted, and clarifies cluster_rank usage (0 for expand_node). This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose ('Record whether Ariadne results were useful') and distinguishes it from siblings by specifying it is used after query_chains or expand_node.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to call this tool ('after using query_chains or expand_node') and explains inference behavior when node_ids is omitted, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
rescanA
Refresh the Ariadne index from inside the conversation. Call this when query_chains or expand_node returned a stale_warning, or after you know the user's code has changed. Re-scans every repo listed in the install-time ariadne.config.json, rebuilds TF-IDF token edges, and invalidates cached DB handles so the next query sees fresh data. No arguments; zero configuration.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does: re-scans repos from a config file, rebuilds TF-IDF edges, and invalidates caches. It mentions 'No arguments; zero configuration' which clarifies operational simplicity. However, it doesn't cover potential side effects like performance impact or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the primary use case and then detailing the actions. Every sentence earns its place by providing essential information without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (index refresh with multiple actions) and no annotations or output schema, the description is mostly complete. It covers purpose, usage, and behavior well, but lacks details on output (e.g., success confirmation or error messages) and potential limitations like execution time or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so the baseline is 4. The description adds value by explicitly stating 'No arguments; zero configuration,' which reinforces the parameterless nature beyond what the schema indicates, helping the agent understand there are no optional or hidden parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Refresh', 'Re-scans', 'rebuilds', 'invalidates') and resources ('Ariadne index', 'TF-IDF token edges', 'cached DB handles'). It distinguishes from siblings by explaining when to use it versus query_chains or expand_node, which return stale_warnings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Call this when query_chains or expand_node returned a stale_warning, or after you know the user's code has changed.' It provides clear alternatives by naming specific sibling tools and scenarios for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
show_helpA
Return a quick setup and usage guide for Ariadne. Call this first when you are unsure how to use Ariadne, how to index your own microservices, or why query_chains returned no results. Always safe to call — no DB required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it's safe (no destructive effects), requires no database, and returns guidance. However, it doesn't specify format, length, or potential rate limits, leaving some gaps in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by usage guidelines and safety note. Every sentence earns its place by providing essential information without waste, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no annotations, no output schema), the description is nearly complete. It covers purpose, usage, and safety. However, without an output schema, it could briefly mention the type of guidance returned (e.g., text or structured data), leaving a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description adds value by implying no inputs are required, aligning with the schema. Baseline is 4 for 0 parameters, as it appropriately handles the lack of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Return a quick setup and usage guide') and resource ('for Ariadne'). It distinguishes from siblings by focusing on help/guidance rather than operations like querying, expanding, rating, or rescanning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use this tool ('Call this first when you are unsure how to use Ariadne, how to index your own microservices, or why query_chains returned no results') and when it's safe ('Always safe to call — no DB required'), effectively differentiating it from alternatives like query_chains for troubleshooting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v1.0.7- Removed
ariadne_help - Changed
expand_node2 fields changed- changed
Input schema / properties / name / descriptionPrevious value: -"Node id or raw name (endpoint method, Kafka topic, GraphQL operation, frontend call). Case-insensitive substring match against both id and raw_name. Prefer exact names copied from a prior query_chains result to avoid ambiguity; very short strings (e.g. 'get') will match many nodes and only the first 3 are expanded."New value: +"Node id or raw name (endpoint method, Kafka topic, GraphQL operation, frontend call). Case-insensitive substring match against both id and raw_name. Prefer exact names copied from a prior query_chains result to avoid ambiguity; short strings (e.g. 'get') will match many nodes and only the first 3 are expanded." - added
Input schema / properties / name / minLengthAdded value: +2
- Removed
log_feedback - Added
rate_result - Added
show_help
1 tool update
v1.0.6- Changed
expand_node1 field changed- changed
Input schema / properties / name / descriptionPrevious value: -"Endpoint method name, Kafka topic name, or GraphQL operation name (partial match supported)"New value: +"Node id or raw name (endpoint method, Kafka topic, GraphQL operation, frontend call). Case-insensitive substring match against both id and raw_name. Prefer exact names copied from a prior query_chains result to avoid ambiguity; very short strings (e.g. 'get') will match many nodes and only the first 3 are expanded."
1 tool update
v1.0.5- Added
rescan
2 tool updates
v1.0.3- Added
expand_node - Added
query_chains
2 tool updates
v1.0.2- Added
ariadne_help - Added
log_feedback
3 tool updates
v1.0.1- Removed
expand_node - Removed
log_feedback - Removed
query_chains
3 tool updates
v1.0.0- First observed
expand_node - First observed
log_feedback - First observed
query_chains
TDQS
Scored across 5 tools
Each tool has a clear, distinct purpose: querying chains, expanding neighbors, recording feedback, refreshing the index, and showing help. No overlap or ambiguity.
All tool names follow a verb_noun pattern (expand_node, query_chains, rate_result, show_help) except rescan, which is a common verb-only name but consistent with the imperative style.
5 tools cover the essential operations for a microservice mapping tool: search, explore, feedback, refresh, and help. Ideal count for the domain.
The tool set covers the full workflow: search for chains, explore neighbors, provide feedback, refresh the index, and get help. No obvious gaps.
Maintenance
Related MCP Connectors
LLM Orchestration Agent (Opentelemetry Api)
LLM Observability & Orchestration Agent (Langchain)
Related MCP Servers
- FlicenseAqualityDmaintenanceA TypeScript tool that ranks files in your codebase by importance, tracks dependencies, and provides file summaries to help understand code structure through Cursor's Model Context Protocol.14302-
- AlicenseAqualityCmaintenanceCode graph context engine that parses codebases with tree-sitter (170+ languages), builds structural dependency graphs, and provides 24 MCP tools for code intelligence. One prepare_context call gives your AI agent the right files for any task. Includes focus, blast radius, hotspots, dead code detection, and hybrid search.2442 PyPI1AGPL 3.0
- AlicenseAqualityCmaintenanceExtract domain knowledge from codebases to reduce LLM token consumption by 20x and time in agentic search by 10x — gathers and makes concepts, naming conventions, and vocabulary queryable via MCP.1941MIT
- AlicenseNot gradedqualityCmaintenanceMulti-language code-graph MCP server with 18 tools for structural code queries — find_symbol, callers, callees, blast_radius, dead_code, and cross-stack dataflow_trace from HTTP request through service layers to SQL. Tree-sitter parsing for Python, TypeScript, JavaScript, and Go; local-first, no API key required.17MIT