Vulnerability Registry MCP Server

A TypeScript MCP server that exposes a legacy, file-based vulnerability registry to MCP-compatible LLM clients. The server parses versioned pipe-delimited files at startup, validates referential integrity, builds in-memory indexes, and exposes focused tools for CVE lookup, search, vendor navigation, and aggregate statistics.

Architecture

Legacy DB files
      ↓
Version-aware parser
      ↓
Validated domain models
      ↓
In-memory registry and indexes
      ↓
MCP tools over stdio

The parser reads FORMAT dynamically, so the implementation does not depend on a fixed column order. Version-specific parsing is selected through a parser registry. Raw parsing and domain mapping are deliberately separated: the parser understands file structure, while mappers validate business meaning such as CVE syntax, CVSS range, status, severity, and dates.

Requirements

• Node.js 20 or newer
• npm

Install and run

npm ci
npm run build
npm start

Development mode:

npm run dev

All logs are written to stderr; stdout remains reserved for MCP stdio traffic.

Configuration

Optional environment variables:

• VENDORS_DB_PATH
• VULNERABILITIES_DB_PATH
• DEFAULT_PAGE_SIZE (default: 20)
• MAX_PAGE_SIZE (default: 100)

Tools

get_vulnerability

Retrieves one vulnerability by exact CVE identifier.

Example: What is the CVSS score and status of CVE-2021-44228?

search_vulnerabilities

Searches and filters by free text, vendor, severity, status, CVSS range, publication dates, sorting, and pagination.

Example: Which open Linux Kernel vulnerabilities have CVSS 7 or higher?

search_vendors

Finds vendors by name, category, or headquarters and includes useful counts.

get_vendor_overview

Returns vendor details, aggregate statistics, and the five most recent vulnerabilities.

get_vulnerability_statistics

Returns counts by status and severity plus CVSS minimum, maximum, and average without returning every matching row.

Example: How many critical vulnerabilities are still open?

Validation policy

Startup fails when data cannot be trusted, including:

• unsupported database version;
• missing metadata or required columns;
• malformed row field counts;
• invalid CVE, CVSS, status, severity, date, or founded year;
• duplicate vendor IDs, vulnerability IDs, or CVE IDs;
• vulnerability references to missing vendors.

This fail-fast policy avoids plausible but incomplete security answers.

Performance

The files are loaded once at startup. Exact lookups and joins use:

• vendorsById;
• vulnerabilitiesByCve;
• vulnerabilitiesByVendorId.

For the expected scale of thousands of records, compound text filtering remains a simple in-memory scan. This is easier to reason about and maintain than introducing a search dependency prematurely. Pagination and deterministic sorting prevent oversized or unstable responses.

affected_versions is intentionally kept as free text. The source format does not define a formal version-range grammar, so the server supports text search but does not claim semantic range evaluation.

Quality checks

npm run typecheck
npm run lint
npm test
npm run build
npm run check

To inspect the MCP server interactively:

npm run inspect

Claude Desktop configuration

Build first, then add an absolute path:

{
  "mcpServers": {
    "vulnerability-registry": {
      "command": "node",
      "args": ["/absolute/path/to/vulnerability-registry-mcp/dist/src/index.js"]
    }
  }
}

Design decisions

• Modular monolith rather than a framework-heavy application.
• No dependency-injection container; dependencies are passed explicitly from the composition root.
• No repository interface until a second persistence implementation exists.
• MCP handlers contain transport concerns only; all querying lives in VulnerabilityRegistry.
• Errors are typed and translated to safe MCP error payloads without leaking stack traces.
• Both text content and machine-readable structuredContent are returned.

With more time

I would add atomic hot reload when source files change, richer full-text indexing, support for additional format versions, audit logging, operational metrics, and a dedicated natural-language agent client. For a remotely hosted deployment, I would add authentication, authorization, rate limiting, and Streamable HTTP transport.

Production-oriented AI agent stack

This repository now includes an optional end-to-end stack:

Open WebUI
    ↓ OpenAI-compatible HTTP (/v1/chat/completions)
TypeScript Agent Service
    ↓ MCP Streamable HTTP
Vulnerability Registry MCP Server
    ↓
Validated in-memory registry loaded from the legacy .db files

The original stdio entry point remains available for local MCP clients. The remote entry point is src/http.ts, and the OpenAI-compatible agent entry point is src/agent/http-server.ts.

Why the Agent Service exists

Open WebUI is the user interface, not the MCP client that contains the application-specific orchestration policy. The Agent Service:

