PG_CVE-MCP

# pg-cve-mcp — PostgreSQL CVE & Release Intelligence for AI Agents

[![PyPI version](https://img.shields.io/pypi/v/pg-cve-mcp.svg)](https://pypi.org/project/pg-cve-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/pg-cve-mcp.svg)](https://pypi.org/project/pg-cve-mcp/)
[![License](https://img.shields.io/github/license/meob/PG_CVE-MCP.svg)](https://github.com/meob/PG_CVE-MCP/blob/main/LICENSE)

<!-- mcp-name: io.github.meob/pg-cve-mcp -->

**Give your AI assistant direct access to PostgreSQL security intelligence: CVEs, yanked releases, known exploits, and upgrade paths for any version — queried, not browsed.**

---

## Why pg-cve-mcp?

Browsing a CVE dashboard is a human habit. **Agents need answers, not pages.**

`pg-cve-mcp` turns the curated dataset of the [**PG_CVE**](https://github.com/meob/PG_CVE) project — the same one powering the [PostgreSQL CVE Dashboard](https://meob.github.io/PG_CVE/) — into MCP tools that any AI assistant (opencode, Claude Desktop, etc.) can call directly. What was a static page becomes a first-class, programmatic part of your AI workflow.

Unlike raw NVD feeds, the PG_CVE dataset is **manually curated** to carry the same judgment a careful DBA would apply:

- **Yanked releases** flagged with the real reason (e.g. *"Data corruption using CONCURRENTLY"*)
- **Known exploits** confirmed to exist in the wild
- **EOL branches** marked, with a synthetic `CVE-EOL-WARNING` (CVSS 10.0) prepended to unsupported reports
- **Verified CVEs** — no false positives from automated scraping

### What your agent can now do

| Prompt to your agent | Tool used | Result |
|---|---|---|
| "Is PostgreSQL 15.8 safe?" | `get_cves("15.8")` | EOL/yanked flags, full CVE list sorted by CVSS |
| "Compare 16.3 vs 16.4" | `compare_versions("16.3", "16.4")` | fixed / new / still-present CVEs |
| "Should I upgrade from 14.10?" | `get_upgrade_path("14.10")` | recommended target + the CVEs it fixes |
| "Any known exploits right now?" | `get_exploits()` | all exploitable CVEs, sorted by CVSS |
| "What does this database track?" | `get_summary()` | stats, EOL and yanked-release overview |

### Agent-first design

Every tool returns **structured JSON**, sorted by CVSS (highest first). Tools flag *yanked* and *EOL* state explicitly on the version metadata, and `get_upgrade_path` distinguishes a safe **minor** upgrade from a forced **major** one when a branch is at or near end-of-life — so the agent can give advice, not just data.

See real tool outputs in the [live demo](docs/demo.md).

---

## Quick Start

```bash
pip install pg-cve-mcp
pg-cve-mcp
```

Or with `npx` (no install):

```bash
npx -y pg-cve-mcp
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `get_cves(version)` | Complete security report for a version: EOL/yanked status, stats, CVEs sorted by CVSS (a synthetic `CVE-EOL-WARNING` at 10.0 is prepended for unsupported releases) |
| `compare_versions(v1, v2)` | Side-by-side CVE comparison (fixed/new/still present) with yanked & EOL flags |
| `get_upgrade_path(from_version)` | Recommended upgrade (minor by default; major when EOL or next-to-EOL) with fixed CVEs |
| `get_exploits()` | All CVEs with known public exploits, sorted by CVSS |
| `get_summary()` | Overview of the tracked CVE database incl. yanked releases |

## Transports

### stdio (default)

Run locally over stdio for opencode, Claude Desktop, and other stdio MCP clients:

```bash
pip install -e .
pg-cve-mcp
```

### Streamable HTTP (self-hosted)

For remote or enterprise deployments, serve the same tools over HTTP. Run
`python run_server.py` (or build the Dockerfile); the server listens on `$PORT`
(default 8000) at path `/mcp`:

```bash
python run_server.py
# MCP endpoint: http://127.0.0.1:8000/mcp
```

Configure any MCP client with the URL, e.g. in `opencode.json`:

```json
{
  "mcp": {
    "pg-cve-mcp": {
      "type": "remote",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

## Configuration

| Env Var | Default | Description |
|---------|---------|-------------|
| `PG_CVE_MCP_TTL` | `86400` | Cache TTL in seconds for CVE data |
| `PG_CVE_MCP_DATA_URL` | `https://meob.github.io/PG_CVE/postgresql_cves.json` | CVE data source URL |
| `PORT` | `8000` | HTTP port for the Streamable HTTP server (`run_server.py`) |

## Development

Run the test suite and linters:

```bash
python -m pytest
ruff check src tests
mypy src
```

## Data Source

Data is fetched from the [PG_CVE](https://github.com/meob/PG_CVE) project's GitHub Pages with local caching. Falls back to a bundled copy if the network is unavailable.

## Example Prompts

> "What CVEs affect PostgreSQL 16.4?"
>
> "Is PostgreSQL 15.8 safe to use?"
>
> "Compare CVEs in 16.3 vs 16.4"
>
> "What's the upgrade path from PostgreSQL 14.10?"

## License

Apache 2.0