NPMScan

Simulate an npm dependency upgrade

simulate_dependency_upgrade

Read-only

Before running npm install, check whether upgrading a package from a current to a target version is safe. Pass packageName + currentVersion + targetVersion (omit target for "latest"), or packages: [...] (1-100) to check many in one call; a name that cannot be resolved comes back with fetchError instead of failing the batch. A natural follow-up to prioritize_remediation: pass its packageName/currentVersion/fixedVersion straight in.

What it checks:

semver jump (major/minor/patch/prerelease; a 0.x minor bump counts as breaking; skipped majors are flagged)
registry signals on the target: deprecated, a newly added preinstall/install/postinstall script (installScriptIntroduced; a new prepare is listed in installScriptKeysIntroduced but never runs on a registry install), a tightened engines.node, prerelease
OSV for both versions: vulnerabilityDelta (introduced/fixed/still-vulnerable/still-clean) and targetVulnerabilities with isMalware — catching a "fix" that does not clear every CVE

Result: one riskTier — safe / low-risk / review-recommended / breaking-change-likely / unknown / do-not-upgrade — with reasons. do-not-upgrade means the target is known malware, or npm no longer lists it while OSV still has advisories for it (how npm removes malicious releases). It does not read changelogs or diff source; it is a fast pre-check, not a substitute for release notes on a major bump.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	No	Alias for `packageName`, matching the other tools
`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
`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
`vulnerabilityCheckNote`	No	Set when the OSV check was incomplete (query failed, or advisories came back id-only with no severity/malware flag) — treat the vulnerability fields as unverified.
`installScriptIntroduced`	No
`requestedCurrentVersion`	No
`installScriptKeysIntroduced`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 11, 2026

