Ariadne 是一个面向微服务架构的跨服务 API 依赖图工具，旨在帮助开发者从微服务迷宫中找到出路。它作为本地 MCP（Model Context Protocol）stdio 服务器运行，供 AI 编程助手（如 Claude Code、Cursor、Windsurf）调用，同时提供 CLI 孪生工具。
用途： Ariadne 专注于索引契约层——GraphQL 变更、REST 端点、Kafka 主题、前端查询，不索引其他内容。这使得查询结果能够适配 AI 上下文窗口。例如，向 Claude 提问“createOrder 在整个栈中位于哪里？”，query_chains 会返回有界的响应，便于 AI 理解。
主要能力：
- 确定性跨服务 API 链发现，覆盖 REST、GraphQL、Kafka、TypeScript 和 FastAPI。
- 本地 SQLite + TF-IDF 实现，零机器学习依赖。
- 支持 GraphQL、Spring HTTP/Kafka/RestClient、Python FastAPI、TypeScript Apollo/fetch/axios、Cube.js。
- 提供可复现的公开栈基准测试（48 个审查查询，覆盖 Spring REST、GraphQL/TypeScript、Kafka 和 FastAPI），测量检索、序列化 token 和计时结果，并与 rg 和 grep 对比。
- 支持自定义扫描器（Go、Rust 等），详见 docs/CUSTOM_SCANNERS.md。
- 提供评估排名功能，可维护 JSONL 判断列表，评估 top-k 命中率和 MRR。
使用方式：
- 30 秒零配置试用：克隆 spring-petclinic-microservices 到 ~/.cache/ariadne-mcp/demo，扫描并打印 owner 的顶级集群，展示真实跨服务调用链。无需配置文件或工作区设置。
- 在自己的工作区安装：运行安装命令后重启 Claude Code。install 是幂等的，拉取新代码后可重新运行，或让助手在 stale_warning 时调用 rescan。
- 扫描器根据每个仓库的顶层文件（pom.xml / build.gradle / package.json / SDL）推断，检测表和覆盖语法见 docs/CONFIG.md。
- 可复现公开样本：每个样本固定上游提交，扫描真实服务源码，运行一个查询，并验证人工审查的节点 ID。
- 评估排名：保留 JSONL 判断列表，针对构建的数据库运行命令，评估 top-k 命中率和 MRR，可添加 --feedback-db .ariadne/feedback.db 包含本地反馈重排。
适用场景：
- 微服务架构下的跨服务 API 调用链追踪。
- AI 编程助手需要理解代码库中业务术语或端点相关操作时。
- 需要确定性、本地化、无 ML 依赖的代码检索工具。
限制：
- 当前公开栈基准测试以操作名称为主，测量确定性契约查找兼容性，尚不是自然语言相关性基准。
- 仅索引契约层，不索引其他代码内容。
- 当前服务器使用 MCP Python SDK v1（mcp<2）。
- 商业验收和消融实验使用合成契约；私有工作区源码和反馈保留在本地。
- Ariadne 本身不自动发送使用数据；反馈表单仅在用户选择提交时打开。