• exposes /v1/models and /v1/chat/completions, which Open WebUI understands;
• connects to the MCP server and discovers its tools dynamically;
• gives those tool schemas to an OpenAI-compatible model provider;
• executes requested MCP tool calls;
• returns the final grounded answer to Open WebUI;
• keeps model-provider credentials out of the browser;
• applies authentication, timeouts, request-size limits and a maximum number of tool rounds.

Important: ChatGPT Plus and API billing

A ChatGPT Plus subscription is separate from OpenAI API usage. To use an OpenAI model through this Agent Service, create an API key and enable API billing separately. The Agent Service is provider-neutral: LLM_BASE_URL, LLM_API_KEY and LLM_MODEL can point to another OpenAI-compatible provider instead.

HTTP MCP entry point

Run the remote MCP server:

npm run build
MCP_API_KEY=local-mcp-key npm run start:http

Endpoints:

• POST /mcp — stateless MCP Streamable HTTP transport
• GET /health — process liveness
• GET /ready — verifies that the registry files can be loaded and validated

Environment variables:

Variable	Default	Purpose
MCP_HTTP_HOST	0.0.0.0	Bind address
MCP_HTTP_PORT	8080	HTTP port
MCP_API_KEY	unset	Optional bearer token required by /mcp

Agent Service

Run it after the HTTP MCP server is available:

LLM_API_KEY=replace-me \
MCP_URL=http://localhost:8080/mcp \
MCP_API_KEY=local-mcp-key \
AGENT_API_KEY=local-agent-key \
npm run start:agent

Main environment variables:

Variable	Default	Purpose
AGENT_PORT	8081	Agent HTTP port
AGENT_API_KEY	unset	Bearer token accepted from Open WebUI
AGENT_MODEL_ID	vulnerability-agent	Model name shown in Open WebUI
MCP_URL	http://localhost:8080/mcp	Remote MCP endpoint
MCP_API_KEY	unset	Token sent to the MCP server
LLM_BASE_URL	https://api.openai.com/v1	OpenAI-compatible provider base URL
LLM_API_KEY	required	Provider API key
LLM_MODEL	gpt-4.1-mini	Provider model used for reasoning/tool calls
MAX_TOOL_ROUNDS	8	Prevents unbounded tool loops
REQUEST_TIMEOUT_MS	60000	Provider request timeout

Docker Compose

Copy the example environment file and replace every placeholder:

cp .env.example .env

On PowerShell:

Copy-Item .env.example .env

Start the full stack:

docker compose up --build

Open WebUI at http://localhost:3000. On first launch, create the admin user. Then open:

Admin Settings → Connections → OpenAI → Add Connection

Configure:

URL:     http://agent:8081/v1
API key: the value of AGENT_API_KEY in .env
Model:   vulnerability-agent

The Docker network resolves the hostname agent from the Open WebUI container. Do not use localhost:8081 in this screen because, inside the Open WebUI container, localhost refers to Open WebUI itself.

Why PostgreSQL is included

PostgreSQL is not needed for the vulnerability registry itself in the current assignment. The legacy files are loaded once, validated and indexed in memory, which is appropriate for the stated scale of thousands of records.

PostgreSQL is included for Open WebUI persistence. It stores application state such as:

• users and authentication records;
• chat history;
• saved settings and model connections;
• permissions and shared UI objects.

For one local demo instance, Open WebUI can use its built-in SQLite database and PostgreSQL may be removed from docker-compose.yml. For a production deployment with multiple workers or replicas, PostgreSQL is the safer choice because SQLite does not support concurrent writes from several application instances and should not be placed on shared network storage.

The Agent Service itself is deliberately stateless. It does not need PostgreSQL merely to call MCP tools. A future version could add agent-owned tables for audit records, feedback, conversation checkpoints, usage accounting or idempotency, but those concerns should be added only when required rather than coupling them to the vulnerability data.

Production notes

• Pin the Open WebUI image to a tested release before deployment; do not use a floating development tag.
• Replace all example secrets and store them in a secret manager in hosted environments.
• Terminate TLS at a reverse proxy or ingress and do not expose plain HTTP publicly.
• Add rate limiting at the gateway/ingress layer.
• The HTTP MCP server is stateless, so replicas can be scaled horizontally without session affinity.
• The current streaming response is OpenAI-compatible but buffered: the Agent completes its tool loop before emitting one SSE content chunk. Token-by-token provider streaming can be added later without changing the Open WebUI contract.