convez.ai
MCP ServerSegurançaIntermediário
cyanheads

OSV Advisory MCP Server

cyanheads/osv-advisory-mcp-server

Auditoria de vulnerabilidades em pacotes via OSV.dev em tempo real

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que consulta o banco de dados de vulnerabilidades OSV.dev para identificar falhas de segurança em pacotes específicos. Permite auditoria em lote de dependências, busca por versão e recuperação de registros completos de avisos de segurança.

Instalação

$npx convez-ai cyanheads/osv-advisory-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
v0.5.1
Issues abertas
7
Contribuidores
1

Casos de uso

  • Verificar vulnerabilidades conhecidas em dependências de projetos
  • Auditar listas completas de dependências ou SBOMs para riscos de segurança
  • Integrar análise de vulnerabilidades em pipelines de DevOps/CI-CD
  • Consultar detalhes completos de avisos de segurança por ID de vulnerabilidade

Veredito

Ferramenta sólida e pronta para produção que integra dados de vulnerabilidades do OSV.dev via MCP. Essencial para equipes que precisam automatizar auditoria de segurança em dependências sem sair do contexto Claude/Cursor.

README

A tradução para o português deste README ainda está na fila.

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

Public Hosted Server: https://osv-advisory.caseyjhand.com/mcp


Tools

4 tools for querying the OSV.dev vulnerability database — single package lookups, batch dependency audits, and full advisory fetch:

ToolDescription
osv_query_packageQuery known vulnerabilities for a single package version by name, ecosystem, and version
osv_query_batchBatch vulnerability query for an array of package tuples — one call for a full dependency list or SBOM audit
osv_get_vulnerabilityFetch the full advisory record for a single OSV vulnerability ID
osv_list_ecosystemsReturn the list of supported ecosystem identifier strings

osv_query_package

The primary "is this package version vulnerable?" tool.

  • Accepts name, ecosystem (case-sensitive exact match — use osv_list_ecosystems to validate), and version
  • Returns all matching advisories: OSV IDs, CVE aliases, CVSS severity vectors, derived severity label, first safe versions, affected version ranges (SEMVER/ECOSYSTEM/GIT), and CWE IDs
  • aliases field surfaces CVE IDs for chaining to nist-nvd-mcp-server for CVSS base scores, EPSS exploitation probability, and CISA KEV status
  • No API key required — OSV.dev is fully public and keyless

osv_query_batch

The primary tool for dependency audits, SBOM scanning, and lockfile triage.

  • Accepts an array of {name, ecosystem, version} tuples (1–1000 packages per call)
  • All ecosystems are pre-validated before the API call — a single invalid ecosystem string fails the batch (OSV API behavior)
  • Returns per-package results positionally matching the input, with vulnerable, vulnCount, vulns (including aliases and severityLabel), and fixedVersions
  • Includes aggregate summary: totalPackages, vulnerableCount, cleanCount, errorCount, totalVulns, worstSeverity

osv_get_vulnerability

Fetch the complete advisory record by OSV ID.

  • Accepts any OSV ID prefix: GHSA- (GitHub), PYSEC- (Python), RUSTSEC- (Rust), GO- (Go), DSA-/DLA- (Debian), CVE- (direct CVE fallbacks)
  • Returns: summary, full advisory details text, all CVE aliases, all affected packages and their version ranges, fix versions, CVSS severity vectors, CWE weakness IDs, and references (ADVISORY, FIX, REPORT, etc.)
  • Use after osv_query_package or osv_query_batch returns a vuln ID and you need the full advisory context — remediation guidance, scope of affected packages, or eligibility criteria

osv_list_ecosystems

Return the list of valid ecosystem identifier strings. Ecosystem strings are case-sensitive exact matches — "pypi" is not "PyPI". Call this tool before querying to validate ecosystem strings from lockfiles or user input. The list is static (sourced from the OSV schema spec) and may occasionally lag newly added ecosystems.

