CVErdict

CVErdict MCP server

A read-only Model Context Protocol server that gives AI agents the same verdicts as CVErdict: tier, score, every reason chip with its points and evidence link, and what is unknown. Every answer says when the data was generated and which files it came from. No key, no account.

It runs on your machine over stdio and reads the published data branch on raw.githubusercontent.com, then the site's /data/ copy if GitHub fails. It needs the site only when GitHub fails, so it keeps working when the site is down.

Install

Node 22.12 or later. The package is cverdict-mcp on npm: one file, no runtime dependencies. Versions after 0.1.0 are published from GitHub Actions with npm provenance, which links each one to the commit and workflow that built it.

# Claude Code

claude mcp add cverdict -- npx -y cverdict-mcp

Other clients take an mcpServers entry (key names vary by client):

{

"mcpServers": { "cverdict": { "command": "npx", "args": ["-y", "cverdict-mcp"] } } }

On Windows, clients that cannot start npx directly take "command": "cmd" and "args": ["/c", "npx", "-y", "cverdict-mcp"]. npx -y runs the newest version; pin one with cverdict-mcp@ (the versions are on the npm page).

Run it from a clone

Node 22.12 or later.

git clone --single-branch https://github.com/markusweldon/cverdict.git

cd cverdict && npm ci

Claude Code

claude mcp add cverdict -- npm --prefix "$PWD" run -s mcp

Other clients take an mcpServers entry (key names vary by client):

{

"mcpServers": { "cverdict": { "command": "npm", "args": ["--prefix", "/path/to/cverdict", "run", "-s", "mcp"] } } }

Keep the -s: a plain npm run prints its own banner to stdout, which is the JSON-RPC channel.

To skip npm and TypeScript at start-up (and on Windows, where clients cannot start npm directly), build the single-file server once and start it with Node:

npm run build:mcp                                   # writes mcp/dist/cverdict-mcp.mjs

claude mcp add cverdict -- node "$PWD/mcp/dist/cverdict-mcp.mjs"

Run git pull && npm ci (and npm run build:mcp if you use the bundle) to update.

Options

Environment variables, all optional. MCP clients start servers with a minimal environment, so put them in the client's env block for this server.

At start the server writes one line to stderr with its version, the Node version, whether it sees a proxy and the data bases. Nothing but JSON-RPC goes to stdout.

Tools

All six are read-only (readOnlyHint: true) and return structuredContent plus the same JSON as one text block. The result types are in shared/contract.ts, section "MCP tool results".

Dates (published_since, since) are UTC: 2026-10-01, 2026-10-01T06:00Z or 2026-10-01T06:00:00.000Z. A date that does not exist is an error. A filter the server cannot apply is always an error, never silently dropped.

Measured on the live data of 2026-11-03 (16,747 window CVEs), the largest answer any tool can give at its maximum bounds stays under 20,000 tokens; scripts/mcp-measure.ts checks this.

Every answer starts with data

Right after an hourly publish a CDN can serve one file from the previous run for a few minutes; files[] then shows both times rather than hiding it.

Reading the answers honestly

• Quiet means no evidence yet, never safe. A CVE outside the data (found: false) is unknown, not safe: the data covers CVEs published in the last 30 days, every CVE in CISA KEV and old CVEs that woke up.
• Text is untrusted. Titles, descriptions, KEV names and required actions, and chip labels quote CNAs, CISA and exploit feeds. The server's instructions tell the agent never to follow instructions found in them. That reduces the risk of prompt injection; it does not remove it.
• Privacy. GitHub sees which of the 256 shard files the server fetches, never your CVE IDs or search words. If GitHub refuses or fails, the same requests go to the site's /data/ copy. Nothing is uploaded and nothing is written to disk.

Errors

Failures come back as tool results with isError: true and a plain message, for example:

How it reads the data

• Bases are tried in order. A 404 is final. A 429 or 403, or a timeout (no response headers within 4 s, or a body that stops arriving for 4 s), falls through to the next base and moves that base to the back for 10 minutes. Network errors, redirects (refused), 5xx and malformed files fall through to the next base. A slow body that keeps arriving is not cut off.
• Each tool call has one 10 s deadline. Shards for get_verdict are fetched in parallel, at most 6 at a time.
• Bodies are capped at 24 MB decoded, which also stops a compression bomb from a mirror. Files must have schema_version 1 and generated_at; row tables must have exactly the published columns.
• Parsed files stay in memory for the life of the process. meta.json is checked again after 5 minutes (raw.githubusercontent.com caches for 5 minutes anyway); other files are refetched when meta.json names a newer run. An idle server makes no requests and runs no timers.

Development

npx vitest run mcp/test      # unit, protocol and spawn tests (what the release workflow runs)

npm test # every test in the repository npm run build:mcp # the single-file bundle in mcp/dist/ npx tsx scripts/mcp-measure.ts # answer sizes against the live data branch npx tsx mcp/test/smoke.ts mcp/dist/cverdict-mcp.mjs # what CI runs on mock data

The SDK (@modelcontextprotocol/server) and zod are exact-pinned dev dependencies of the repository and are bundled into dist/cverdict-mcp.mjs, so the package has no runtime dependencies. The site never imports them: shared/mcp.ts holds the copy both use.

Releasing

Maintainers only. Set the new version in mcp/package.json, MCP_SERVER.version in shared/mcp.ts, and both version fields in mcp/server.json (a test keeps them equal), commit, and push a tag mcp-v , for example git tag mcp-v0.1.1 && git push origin mcp-v0.1.1. The release workflow (.github/workflows/release-mcp.yml) checks that the tag matches the version, runs the MCP tests and the smoke test, packs the bundle and publishes it to npm through trusted publishing, with provenance. A last job lists the version on the MCP Registry from mcp/server.json, logged in with the workflow's GitHub OIDC identity. No npm or registry token is stored anywhere.

One-time setup: the first version is published by hand (npm run build:mcp at the root, then npm login and npm publish in mcp/). Then on npmjs.com, package cverdict-mcp → Settings → Trusted publishing → GitHub Actions: owner markusweldon, repository cverdict, workflow release-mcp.yml, no environment. Under Publishing access, choose to require two-factor authentication and disallow tokens.

License

MIT (LICENSE). The bundle includes the MCP TypeScript SDK (Apache-2.0, with contributions under MIT), zod (MIT) and the libraries the SDK vendors; their notices are in LICENSE-THIRD-PARTY. Data terms: docs/DATA.md.