nvd-cve-mcp-server: Instructions file for GitHub Copilot

nvd-cve-mcp-server AI Coding Agent Instructions

Project Overview

nvd-cve-mcp-server is an MCP (Model Context Protocol) stdio server that exposes CVE vulnerability data from the NVD API v2.0 as MCP tools. It is designed to be wired into MCP-compatible AI clients (e.g., Claude Desktop, Cursor) so that those clients can query live CVE data during conversations.

Key characteristics:

• stdio transport only (no HTTP server; MCP clients launch it as a subprocess)
• Optional NVD API key support (unauthenticated: 5 req/30s, authenticated: 50 req/30s)
• Sliding-window rate limiter + exponential-backoff retry with Retry-After header support
• NVD API constraint: date range windows capped at 120 days

Architecture

Two-Module Design

1. nvd_client.py: NVD API v2.0 client — rate limiting, retry logic, response normalization

   • NVDClient dataclass: configures HTTP client, rate limiter, and optional API key
   • RateLimiter: thread-safe sliding-window limiter using collections.deque
   • NVDAPIError: single public exception for all API failures
   • _RetryNeeded: internal signal; never surfaces to callers
   • format_cve_response(): normalizes raw NVD payload into a compact dict with keys total_results, returned_results, cves
   • _extract_primary_metric(): prefers CVSS v3.1 → v3.0 → v2 when multiple metrics exist

2. server.py: FastMCP server exposing four tools via stdio

   • search_cve_by_id(cve_id): exact CVE lookup (e.g., CVE-2024-1234)
   • search_cve_by_keyword(keyword, limit, days_back): keyword search with optional date window (max 120 days)
   • get_recent_cves(limit, days_back): recent CVEs by publication date (max 120 days)
   • search_by_severity(severity, limit): filter by CRITICAL, HIGH, MEDIUM, or LOW

Response Shape

All tools return a dict with a success bool. On success:

{"success": True, "total_results": int, "returned_results": int, "cves": [...]}

On error:

{"success": False, "error": str}

Each CVE entry contains: id, published, last_modified, description, severity, base_score, vector, cwes, references.