@zevruna/mcp

Zevruna's MCP server. Lets a coding agent resolve a contract break end to end.

The zevruna CLI tells you when an MCP contract moved. This gives your agent the tools to do something about it: the classified diff, the blast radius, a suggested patch, and the check that verifies the fix. Zevruna never needs write access to your repository — the agent makes the edits.

Install

npx zevruna registers this server and installs the matching skill, so most people never install it by hand. To wire it up yourself:

claude mcp add zevruna -- npx -y @zevruna/mcp

Any MCP client works — the entry is a stdio command:

{
  "mcpServers": {
    "zevruna": { "command": "npx", "args": ["-y", "@zevruna/mcp"] }
  }
}

Authentication

The server reads ZEVRUNA_TOKEN from the environment, falling back to the .env.zevruna file the wizard writes. Keep the token out of your client config — that file is usually committed.

Without a token the public tools still answer: get_advisories and check_endpoint.

Tools

| Tool | What it does | |---|---| | propose_instrumentation | Where to wrap agent runs in this repo, ranked, with the exact edit for each | | run_doctor | Verifies the install against reality and names the single next step | | list_servers | Monitored servers, latest contract hash, drift status | | list_incidents | Open and recent incidents — start here when no id was given | | get_change | The classified diff behind an incident | | get_blast_radius | Which agents, call sites and fields are affected | | suggest_patch | The edit list for the call sites | | run_check | Re-run the check for a consumer; a green check resolves the incident | | get_advisories | Public advisory feed, all servers or one | | report_upstream | A ready-to-file GitHub issue, when the change looks like an upstream mistake | | check_endpoint | Instant contract report for any MCP endpoint — no account required |

Typical use

Setting it up:

claude "set up Zevruna"

run_doctor reports the next step, propose_instrumentation returns the ranked boundaries and the edit for each, and the agent applies one where you can review the diff. It proposes; it never writes unattended.

Fixing a break:

claude "fix ZV-2481"

The agent pulls the diff, edits the call sites, regenerates manifests, and reruns the check. Nobody marks anything resolved by hand — the green check is the resolution.

Two things worth knowing

An empty answer is not an auth failure. Every account-scoped tool reports whether it is authenticated and says why a list is empty, because [] and "no token" are otherwise indistinguishable — and an agent reading [] will confidently diagnose the wrong cause.

Never apply a browser-side proposal. @zevruna/observe imports node:async_hooks. A bundler stubs that to an empty object, so the wrap builds green and throws when the chunk evaluates. propose_instrumentation marks those candidates and says to wrap the server route instead.

MIT © Zevruna