Supply Chain Server

English | 简体中文 | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | Dansk | 日本語 | Polski | Русский | Bosanski | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська | বাংলা | Ελληνικά | Tiếng Việt | हिन्दी

Supply chain security intelligence for AI agents.

OSV, GHSA, NVD, EPSS, CISA KEV, npm, PyPI, crates.io, RubyGems, NuGet, Packagist, Go, deps.dev, Scorecard, Libraries.io, ClearlyDefined, Rekor, Repology, typosquatting detection — unified into a single MCP server.
Your AI agent gets full-spectrum supply chain intelligence on demand, not 21 browser tabs and manual correlation.

The Problem • How It's Different • Quick Start • What The AI Can Do • Tools (7 + 90) • Data Sources • Architecture • Changelog • Contributing

The Problem

Supply chain security intelligence is the missing layer in modern software development. Vulnerability databases, package registries, provenance verification, exploit prediction scoring, license compliance, security scorecards, typosquatting detection — the data you need is scattered across dozens of platforms, each with its own API, its own auth, its own rate limits, its own output format. Today you check OSV in one tab, NVD in another, pull up npm advisories, check EPSS scores on FIRST.org, verify Sigstore provenance in yet another tab, look up OpenSSF Scorecard, cross-reference CISA KEV, and then spend an hour manually piecing it all together.

Traditional supply chain security workflow:
  check vulnerabilities            ->  OSV + NVD + GitHub Advisories (3 separate UIs)
  assess exploit likelihood        ->  EPSS scores (separate API)
  check active exploitation        ->  CISA KEV catalog (separate JSON feed)
  verify package provenance        ->  Sigstore/Rekor + npm attestations (multiple CLIs)
  check security practices         ->  OpenSSF Scorecard + Best Practices Badge (2 UIs)
  audit dependencies               ->  deps.dev + Libraries.io (2 more UIs)
  check registry metadata          ->  npm + PyPI + crates.io + Go (4 registries)
  check for typosquatting          ->  manual name comparison (error-prone)
  verify license compliance        ->  ClearlyDefined (another UI)
  check distro packaging           ->  Repology (yet another UI)
  ────────────────────────────────
  Total: 45+ minutes per package audit, most of it switching contexts

supply-chain-mcp-server gives your AI agent 7 composite tools (orchestrating 90 techniques internally) across 21 data sources via the Model Context Protocol. The agent calls a single tool like vuln_scan or package_info, which automatically fans out to the right techniques in parallel, correlates vulnerability data with exploit predictions, verifies provenance, checks security posture, and presents a unified supply chain risk assessment — in a single conversation.

With supply-chain-mcp-server:
  You: "Audit the security posture of the express npm package"

  Agent: -> vuln_scan(mode:"package", ecosystem:"npm", name:"express")
            internally runs: osv_query + ghsa_package + epss_batch + kev_lookup
         -> package_info(ecosystem:"npm", name:"express", version:"4.21.2")
            internally runs: npm_package + npm_downloads + npm_maintainers + npm_scripts + npm_provenance
         -> quality(mode:"scorecard", owner:"expressjs", repo:"express")
            internally runs: scorecard_repo
         -> "express has a strong security posture. 2 known vulns but
            neither actively exploited (not in KEV). High EPSS on one
            CVE warrants patching priority. Provenance verified via
            Sigstore. OpenSSF Scorecard 8.2/10."

How It's Different

Existing tools give you raw data one source at a time. supply-chain-mcp-server gives your AI agent the ability to reason across vulnerability, provenance, and package intelligence simultaneously.

Quick Start

Option 1: npx (no install)

npx supply-chain-mcp-server

7 composite tools (90 techniques) work immediately. No API keys required for most data sources — 18 of 21 sources are fully free.

Option 2: Clone

git clone https://github.com/badchars/supply-chain-mcp-server.git
cd supply-chain-mcp-server
bun install

Environment variables (optional)

export GITHUB_TOKEN=your-token        # GHSA + Scorecard higher rate limits
export LIBRARIES_API_KEY=your-key     # Required for Libraries.io tools
export NVD_API_KEY=your-key           # 50 req/30s vs 5 req/30s without key

All API keys are optional. Without them, you still get 6 of 7 composite tools fully operational — only Libraries.io (within dep_tree) requires an API key.

Connect to your AI agent

# With npx
claude mcp add supply-chain-mcp-server -- npx supply-chain-mcp-server

# With local clone
claude mcp add supply-chain-mcp-server -- bun run /path/to/supply-chain-mcp-server/src/index.ts

{
  "mcpServers": {
    "supply-chain": {
      "command": "npx",
      "args": ["-y", "supply-chain-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "optional",
        "LIBRARIES_API_KEY": "optional",
        "NVD_API_KEY": "optional"
      }
    }
  }
}

Start querying

You: "Check if [email protected] has any known vulnerabilities and verify its provenance"

