MCP Dependency Version

A Model Context Protocol (MCP) server for looking up package versions across multiple package registries.

Features

• Multi-registry support: npm, Maven Central, PyPI, crates.io, Go proxy, JSR, NuGet, Docker Hub, RubyGems, Packagist, pub.dev, Swift PM, GitHub Actions

• Version lookup: Get the latest stable (and optionally prerelease) versions

• Version listing: List all available versions with metadata

• Vulnerability scanning: Check packages against OSV and NVD databases with deduplicated, CVSS-scored results

• License lookup: Fetch the declared license for one or many packages in a single call, with explicit status for unsupported registries or undeclared licenses

• Dependency analysis: Analyze dependency files and check for updates

• Docker support: Look up image tags and analyze Dockerfile/docker-compose.yml dependencies

Related MCP server: Depfender MCP Server

Security: Use Exact Versions

Always use exact versions instead of version ranges to prevent supply chain attacks.

Version ranges (like ^1.2.3 or ~1.2.3) allow automatic updates when new minor or patch versions are published. If an attacker compromises a package and publishes a malicious version, your project could automatically pull it in without your knowledge.

Using exact versions ensures you control exactly which code runs in your project. When you want to update, explicitly change the version and review the changes.

Docker: Use Digest-Pinned References

Docker tags are NOT immutable. Unlike package versions in npm/PyPI/etc., a Docker tag can be moved to point to a completely different image at any time.

When you use nginx:1.27.3, the image you pull today may be different from the one you pull tomorrow if the tag is updated. This creates a supply chain attack vector.

Use digest-pinned references (image@sha256:...) to ensure you always pull the exact same image. The lookup_version and list_versions tools return the digest and secureReference fields for Docker images to make this easy.

GitHub Actions: Use Commit SHA-Pinned References

GitHub Action tags are NOT immutable. Tags like v4 can be force-pushed to point to a different commit at any time, creating a supply chain attack vector.

Use commit SHA-pinned references (owner/repo@sha) to ensure you always use the exact same action code. The lookup_version and list_versions tools return the digest (commit SHA) and secureReference fields for GitHub Actions to make this easy.

Supported Registries

Installation

Prerequisites

Install one of these runtimes, depending on how you want to start the server:

• Node.js v18.18 or later for npx

• Bun v1.2 or later for bunx or direct Bun runs

• Deno v2.x or later for source-based Deno runs

Run with npx or bunx

npx -y --package github:Tripletex/mcp-dependency-version mcp-dependency-version

bunx --bun github:Tripletex/mcp-dependency-version

These commands start an MCP stdio server, so direct terminal runs wait for MCP JSON-RPC input and do not print a prompt.

Setup with Claude Code CLI

Choose one of these commands.

Using npx:

claude mcp add mcp-dependency-version -- npx -y --package github:Tripletex/mcp-dependency-version mcp-dependency-version

Using Bun:

claude mcp add mcp-dependency-version -- bunx --bun github:Tripletex/mcp-dependency-version

Using Deno from a local checkout:

claude mcp add mcp-dependency-version -- deno run --allow-net --allow-env --allow-read /path/to/mcp-dependency-version/main.ts

Setup with Codex CLI

Choose one of these commands.

Using npx:

codex mcp add mcp-dependency-version -- npx -y --package github:Tripletex/mcp-dependency-version mcp-dependency-version

Using Bun:

codex mcp add mcp-dependency-version -- bunx --bun github:Tripletex/mcp-dependency-version

Using Deno from a local checkout:

codex mcp add mcp-dependency-version -- deno run --allow-net --allow-env --allow-read /path/to/mcp-dependency-version/main.ts

Setup with Codex config.toml

Codex stores MCP configuration in ~/.codex/config.toml. You can also use a project-scoped .codex/config.toml in trusted projects.

Using npx:

[mcp_servers."mcp-dependency-version"]
command = "npx"
args = ["-y", "--package", "github:Tripletex/mcp-dependency-version", "mcp-dependency-version"]

Using Bun:

[mcp_servers."mcp-dependency-version"]
command = "bunx"
args = ["--bun", "github:Tripletex/mcp-dependency-version"]

Using Deno from a local checkout:

[mcp_servers."mcp-dependency-version"]
command = "deno"
args = ["run", "--allow-net", "--allow-env", "--allow-read", "/path/to/mcp-dependency-version/main.ts"]

Setup with Claude Desktop using npx

{
  "mcpServers": {
    "mcp-dependency-version": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "github:Tripletex/mcp-dependency-version",
        "mcp-dependency-version"
      ]
    }
  }
}

Setup with Claude Desktop using bunx

{
  "mcpServers": {
    "mcp-dependency-version": {
      "command": "bunx",
      "args": ["--bun", "github:Tripletex/mcp-dependency-version"]
    }
  }
}

