Metadata-Version: 2.4
Name: mcp-server-vdb
Version: 7.0.1
Summary: AppThreat Vulnerability Database MCP server
Author-email: Team AppThreat <cloud@appthreat.com>
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: Free Threading :: 1 - Unstable
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: appthreat-vulnerability-db[oras]==7.0.1
Requires-Dist: mcp[cli]<3.0.0,>=2.0.0
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: bandit; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# Introduction

This folder contains the source code for running VDB as a Model Context Protocol (MCP) server. Below you can find the configuration for running the VDB MCP server with Claude Desktop. Please feel free to share the configuration for other [clients](https://modelcontextprotocol.io/clients) via pull requests.

## What is available

The MCP server provides:

- Structured JSON tool results with summaries and machine-readable evidence.
- Bulk search tools for package lists and CycloneDX BOMs.
- Filter-aware search for severity thresholds, sources (`osv`, `nvd`, `github`, `aqua`), date ranges, malware-only / exclude-malware, package scope (`app_only`, `os_only`), package ecosystem, and pagination.
- Metadata and full-text search over aliases, references, package names, descriptions, and affected functions/modules.
- Resource templates such as `cve://{id}` and `purl://{purl}`.
- Concrete resources such as `vdb://metadata`, `vdb://health`, `vdb://sources`, and `vdb://malware/latest`.
- A `db_refresh` tool that fetches or refreshes local data through the same staged, validated, atomically-swapped path as `vdb db refresh` — `{"target": "full"}` (optionally `app_only` or an `image` URL override), `{"target": "shards", "shards": ["npm", "pypi"]}`, or `{"target": "sync"}` (the default: refresh everything already local). Every result carries the post-refresh health report.
- Richer prompts for package-risk assessment, CVE triage, SBOM summaries, fix prioritization, version-match explanations, and overlay review.

### VDB 7 shard stores, coverage, and health

VDB 7 data can be a full database under `VDB_HOME` or a set of type shards (see the root [README type-shard section](../../README.md#type-shard-databases-v7-preview)). The server is honest about which one it has:

- Every tool payload carries a `status`: `ok`, `coverage_gap` (some requested purl types have no local shard — those results were NOT checked), or `stale_data` (a shard lags its siblings by more than `shard_store.STALE_SHARD_LAG_DAYS` days). Shard-mode payloads also carry a `coverage` object with `uncovered_types`, `shard_build_ids`, and `stale_shards`; batch and BOM results mark affected packages with a per-package `coverage_gap` flag.
- An empty or unusable database is a tool error, never an empty result list that reads as "no vulnerabilities found".
- `vdb://health` reports `status` (`ok` | `degraded` | `error` | `empty`), the main-DB state, and the full per-shard store report (build ids, ages, staleness, missing group shards) — the same computation `vdb db status` uses. Use it to tell "I have no deb data" from "my deb data is three weeks old" from "I am fully current".
- When the database is missing or older than `VDB_AGE_DAYS` at startup, the server refreshes it with `db_refresh target=full --app-only` semantics (downloaded to a staging directory, validated as a usable v7 artifact, then atomically swapped in — a failed or interrupted download never damages the existing database). A failed refresh is a visible warning and the server continues with whatever local data it has.

## Pre-requisites

- Python >= 3.10 installed
- docker or Rancher Desktop (or)
- uv [installed](https://docs.astral.sh/uv/getting-started/installation/)

## docker-based execution (Recommended)

Use our container image `ghcr.io/appthreat/mcp-server-vdb:master`.

### Claude Desktop configuration

Edit the file using VS code or any editor of your choice. `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows, the config file is `$env:AppData\Claude\claude_desktop_config.json`. Use the below configuration:

```json
{
  "mcpServers": {
    "vdb": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VDB_HOME=/db",
        "-v",
        "$HOME/vdb:/db:rw",
        "ghcr.io/appthreat/mcp-server-vdb:master"
      ]
    }
  }
}
```

`nerdctl` example.

```json
{
  "mcpServers": {
    "vdb": {
      "command": "nerdctl",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VDB_HOME=/db",
        "-v",
        "$HOME/vdb:/db:rw",
        "ghcr.io/appthreat/mcp-server-vdb:master"
      ]
    }
  }
}
```

Restart the Claude Desktop application.

If you get `ENOENT` error, specify the full path to docker. On a mac, `/Applications/Docker.app/Contents/Resources/bin/docker`.

## Local uv-based execution (Developers only)

```shell
git clone https://github.com/AppThreat/vulnerability-db.git
cd vulnerability-db
python -m pip install .

export VDB_HOME=$HOME/vdb
mkdir -p $VDB_HOME
vdb db refresh full --app-only
uv --directory packages/mcp-server-vdb run mcp-server-vdb
```

### Claude Desktop configuration

Edit the file using VS code or any editor of your choice. `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows, the config file is `$env:AppData\Claude\claude_desktop_config.json`.

Use the below configuration and adjust the following paths:

- absolute path to the `mcp-server-vdb` package inside the `packages` directory.
- `VDB_HOME` - Full path to the directory containing the vulnerability database. Must have run `vdb db refresh full --app-only`

```json
{
  "mcpServers": {
    "vdb": {
      "command": "uv",
      "args": [
        "--directory",
        "/Volumes/Work/AppThreat/vulnerability-db/packages/mcp-server-vdb",
        "run",
        "mcp-server-vdb"
      ],
      "env": {
        "VDB_HOME": "/Users/guest/vdb"
      }
    }
  }
}
```

Restart the Claude Desktop application.

## Environment variables

The MCP server uses the same `vdb` configuration as the CLI. See the root [README environment variables](../../README.md#environment-variables) for the full reference. The most common MCP settings are:

| Variable | Default | Description |
| :------- | :------ | :---------- |
| `VDB_HOME` | Platform user data directory for `vdb` | Directory containing `data.vdb7`, `data.index.vdb7`, and `vdb.meta`. Set this explicitly for Docker volume mounts and local Claude Desktop configurations. |
| `VDB_SHARDS_DIR` | `$VDB_HOME/shards` | Type-shard store directory. Searches fan out across shards when the main DB under `VDB_HOME` is a shard (`vdb.meta` `completeness: "partial"`). |
| `VDB_AGE_DAYS` | `2` | Number of days before the server treats the local database as stale. When stale or missing and ORAS support is installed, the server downloads the app-only database on startup. Use an integer string. |
| `VDB_APP_ONLY_DATABASE_URL` | `ghcr.io/appthreat/vdb7-app-only:v7.0.x-xz` | OCI image URL used by MCP automatic downloads. Override this for internally published app-only artifacts. Prefer the `-xz` suffix: it unpacks unconditionally, while `-zst` needs a zstd decompressor (Python 3.14+ or a `zstd` binary on PATH). |
| `VDB_SQLITE_IMMUTABLE` | unset | Open existing `.vdb7` files with SQLite's immutable URI option in read-only deployments. |

If the MCP server needs extended metadata searches such as full-text, alias, reference, package-name, or symbol lookup, v7 publishes no pre-built extended artifacts — pre-populate `VDB_HOME` with a database built using `vdb --cache --include-metadata` (or `--cache-os --include-metadata`), or point `VDB_DATABASE_URL`/`VDB_APP_ONLY_DATABASE_URL` at your own internally published metadata artifact.

## Screenshots

### Claude context screen

![Claude context](./docs/claude-context.png)

### Claude permissions on first run

![Claude permissions](./docs/claude-permissions.png)

### Claude results

![Vulnerability description](./docs/vuln-description.png)

### Latest malware

![Latest Malware](./docs/latest-malware.png)

## Configuration for MCP Inspector

- Transport Type: STDIO
- Command: uv
- Arguments: `--directory /absolute/path/to/vulnerability-db/packages/mcp-server-vdb run mcp-server-vdb`

Click "Connect"

![MCP Inspector](./docs/vdb-mcp-inspector.png)

### Testing

1. Click "List Tools". You should see structured tools such as `search_by_purl_like`, `search_full_text`, `search_packages`, `search_bom_summary`, and `search_bom_detailed`.
2. Select `search_by_purl_like` and enter a purl string such as `pkg:swift/vapor/vapor@4.89.0`.
3. Confirm that the tool returns structured JSON content with `summary` and `results`.
4. Try resources such as `vdb://metadata`, `vdb://health`, or `cve://CVE-2024-25169`.

## Example common search options

Many tools accept the following optional fields in addition to their main locator:

```json
{
  "severity_threshold": "HIGH",
  "source": ["osv", "github"],
  "exclude_malware": true,
  "package_ecosystem": "pypi",
  "with_data": true,
  "summary_only": false,
  "include_references": true,
  "include_affected_symbols": true,
  "include_remediation": true,
  "include_evidence": true,
  "page": 1,
  "page_size": 25
}
```