That's it. The agent handles vulnerability lookups, EPSS scoring, KEV checks, provenance verification, and more automatically.

What The AI Can Do

Full Package Audit

You: "Do a complete security audit of the lodash npm package"

Agent: -> vuln_scan {mode: "package", ecosystem: "npm", name: "lodash"}
          ↳ osv_query + ghsa_package + epss_batch + kev_lookup (parallel)
       -> package_info {ecosystem: "npm", name: "lodash", version: "4.17.21"}
          ↳ npm_package + npm_downloads + npm_maintainers + npm_scripts + npm_provenance + npm_attestations + npm_audit_bulk (parallel)
       -> quality {mode: "scorecard", owner: "lodash", repo: "lodash"}
          ↳ scorecard_repo
       -> license {mode: "lookup", type: "npm", name: "lodash", version: "4.17.21"}
          ↳ license_lookup
       -> "[email protected] security audit:
          Vulnerabilities: 3 historical (all fixed in 4.17.21),
          including prototype pollution CVE-2020-8203.
          Provenance: No Sigstore attestation (published pre-provenance era).
          OpenSSF Scorecard: 6.1/10 — no branch protection, no fuzzing.
          Dependencies: Zero runtime deps (self-contained).
          License: MIT (ClearlyDefined confirmed).
          Lifecycle scripts: None — clean.
          Recommendation: Safe to use at latest version. Consider
          migrating to lodash-es for tree-shaking."

Vulnerability Triage

You: "Triage CVE-2024-3094 — how urgent is this?"

Agent: -> vuln_scan {mode: "cve", cve_id: "CVE-2024-3094"}
          ↳ nvd_cve + osv_id + ghsa_id + epss_score + kev_lookup (parallel)
       -> "CVE-2024-3094 (xz-utils backdoor):
          CVSS: 10.0 Critical — backdoor in xz-utils 5.6.0/5.6.1
          EPSS: 0.95 (99th percentile) — extremely likely to be exploited
          CISA KEV: YES — actively exploited, deadline March 2024
          Affects: xz-utils/liblzma on Linux (sshd via systemd)
          This is CRITICAL. Immediate action required:
          1. Downgrade xz-utils to 5.4.x or remove 5.6.0/5.6.1
          2. Check all systems for affected versions
          3. This was a sophisticated supply chain attack via
             a compromised maintainer."

Dependency Risk Assessment

You: "Assess the supply chain risk of adding fastapi to our Python project"

Agent: -> package_info {ecosystem: "pypi", name: "fastapi"}
          ↳ pypi_package + pypi_releases + pypi_maintainers (parallel)
       -> vuln_scan {mode: "package", ecosystem: "PyPI", name: "fastapi"}
          ↳ osv_query + ghsa_package + epss + kev (parallel)
       -> dep_tree {mode: "dependencies", ecosystem: "pypi", name: "fastapi", version: "0.115.0"}
          ↳ deps_dependencies + deps_requirements + libraries_deps (parallel)
       -> quality {mode: "full", owner: "tiangolo", repo: "fastapi", repo_url: "https://github.com/tiangolo/fastapi"}
          ↳ scorecard_repo + badge_by_repo (parallel)
       -> security_check {mode: "typosquat", name: "fastapi", ecosystem: "pypi"}
          ↳ typosquat_check
       -> "fastapi supply chain risk assessment:
          Vulnerabilities: 1 low-severity (fixed in latest).
          Dependencies: 5 direct (starlette, pydantic, etc.), 23 transitive.
          OpenSSF Scorecard: 7.4/10 — good CI/CD, signed releases.
          Maintainer: single primary maintainer (tiangolo).
          Typosquatting: 'fast-api' and 'fastapi2' exist — verify
          you're installing the correct package.
          Risk: LOW. Well-maintained, active community, good security
          practices. Single-maintainer risk is mitigated by strong
          automation and community oversight."

Typosquatting Detection

You: "I'm about to install 'reqeusts' from PyPI — is this safe?"

Agent: -> security_check {mode: "typosquat", name: "reqeusts", ecosystem: "pypi"}
          ↳ typosquat_check
       -> security_check {mode: "compare_names", name_a: "reqeusts", name_b: "requests"}
          ↳ typosquat_compare
       -> "WARNING: 'reqeusts' is a likely typosquat of 'requests'.
          Edit distance: 2 (transposed 'ue' -> 'eu')
          Similarity: 87.5%
          The legitimate package is 'requests' (800M+ monthly downloads).
          'reqeusts' has very low downloads and was likely published
          to exploit typos. DO NOT install this package.
          Correct command: pip install requests"

Composite Tools (7 tools, 90 techniques)

The AI agent sees only 7 composite tools (~1K tokens), each orchestrating multiple techniques in parallel internally.

Individual Techniques (90)

CLI Usage

# List 7 composite tools
npx supply-chain-mcp-server --list

# List all 90 individual techniques
npx supply-chain-mcp-server --list-all