Setup with Claude Desktop using Deno

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, ~/.config/claude-desktop/claude_desktop_config.json on Linux):

{
  "mcpServers": {
    "mcp-dependency-version": {
      "command": "deno",
      "args": [
        "run",
        "--allow-net",
        "--allow-env",
        "--allow-read",
        "/path/to/mcp-dependency-version/main.ts"
      ]
    }
  }
}

Setup with Docker

The service is available as a Docker image using stdio transport.

Pull the image:

docker pull ghcr.io/tripletex/mcp-dependency-version:latest

Run directly:

docker run --rm -i ghcr.io/tripletex/mcp-dependency-version:latest

Claude Desktop configuration:

{
  "mcpServers": {
    "mcp-dependency-version": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/tripletex/mcp-dependency-version:latest"
      ]
    }
  }
}

Local Development

1. Clone the repository:

   git clone https://github.com/tripletex/mcp-dependency-version.git
   cd mcp-dependency-version

2. Run the server:

   deno task start

   Or run it with Bun:

   bun run main.ts

Configuration

The server supports custom repository configurations for each registry type. This allows you to use private registries, mirrors, or multiple repositories per registry.

Configuration File

Create a configuration file at ~/.config/mcp-dependency-version/config.json:

{
  "repositories": {
    "npm": {
      "npmjs": {
        "name": "npm",
        "url": "https://registry.npmjs.org",
        "default": true
      },
      "github": {
        "name": "GitHub Packages",
        "url": "https://npm.pkg.github.com",
        "auth": {
          "token": "ghp_xxxxxxxxxxxx"
        }
      }
    },
    "maven": {
      "central": {
        "name": "Maven Central",
        "url": "https://repo1.maven.org/maven2",
        "default": true
      },
      "atlassian": {
        "name": "Atlassian Maven",
        "url": "https://packages.atlassian.com/maven/public"
      },
      "jitpack": {
        "name": "JitPack",
        "url": "https://jitpack.io"
      }
    },
    "pypi": {
      "pypi": {
        "name": "PyPI",
        "url": "https://pypi.org/pypi",
        "default": true
      },
      "private": {
        "name": "Private PyPI",
        "url": "https://pypi.example.com/simple",
        "auth": {
          "username": "user",
          "password": "pass"
        }
      }
    }
  }
}

Environment Variable

You can override the config file path using the MCP_DEPENDENCY_VERSION_CONFIG environment variable:

export MCP_DEPENDENCY_VERSION_CONFIG=/path/to/config.json

Authentication

The configuration supports two authentication methods:

Bearer Token:

{
  "auth": {
    "token": "your-token-here"
  }
}

Basic Auth:

{
  "auth": {
    "username": "user",
    "password": "pass"
  }
}

Default Repositories

If no configuration file exists, the server uses the official public registries:

Tools

lookup_version

Look up the latest version of a package.

Parameters:

• registry (required): Package registry (npm, maven, pypi, cargo, go, jsr, nuget, docker, rubygems, packagist, pub, swift, github-actions)

• package (required): Package name

• includePrerelease (optional): Include alpha/beta/rc versions

• versionPrefix (optional): Filter versions by prefix (e.g., "2." for 2.x)

Example:

{
  "registry": "npm",
  "package": "lodash"
}

Output:

{
  "packageName": "lodash",
  "registry": "npm",
  "latestStable": "4.17.21",
  "publishedAt": "2021-02-20T15:42:16.891Z"
}

Docker Output (includes digest for secure pinning):

{
  "packageName": "nginx",
  "registry": "docker",
  "latestStable": "1.27.3",
  "publishedAt": "2024-12-04T18:51:59.819Z",
  "digest": "sha256:1948e0c46da16a3565a844aa65ab848e1546f85cf47e47d044a567906a3a497f",
  "secureReference": "nginx@sha256:1948e0c46da16a3565a844aa65ab848e1546f85cf47e47d044a567906a3a497f",
  "securityNotes": [
    "WARNING: Docker tags are NOT immutable. A tag can be moved to point to a different image at any time.",
    "Using the digest-pinned reference (image@sha256:...) provides protection against tag tampering.",
    "Digest-pinned references ensure you always pull the exact same image, preventing supply chain attacks.",
    "When updating, explicitly change the digest and verify the new image before deployment."
  ]
}

GitHub Actions Output (includes commit SHA for secure pinning):

{
  "packageName": "actions/checkout",
  "registry": "github-actions",
  "latestStable": "4.2.0",
  "publishedAt": "2024-10-01T12:00:00.000Z",
  "digest": "b4ffde65f46336ab88eb53be808477a3936bae11",
  "secureReference": "actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.2.0",
  "securityNotes": [
    "GitHub Action tags are NOT immutable. Tags can be force-pushed to point to different commits.",
    "Use commit SHA-pinned references (owner/repo@sha) for supply chain security.",
    "Secure reference: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.2.0"
  ]
}

