CVE MCP Server

# CVE MCP Server (Prototype) A local, containerized Model Context Protocol (MCP) server that provides conversational access to a CVE (Common Vulnerabilities and Exposures) database. > **PROTOTYPE**: This is a project demonstrating MCP server implementation. It is functional but not production-ready. ## Overview This project enables natural-language queries against a local CVE database using any MCP-compatible client. All data is stored locally for privacy and can be refreshed from public CVE sources. ## Features - Fully local - all data on your machine, stdio transport only - Refreshable CVE data from GitHub database - Runs in Docker - Works with MCP Inspector and other MCP clients - Three tools: `get_cve_details`, `search_cves`, `get_statistics` ## Prerequisites - Docker (with `docker compose` support) - Python 3.11+ (for local development) - Node.js 18+ (for MCP Inspector) ## Installation ```bash # Development pip install -e ".[dev]" # Docker/Production pip install -r requirements.txt ``` Project uses `pyproject.toml` for configuration. ### Configuration (optional) Create a `.env` file to customize paths: ```bash cp .env.example .env # Edit CVE_REPO_URL, CVE_REPO_PATH, CVE_GITHUB_API_BASE, CVE_DB_PATH ``` Works fine without any configuration. ## Quick Start with Run Scripts (Recommended) Convenient shell scripts automate the testing workflow: ### Docker Testing (Full Workflow) ```bash # 1. Build and start Docker container ./run_docker.sh # 2. Load CVE data (choose one): docker exec cve-mcp-server python -m src.data_ingestion.loader --year 2024 --limit 100 # Quick docker exec cve-mcp-server python -m src.data_ingestion.loader_optimized # Full dataset # 3. Test with MCP Inspector ./run_test_inspector.sh # Choose option 2 (Docker) ``` ### Local Testing (Full Workflow) ```bash # 1. Setup environment python3 -m venv venv source venv/bin/activate pip install -r requirements.txt # 2. Load CVE data (choose one): ./run_load_limited.sh # Quick: 100 CVEs from 2024 ./run_load_optimized.sh # Full: ~240K CVEs (6-7 min) ./run_load_optimized.sh 2024 2023 # Specific years only # 3. Test with MCP Inspector ./run_test_inspector.sh # Choose option 1 (Local) ``` ### Available Run Scripts | Script | Purpose | Usage | |--------|---------|-------| | `run_load_limited.sh` | Load small dataset via API | `./run_load_limited.sh [year] [limit]` | | `run_load_optimized.sh` | Load full/filtered dataset via Git | `./run_load_optimized.sh [year1] [year2] ...` | | `run_docker.sh` | Build and start Docker container | `./run_docker.sh` | | `run_test_inspector.sh` | Launch MCP Inspector for testing | `./run_test_inspector.sh` | ## Quick Start with Docker (Manual) ### 1. Clone the Repository ```bash git clone https://github.com/yourusername/cve-mcp-server.git cd cve-mcp-server ``` ### 2. Build Docker Image ```bash docker build -t cve-mcp-server . ``` ### 3. Load CVE Data ```bash ./scripts/docker_load_data.sh ``` This downloads ~100 recent CVEs from GitHub (takes 1-2 minutes). ### 4. Start Container ```bash docker compose up -d ``` Verify it's running: ```bash docker ps ``` ### 5. Test with MCP Inspector ```bash npx @modelcontextprotocol/inspector ``` Inspector configuration: - Command: `docker` - Arguments: `exec -i cve-mcp-server python -m src.mcp_server` - Environment: `PYTHONPATH=/app` ## Local Development (Without Docker) ### 1. Setup Python Environment ```bash # Create virtual environment python3 -m venv venv source venv/bin/activate # Install dependencies pip install -r requirements.txt ``` ### 2. Load CVE Data ```bash python -m src.data_ingestion.loader --year 2024 --limit 100 ``` ### 3. Run MCP Server ```bash python -m src.mcp_server ``` The server will wait for MCP client connections via stdio. ### 4. Test Locally with MCP Inspector In a new terminal: ```bash npx @modelcontextprotocol/inspector ``` Configuration: - Command: `python` - Arguments: `-m src.mcp_server` - Environment: `PYTHONPATH=/path/to/cve-mcp-server` ### 5. Run Unit Tests ```bash # Test database operations python tests/test_database.py # Test MCP tools directly python tests/test_tools.py ``` ## Available Tools ### get_cve_details Get detailed information about a specific CVE. Parameters: - `cve_id` (string): CVE identifier like "CVE-2024-0001" Example: ```json { "cve_id": "CVE-2024-0001" } ``` Response: ```json { "cve_id": "CVE-2024-0001", "description": "A critical vulnerability in Apache HTTP Server...", "severity": "CRITICAL", "cvss_score": 9.8, "published_date": "2024-01-15", "modified_date": "2024-01-20", "references": ["https://..."] } ``` ### search_cves Search CVEs by keyword. Parameters: - `keyword` (string): Search term - `limit` (integer): Max results, default 10 Example response: ```json { "query": "remote code execution", "count": 5, "results": [ { "cve_id": "CVE-2024-0015", "severity": "HIGH", "cvss_score": 8.5, "description": "Remote code execution...", "published_date": "2024-01-10" } ] } ``` ### get_statistics Get database stats. No parameters. ```json { "database_info": { "total_cves": 95, "date_range": { "oldest": "2024-01-05", "newest": "2024-02-15" }, "last_update": "2025-01-18T14:32:00.123456" } } ``` ## Data Management ### Using Run Scripts (Recommended) **Local development:** ```bash # Quick test with limited data ./run_load_limited.sh # Default: 100 CVEs from 2024 ./run_load_limited.sh 2023 50 # Custom: 50 CVEs from 2023 # Full dataset or specific years ./run_load_optimized.sh # All ~240K CVEs (6-7 min) ./run_load_optimized.sh 2024 2023 # Only 2024 and 2023 ``` **Docker:** ```bash # Quick test docker exec cve-mcp-server python -m src.data_ingestion.loader --year 2024 --limit 100 # Full dataset docker exec cve-mcp-server python -m src.data_ingestion.loader_optimized # Specific years docker exec cve-mcp-server python -m src.data_ingestion.loader_optimized --years 2024 2023 ``` ### Manual Commands **Load More CVE Data (Local):** ```bash # Limited dataset via API python -m src.data_ingestion.loader --year 2024 --limit 500 # Full dataset via Git clone python -m src.data_ingestion.loader_optimized python -m src.data_ingestion.loader_optimized --years 2024 2023 ``` **Load More CVE Data (Docker):** ```bash # Load 500 CVEs from 2024 docker exec cve-mcp-server python -m src.data_ingestion.loader --year 2024 --limit 500 # Load from different year docker exec cve-mcp-server python -m src.data_ingestion.loader --year 2023 --limit 200 ``` ## Performance & Benchmarks Based on systematic benchmarking: - **Full dataset load time**: ~6-7 minutes (240,000 CVEs) - **Database size**: ~190 MB - **Loading speed**: 2,700+ CVEs/second (using optimized loader) ### Load Full Dataset ```bash # Using optimized loader (recommended) python -m src.data_ingestion.loader_optimized # Or in Docker docker exec cve-mcp-server python -m src.data_ingestion.loader_optimized ``` See `benchmarks/BENCHMARK_RESULTS.md` for detailed analysis. ### Check Database Status ```bash # Using Docker docker exec cve-mcp-server python -c " import sys sys.path.insert(0, '/app') from src.database.db import init_db, get_stats print(get_stats(init_db())) " # Using local Python python -c " import sys from pathlib import Path sys.path.insert(0, str(Path.cwd() / 'src')) from database.db import init_db, get_stats print(get_stats(init_db())) " ``` ## Project Structure ``` cve-mcp-server/ ├── src/ │ ├── mcp_server/ # MCP server implementation │ │ ├── server.py # Server and tool definitions │ │ ├── tools.py # Tool implementation logic │ │ └── __main__.py # Entry point │ ├── database/ # Database layer │ │ └── db.py # SQLite schema and queries │ ├── data_ingestion/ # CVE data pipeline │ │ ├── loader.py # GitHub API CVE fetcher │ │ └── loader_optimized.py # Git clone CVE fetcher │ └── config.py # Configuration management ├── data/ # SQLite database (Docker volume) ├── tests/ # Unit tests │ ├── test_database.py # Database operation tests │ └── test_tools.py # Tool logic tests ├── run_load_limited.sh # Quick data load script (API) ├── run_load_optimized.sh # Full data load script (Git) ├── run_docker.sh # Docker build and start script ├── run_test_inspector.sh # MCP Inspector testing script ├── Dockerfile # Container image definition ├── docker-compose.yml # Container orchestration ├── pyproject.toml # Project configuration (PEP 621) ├── requirements.txt # Python dependencies ├── .env.example # Configuration template ├── CLAUDE.md # Architecture documentation ├── TESTING.md # Testing guide └── README.md # This file ``` ## Technologies Used - **Python 3.11**: Core language - **MCP SDK**: Model Context Protocol implementation - **SQLite**: Local database with full-text search capability - **Docker**: Containerization and deployment - **GitHub CVE Database**: Data source ([CVEProject/cvelistV5](https://github.com/CVEProject/cvelistV5)) - **pyproject.toml**: Modern Python project configuration (PEP 621) ## Testing ### Quick Testing with Run Script (Recommended) Use the convenient testing script that handles both local and Docker deployments: ```bash ./run_test_inspector.sh ``` The script will: 1. Ask if you want to test Local or Docker deployment 2. Validate prerequisites (virtual environment, container running, database exists) 3. Display the correct MCP Inspector configuration 4. Launch MCP Inspector automatically ### Manual Testing with MCP Inspector MCP Inspector provides an interactive UI to test all tools: 1. Start the server (Docker or local) 2. Run `npx @modelcontextprotocol/inspector` 3. Configure connection (see Quick Start sections above) 4. Test each tool with various inputs For detailed testing procedures, see `TESTING.md`. ### Unit Testing ```bash # Database operations python tests/test_database.py # Tool implementations python tests/test_tools.py ``` ## Troubleshooting ### Docker Issues **Container won't start:** ```bash docker logs cve-mcp-server docker compose down docker compose up -d ``` **No CVE data loaded:** ```bash ./scripts/docker_load_data.sh ``` **Rebuild after code changes:** ```bash docker compose down docker build -t cve-mcp-server . docker compose up -d ``` ### MCP Inspector Connection Issues **Connection fails:** - Verify container is running: `docker ps` - Check exact command: `docker exec -i cve-mcp-server python -m src.mcp_server` - Ensure container name matches: `cve-mcp-server` **Tools not appearing:** - Check server logs for import errors - Verify PYTHONPATH is set correctly ### Local Development Issues **Import errors:** - Ensure virtual environment is activated - Check PYTHONPATH includes project root - Verify all dependencies installed: `pip install -r requirements.txt` **Database not found:** - Check `data/cve.db` exists - Run data loader: `python -m src.data_ingestion.loader` ## Limitations - Local only (stdio transport) - Basic keyword search, no FTS5 yet - Manual data refresh - No auth/security (local use only) ## TODO Things that would be nice to add: - SSE transport for network access - SQLite FTS5 for better search - Filter by CVSS score/severity/date ranges - Automated data refresh (cron job?) - Example UI with Streamlit or something - Maybe a REST API wrapper - CVE monitoring/alerts - Export to PDF/CSV - Stats dashboard ## Contributing Prototype project. PRs welcome for bug fixes, docs, or features from TODO list. ## License MIT - see LICENSE file ## Credits - CVE data from [CVEProject/cvelistV5](https://github.com/CVEProject/cvelistV5) - Built with [Anthropic MCP SDK](https://github.com/anthropics/anthropic-sdk-python) --- Note: This is a prototype. For production use you'd want proper security, auth, error handling, etc.