# Run composite tools
npx supply-chain-mcp-server --tool vuln_scan '{"mode":"cve","cve_id":"CVE-2024-3094"}'
npx supply-chain-mcp-server --tool vuln_scan '{"mode":"package","ecosystem":"npm","name":"express"}'
npx supply-chain-mcp-server --tool package_info '{"ecosystem":"npm","name":"express","version":"4.21.2"}'
npx supply-chain-mcp-server --tool security_check '{"mode":"typosquat","name":"reqeusts","ecosystem":"pypi"}'
npx supply-chain-mcp-server --tool quality '{"mode":"scorecard","owner":"expressjs","repo":"express"}'
npx supply-chain-mcp-server --tool dep_tree '{"mode":"dependencies","ecosystem":"npm","name":"express","version":"4.21.2"}'

# Individual techniques also work (backward compatible)
npx supply-chain-mcp-server --tool osv_query '{"ecosystem":"npm","name":"express"}'
npx supply-chain-mcp-server --tool epss_score '{"cve_id":"CVE-2024-3094"}'

Data Sources (21)

Architecture

src/
  index.ts                # CLI entrypoint (--help, --list, --list-all, --tool, stdio server)
  composite/              # 7 composite tools (MCP-registered)
    helpers.ts            # callTool(), callToolsParallel(), buildCompositeResponse(), TOOL_REGISTRY
    vuln-scan.ts          # vuln_scan — 24 techniques (5 modes)
    package-info.ts       # package_info — 33 techniques (7 ecosystems)
    dep-tree.ts           # dep_tree — 14 techniques (6 modes)
    security-check.ts     # security_check — 7 techniques (5 modes)
    quality.ts            # quality — 8 techniques (5 modes)
    license.ts            # license — 3 techniques (3 modes)
    meta.ts               # meta — 1 technique
    index.ts              # compositeTools barrel export
  protocol/
    mcp-server.ts         # MCP server setup (stdio transport)
    tools.ts              # Tool registry — imports compositeTools
  types/
    index.ts              # Shared types (ToolDef, ToolContext, ToolResult)
  utils/
    rate-limiter.ts       # Per-provider rate limiter
    cache.ts              # TTL cache for API responses
    http.ts               # Native fetch() wrapper with error handling
    require-key.ts        # API key validation helper
  osv/                    # 5 techniques    govuln/        # 4 techniques
  ghsa/                   # 4 techniques    depsdev/       # 10 techniques
  nvd/                    # 3 techniques    scorecard/     # 2 techniques
  epss/                   # 4 techniques    badge/         # 3 techniques
  kev/                    # 4 techniques    libraries/     # 4 techniques
  npm/                    # 10 techniques   clearlydefined/# 3 techniques
  pypi/                   # 4 techniques    rekor/         # 5 techniques
  crates/                 # 4 techniques    repology/      # 3 techniques
  rubygems/               # 4 techniques    typosquat/     # 2 techniques
  nuget/                  # 4 techniques    meta/          # 1 technique
  packagist/              # 4 techniques
  go/                     # 3 techniques

Design decisions:

• Composite architecture — 7 composite tools registered with MCP, each orchestrating multiple individual techniques. LLM context reduced from ~12K tokens (90 tool definitions) to ~1K tokens (7 composites).
• 22 providers, 1 server — Every data source is an independent module. Composite tools dispatch to the right provider techniques based on mode/ecosystem.
• Per-provider rate limiters — Each data source has its own RateLimiter instance calibrated to that API's limits. No shared bottleneck.
• TTL caching — Vulnerability data (5-30min), package metadata (5-15min), KEV catalog (60min), scorecard data (30min) are cached to avoid redundant API calls during multi-tool workflows.
• Graceful degradation — Missing API keys don't crash the server. Tools return descriptive error messages: "Set LIBRARIES_API_KEY to enable Libraries.io tools."
• 2 dependencies — @modelcontextprotocol/sdk and zod. All HTTP via native fetch(). No external HTTP libraries needed.
• Backward compatible — --tool CLI accepts both composite and individual technique names. --list-all shows all 90 techniques.

Limitations

• Libraries.io tools require a (free) API key from libraries.io
• NVD free tier is limited to 5 requests per 30 seconds (50 with API key)
• GHSA and Scorecard benefit from GITHUB_TOKEN for higher rate limits
• CISA KEV is fetched as a single JSON file (~2MB) and cached for 60 minutes
• Typosquatting detection compares against a curated list of top npm/PyPI packages (not exhaustive)
• Go checksum database (sum.golang.org) may return 404 for very old or vendored-only modules
• Repology API has strict rate limits and may throttle aggressive querying
• ClearlyDefined coverage varies by ecosystem — npm and Maven have best coverage
• macOS / Linux tested (Windows not tested)

Part of the MCP Security Suite

For authorized security testing and assessment only.
Always ensure you have proper authorization before performing supply chain analysis on any target.

MIT License • Built with Bun + TypeScript