ratatosk-mcp

---

在北欧神话中，Ratatoskr 是一只在世界之树上上下传递消息的松鼠。这个项目传递的是发布情报。ratatosk.io 监控 76 个 CNCF 项目，并将每条发布说明转化为经过类型化的实体级变更：安全修复、破坏性变更、移除、弃用、默认值变更——并根据你现在应采取的行动逐一分类。常规事项也会记录下来，但不会妨碍你查看重要内容。

此仓库是 MCP 服务，会将这些变更作为工具提供给你的 Agent。MCP（Model Context Protocol）是 AI Agent 用来调用外部工具的开放标准；任何支持 MCP 的客户端——Claude Code、Claude Desktop、kagent、你自己的 SDK Agent——都可以连接。无需账户，也无需 API 密钥。

两种连接方式

托管服务——无需安装。 在任何支持远程连接器的客户端中，将 https://ratatosk.io/mcp 注册为 远程 MCP 服务。托管端点限制每位调用者每分钟调用工具 60 次，按调用者分别计数，不共享配额——对于轮询或 CI 工作负载，请自行托管。使用 Claude Code CLI：

claude mcp add --transport http ratatosk https://ratatosk.io/mcp

自托管——运行在你自己的进程中的同一服务。 使用 Docker、Helm chart 或从源码构建来运行。安装 Claude Code 和 Docker 后：

claude mcp add ratatosk -- docker run -i --rm ghcr.io/basphere/ratatosk-mcp:0.10.0

当前发布版本为 0.10.0；使用 latest 可跟踪后续新版本。

无论采用哪种方式，都请验证连接：

claude mcp list
# ratatosk: … - ✔ Connected

然后向 Agent 提出一个这些工具可以回答的问题：

你：“我们运行的是 envoy v1.36.8 和 istio 1.30.1。升级前有什么必须做的吗？”

你的 Agent 调用 check_stack 并根据记录作答：你的版本之后修复的 CVE、升级路径上移除的 API、发生变更的默认值——并区分哪些适用于所有人，哪些仅在配置符合条件时适用。每项变更都附有发布说明中的原文引述作为证据。

下面是 Agent 收到的真实 check_stack 答案中的一条记录 （istio，测量时间为 2026-08-20）：

{
  "severity": "high",
  "family": "security",
  "bucket": "action",
  "applies_if": "uses JWKS Resolver",
  "quote": "- CVE-2026-31837 / GHSA-v75c-crr9-733c : (CVSS score 8.7, High): JWKS Resolver Failure May Allow Authentication Bypass Using Known Default Keys.",
  "same_matter_also_addressed_in": ["1.28.5", "1.29.1"]
}

applies_if 是由 Agent 评估的条件，而非供人阅读的描述：如果某个技术栈没有运行 JWKS resolver，Agent 就会跳过此条目，无需询问任何人。答案还附带了原样呈现的隐私说明：“versions were compared locally; only project slugs were sent to the server.”（版本在本地进行了比较；仅将项目代称发送到服务端。）

其他客户端（Claude Desktop、kagent、集群内 Agent）及完整配置参考，请参阅安装指南。

工具

工具使用两种概念。变更是某个版本发布所做的一项改动，内容取自官方发布说明，并关联到其涉及的确切标识符（CVE id、标志、CRD、配置字段），同时附有逐字引用作为证据。每项变更都包含三个维度：

• family — security、breaking 或 deprecated：表示变更类型。
• bucket — action（适用于所有人）、check（仅当 applies_if 与你的设置匹配时适用）、plan（已宣布将在之后实施）、other（完整记录）。
• applies_if — 可根据你自己的清单进行求值的布尔表达式，而不是供阅读的说明文字。

事项是变更背后的问题，以 matter_key 标识，在不同版本和分支间保持稳定：同一项安全汇总在五个分支上落地时，共用一个键。严重性记录在所引用的公告中，读取的是账本中的当前值，而非分析时冻结的值。

