osv-advisory-mcp-server

---

概要

オープンソースの脆弱性データベース、OSV.dev の脆弱性データを提供します。パッケージのバージョンまたは Git コミットを照会し、依存関係リストや SBOM を一括監査して、CVSS 重大度、CVE エイリアス、影響を受けるバージョン範囲を含む完全なアドバイザリーレコードを取得できます。

ツール

ツール	説明
osv_query_package	名前／エコシステム／バージョン、または Package URL（PURL）でパッケージのバージョンを照会します
osv_query_batch	1 回の呼び出しで最大 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 に必要なバージョンは 1 つだけです。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 を 1 つ指定します。SHA-1 は 40 桁、SHA-256 は 64 桁の 16 進数で指定し、大文字と小文字のどちらも使用できます。省略形は受け付けません
• アドバイザリには、レコード全体の深刻度、エイリアス、リポジトリ URL と順序付きイベントを含む GIT 範囲が保持されます。パッケージ固有の fixedVersions は推定されません
• truncated: true は、OSV のページがまだ残っていることを示します。切り詰められた空の結果は、脆弱性がないと確認されたことを意味しません

---

osv_get_vulnerability _ツール

• 任意の OSV ソースから取得した、正確なアドバイザリ ID を 1 つ指定します（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 は公開されており、API キーは不要で、公開されたレート制限もありません
• osv_query_batch は、OSV の /v1/querybatch を通じて一致するアドバイザリ ID を見つけた後、アドバイザリごとに一度だけ取得します。そのため、バッチエンドポイントでは省略される完全なレコード（aliases を含む）がバッチ行に含まれます。リクエスト数は OSV_BATCH_CONCURRENCY によって制限されます
• osv_list_ecosystems は、bun run check:ecosystems により OSV のライブスキーマと API に照らして確認されます

エージェント向けの出力：

• 切り詰められた結果をクリーンと見なすことはありません。truncated フラグは OSV ページネーションが未完了であることを示し、切り詰められたバッチ行は cleanCount から除外されます
• すべてのアドバイザリの aliases（CVE ID）は nist-nvd-mcp-server に連携し、CVSS 基本スコアと CISA KEV ステータスを取得できます
• 応答は 24,000 バイトに制限されています。取得を開始するには、元の入力を page: overflow.page とともに再度指定します。offset: page.nextOffset と revision: page.revision を指定して同じ path を続行し、nextOffset が null になるまで繰り返します。各 entries[].deferred.path は、リビジョンを指定せず、オフセット 0 から個別に取得します。出力の 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	結果が truncated としてマークされるまでに、パッケージまたはコミットごとに取得する OSV.dev の結果ページの最大数。	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 instrumentation（スパン、メトリクス、完了ログ）を有効にします。	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、キャンセル可能な OSV リクエストには ctx.signal を使用します
• 新しいツールは src/mcp-server/tools/definitions/index.ts のバレル経由で登録します
• 外部 API 呼び出しをラップします：生データを検証 → ドメイン型に正規化 → 出力スキーマを返す。欠落フィールドを捏造しないでください

貢献

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細については LICENSE を参照してください。