NPMScan

Simulate upgrading one package from one version to another, or a whole batch at once

simulate_dependency_upgrade

Read-only

Given a package and a current/target version, tells you whether that specific upgrade is a safe patch/minor bump or a likely-breaking major bump, before you actually run npm install. Natural follow-up to prioritize_remediation: pass its packageName + currentVersion + fixedVersion straight in to check whether the suggested fix is a drop-in patch or something that needs a review pass. Classifies the jump by semver (major/minor/patch/prerelease), treats a minor bump between two pre-1.0 (0.x) versions as breaking-risk per semver's own "the API isn't stable yet" convention, and flags skipping over multiple major versions in one jump (e.g. 2.x -> 5.x) as needing a per-major changelog review rather than just a diff against the final target. Beyond semver, it also checks the registry for real signals the version number alone won't tell you: whether the target version is marked deprecated, whether it introduces a preinstall/install/postinstall/prepare lifecycle script the current version didn't have, whether it tightens its engines.node requirement, and whether it is itself a prerelease. Finally it batch-checks both versions against OSV.dev and reports vulnerabilityDelta (introduced/fixed/still-vulnerable/still-clean) — catching the case where a suggested "fix" version doesn't actually clear every open CVE. Combines all of this into one riskTier (safe/low-risk/review-recommended/breaking-change-likely/unknown) with a reasons list explaining exactly which signals drove it. This does NOT read the package's changelog/release notes or scan the target tarball's source diff for actual breaking API usage — it's a fast, deterministic pre-check, not a substitute for reading the release notes on a flagged major bump. For simulating more than one upgrade at once — e.g. every "patch-now" finding prioritize_remediation just ranked — pass packages: [{packageName, currentVersion, targetVersion?}, ...] (1-100 items) instead of packageName/currentVersion/targetVersion, not both. Registry fetches are deduped/parallelized and all OSV checks for the whole batch run as one call, so this is not the same cost as N single-item calls. A package that can't be resolved at all (typo, unpublished, registry error) shows up as its own results entry with fetchError set instead of failing the whole batch.

Input Schema

TableJSON Schema

Name	Required	Description
`packages`	No	Batch of upgrades to simulate (1-100 items), each mirroring the single-item packageName/currentVersion/targetVersion fields. Use this OR packageName/currentVersion, not both. Natural pairing with prioritize_remediation: pass its ranked findings straight in as one call instead of one simulate_dependency_upgrade call per finding.
`packageName`	No	Exact npm package name, e.g. "lodash" or "@scope/name". Use this (with currentVersion) OR `packages`, not both.
`targetVersion`	No	Version to simulate upgrading to — exact version, range, or dist-tag (e.g. the fixedVersion a prioritize_remediation finding named). Omit to use the registry's "latest" dist-tag. Only applies to the single-item `packageName` form.
`currentVersion`	No	Currently installed version — an exact version (e.g. "4.17.20"), a semver range (e.g. "^4.17.0"), or a dist-tag. Required when `packageName` is used.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`reasons`	No
`results`	No
`verdict`	No
`riskTier`	No
`direction`	No
`npmscanUrl`	No
`semverBump`	No
`packageName`	No
`batchSummary`	No
`engineChange`	No
`zeroMajorNote`	No
`targetDeprecated`	No
`targetVersionNote`	No
`currentVersionNote`	No
`isBreakingBySemver`	No
`targetIsPrerelease`	No
`targetIsVulnerable`	No
`vulnerabilityDelta`	No
`currentIsVulnerable`	No
`majorVersionsSkipped`	No
`resolvedTargetVersion`	No
`targetVulnerabilities`	No
`requestedTargetVersion`	No
`resolvedCurrentVersion`	No
`installScriptIntroduced`	No
`requestedCurrentVersion`	No

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

Changed8 schema fields changedSep 4, 2026

changedInput schema / properties / currentVersion / description

Previous value: -"Currently installed version — an exact version (e.g. \"4.17.20\"), a semver range (e.g. \"^4.17.0\"), or a dist-tag"New value: +"Currently installed version — an exact version (e.g. \"4.17.20\"), a semver range (e.g. \"^4.17.0\"), or a dist-tag. Required when `packageName` is used."

changedInput schema / properties / packageName / description

Previous value: -"Exact npm package name, e.g. \"lodash\" or \"@scope/name\""New value: +"Exact npm package name, e.g. \"lodash\" or \"@scope/name\". Use this (with currentVersion) OR `packages`, not both."

addedInput schema / properties / packages

