ariadne
Ariadne
阿里阿德涅之线(Ariadne's thread)——走出微服务迷宫的指引。
专为 Spring Boot + TypeScript 微服务技术栈设计的跨服务 API 依赖关系图。它是面向 AI 编程助手(Claude Code、Cursor、Windsurf)的 MCP stdio 服务器,并配有 CLI 工具。基于本地 SQLite + TF-IDF 实现,无任何机器学习依赖。

功能概述
索引契约层——包括 GraphQL Mutation、REST 端点、Kafka 主题以及前端查询。仅此而已,因此结果完全适配 AI 的上下文窗口。
询问 Claude “createOrder 在整个技术栈中位于何处?”,query_chains 将返回:
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 个 token。而在四个代码库中执行等效的 grep -r createOrder 会返回 40 多个匹配项(包含 DTO、测试和配置),占用约 2000 个 token,且契约层被淹没其中。
支持:GraphQL · Spring HTTP/Kafka/RestClient · TypeScript Apollo/fetch/axios · Cube.js。
Related MCP server: TempoGraph
30 秒快速上手(零配置)
pip install ariadne-mcp
ariadne-mcp demo将 spring-petclinic-microservices 克隆到 ~/.cache/ariadne-mcp/demo,扫描它,并打印出 owner 的顶级集群——这是一个真实的跨服务调用链。无需配置文件,无需工作区设置。
在自己的工作区安装
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重启 Claude Code。install 是幂等的——在拉取新代码后重新运行即可,或者让助手在出现 stale_warning 时调用 rescan。
配置
{ "repos": [
{ "path": "../gateway" },
{ "path": "../orders-svc" },
{ "path": "../web" }
]}扫描器会根据每个代码库的顶层文件(pom.xml / build.gradle / package.json / SDL)自动推断。查看 docs/CONFIG.md 获取检测表和覆盖语法。
在公共示例上尝试
examples/spring-petclinic/ —— 克隆公共的 spring-petclinic-microservices 示例,放入配置,扫描,查询。在一分钟内即可完成端到端的复现。
架构、MCP 工具、评分算法、反馈增强 → docs/ARCHITECTURE.md。自定义扫描器(Go、Rust 等) → docs/CUSTOM_SCANNERS.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 a local exploration 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.
Inputs: name (required).
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.
Inputs: hint (required), top_n.
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.
Inputs: hint (required), accepted (required), node_ids, cluster_rank.
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.
Inputs: no named parameters.
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.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: query_chains for discovery from a business term, expand_node for one-hop traversal from a known node, rescan for index refresh, rate_result for feedback, and show_help for guidance. The descriptions explicitly disambiguate the closest pair (query_chains vs expand_node) by stating when to use each. No two tools overlap in function.
Four of five names follow a clear verb_noun pattern (expand_node, query_chains, rate_result, show_help). The lone 'rescan' is a bare verb without a noun object, a minor deviation that stays readable and consistent in style. Overall predictable and snake_case throughout.
Five tools is well-scoped for a code-relationship exploration server, covering discovery, traversal, maintenance, feedback, and help. Each tool earns its place with no redundant or filler entries. The surface is focused rather than bloated.
The lifecycle is well covered: discovery (query_chains), traversal (expand_node), freshness (rescan), and feedback (rate_result) plus onboarding help. Minor gaps exist — e.g. no way to list indexed repos or enumerating all nodes — but core workflows are supported. A read-only exploration domain reasonably needs no create/update/delete operations.
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.2448 PyPI1AGPL 3.0
- AlicenseAqualityDmaintenanceExtract 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.1944MIT
- 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.18MIT