Dependency Upgrade Planner MCP

An Apify-hosted Model Context Protocol server that turns package registry, vulnerability, and release data into NPM upgrade decision support.

Scope

v1 supports NPM packages only. Package names and versions are queried against the public NPM registry and OSV's npm ecosystem. Other ecosystems are intentionally out of scope for this release.

The server is advisory: semver classifications, vulnerability data, release notes, and checklists do not guarantee compatibility. Validate upgrades in the consuming project.

Data sources and resilience

• NPM Registry: https://registry.npmjs.org/{package} for versions, publish times, metadata, and dependency groups.
• OSV: POST https://api.osv.dev/v1/query for vulnerability records.
• GitHub Releases (optional): used only when the NPM repository field safely resolves to an HTTPS GitHub owner/repo URL or github:owner/repo shorthand. Otherwise, release notes fall back to NPM publish-time data.

External-source failures are non-fatal whenever another useful response can be returned. For example, an unavailable OSV response is surfaced as a source error with an empty advisory list, and an unavailable GitHub response falls back to NPM release times. No credentials or secrets are required.

Tools

plan-npm-upgrade

Required inputs: packageName, currentVersion. Optional: targetVersion (defaults to the latest NPM dist-tag when available).

Returns the latest and selected target versions, semver classification, current/target release dates and dependency counts, OSV results for both versions, risk flags, and an ordered upgrade checklist. It explicitly does not guarantee compatibility.

compare-npm-versions

Required inputs: packageName, versions (2–5 unique exact versions).

Returns available package metadata and runtime/development/peer/optional dependency counts for each requested version, plus semver differences between consecutive versions.

check-npm-security

Required input: packageName. Optional: exact version.

Queries OSV and returns vulnerability IDs, summaries, aliases, affected ranges, and references where supplied by OSV.

get-package-release-notes

Required input: packageName. Optional: maxReleases (default 10, maximum 30).

Returns GitHub release data when a repository URL can be safely parsed and the public releases endpoint is available. Otherwise it returns an NPM registry publish-time/version fallback.

Every tool call charges the Apify PPE event tool-call with await Actor.charge({ eventName: 'tool-call' }).

Local development

npm install
npm run build
npm test
apify validate-schema
APIFY_LOCAL_STORAGE_DIR=$PWD/storage APIFY_CONTAINER_PORT=3199 npm run start:dev

The streamable HTTP MCP endpoint is http://localhost:3199/mcp. Verify the tool catalog with:

curl -sS -X POST http://localhost:3199/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Example upgrade request:

curl -sS -X POST http://localhost:3199/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"plan-npm-upgrade","arguments":{"packageName":"axios","currentVersion":"1.6.0"}}}'

Deployment

The Actor uses standby mode and serves MCP at /mcp. Deploy with Apify CLI after authenticating:

$apify push

Connect an MCP client to the deployed Actor's /mcp endpoint with the appropriate Apify authorization header.