CVEasy AI — MCP Server

A Model Context Protocol server that exposes a live CVEasy AI install — scans, findings, CVEs, assets, threat intel, metrics — to MCP clients like Claude Desktop and Claude Code.

Its purpose is to refine report-making. Today CVEasy fills report narrative sections with the bundled local model using only aggregate numbers, which keeps prose thin and occasionally wrong. This server flips that: it lets a far more capable model (Claude) pull the real, structured data behind any report and draft or critique the prose grounded in actual figures — then render the final HTML/PDF through the same backend.

┌────────────────────┐   stdio (JSON-RPC)   ┌──────────────────┐   HTTP :3001   ┌─────────────────────┐
│ Claude Desktop /    │ ───────────────────▶ │    cveasy-mcp     │ ─────────────▶ │ CVEasy AI backend   │
│ Claude Code (LLM)   │ ◀─────────────────── │  (this package)   │ ◀───────────── │ (Hono, SQLite, AI)  │
└────────────────────┘   tools/prompts/res   └──────────────────┘   /api/*        └─────────────────────┘

The server is a thin client over the CVEasy REST API — it never touches the database directly. That avoids lock contention with the running desktop app, reuses the backend's scoring/dedup logic, and survives schema changes.

Quick start

git clone https://github.com/CVEasy/cveasy-mcp && cd cveasy-mcp
bun install
bun run smoke      # spins up the server and exercises it against your live backend

bun run smoke should print SMOKE TEST PASSED if the CVEasy AI app is running (backend on :3001).

Then wire it into a client (below) and ask: "Use CVEasy to draft an executive risk summary for Acme Corp."

Requires the CVEasy AI desktop app (or bun run backend/src/index.ts) running so the backend answers on :3001. The server starts fine without it and every tool simply returns a clear "backend not reachable" error until it's up.

Configuration

All configuration is via environment variables; defaults match a stock local install.

On a normal local CVEasy install RBAC is off (/api/auth/status → authEnabled:false), so no tokens are required even for writes.

Wiring into a client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "cveasy": {
      "command": "/Users/<you>/.bun/bin/bun",
      "args": ["run", "/absolute/path/to/cveasy-mcp/src/index.ts"],
      "env": { "CVEASY_BASE_URL": "http://127.0.0.1:3001" }
    }
  }
}

Use the absolute path to bun (which bun) — Claude Desktop doesn't inherit your shell PATH. Restart Claude Desktop; "cveasy" appears in the tools menu.

Claude Code

# from anywhere
claude mcp add cveasy -- /Users/<you>/.bun/bin/bun run /absolute/path/to/cveasy-mcp/src/index.ts

Or commit a project-scoped .mcp.json so the team shares it:

{
  "mcpServers": {
    "cveasy": {
      "command": "bun",
      "args": ["run", "cveasy-mcp/src/index.ts"],
      "env": { "CVEASY_BASE_URL": "http://127.0.0.1:3001" }
    }
  }
}

Standalone binary (no bun on PATH)

bun run compile          # → dist/cveasy-mcp (self-contained)
# then point the client's "command" at the absolute path of dist/cveasy-mcp with no args

The report-refinement workflow

This is the core use case. The pattern is always pull data → write/refine → (optionally) render.

1. Pull the ground truth. report_context { type: "executive" } returns one JSON bundle with metrics, top risks, priority bands, patch compliance, threat feed, and the org profile. Every sub-source is fetched independently; any that fail land in warnings instead of failing the whole call.

2. Draft or refine. Use a prompt — e.g. refine_executive_summary — which instructs the model to ground every number in that context and follow house style. Or just ask in natural language. (report_template_guide returns the recommended section skeleton per type.)

3. Render the deliverable. report_render { type, kpis, sections } lays Claude's authored prose + tables into a polished, branded, print-ready HTML document using the built-in design system, and saves it. The user opens it and chooses Print → Save as PDF. This closes the loop entirely in the MCP layer — Claude controls the prose AND the layout, no backend involvement.

4. Critique loop. critique_report { report_type: "executive", report_text: "…" } reviews an existing report against live data and lists factual errors, gaps, and rewrites.

Two ways to render

Use report_render for the refined deliverable; use report_generate when you want the exact in-app report.

The template engine

src/template/ is a small, dependency-free, offline-safe design system:

• design.ts — one shared stylesheet (system fonts, KPI cards, severity badges, callouts, @page/page-break print rules) + per-type accent presets.

• markdown.ts — injection-safe Markdown→HTML (escapes first; _ is left literal so finding_fp_hash/T1110_001 survive).

• render.ts — renderReport(model) assembles the full HTML from a ReportModel (header+logo, KPI band, sections with prose/bullets/tables/callouts, footer).

Improving a template here improves every rendered report. To port the same look into the in-app reports later, lift these into backend/src/services/report-builder.ts.

Tools (50)

Posture & metrics

CVEs

Inventory & assets

Findings

BAS scans (read)

Threat intel

Reports

Mutating tools — gated by CVEASY_ALLOW_WRITES (scan tools also by CVEASY_ALLOW_SCANS)

Prompts (6)

Reusable, data-grounded report-writing workflows. Improving the prose rules here improves every report.

Each prompt tells the model to call the relevant data tool first and forbids invented figures.

Resources (5)

Read-only snapshots for clients with a resource/"attach context" UI: cveasy://reports/types, cveasy://metrics/summary, cveasy://posture/status, cveasy://org/profile, cveasy://threat/feed.

Safety & permissions

• Writes are on by default but can be disabled wholesale (CVEASY_ALLOW_WRITES=0) for a read-only deployment. Mutating tools are annotated destructiveHint where they change/delete state, so clients can prompt before running them.

• Scans (bas_scan_start, bas_validate_cve) actively probe systems and require the target to be inside an active BAS authorization scope on the backend (else 403). They can be disabled separately (CVEASY_ALLOW_SCANS=0).

• RBAC: when access control is enabled on the backend, mutating actions need an operator session token (CVEASY_SESSION_TOKEN).

• All logs go to stderr — stdout is reserved for the JSON-RPC stream.

Development

bun run typecheck   # tsc --noEmit (strict, no unused)
bun run smoke       # end-to-end stdio test against the live backend
bun run dev         # hot-reload the server
bun run build       # → dist/index.js
bun run compile     # → dist/cveasy-mcp (standalone binary)

Layout: src/config.ts (env), src/client.ts (HTTP), src/util.ts (result helpers + tool registration), src/tools/* (domain tools — incl. render.ts), src/template/* (the design system + Markdown + renderer), src/prompts.ts, src/resources.ts, src/index.ts (wiring). Adding a tool = one registerTool(...) call in the relevant module.

Roadmap / nice-to-haves

• Port the src/template/ design system into the backend (report-builder.ts) so the in-app reports match the rendered ones, and optionally add a narrative-injection endpoint (POST /api/reports/generate { narrative }) so report_generate can use Claude's prose too. (The MCP-side loop is already closed by report_render.)

• Native one-click PDF in report_render (currently print-to-PDF). Would need a PDF lib or headless renderer; print-ready HTML is intentionally dependency-free for now.

• report_render_from_context — a convenience that pulls report_context and pre-fills the KPI band/tables, leaving Claude to write only the prose.

• More section primitives (charts via inline SVG, two-column layouts, appendix tables).