{
  "markdown": "<div align=\"center\">\n\n<img src=\"docs/assets/ratatosk-hero.webp\" width=\"280\" alt=\"Ratatosk, a messenger squirrel with a scroll in its bag, waving hello\">\n\n# ratatosk-mcp\n\n**Ratatosk reads CNCF release notes every hour. Your agents get the changes.**\n\n[English](README.md) · [한국어](README.ko.md) · [日本語](README.ja.md)\n\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io/?q=ratatosk&all=1)\n[![Release](https://img.shields.io/github/v/release/garlicKim21/ratatosk-mcp)](https://github.com/garlicKim21/ratatosk-mcp/releases)\n[![License](https://img.shields.io/github/license/garlicKim21/ratatosk-mcp)](LICENSE)\n[![Glama score](https://glama.ai/mcp/servers/garlicKim21/ratatosk-mcp/badges/score.svg)](https://glama.ai/mcp/servers/garlicKim21/ratatosk-mcp)\n\n\n</div>\n\n---\n\nIn Norse myth, Ratatoskr is the squirrel that carries messages up and down the\nworld tree. This one carries release intelligence. [ratatosk.io](https://ratatosk.io)\nwatches 76 CNCF projects and turns every release note into typed, entity-level\nchanges: security fixes, breaking changes, removals, deprecations, changed\ndefaults — each one classified by how you should act on it now. Routine lines\nare recorded too, but kept out of the way.\n\nThis repository is the MCP server that hands those changes to your agent as\ntools. MCP (Model Context Protocol) is the open standard AI agents use to call\nexternal tools; any MCP-capable client — Claude Code, Claude Desktop, kagent,\nyour own SDK agent — can connect. No account, no API key.\n\n## Two ways to connect\n\n**Hosted — nothing to install.** Register `https://ratatosk.io/mcp` as a\nremote MCP server in any client that supports remote connectors. The hosted\nendpoint allows each caller 60 tool calls a minute, counted per caller rather\nthan pooled — for polling or CI workloads, self-host. With the Claude Code\nCLI:\n\n```bash\nclaude mcp add --transport http ratatosk https://ratatosk.io/mcp\n```\n\n**Self-hosted — the same server, running as your own process.** Run it with\nDocker, the Helm chart, or a source build. With Claude Code and Docker\ninstalled:\n\n```bash\nclaude mcp add ratatosk -- docker run -i --rm ghcr.io/garlickim21/ratatosk-mcp:0.9.0\n```\n\n`0.9.0` is the current release; use `latest` to follow new ones.\n\nEither way, verify the connection:\n\n```bash\nclaude mcp list\n# ratatosk: … - ✔ Connected\n```\n\nThen ask your agent a question the tools can answer:\n\n> **You:** \"We run envoy v1.36.8 and istio 1.30.1. Anything we must do before upgrading?\"\n>\n> **Your agent** calls `check_stack` and answers from the record: the CVEs\n> fixed after your version, the APIs removed on your upgrade path, the defaults\n> that changed — separated into what applies to everyone and what applies only\n> if your configuration matches. Each change carries a verbatim quote from the\n> release notes as evidence.\n\nOne entry from a real `check_stack` answer, as the agent receives it\n(istio, measured 2026-08-20):\n\n```json\n{\n  \"severity\": \"high\",\n  \"family\": \"security\",\n  \"bucket\": \"action\",\n  \"applies_if\": \"uses JWKS Resolver\",\n  \"quote\": \"- CVE-2026-31837 / GHSA-v75c-crr9-733c : (CVSS score 8.7, High): JWKS Resolver Failure May Allow Authentication Bypass Using Known Default Keys.\",\n  \"same_matter_also_addressed_in\": [\"1.28.5\", \"1.29.1\"]\n}\n```\n\n`applies_if` is a condition the agent evaluates, not prose to read: a stack\nthat runs no JWKS resolver skips this entry without asking anyone. The answer\nalso carries its own privacy line, verbatim: *\"versions were compared locally;\nonly project slugs were sent to the server.\"*\n\nOther clients (Claude Desktop, kagent, in-cluster agents) and the full setup\nreference: see the [install guide](docs/install.en.md).\n\n## Tools\n\nTwo things the tools speak in. A **change** is one thing a release did, taken\nfrom an official release note and tied to the exact identifiers it touches\n(a CVE id, a flag, a CRD, a config field), with a verbatim quote as evidence.\nEvery change carries three axes:\n\n- **family** — `security`, `breaking`, or `deprecated`: what kind of thing it is.\n- **bucket** — `action` (applies to everyone), `check` (only if `applies_if`\n  matches your setup), `plan` (announced for later), `other` (the full record).\n- **applies_if** — a boolean expression you can evaluate against your own\n  manifests, not prose to read.\n\nA **matter** is the issue underneath, identified by `matter_key` and stable\nacross releases and branches: the same security roll-up landing on five\nbranches shares one key. Severity lives on the cited advisories and is read\nfrom the ledger's current value, not frozen at analysis time.\n\n| Tool | What it does |\n|---|---|\n| `check_stack` | Takes the component versions you run and returns the changes on your upgrade path, split by bucket: `action_required` applies to everyone, `check_config` only if its `applies_if` holds. The comparison happens inside the server process — which is your own process when you self-host ([how your component versions are handled](#how-your-component-versions-are-handled)) |\n| `list_changes` | The incremental change feed, oldest-analyzed first. Filter by project, family, or bucket; page with the `since` cursor to keep a local copy in sync |\n| `changes_by_entity` | Reverse lookup: every change touching one exact identifier — such as a CVE id, CRD, feature gate, flag, config field, or dependency |\n| `get_matter` | Every release in which one matter appeared. The same roll-up lands on several branches carrying different advisories — told only the newest, you would assume you were covered |\n| `get_release` | One release in full: its changes, a summary, and the link to the original note. A release with zero changes means it was read and found routine |\n| `list_releases` | The newest releases of one project as one-line summaries (dates, counts by bucket and family, highest advisory severity), newest first — the tool for \"what changed in X lately\" |\n| `list_projects` | The roster of tracked projects and their canonical slugs (the short project id every other tool takes) — look names up here instead of guessing |\n\nFull per-tool parameters, example calls, and measured responses live in the [tools reference](docs/tools.en.md).\n\n## How your component versions are handled\n\n**Self-hosted:** `check_stack` sends only project slugs to the server and\ncompares versions locally, inside this process — the versions you pass it\nnever reach ratatosk.io. The server publishes changes; your agent decides what\napplies. The version normalizer is bundled (`internal/version`), so range\ncomparison happens client-side too. This holds for upgrade questions as well:\nthe upstream API has a convenience endpoint (`/v1/upgrade/{project}`) that\nreceives caller-supplied versions — `check_stack` does not call it; the\ncomparison is in the source you can read.\n\nOne limit on that guarantee: it covers `check_stack`. Tools that take a\nversion as an argument — `get_release(project, version)` — put that version\nin the upstream request path, because fetching a specific release means\nnaming it. That named path is not kept on my side, though: before a log line\nis written, query strings are stripped and `/v1/releases/…` and\n`/v1/upgrade/…` paths are reduced to their prefix, so neither the slug nor\nthe version lands in a log.\n\n**Hosted:** your `check_stack` arguments (the versions you run) pass through\nthe server's memory to produce the same answer, and are not written down.\nHere is what each layer on the way keeps:\n\n- The hosted MCP process itself logs only its startup line — a normal\n  request adds nothing.\n- The upstream API's request log writes one line only when the caller sends a\n  `traceparent`, and that line carries a normalized endpoint label and the\n  trace id — never a path, query, or body.\n- The front-door access log strips query strings, reduces `/v1/releases/…`\n  and `/v1/upgrade/…` paths to their prefix, masks caller IPs, and has no\n  field for request bodies.\n\nThe hosted endpoint runs with its audit stream off, and I keep it off — not\nrecording request content is the operating stance for that endpoint. One\nboundary I do not control: connection metadata on the CDN leg\nfollows the CDN provider's own policy. If your requirements rule out that transit,\nself-host: then only project slugs leave your infrastructure on a\n`check_stack` call.\n\nSelf-hosting adds the opposite capability: an opt-in audit stream\n(`MCP_AUDIT=metadata` or `full`) that records who called which tool, emitted\ninside your own infrastructure into your own collectors. The hosted endpoint\nhas none by design. Details in the [install guide](docs/install.en.md).\n\n## Documentation\n\n- **[Install & usage](docs/install.en.md)** — hosted endpoint · local stdio · in-cluster (Helm) · kagent ([한국어](docs/install.ko.md) · [日本語](docs/install.ja.md))\n- **[Helm chart](charts/ratatosk-mcp/README.md)** — values, kagent toggle ([한국어](charts/ratatosk-mcp/README.ko.md) · [日本語](charts/ratatosk-mcp/README.ja.md))\n- **[kagent example](examples/kagent/README.md)** — manifests + ratatosk-agent ([한국어](examples/kagent/README.ko.md) · [日本語](examples/kagent/README.ja.md))\n- **[Contributing](CONTRIBUTING.md)** · **[Security policy](SECURITY.md)**\n\n## Upstream API\n\nThis server is a thin client over the public REST API. If you would rather\ncall it directly, `GET /v1` on ratatosk.io describes itself. No API key; rate\nlimited at 1200 requests per minute per IP.\n\n## Data & terms\n\nThe data is served free of charge by ratatosk.io — a term that may change,\nwith advance notice — under its [terms of service](https://ratatosk.io/terms).\nAnalyses are AI-generated reference information with no warranty — check the\noriginal release notes before acting, especially when an agent acts on your\nbehalf. Original notes belong to their respective projects; responses that\ncarry a full note include an attribution notice (`raw_notes_notice`).\n\n## License\n\nThe code in this repository is licensed under [Apache-2.0](LICENSE).\n",
  "bytes": 9970,
  "sha": "ca64b226801604efe5ad9652a4026d29aa273294a5507331b83cbd6a5672fd7d",
  "repo_slug": "garlickim21/ratatosk-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_garlickim21_ratatosk_mcp_3b4d6587/readme"
}