Ariadne

Ariadne

Ariadne 的线索——带你走出微服务迷宫。

适用于 Spring Boot + TypeScript 微服务技术栈的跨服务 API 依赖图。 面向 AI 编码助手（Claude Code、Cursor、Windsurf）的 MCP stdio 服务， 并提供配套 CLI。本地 SQLite + TF-IDF。 零 ML 依赖。

_{70 秒确定性的终端演示。可根据 docs/demo.tape 重现。}

---

功能介绍

为 契约层 建立索引——GraphQL mutations、REST endpoints、Kafka topics、前端 queries。仅此而已。这就是结果能放进 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

响应有意限制了大小，以适应 AI 上下文窗口。有关针对 rg 和 grep 进行的检索、序列化 token 数量和耗时测量，请参阅 可复现的公开技术栈基准测试。

当前公开技术栈基准测试（涵盖 Spring REST、 GraphQL/TypeScript、Kafka 和 FastAPI，共 48 个已审核查询）：

后端	Top-1	Top-3	MRR	热查询	平均输出
Ariadne	89.6%	95.8%	0.927	<0.4 ms	375 tokens
rg	37.5%	56.2%	0.510	~9 ms	591 tokens
grep	37.5%	56.2%	0.510	~9 ms	591 tokens

完整方法和各技术栈的结果 · 原始 JSON 证据

该语料库以操作名称为主，衡量确定性契约查询的兼容性。目前还不是自然语言相关性基准测试。

使用 uv 重现测量结果：

uv run --locked --extra benchmark python benchmarks/run.py

首次使用 tiktoken 的运行会下载其编码数据，需要网络连接。基准测试还会调用系统的 git、rg 和 grep 命令。

支持：GraphQL · Spring HTTP/Kafka/RestClient · Python FastAPI · TypeScript Apollo/fetch/axios · Cube.js。

---

30 秒快速体验（零配置）

pip install ariadne-mcp
ariadne-mcp demo

将 spring-petclinic-microservices 克隆到 ~/.cache/ariadne-mcp/demo，扫描它，并输出 owner 的首个集群—— 一条真实的跨服务调用链。无需配置文件，也无需设置工作区。

Ariadne 找到了你预期的调用链吗？花一分钟填写 结构化反馈。Ariadne 不会自动发送使用数据； 只有在你选择提交时才会打开表单。

---

在自己的工作区安装

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。

从源代码检出目录运行 MCP 服务

使用项目固定的 uv 版本准备环境，然后将 MCP 客户端配置为直接启动该环境的 Python：

cd /path/to/ariadne
uv sync --locked --no-dev --inexact
.venv/bin/python -m ariadne_mcp.server \
  --db /path/to/workspace/.ariadne/ariadne.db \
  --fb /path/to/workspace/.ariadne/feedback.db

在 MCP 客户端配置中使用绝对解释器路径。依赖项变更后运行同步步骤；该步骤与长期运行的服务分开。--inexact 会在开发检出目录中保留其他已安装的依赖组。 如果 UV_PROJECT_ENVIRONMENT 指向其他环境，请配置为使用该环境的 Python，而不是 .venv/bin/python。

使用项目固定的 uv 版本时，通过 uv run 包装长期运行的服务，会使 uv 的共享软件包缓存锁在服务运行期间一直被持有，从而阻止正常执行 uv cache prune。直接启动 Python 可以避免该锁。 不同的 stdio 客户端连接可以运行不同的服务进程。

首次执行真实查询后，你可以选择提交 封闭式使用反馈。Ariadne 本身不会传输任何源代码、查询或使用数据。

---

配置

{ "repos": [
    { "path": "../gateway" },
    { "path": "../orders-svc" },
    { "path": "../web" }
]}

扫描器根据每个代码库的顶层文件推断 （pom.xml / build.gradle / package.json / SDL）。检测表和覆盖语法请参阅 docs/CONFIG.md。

---

可复现的公开示例

每个示例都会固定上游提交，扫描真实服务源代码，运行一次查询， 并验证经过人工审核的节点 ID：

示例	契约路径
spring-petclinic	Spring REST 网关 → 服务
one-platform	GraphQL/TypeScript 服务
kafka-microservices	Kafka 生产者 → 消费者
fastapi-microservices	Python FastAPI 路由

从源代码检出目录运行一个示例：

python examples/run.py kafka-microservices

---

评估排序

为与你的工作区相关的查询维护 JSONL 判定列表：

{"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}

针对已构建的 DB 运行评估：

ariadne-mcp --db .ariadne/ariadne.db eval eval/queries.jsonl --top 3 --min-hit-rate 0.8

该命令使用稳定的内部候选深度评估 top-k 命中率和 MRR；如果未达到配置的阈值，则以非零状态码退出。添加 --feedback-db .ariadne/feedback.db，即可在评估中纳入本地反馈重排。

---

_{架构、MCP 工具、评分计算、反馈加权 → docs/ARCHITECTURE.md。自定义扫描器（Go、 Rust 等）→ docs/CUSTOM_SCANNERS.md。 维护者采用情况快照 → docs/ADOPTION_METRICS.md。}

业务验收与消融实验

基于源代码的业务套件覆盖全部九个内置扫描器，以及完整的 MCP 查询/展开/评分/重新扫描生命周期，其中包括一个真实的 stdio 客户端。 它使用合成契约；私有工作区源代码和反馈数据保留在本地。

uv sync --locked --extra benchmark --group dev
uv run --locked --extra benchmark --group dev python -m pytest tests/ -q
uv run --locked --extra benchmark python benchmarks/ablation.py \
  --output benchmarks/.work/ablation.json

请参阅质量实验结果，了解固定输入基线、组件消融、输出成本和仍存的限制。该服务支持 Python 3.10、3.11 和 3.12。运行时依赖为 MCP Python SDK v1（mcp>=1,<2）和 PyYAML（PyYAML>=6,<7）；tiktoken 是可选的基准测试依赖。uv.lock 固定维护者和 CI 环境的依赖，不会约束软件包用户解析的依赖。