addedOutput schema / properties / batchSummary / properties / advisoryDetailFailedCount
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / batchSummary / properties / vulnerabilityCheckNote
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```

changedOutput schema / properties / batchSummary / required

Previous value: -[
-  "totalRequested",
-  "fetchFailedCount",
-  "riskTierCounts",
-  "vulnQueryFailedCount"
-]New value: +[
+  "totalRequested",
+  "fetchFailedCount",
+  "riskTierCounts",
+  "vulnQueryFailedCount",
+  "advisoryDetailFailedCount",
+  "vulnerabilityCheckNote"
+]

addedOutput schema / properties / vulnerabilityCheckNote

Added value: +{
+  "description": "Set when the OSV check was incomplete (query failed, or advisories came back id-only with no severity/malware flag) — treat the vulnerability fields as unverified.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Changed1 schema field changedOct 6, 2026

addedInput schema / properties / name

Added value: +{
+  "description": "Alias for `packageName`, matching the other tools",
+  "maxLength": 214,
+  "minLength": 1,
+  "type": "string"
+}

Changed10 schema fields changedOct 6, 2026

addedOutput schema / properties / batchSummary / properties / riskTierCounts / properties / doNotUpgrade
```
Added value: +{
+  "type": "number"
+}
```

changedOutput schema / properties / batchSummary / properties / riskTierCounts / required

Previous value: -[
-  "safe",
-  "lowRisk",
-  "reviewRecommended",
-  "breakingChangeLikely",
-  "unknown"
-]New value: +[
+  "safe",
+  "lowRisk",
+  "reviewRecommended",
+  "breakingChangeLikely",
+  "unknown",
+  "doNotUpgrade"
+]

addedOutput schema / properties / installScriptKeysIntroduced

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / results / items / properties / installScriptIntroduced / description

Added value: +"A preinstall/install/postinstall script is new in the target (prepare excluded: it never runs on a registry install)."

addedOutput schema / properties / results / items / properties / installScriptKeysIntroduced

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Every lifecycle key new in the target, prepare included."
+}

changedOutput schema / properties / results / items / properties / riskTier / enum

Previous value: -[
-  "safe",
-  "low-risk",
-  "review-recommended",
-  "breaking-change-likely",
-  "unknown"
-]New value: +[
+  "safe",
+  "low-risk",
+  "review-recommended",
+  "breaking-change-likely",
+  "unknown",
+  "do-not-upgrade"
+]

changedOutput schema / properties / results / items / required

Previous 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",
-  "fetchError"
-]New value: +[
+  "packageName",
+  "npmscanUrl",
+  "requestedCurrentVersion",
+  "requestedTargetVersion",
+  "resolvedCurrentVersion",
+  "resolvedTargetVersion",
+  "currentVersionNote",
+  "targetVersionNote",
+  "direction",
+  "semverBump",
+  "isBreakingBySemver",
+  "majorVersionsSkipped",
+  "zeroMajorNote",
+  "targetIsPrerelease",
+  "targetDeprecated",
+  "installScriptIntroduced",
+  "installScriptKeysIntroduced",
+  "engineChange",
+  "currentIsVulnerable",
+  "targetIsVulnerable",
+  "vulnerabilityDelta",
+  "targetVulnerabilities",
+  "riskTier",
+  "reasons",
+  "verdict",
+  "fetchError"
+]

changedOutput schema / properties / riskTier / enum

Previous value: -[
-  "safe",
-  "low-risk",
-  "review-recommended",
-  "breaking-change-likely",
-  "unknown"
-]New value: +[
+  "safe",
+  "low-risk",
+  "review-recommended",
+  "breaking-change-likely",
+  "unknown",
+  "do-not-upgrade"
+]

addedOutput schema / properties / targetVulnerabilities / items / properties / isMalware

Added value: +{
+  "description": "Confirmed-malicious package (MAL-* id/alias or CWE-506), not an ordinary vulnerability: remove it, do not patch.",
+  "type": "boolean"
+}

changedOutput schema / properties / targetVulnerabilities / items / required

Previous value: -[
-  "id",
-  "summary",
-  "severity",
-  "aliases",
-  "publishedAt",
-  "fixedVersion",
-  "npmscanUrl"
-]New value: +[
+  "id",
+  "summary",
+  "severity",
+  "aliases",
+  "publishedAt",
+  "fixedVersion",
+  "isMalware",
+  "npmscanUrl"
+]

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

A4.8/5.0

Behavior5/5

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

Annotations only declare readOnly/openWorld/non-destructive; the description adds substantial behavior beyond that: batch failure semantics (a name that can't resolve returns `fetchError` rather than failing the batch), the six-value riskTier vocabulary, what triggers `do-not-upgrade` (known malware or npm delisting a release OSV still flags), and nuances like a new `prepare` script never running on a registry install.

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

Conciseness4/5

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

Front-loaded call instructions in the first paragraph, then a clearly headed 'What it checks' list and a result summary — well organized and scannable. It is on the long side and some registry-signal detail borders on documentation rather than selection guidance, keeping it just short of a 5.

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?

Despite a rich output schema, the description still names the single result field (riskTier), its enum values, and the accompanying `reasons`, so an agent knows what to expect. Combined with the check list and failure mode, nothing needed to invoke or interpret the tool is missing.

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

Parameters4/5

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

Schema coverage is 100% and the schema already documents aliases, ranges, dist-tags and mutual exclusivity, so the baseline is 3. The description still adds value the schema lacks: the prioritize_remediation field mapping, the 1-100 batch size rationale, and 'omit target for latest' framing in the entry sentence.

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?

States a specific verb and resource: simulate whether upgrading a package from current to target version is safe before running npm install. It explicitly distinguishes itself from siblings by framing it as a fast pre-check ('not a substitute for release notes on a major bump') and naming prioritize_remediation as the upstream tool it complements.

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?

Gives explicit invocation conditions (before npm install), tells the agent how to feed prioritize_remediation output straight in (packageName/currentVersion/fixedVersion), and documents both the single-item and batch forms with their mutual exclusivity. It also states the boundary of applicability — no changelog or source diffing.

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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?