Added value: +{
+  "description": "Batch of upgrades to simulate (1-100 items), each mirroring the single-item packageName/currentVersion/targetVersion fields. Use this OR packageName/currentVersion, not both. Natural pairing with prioritize_remediation: pass its ranked findings straight in as one call instead of one simulate_dependency_upgrade call per finding.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "currentVersion": {
+        "description": "Currently installed version — an exact version, a semver range, or a dist-tag",
+        "maxLength": 128,
+        "minLength": 1,
+        "type": "string"
+      },
+      "packageName": {
+        "description": "Exact npm package name, e.g. \"lodash\" or \"@scope/name\"",
+        "maxLength": 214,
+        "minLength": 1,
+        "type": "string"
+      },
+      "targetVersion": {
+        "description": "Version to simulate upgrading to — exact version, range, or dist-tag. Omit to use the registry's \"latest\" dist-tag.",
+        "maxLength": 128,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "packageName",
+      "currentVersion"
+    ],
+    "type": "object"
+  },
+  "maxItems": 100,
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / properties / targetVersion / description

Previous value: -"Version to simulate upgrading to — exact version, range, or dist-tag (e.g. the fixedVersion a prioritize_remediation finding named). Omit to use the registry's \"latest\" dist-tag."New value: +"Version to simulate upgrading to — exact version, range, or dist-tag (e.g. the fixedVersion a prioritize_remediation finding named). Omit to use the registry's \"latest\" dist-tag. Only applies to the single-item `packageName` form."

removedInput schema / required

Removed value: -[
-  "packageName",
-  "currentVersion"
-]

