NPMScan

Batch query known vulnerabilities

batch_query_vulnerabilities

Read-only

Check a whole npm dependency inventory against OSV.dev in one call: pass packages: [{name, version?}], or raw package.json / package-lock / yarn.lock / pnpm-lock / CycloneDX / SPDX content via content. Large inventories are chunked automatically. Each finding has severity, summary, CVE aliases, fixedVersion and isMalware, so no per-package follow-up is needed.

Before calling anything clean, read:

unresolvedPackages/nonexistentVersions (and each result's registryStatus): a name or version not on npm shows vulnerabilityCount 0 just like a clean package. A version npm removed can still have real OSV findings (often malware).
A packages entry with no version is checked against every historical version; confirm against the version actually in use before calling it vulnerable.
signals (deprecated, hasInstallScripts, popularity/maintenance tiers, possibleTyposquatOf): 0 vulnerabilities can still be deprecated, abandoned or a typosquat. signals is null for git/file/workspace/URL entries, which are not scanned.
source (lockfile input): nonRegistryHost means the tarball comes from an unexpected host; identityMismatch means it is a different package/version than declared (resolvedName/resolvedVersion) and the counts describe the declared one. Treat both as lockfile tampering.
Use uniqueVulnerabilityCount for distinct issues; raw counts can list one CVE twice.
package.json input: projectLifecycleScripts/projectLifecycleScriptRisk are the project's own install scripts; peerDependencies are skipped unless includePeerDependencies: true (see ignoredPeerDependencyNames); declaredSpec marks a version resolved from a range, which can change on the next install.
npm aliases are followed: package.actualName is the real package the data describes.

Input Schema

TableJSON Schema

Name	Required	Description
`content`	No	Raw dependency inventory content: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, CycloneDX JSON, or SPDX JSON. Use this OR `packages`, not both.
`packages`	No	Explicit package list (1-1000 items). Use this OR `content`, not both.
`includeDevDependencies`	No	Ignored when using `packages`; only applies when `content` is a manifest/lockfile format that distinguishes dev dependencies.
`includePeerDependencies`	No	Ignored when using `packages`; only applies when `content` is a package.json. peerDependencies are excluded from scanning by default (see ignoredPeerDependencyNames) since a peer is often intentionally left unresolved by the consumer — set this to also check them.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`results`	Yes
`warnings`	No
`inputFormat`	No
`ignoredCount`	No
`enrichmentNote`	No
`queryFailureCount`	No
`existenceCheckNote`	No
`parsedPackageCount`	No
`unresolvedPackages`	No
`nonexistentVersions`	No
`totalVulnerabilities`	Yes
`projectLifecycleScripts`	No
`ignoredPeerDependencyNames`	No
`projectLifecycleScriptRisk`	No
`totalUniqueVulnerabilities`	Yes
`packagesWithVulnerabilities`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 6, 2026

addedOutput schema / properties / results / items / properties / vulnerabilities / 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 / results / items / properties / vulnerabilities / items / required

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

Changed2 schema fields changedOct 2, 2026

addedOutput schema / properties / results / items / properties / registryStatus

Added value: +{
+  "enum": [
+    "found",
+    "package-not-found",
+    "version-not-found",
+    "unchecked"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / results / items / required

Previous value: -[
-  "package",
-  "npmscanUrl",
-  "scanStatus",
-  "vulnerabilityCount",
-  "advisoryCount",
-  "uniqueVulnerabilityCount",
-  "vulnerabilities",
-  "signals",
-  "source"
-]New value: +[
+  "package",
+  "npmscanUrl",
+  "scanStatus",
+  "registryStatus",
+  "vulnerabilityCount",
+  "advisoryCount",
+  "uniqueVulnerabilityCount",
+  "vulnerabilities",
+  "signals",
+  "source"
+]

Changed1 schema field changedSep 24, 2026

changedOutput schema / properties / results / items / properties / source / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "integrity": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "nonRegistryHost": {
-        "type": [
-          "boolean",
-          "null"
-        ]
-      },
-      "resolvedUrl": {
-        "type": [
-          "string",
-          "null"
-        ]
-      }
-    },
-    "required": [
-      "resolvedUrl",
-      "integrity",
-      "nonRegistryHost"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "identityMismatch": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "integrity": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "nonRegistryHost": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "resolvedName": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "resolvedUrl": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "resolvedVersion": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "resolvedUrl",
+      "integrity",
+      "nonRegistryHost",
+      "identityMismatch",
+      "resolvedName",
+      "resolvedVersion"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed2 schema fields changedSep 24, 2026

addedOutput schema / properties / results / items / properties / source

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "integrity": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "nonRegistryHost": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "resolvedUrl": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "resolvedUrl",
+        "integrity",
+        "nonRegistryHost"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / properties / results / items / required

Previous value: -[
-  "package",
-  "npmscanUrl",
-  "scanStatus",
-  "vulnerabilityCount",
-  "advisoryCount",
-  "uniqueVulnerabilityCount",
-  "vulnerabilities",
-  "signals"
-]New value: +[
+  "package",
+  "npmscanUrl",
+  "scanStatus",
+  "vulnerabilityCount",
+  "advisoryCount",
+  "uniqueVulnerabilityCount",
+  "vulnerabilities",
+  "signals",
+  "source"
+]

Changed7 schema fields changedSep 20, 2026

addedInput schema / properties / includePeerDependencies

Added value: +{
+  "description": "Ignored when using `packages`; only applies when `content` is a package.json. peerDependencies are excluded from scanning by default (see ignoredPeerDependencyNames) since a peer is often intentionally left unresolved by the consumer — set this to also check them.",
+  "type": "boolean"
+}

addedOutput schema / properties / ignoredPeerDependencyNames

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / projectLifecycleScriptRisk

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "hasLifecycleScripts": {
+      "type": "boolean"
+    },
+    "riskTier": {
+      "enum": [
+        "none",
+        "low",
+        "moderate",
+        "high",
+        "critical"
+      ],
+      "type": "string"
+    },
+    "totalScore": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "hasLifecycleScripts",
+    "riskTier",
+    "totalScore"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / results / items / properties / package / properties / actualName
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / package / properties / declaredSpec
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / results / items / properties / scanStatus

Added value: +{
+  "enum": [
+    "scanned",
+    "not-scanned"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / results / items / required

Previous value: -[
-  "package",
-  "npmscanUrl",
-  "vulnerabilityCount",
-  "advisoryCount",
-  "uniqueVulnerabilityCount",
-  "vulnerabilities",
-  "signals"
-]New value: +[
+  "package",
+  "npmscanUrl",
+  "scanStatus",
+  "vulnerabilityCount",
+  "advisoryCount",
+  "uniqueVulnerabilityCount",
+  "vulnerabilities",
+  "signals"
+]

Changed9 schema fields changedSep 17, 2026

addedInput schema / properties / packages / items / properties / version / description

Added value: +"One exact published version, e.g. \"18.2.0\" (not a range/tag like \"^18.2.0\" or \"latest\" — those are resolved against the registry first, at the cost of an extra lookup, rather than rejected)"

addedOutput schema / properties / nonexistentVersions

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / projectLifecycleScripts

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / results / items / properties / advisoryCount
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / results / items / properties / signals

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "deprecated": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "hasInstallScripts": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "maintenanceTier": {
+          "enum": [
+            "active",
+            "aging",
+            "stale",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "popularityTier": {
+          "enum": [
+            "very-high",
+            "high",
+            "moderate",
+            "low",
+            "very-low",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "possibleTyposquatOf": {
+          "anyOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "rank": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "name",
+                "rank"
+              ],
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "deprecated",
+        "hasInstallScripts",
+        "popularityTier",
+        "maintenanceTier",
+        "possibleTyposquatOf"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / results / items / properties / uniqueVulnerabilityCount
```
Added value: +{
+  "type": "number"
+}
```

changedOutput schema / properties / results / items / required

Previous value: -[
-  "package",
-  "npmscanUrl",
-  "vulnerabilityCount",
-  "vulnerabilities"
-]New value: +[
+  "package",
+  "npmscanUrl",
+  "vulnerabilityCount",
+  "advisoryCount",
+  "uniqueVulnerabilityCount",
+  "vulnerabilities",
+  "signals"
+]

addedOutput schema / properties / totalUniqueVulnerabilities
```
Added value: +{
+  "type": "number"
+}
```

changedOutput schema / required

Previous value: -[
-  "results",
-  "totalVulnerabilities",
-  "packagesWithVulnerabilities"
-]New value: +[
+  "results",
+  "totalVulnerabilities",
+  "totalUniqueVulnerabilities",
+  "packagesWithVulnerabilities"
+]

Changed2 schema fields changedSep 8, 2026
- addedOutput schema / properties / existenceCheckNote
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / unresolvedPackages
```
Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
```

Changed3 schema fields changedSep 1, 2026

changedInput schema / properties / content / description

Previous value: -"Optional raw dependency inventory content: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, CycloneDX JSON, or SPDX JSON."New value: +"Raw dependency inventory content: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, CycloneDX JSON, or SPDX JSON. Use this OR `packages`, not both."

changedInput schema / properties / includeDevDependencies / description

Previous value: -"Only applies when `content` is a package manifest/lockfile format that can distinguish dev dependencies. Default false."New value: +"Ignored when using `packages`; only applies when `content` is a manifest/lockfile format that distinguishes dev dependencies."

changedInput schema / properties / packages / description

Previous value: -"Optional explicit package list (1-1000 items). Use this OR `content`, not both."New value: +"Explicit package list (1-1000 items). Use this OR `content`, not both."

Changed10 schema fields changedSep 1, 2026

addedInput schema / properties / content

Added value: +{
+  "description": "Optional raw dependency inventory content: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, CycloneDX JSON, or SPDX JSON.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / includeDevDependencies

Added value: +{
+  "description": "Only applies when `content` is a package manifest/lockfile format that can distinguish dev dependencies. Default false.",
+  "type": "boolean"
+}

changedInput schema / properties / packages / description

Previous value: -"1-100 packages to check"New value: +"Optional explicit package list (1-1000 items). Use this OR `content`, not both."

changedInput schema / properties / packages / maxItems
```
Previous value: -100New value: +1000
```
removedInput schema / required
```
Removed value: -[
-  "packages"
-]
```
addedOutput schema / properties / ignoredCount
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / inputFormat
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / parsedPackageCount
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / queryFailureCount
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / warnings

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed1 schema field changedSep 1, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "enrichmentNote": {
+      "type": "string"
+    },
+    "packagesWithVulnerabilities": {
+      "type": "number"
+    },
+    "results": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "npmscanUrl": {
+            "type": "string"
+          },
+          "package": {
+            "additionalProperties": false,
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "version": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "name"
+            ],
+            "type": "object"
+          },
+          "vulnerabilities": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "aliases": {
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                },
+                "fixedVersion": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "id": {
+                  "type": "string"
+                },
+                "npmscanUrl": {
+                  "type": "string"
+                },
+                "publishedAt": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "severity": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "summary": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              },
+              "required": [
+                "id",
+                "summary",
+                "severity",
+                "aliases",
+                "publishedAt",
+                "fixedVersion",
+                "npmscanUrl"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "vulnerabilityCount": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "package",
+          "npmscanUrl",
+          "vulnerabilityCount",
+          "vulnerabilities"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "totalVulnerabilities": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "results",
+    "totalVulnerabilities",
+    "packagesWithVulnerabilities"
+  ],
+  "type": "object"
+}

First observedAug 1, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Goes well beyond the readOnly/openWorld/non-destructive annotations: automatic chunking, deduplication via uniqueVulnerabilityCount, npm alias resolution, and explicit warnings that 0-counts can mask unresolved packages, nonexistent versions, deprecated/abandoned/typosquat packages, and lockfile tampering (nonRegistryHost, identityMismatch). This is exactly the extra context annotations cannot carry.

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-loads purpose, then a tightly scoped bullet block; each caveat addresses a specific false-positive risk, so most sentences earn their place. Minor redundancy remains, e.g. enumerating finding fields (severity, summary, CVE aliases, fixedVersion, isMalware) that the output schema already documents.

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?

For a high-complexity batch tool with two mutually exclusive input modes and subtle failure modes, the description covers input selection, chunking behavior, and the interpretation pitfalls an agent would otherwise misread as clean results. An output schema exists, so its coverage of return values is a bonus rather than a necessity.

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 already 100%, so the baseline is 3, but the description adds real meaning: an entry with no version is checked against every historical version, ranges/tags cost an extra lookup, and includePeerDependencies surfaces ignoredPeerDependencyNames. It enriches rather than merely restates the schema.

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

Purpose4/5

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

States a concrete verb, resource and scope: 'Check a whole npm dependency inventory against OSV.dev in one call.' The batch framing plus 'no per-package follow-up is needed' implicitly distinguishes it from query_vulnerabilities, but the sibling is never named, so the routing contrast is left to inference.

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

Usage Guidelines4/5

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

Gives clear operational context: use `packages` OR `content` (not both), large inventories are chunked automatically, and peerDependencies are skipped unless opted in. However it never explicitly says when to prefer this over query_vulnerabilities for a single package, and the 'Before calling anything clean' block is output-interpretation guidance rather than selection guidance.

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?