Features

Built on @cyanheads/mcp-ts-core:

  • Declarative tool definitions — single file per tool, framework handles registration and validation
  • Unified error handling — handlers throw, framework catches, classifies, and formats
  • Pluggable auth: none, jwt, oauth
  • Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
  • Structured logging with optional OpenTelemetry tracing
  • STDIO and Streamable HTTP transports

OSV-specific:

  • No API key required — OSV.dev is fully public, keyless, and has no published rate limit
  • Parallel single-package queries in osv_query_batch return full records including aliases (CVE IDs) that the upstream batch endpoint omits
  • Ecosystem pre-validation guards against OSV's all-or-nothing batch rejection behavior

Agent-friendly output:

  • aliases (CVE IDs) prominently surfaced on every vuln entry — the primary composition point for chaining to nist-nvd-mcp-server for CVSS base scores, EPSS, and CISA KEV status
  • severityLabel derived from database_specific.severity (GHSA records) or the highest CVSS base score; null rather than fabricated when neither source is available
  • Echo of query parameters (queryMeta) on osv_query_package output so agents can verify the request was applied correctly
  • Batch aggregate summary (worstSeverity, vulnerableCount, cleanCount) for quick triage without reading per-package rows

Getting started

Public Hosted Instance

A public instance is available at https://osv-advisory.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "osv-advisory-mcp-server": {
      "type": "streamable-http",
      "url": "https://osv-advisory.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file. No API key is required — OSV.dev is fully public.

{
  "mcpServers": {
    "osv-advisory-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/osv-advisory-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "osv-advisory-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/osv-advisory-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "osv-advisory-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/osv-advisory-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

  • Bun v1.3.0 or higher (or Node.js v24+).
  • No API key required — OSV.dev is fully public.

Installation

  1. Clone the repository:
git clone https://github.com/cyanheads/osv-advisory-mcp-server.git
  1. Navigate into the directory:
cd osv-advisory-mcp-server
  1. Install dependencies:
bun install
  1. Configure environment:
cp .env.example .env
# edit .env if needed (no required vars)

Configuration

All configuration is validated at startup. No server-specific env vars are required — OSV.dev is keyless and fully public.

VariableDescriptionDefault
OSV_REQUEST_TIMEOUT_MSHTTP request timeout in milliseconds for OSV.dev API calls.10000
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for HTTP server.3010
MCP_HTTP_ENDPOINT_PATHHTTP endpoint path./mcp
MCP_PUBLIC_URLPublic origin override for TLS-terminating reverse-proxy deployments.none
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (RFC 5424).info
LOGS_DIRDirectory for log files (Node.js only).<project-root>/logs
STORAGE_PROVIDER_TYPEStorage backend.in-memory
OTEL_ENABLEDEnable OpenTelemetry instrumentation (spans, metrics, completion logs).false

See .env.example for the full list of optional overrides.

Running the server

Local development

  • Build and run:

    # One-time build
    bun run rebuild
    
    # Run the built server
    bun run start:stdio
    # or
    bun run start:http
    
  • Run checks and tests:

    bun run devcheck   # Lint, format, typecheck, security
    bun run test       # Vitest test suite
    bun run lint:mcp   # Validate MCP definitions against spec
    

Docker

docker build -t osv-advisory-mcp-server .
docker run --rm -p 3010:3010 osv-advisory-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/osv-advisory-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools and inits services.
src/mcp-server/toolsTool definitions (*.tool.ts) — osv_query_package, osv_query_batch, osv_get_vulnerability, osv_list_ecosystems.
src/services/osv-apiOSV.dev REST API service — fetch, retry, response normalization.
tests/Unit and integration tests mirroring src/.

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

  • Handlers throw, framework catches — no try/catch in tool logic
  • Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
  • Register new tools via the barrel in src/mcp-server/tools/definitions/index.ts
  • Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados