osv-advisory-mcp-server

---

概述

OSV.dev 是一个开源漏洞数据库，提供漏洞数据。查询软件包版本或 Git 提交，批量审计依赖项列表或 SBOM，并获取包含 CVSS 严重性、CVE 别名和受影响版本范围的完整安全公告记录。

工具

工具	描述
osv_query_package	按名称／生态系统／版本或 Package URL（PURL）查询软件包版本
osv_query_batch	一次调用审计最多 1000 个软件包版本——完整的依赖项列表或 SBOM
osv_query_commit	查询完整 Git 提交哈希对应的已知漏洞
osv_get_vulnerability	获取单个 OSV 漏洞 ID 对应的完整安全公告记录
osv_list_ecosystems	返回受支持的生态系统标识符字符串列表

功能参考

osv_query_package _工具

• 提供 name、ecosystem（区分大小写且必须完全匹配）和 version，或提供类似 pkg:pypi/[email protected] 的 purl。PURL 必须且只能包含一个版本：可嵌入 URL，也可单独提供。版本必须精确指定，不支持范围
• 每条安全公告都包含 CVE aliases、带有 severitySource 的 severityLabel、所查询软件包的 fixedVersions、affectedRanges 和 cweIds
• truncated: true 表示 OSV 返回的页数超过 OSV_QUERY_MAX_PAGES，后续页面被截断，因此空的 vulns 列表并不代表结果无漏洞；无法识别的生态系统会报错 invalid_ecosystem

---

osv_query_batch _工具

• 每次调用可传入 1–1000 个 {name, ecosystem, version} 元组或 {purl, version?} 条目；两种格式可混用，且 results[i] 与 packages[i] 对应
• 每行包含 vulnerable、vulnCount、vulns、truncated 和 error；发生故障时，错误会写入受影响行的 error，而不会导致整个调用失败
• summary 汇总扫描结果（vulnerableCount、cleanCount、truncatedCount、errorCount、totalVulns、worstSeverity），且截断的行绝不会计为无漏洞。整个扫描的截止时间为 50 秒

---

osv_query_commit _工具

• 一个完整的 commit：SHA-1 为 40 个十六进制字符，SHA-256 为 64 个；大小写均可，拒绝缩写
• 公告保留记录级严重性、别名和 GIT 范围（含仓库 URL 和按顺序排列的事件）。不会推断特定软件包的 fixedVersions
• truncated: true 表示 OSV 还有更多页面；截断且为空的结果不能确认为无漏洞

---

osv_get_vulnerability _工具

• 来自任意 OSV 来源的一个精确公告 ID（GHSA-、PYSEC-、RUSTSEC-、GO-、DSA-、USN-、CVE- 等），按大小写敏感方式匹配
• 完整记录：details、aliases、所有受影响软件包及其范围和修复信息、severityLabel、cweIds 和 references
• 未知 ID 将以 vulnerability_not_found 失败；仅已撤回的公告会设置 withdrawn

---

osv_list_ecosystems _工具

• 无需输入；返回查询工具接受的 ecosystems 字符串，以及包含列表上次对照 OSV.dev 检查日期的 note
• 字符串区分大小写，且必须完全匹配：PyPI 可用，pypi 不可用

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并支持结构化日志记录和可选的 OpenTelemetry 跟踪。

OSV 专属功能：

• 无需 API 密钥 — OSV.dev 是公开服务，无需密钥，且未公布速率限制
• osv_query_batch 通过 OSV 的 /v1/querybatch 查找匹配的公告 ID，然后仅获取每个唯一公告一次，因此批次行包含批次端点未提供的完整记录（包括 aliases）；请求数量受 OSV_BATCH_CONCURRENCY 限制
• osv_list_ecosystems 使用 bun run check:ecosystems 对照实时 OSV 架构和 API 进行检查

便于 Agent 使用的输出：

• 截断结果绝不视为无漏洞 — truncated 标记表示 OSV 分页不完整，且截断的批次行不会计入 cleanCount
• 每条公告中的 aliases（CVE ID）都会指向 nist-nvd-mcp-server，以获取 CVSS 基础分数和 CISA KEV 状态
• 响应上限为 24,000 字节。开始检索时，重复原始输入并设置 page: overflow.page。继续使用相同的 path，并设置 offset: page.nextOffset 和 revision: page.revision，直到 nextOffset 为 null。对每个 entries[].deferred.path，单独以偏移量零且不带 revision 获取；切勿将整个输出的 page 对象复制到输入中
• content[] 中的公告文本会经过转义，无法作为实时 HTML 或链接呈现；structuredContent 会逐字保留所有 OSV 字符串

开始使用

公共托管实例

公共实例位于 https://osv-advisory.caseyjhand.com/mcp — 无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

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

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

{
  "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"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "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"
      }
    }
  }
}

或者使用 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"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

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

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥 — OSV.dev 完全公开。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/osv-advisory-mcp-server.git

2. 进入目录：

cd osv-advisory-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if needed (no required vars)

配置

所有配置均会在启动时进行验证，且每个变量都是可选的。

变量	描述	默认值
OSV_REQUEST_TIMEOUT_MS	OSV.dev API 调用的 HTTP 请求超时时间，单位为毫秒。	10000
OSV_BATCH_CONCURRENCY	osv_query_batch 发起的 OSV.dev 请求的最大并发数。	10
OSV_QUERY_MAX_PAGES	对每个软件包或提交最多跟进的 OSV.dev 结果页数；超过后结果会标记为 truncated。	10
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径。	/mcp
MCP_PUBLIC_URL	用于 TLS 终止反向代理部署的公共源站覆盖值。	无
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果；根据键名进行脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值 16384）以内。自由格式值中的秘密不会被脱敏。	false
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 埋点（跨度、指标、完成日志）。	false

有关所有可选覆盖项，请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

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

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  bun run check:ecosystems  # Compare osv_list_ecosystems with the live OSV schema and API
  

Docker

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

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/osv-advisory-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具并初始化服务。
src/config	使用 Zod 解析并验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）— osv_query_package、osv_query_batch、osv_query_commit、osv_get_vulnerability、osv_list_ecosystems。
src/services/osv-api	OSV.dev REST API 服务 — 获取、重试、响应规范化。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

有关开发指南和架构规则，请参阅 CLAUDE.md/AGENTS.md。简而言之：

• 处理程序抛出异常，框架捕获异常 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.enrich 添加响应上下文，使用 ctx.signal 取消 OSV 请求
• 通过 src/mcp-server/tools/definitions/index.ts 中的汇总导出文件注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。