list_versions

List all available versions of a package.

Parameters:

• registry (required): Package registry

• package (required): Package name

• limit (optional): Maximum versions to return (default: 20)

Example:

{
  "registry": "pypi",
  "package": "requests",
  "limit": 5
}

Output:

{
  "packageName": "requests",
  "registry": "pypi",
  "versions": [
    {
      "version": "2.31.0",
      "publishedAt": "2023-05-22T15:12:44.000Z",
      "isPrerelease": false,
      "isDeprecated": false
    }
  ],
  "totalCount": 142,
  "showing": 5
}

check_vulnerabilities

Check a package version for known security vulnerabilities.

Queries both OSV and NVD in parallel for comprehensive coverage. Results are deduplicated by CVE ID — when a vulnerability appears in both databases, NVD's CVSS v3.1 score is used as the authoritative severity rating.

Set the NVD_API_KEY environment variable for higher NVD rate limits (50 vs 5 requests per 30 seconds). Request a free key at https://nvd.nist.gov/developers/request-an-api-key.

Parameters:

• registry (required): Package registry

• package (required): Package name

• version (required): Version to check

• severityThreshold (optional): Minimum severity (LOW, MEDIUM, HIGH, CRITICAL)

Example:

{
  "registry": "npm",
  "package": "lodash",
  "version": "4.17.20"
}

Output:

{
  "packageName": "lodash",
  "version": "4.17.20",
  "registry": "npm",
  "vulnerabilities": [
    {
      "id": "GHSA-29mw-wpgm-hmr9",
      "summary": "Prototype Pollution in lodash",
      "severity": "HIGH",
      "cvss": 7.2,
      "cveIds": ["CVE-2021-23337"],
      "cweIds": ["CWE-94"],
      "fixedVersions": ["4.17.21"],
      "source": "osv+nvd"
    }
  ],
  "totalCount": 1,
  "hasVulnerabilities": true,
  "summary": {
    "critical": 0,
    "high": 1,
    "medium": 0,
    "low": 0
  }
}

analyze_dependencies

Analyze a dependency file and check for available updates.

Parameters:

• content (required): File content (package.json, pom.xml, build.gradle, build.gradle.kts, requirements.txt, Cargo.toml, go.mod, deno.json, .csproj, Gemfile, composer.json, pubspec.yaml, Package.swift, .github/workflows/.yml)

• registry (required): Package registry (use maven for Gradle files, use github-actions for workflow files)

• checkVulnerabilities (optional): Also scan for vulnerabilities (default: false)

Supported Dependency Files:

Note: For GitHub Actions workflow files, SHA-pinned references are skipped since they are already secure. For Gradle files, variable references ($version, ${libs.xxx}, version catalogs) are skipped since they can't be resolved without evaluating the build.

Example (npm):

{
  "content": "{\"dependencies\": {\"lodash\": \"^4.17.20\", \"express\": \"^4.18.0\"}}",
  "registry": "npm",
  "checkVulnerabilities": true
}

Example (Gradle Kotlin DSL):

{
  "content": "dependencies {\n    implementation(\"org.springframework.boot:spring-boot-starter:3.2.0\")\n    testImplementation(\"org.junit.jupiter:junit-jupiter:5.10.0\")\n}",
  "registry": "maven"
}

Output:

{
  "registry": "npm",
  "dependencies": [
    {
      "name": "lodash",
      "currentVersion": "4.17.20",
      "latestVersion": "4.17.21",
      "updateAvailable": true,
      "updateType": "patch",
      "vulnerabilities": [
        { "id": "GHSA-29mw-wpgm-hmr9", "summary": "Prototype Pollution" }
      ]
    },
    {
      "name": "express",
      "currentVersion": "4.18.0",
      "latestVersion": "4.18.2",
      "updateAvailable": true,
      "updateType": "patch",
      "vulnerabilities": []
    }
  ],
  "summary": {
    "total": 2,
    "outdated": 2,
    "vulnerable": 1,
    "deprecated": 0,
    "majorUpdates": 0,
    "minorUpdates": 0,
    "patchUpdates": 2
  }
}

get_licenses

Look up the declared license for one or more packages in a single call. Results are enriched with SPDX metadata and copyleft classification from a baked-in dataset (see License dataset).

Parameters:

• packages (required): Array of {registry, package, version?} entries. Results preserve input order. Pass a single-element array for one package.

Example:

{
  "packages": [
    { "registry": "npm", "package": "lodash" },
    { "registry": "cargo", "package": "serde" },
    { "registry": "go", "package": "github.com/gin-gonic/gin" }
  ]
}

