Model Context Protocol (MCP) server (#205)

* Model Context Protocol (MCP) server

Signed-off-by: Prabhu Subramanian <prabhu@appthreat.com>

* Fix tests

Signed-off-by: Prabhu Subramanian <prabhu@appthreat.com>

---------

Signed-off-by: Prabhu Subramanian <prabhu@appthreat.com>

Author: prabhu

.github/workflows/pythonpublish.yml

@@ -2,13 +2,14 @@ name: Upload vdb Python Package
 
 on:
   push:
+    paths-ignore:
+      - '**/README.md'
     tags:
       - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
-
+  workflow_dispatch:
 
 jobs:
   deploy:
-
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -52,3 +53,38 @@ jobs:
             bom.json
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  container:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ghcr.io/appthreat/mcp-server-vdb
+      - name: Build and push Docker images
+        uses: docker/build-push-action@v5
+        with:
+          context: contrib/mcp-server-vdb
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha,scope=mcp-server-vdb
+          cache-to: type=gha,mode=max,scope=mcp-server-vdb

contrib/claude-context.png

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

contrib/claude-permissions.png

@@ -0,0 +1,49 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS uv
+
+# Install the project into `/app`
+WORKDIR /app
+
+# Enable bytecode compilation
+ENV UV_COMPILE_BYTECODE=1
+
+# Copy from the cache instead of linking since it's a mounted volume
+ENV UV_LINK_MODE=copy
+
+# Install the project's dependencies using the lockfile and settings
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project --no-dev --no-editable
+
+# Then, add the rest of the project source code and install it
+# Installing separately from its dependencies allows optimal layer caching
+ADD . /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --no-editable
+
+FROM python:3.12-slim-bookworm
+
+LABEL maintainer="Team AppThreat" \
+      org.opencontainers.image.authors="Team AppThreat <cloud@appthreat.com>" \
+      org.opencontainers.image.source="https://github.com/AppThreat/vulnerability-db" \
+      org.opencontainers.image.url="https://github.com/AppThreat/vulnerability-db" \
+      org.opencontainers.image.version="1.0.0" \
+      org.opencontainers.image.vendor="appthreat" \
+      org.opencontainers.image.licenses="MIT" \
+      org.opencontainers.image.title="vulnerability-db" \
+      org.opencontainers.image.description="MCP server for AppThreat's vulnerability database and package search library." \
+      org.opencontainers.docker.cmd="docker run --rm -e VDB_HOME=/db -v /db:/db -v $(pwd):/app:rw -t ghcr.io/appthreat/mcp-server-vdb"
+
+WORKDIR /app
+
+COPY --from=uv /root/.local /root/.local
+COPY --from=uv --chown=app:app /app/.venv /app/.venv
+
+# This directory must contain the vulnerability database
+# export VDB_HOME=/db
+# vdb --download-image
+mkdir -p /db
+ENV PATH="/app/.venv/bin:$PATH" \
+    VDB_HOME="/db"
+
+ENTRYPOINT ["mcp-server-vdb"]

contrib/latest-malware.png

@@ -0,0 +1,76 @@
+# Introduction
+
+
+
+## Local development
+
+```shell
+git clone https://github.com/AppThreat/vulnerability-db.git
+cd vulnerability-db
+python -m pip install .
+vdb --download-image
+export VDB_HOME=$HOME/vdb
+mkdir -p $VDB_HOME
+uv --directory contrib/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` inside the contrib 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/contrib/mcp-server-vdb",
+                "run",
+                "mcp-server-vdb"
+            ],
+            "env": {
+                "VDB_HOME": "/Users/guest/vdb"
+            }
+        }
+    }
+}
+```
+
+Restart the Claude Desktop application.
+
+### Claude context screen
+
+![Claude context](../claude-context.png)
+
+### Claude permissions on first run
+
+![Claude permissions](../claude-permissions.png)
+
+### Claude results
+
+![Vulnerability description](../vuln-description.png)
+
+### Latest malware
+
+![Latest Malware](../latest-malware.png)
+
+## Configuration for MCP Inspector
+
+- Transport Type: STDIO
+- Command: python
+- Arguments: vdb/server.py
+
+Click "Connect"
+
+![MCP Inspector](./docs/vdb-mcp-inspector.png)
+
+### Testing
+
+1. Click "List Tools". Must see a list of tools such as `search_by_purl_like`, `search_by_any`, and so on.
+2. Select `search_by_purl_like` and enter a purl string such as `pkg:swift/vapor/vapor@4.89.0`.

contrib/mcp-server-vdb/.gitignore

@@ -0,0 +1,35 @@
+[project]
+name = "mcp-server-vdb"
+version = "0.1.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.13",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Security",
+    "Topic :: Utilities",
+]
+
+dependencies = [
+    "appthreat-vulnerability-db[oras]>=6.2.3",
+    "mcp[cli]>=1.2.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project.scripts]
+mcp-server-vdb = "mcp_server_vdb:main"

contrib/mcp-server-vdb/Dockerfile

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

contrib/mcp-server-vdb/README.md

@@ -0,0 +1,37 @@
+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(
+        res.get("cve_id"),
+        res.get("matched_by"),
+        Markdown("\n".join(descriptions), justify="left", hyperlinks=True),
+    )
+    added_row_keys[row_key] = True