mcp-server-vdb 6.7.0__tar.gz

mcp_server_vdb-6.7.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: mcp-server-vdb
+Version: 6.7.0
+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]==6.7.0
+Requires-Dist: mcp[cli]>=1.22.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`.
+- Richer prompts for package-risk assessment, CVE triage, SBOM summaries, fix prioritization, version-match explanations, and overlay review.
+
+## 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 --download-image
+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 --download-image`
+
+```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.vdb6`, `data.index.vdb6`, and `vdb.meta`. Set this explicitly for Docker volume mounts and local Claude Desktop configurations. |
+| `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/vdbxz-app:v6.7.x` | OCI image URL used by MCP automatic downloads. Override this for internally published app-only artifacts. |
+| `VDB_SQLITE_IMMUTABLE` | unset | Open existing `.vdb6` 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, point `VDB_APP_ONLY_DATABASE_URL` at an app-only extended artifact such as `ghcr.io/appthreat/vdbxz-app-extended:v6.7.x`, use your own mirrored extended image, or pre-populate `VDB_HOME` with a database built using `vdb --cache --include-metadata`.
+
+## 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
+}
+```

mcp_server_vdb-6.7.0/README.md

@@ -0,0 +1,187 @@
+# 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`.
+- Richer prompts for package-risk assessment, CVE triage, SBOM summaries, fix prioritization, version-match explanations, and overlay review.
+
+## 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 --download-image
+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 --download-image`
+
+```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.vdb6`, `data.index.vdb6`, and `vdb.meta`. Set this explicitly for Docker volume mounts and local Claude Desktop configurations. |
+| `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/vdbxz-app:v6.7.x` | OCI image URL used by MCP automatic downloads. Override this for internally published app-only artifacts. |
+| `VDB_SQLITE_IMMUTABLE` | unset | Open existing `.vdb6` 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, point `VDB_APP_ONLY_DATABASE_URL` at an app-only extended artifact such as `ghcr.io/appthreat/vdbxz-app-extended:v6.7.x`, use your own mirrored extended image, or pre-populate `VDB_HOME` with a database built using `vdb --cache --include-metadata`.
+
+## 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
+}
+```

mcp_server_vdb-6.7.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "mcp-server-vdb"
+version = "6.7.0"
+description = "AppThreat Vulnerability Database MCP server"
+authors = [
+    {name = "Team AppThreat", email = "cloud@appthreat.com"},
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: Free Threading :: 1 - Unstable",
+    "Topic :: Security",
+    "Topic :: Utilities",
+]
+
+dependencies = [
+    "appthreat-vulnerability-db[oras]==6.7.0",
+    "mcp[cli]>=1.22.0",
+]
+
+[build-system]
+requires = ["setuptools>=61", "wheel", "build"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+license-files = []
+
+[tool.uv.sources]
+appthreat-vulnerability-db = { path = "../..", editable = true }
+
+[project.optional-dependencies]
+dev = [
+    "black",
+    "bandit",
+    "flake8",
+    "pylint",
+    "pytest",
+    "pytest-cov",
+]
+
+[project.scripts]
+mcp-server-vdb = "mcp_server_vdb:main"
+
+[tool.pytest.ini_options]
+addopts="--showlocals -v --cov-report=term-missing --no-cov-on-fail --cov mcp_server_vdb"
+testpaths = [
+    "test"
+]

mcp_server_vdb-6.7.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_server_vdb-6.7.0/src/mcp_server_vdb/__init__.py

@@ -0,0 +1,12 @@
+from . import server
+import asyncio
+
+from contextlib import suppress
+
+
+def main():
+    with suppress(asyncio.CancelledError, KeyboardInterrupt):
+        asyncio.run(server.run())
+
+
+__all__ = ["main", "server"]

mcp_server_vdb-6.7.0/src/mcp_server_vdb/display.py

@@ -0,0 +1,41 @@
+import base64
+
+from rich.markdown import Markdown
+from rich.table import Table
+
+from vdb.lib.cve_model import CVE
+
+
+def add_table_row(table: Table, res: dict, added_row_keys: dict):
+    # matched_by is the purl or cpe string
+    row_key = f"""{res["matched_by"]}|{res.get("source_data_hash")}"""
+    # Filter duplicate rows from getting printed
+    if added_row_keys.get(row_key):
+        return
+    source_data: CVE = res.get("source_data")
+    descriptions = []
+    cna_container = source_data.root.containers.cna
+    if cna_container and cna_container.descriptions and cna_container.descriptions.root:
+        for adesc in cna_container.descriptions.root:
+            description = (
+                "\n".join(
+                    [
+                        base64.b64decode(sm.value).decode("utf-8")
+                        for sm in adesc.supportingMedia
+                    ]
+                )
+                if adesc.supportingMedia
+                else adesc.value
+            )
+            description = description.replace("\\n", "\n").replace("\\t", "  ")
+            descriptions.append(description)
+    table.add_row(
+        Markdown(
+            f"[{res.get('cve_id')}](cve://{res.get('cve_id')})",
+            justify="left",
+            hyperlinks=True,
+        ),
+        res.get("matched_by"),
+        Markdown("\n".join(descriptions), justify="left", hyperlinks=True),
+    )
+    added_row_keys[row_key] = True