addedOutput schema / properties / batchSummary

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "fetchFailedCount": {
+      "type": "number"
+    },
+    "riskTierCounts": {
+      "additionalProperties": false,
+      "properties": {
+        "breakingChangeLikely": {
+          "type": "number"
+        },
+        "lowRisk": {
+          "type": "number"
+        },
+        "reviewRecommended": {
+          "type": "number"
+        },
+        "safe": {
+          "type": "number"
+        },
+        "unknown": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "safe",
+        "lowRisk",
+        "reviewRecommended",
+        "breakingChangeLikely",
+        "unknown"
+      ],
+      "type": "object"
+    },
+    "totalRequested": {
+      "type": "number"
+    },
+    "vulnQueryFailedCount": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "totalRequested",
+    "fetchFailedCount",
+    "riskTierCounts",
+    "vulnQueryFailedCount"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / results

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "currentIsVulnerable": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "currentVersionNote": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "direction": {
+        "enum": [
+          "upgrade",
+          "downgrade",
+          "same",
+          "unresolved"
+        ],
+        "type": "string"
+      },
+      "engineChange": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "after": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "before": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "tightened": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "before",
+              "after",
+              "tightened"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "fetchError": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "installScriptIntroduced": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "isBreakingBySemver": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "majorVersionsSkipped": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "npmscanUrl": {
+        "type": "string"
+      },
+      "packageName": {
+        "type": "string"
+      },
+      "reasons": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "requestedCurrentVersion": {
+        "type": "string"
+      },
+      "requestedTargetVersion": {
+        "type": "string"
+      },
+      "resolvedCurrentVersion": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "resolvedTargetVersion": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "riskTier": {
+        "enum": [
+          "safe",
+          "low-risk",
+          "review-recommended",
+          "breaking-change-likely",
+          "unknown"
+        ],
+        "type": "string"
+      },
+      "semverBump": {
+        "anyOf": [
+          {
+            "enum": [
+              "major",
+              "premajor",
+              "minor",
+              "preminor",
+              "patch",
+              "prepatch",
+              "prerelease"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "targetDeprecated": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "targetIsPrerelease": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "targetIsVulnerable": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "targetVersionNote": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "targetVulnerabilities": {
+        "items": {
+          "$ref": "#/properties/targetVulnerabilities/items"
+        },
+        "type": "array"
+      },
+      "verdict": {
+        "type": "string"
+      },
+      "vulnerabilityDelta": {
+        "anyOf": [
+          {
+            "enum": [
+              "introduced",
+              "fixed",
+              "still-vulnerable",
+              "still-clean",
+              "unknown"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "zeroMajorNote": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "packageName",
+      "npmscanUrl",
+      "requestedCurrentVersion",
+      "requestedTargetVersion",
+      "resolvedCurrentVersion",
+      "resolvedTargetVersion",
+      "currentVersionNote",
+      "targetVersionNote",
+      "direction",
+      "semverBump",
+      "isBreakingBySemver",
+      "majorVersionsSkipped",
+      "zeroMajorNote",
+      "targetIsPrerelease",
+      "targetDeprecated",
+      "installScriptIntroduced",
+      "engineChange",
+      "currentIsVulnerable",
+      "targetIsVulnerable",
+      "vulnerabilityDelta",
+      "targetVulnerabilities",
+      "riskTier",
+      "reasons",
+      "verdict",
+      "fetchError"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

removedOutput schema / required

Removed value: -[
-  "packageName",
-  "npmscanUrl",
-  "requestedCurrentVersion",
-  "requestedTargetVersion",
-  "resolvedCurrentVersion",
-  "resolvedTargetVersion",
-  "currentVersionNote",
-  "targetVersionNote",
-  "direction",
-  "semverBump",
-  "isBreakingBySemver",
-  "majorVersionsSkipped",
-  "zeroMajorNote",
-  "targetIsPrerelease",
-  "targetDeprecated",
-  "installScriptIntroduced",
-  "engineChange",
-  "currentIsVulnerable",
-  "targetIsVulnerable",
-  "vulnerabilityDelta",
-  "targetVulnerabilities",
-  "riskTier",
-  "reasons",
-  "verdict"
-]

AddedSep 3, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so the description's extra behavioral detail is genuinely additive: semver classification rules including pre-1.0 breaking-risk convention, multi-major jump flagging, registry signal checks (deprecated, lifecycle scripts, engines.node, prerelease), OSV.dev vulnerabilityDelta, riskTier output, batch deduplication/parallelization, and per-item fetchError handling. It also explicitly disclaims what it does not do (changelog/source-diff analysis). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but highly structured: purpose first, then follow-up use case, semver classification, registry signals, OSV integration, riskTier output, explicit exclusions, batch instructions, and error handling. Every sentence adds a distinct piece of information; there is no filler or tautology. The front-loaded first sentence alone captures the core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, no required fields, 100% schema coverage, an output schema, and batch mode), the description is remarkably complete. It covers input forms, optional behavior, output fields (riskTier, reasons list, vulnerabilityDelta, fetchError), integration with a sibling tool, cost characteristics of batch calls, and known limitations. Nothing essential is missing for an agent to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description goes far beyond repeating parameter names. It explains that targetVersion is optional and defaults to the registry's 'latest' dist-tag, that packages array items mirror the single-item fields, that the array is 1-100 items, and that prioritize_remediation's fixedVersion can be passed directly. It also clarifies the mutual exclusivity of the single-item and batch forms, which the schema alone does not convey as effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair: 'Given a package and a current/target version, tells you whether that specific upgrade is a safe patch/minor bump or a likely-breaking major bump.' It distinctly differentiates itself from siblings like prioritize_remediation (a ranking pre-check) and get_package (single metadata lookup) by framing itself as a pre-install upgrade risk simulator. The scope is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly positions the tool as the natural follow-up to prioritize_remediation, naming the exact field mapping (packageName/currentVersion/fixedVersion). It provides clear when-not guidance ('not a substitute for reading the release notes on a flagged major bump') and distinguishes single-item vs batch invocation with a hard constraint (use packages OR packageName/currentVersion, not both).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All NPMScan tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0

Disambiguation4/5

Most tools target a distinct part of the supply-chain lifecycle, and the detailed descriptions include explicit cross-references that reduce misselection. The main ambiguity is among the vulnerability-lookup tools—especially get_latest_advisories and get_cve, which both accept CVE IDs, and query_vulnerabilities versus batch_query_vulnerabilities, which differ mainly in input shape.

Naming Consistency5/5

Every tool name uses lowercase snake_case with a leading imperative verb or verb phrase: analyze_, audit_, batch_query_, check_, compare_, diff_, get_, prioritize_, query_, search_, and suggest_. The check_* tools form a consistent sub-family, and there are no camelCase or noun-only strays.

Tool Count4/5

18 tools is on the high side, so the server feels slightly heavy rather than lean. However, the domain is broad enough that each tool occupies a meaningful workflow step—metadata lookup, vulnerability querying, transitive analysis, license/maintainer/provenance checks, repo auditing, diffing, and remediation—so the count is still reasonable for a comprehensive npm security server.

Completeness5/5

The surface covers the full npm supply-chain audit workflow: discovery, exact-version and lockfile vulnerability checks, transitive dependency resolution, install-script deep scans, license compliance, maintainer and provenance history, repo-level audits, dependency diffs, remediation prioritization, and alternative suggestions. There are no obvious dead ends, and the tools consistently point to natural follow-up actions.

Resources

Need Help?