工具	功能
check_stack	接收你正在使用的组件版本，并返回升级路径上的变更，按类别拆分：action_required 适用于所有人，check_config 仅在其 applies_if 条件成立时适用。比较在服务进程内部进行——如果你选择自托管，该进程就是你自己的进程（组件版本的处理方式）
list_changes	增量变更动态，按分析时间从早到晚排列。可按项目、类别或分组筛选；使用 since 游标翻页，以便让本地副本保持同步
changes_by_entity	反向查找：获取涉及某个确切标识符的所有变更，例如 CVE id、CRD、功能门控、标志、配置字段或依赖项
get_matter	获取某一事项出现过的所有版本。相同的汇总可能会带着不同的公告落地到多个分支——如果只告知你最新的一个版本，你可能会误以为自己已受到保护
get_release	获取某个版本的完整信息：其变更、摘要，以及原始说明的链接。变更数为零表示已读取该版本，并确认其属于常规更新
list_releases	以单行摘要列出某个项目的最新版本（日期、按分组和类别统计的数量、最高公告严重性），按时间从新到旧排列——用于了解“X 最近有哪些变化”的工具
list_projects	列出已跟踪项目及其规范 slug（其他工具使用的简短项目 id）——可在此查找名称，无需猜测

每个工具的完整参数、调用示例和实测响应见工具参考。

如何处理组件版本

自托管： check_stack 只会向服务器发送项目 slug，并在本地（即此进程内）比较版本——你传入的版本绝不会到达 ratatosk.io。服务器发布变更；由你的 Agent 决定哪些变更适用。版本规范化器随程序打包（internal/version），因此范围比较也在客户端完成。升级问题同样如此：上游 API 提供了一个便捷端点（/v1/upgrade/{project}），用于接收调用方提供的版本——check_stack 不会调用它；比较逻辑就在你可以查看的源代码中。

这项保证有一个限制：它仅适用于 check_stack。接受版本作为参数的工具（get_release(project, version)）会将该版本放入上游请求路径，因为获取特定发行版就意味着要指明它。不过，我这边不会保留这个路径：写入日志行之前，会去掉查询字符串，并将 /v1/releases/… 和 /v1/upgrade/… 路径缩减为前缀，因此 slug 和版本都不会进入日志。

托管： 你的 check_stack 参数（你运行的版本）会经过服务器内存，以生成相同的答案，且不会被记录下来。以下是沿途各层会保留的信息：

• 托管 MCP 进程本身只记录启动行——普通请求不会增加任何日志。
• 只有调用方发送 traceparent 时，上游 API 的请求日志才会写入一行，其中包含规范化的端点标签和 trace id——绝不包含路径、查询字符串或请求体。
• 入口访问日志会去掉查询字符串，将 /v1/releases/… 和 /v1/upgrade/… 路径缩减为前缀，对调用方 IP 进行掩码处理，并且没有用于记录请求体的字段。

托管端点运行时会关闭其审计流，而且我会让它保持关闭——不记录请求内容是该端点的运行原则。有一个边界不受我控制：CDN 链路上的连接元数据遵循 CDN 提供商自己的政策。如果你的要求不允许这类传输，请选择自托管：调用 check_stack 时，只有项目 slug 会离开你的基础设施。

自托管还提供相反的能力：可选择启用审计流（MCP_AUDIT=metadata 或 full），记录谁调用了哪个工具，并在你自己的基础设施内输出到你自己的收集器。托管端点则按设计不提供此功能。详情请参阅安装指南。

文档

• 安装与使用 — 托管端点 · 本地 stdio · 集群内（Helm）· kagent（한국어 · 日本語）
• Helm chart — values、kagent 开关（한국어 · 日本語）
• kagent 示例 — 清单 + ratatosk-agent（한국어 · 日本語）
• 参与贡献 · 安全政策

上游 API

此服务是一个基于公共 REST API 的轻量客户端。如果你更愿意直接调用，访问 ratatosk.io 上的 GET /v1 即可查看 API 自身的说明。无需 API 密钥；每个 IP 每分钟最多请求 1200 次。

数据与条款

ratatosk.io 免费提供这些数据——此条款可能会变更，并会提前通知——具体内容见其服务条款。分析结果是由 AI 生成的参考信息，不提供任何保证——采取行动前请查看原始发行说明，尤其是在 Agent 代表你采取行动时。原始说明归各自项目所有；包含完整说明的响应会附带归属声明（raw_notes_notice）。

许可证

此仓库中的代码根据 Apache-2.0 许可证授权。