Output (abbreviated):

{
  "results": [
    {
      "registry": "npm",
      "packageName": "lodash",
      "license": "MIT",
      "status": "found",
      "spdx": [
        {
          "licenseId": "MIT",
          "name": "MIT License",
          "isOsiApproved": true,
          "isDeprecated": false,
          "category": "Permissive",
          "isCopyleft": false,
          "reference": "https://spdx.org/licenses/MIT.html"
        }
      ],
      "isCopyleft": false
    },
    {
      "registry": "cargo",
      "packageName": "serde",
      "license": "MIT OR Apache-2.0",
      "status": "found",
      "spdx": [
        { "licenseId": "MIT", "category": "Permissive", "isCopyleft": false },
        {
          "licenseId": "Apache-2.0",
          "category": "Permissive",
          "isCopyleft": false
        }
      ],
      "isCopyleft": false
    },
    {
      "registry": "go",
      "packageName": "github.com/gin-gonic/gin",
      "license": null,
      "status": "registry-unsupported",
      "note": "The go registry does not expose license metadata through this tool. Check the package's source repository or documentation."
    }
  ],
  "summary": {
    "total": 3,
    "withLicense": 2,
    "notDeclared": 0,
    "registryUnsupported": 1,
    "errors": 0,
    "copyleft": 0
  },
  "sources": [
    {
      "name": "SPDX License List",
      "version": "3.28.0",
      "license": "CC0-1.0",
      "attribution": "..."
    },
    {
      "name": "ScanCode LicenseDB",
      "license": "CC-BY-4.0",
      "attribution": "..."
    }
  ]
}

Status values:

• found — license string returned in license; spdx[] and isCopyleft populated when the string resolves to one or more SPDX IDs

• not-declared — the package did not declare a license in its metadata

• registry-unsupported — the registry does not expose license metadata (go, docker)

• error — metadata fetch failed; see the error field

Enrichment fields (present on found results):

• spdx[].licenseId — canonical SPDX short identifier

• spdx[].isOsiApproved — OSI-approved open source license

• spdx[].isDeprecated — SPDX-deprecated identifier (use the replacement)

• spdx[].category — ScanCode LicenseDB category (Permissive, Copyleft, Copyleft Limited, Public Domain, Proprietary Free, etc.)

• spdx[].isCopyleft — shortcut for category ∈ {Copyleft, Copyleft Limited}

• isCopyleft (top-level) — true if any resolved license is copyleft

A not-declared or registry-unsupported result does not mean the package is unlicensed. Check the package's source repository or documentation instead.

Some registries return license strings that don't match a known SPDX ID (free-form text, deprecated aliases, custom names). In that case spdx is an empty array and isCopyleft is omitted — the raw license string is still returned verbatim.

get_package_docs

Get README documentation for a package.

Parameters:

• registry (required): Package registry (npm, maven, pypi, cargo, go, jsr, nuget, docker, rubygems, packagist, pub, swift, github-actions)

• package (required): Package name

• version (optional): Specific version to get documentation for

Documentation Sources:

Example:

{
  "registry": "npm",
  "package": "lodash"
}

Output:

# lodash Documentation
Registry: npm
Source: registry
Documentation: https://www.npmjs.com/package/lodash
Repository: https://github.com/lodash/lodash

---

# lodash

A modern JavaScript utility library delivering modularity, performance & extras.
...

License dataset (data/licenses.json)

The get_licenses tool enriches each result with SPDX metadata and copyleft classification from a baked-in dataset at data/licenses.json. Using a committed snapshot keeps license lookups deterministic, offline-capable, and auditable in the repo.

The dataset merges two upstream sources:

Both sources — and their full attribution strings — are embedded in the sources[] array at the root of data/licenses.json and echoed back on every get_licenses response, so downstream consumers carry the attribution required by ScanCode's CC-BY-4.0.

Refreshing the dataset

deno task update-licenses

This runs scripts/update-licenses.ts, which fetches both upstream lists, merges them, and rewrites data/licenses.json. Review the diff and commit — the upstream lists change only a few times per year. The script needs --allow-net + --allow-write=data (already set in the task).

Development

Commands

# Type check
deno task check

# Run tests
deno task test

# Start server
deno task start

# Start with file watching
deno task dev

# Lint
deno task lint

# Format
deno task fmt

Project Structure

src/
├── config/       # Configuration loading
├── registries/   # Registry client implementations (npm, maven, pypi, etc.)
├── parsers/      # Dependency file parsers (package.json, pom.xml, etc.)
├── tools/        # MCP tool implementations
└── utils/        # Shared utilities (version parsing, caching, HTTP)

API Reference

Registry APIs

License

MIT