NPMScan

Query known vulnerabilities for a package

query_vulnerabilities

Read-only

Query OSV.dev for known vulnerabilities affecting an npm package, optionally scoped to one exact version (e.g. to check whether a version pinned in a lockfile is safe). Returns isVulnerable and highestSeverity as a direct answer, plus each finding's severity, a plain-language summary, CVE aliases, and the fixedVersion to upgrade to — not a raw advisory dump. Also cross-checks the name/version against the npm registry: isVulnerable:false on a package that does not actually exist there (typo, wrong ecosystem) would otherwise look identical to a genuinely clean result — see packageExists/existenceCheckNote. A name or version not found on the registry does NOT discard already-fetched OSV data or short-circuit into an error: OSV/GHSA advisory data is independent of the package's current registry listing, and a package/version pulled from npm for being malicious (unpublished/yanked) is exactly the case where real vulnerability data must still be reported, not hidden behind a 404. Use before recommending, installing, or upgrading a package.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	No	npm package name (required; `packageName` is accepted as an alias)
`version`	No	Optional exact version to narrow results, e.g. to check one version pinned in a lockfile. For the npm ecosystem a dist-tag such as "latest" is also accepted and resolved to its exact version first; semver ranges like "^4.17.0" are rejected.
`ecosystem`	No	OSV ecosystem, default "npm"
`packageName`	No	Alias for `name`, matching simulate_dependency_upgrade/prioritize_remediation

Output Schema

TableJSON Schema

Name	Required	Description
`package`	Yes
`version`	Yes
`npmscanUrl`	Yes	npmscan package page; null for a non-npm ecosystem.
`isVulnerable`	Yes
`packageExists`	Yes
`highestSeverity`	Yes
`vulnerabilities`	Yes
`existenceCheckNote`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 6, 2026

changedInput schema / properties / name / description

Previous value: -"npm package name"New value: +"npm package name (required; `packageName` is accepted as an alias)"

addedInput schema / properties / packageName

Added value: +{
+  "description": "Alias for `name`, matching simulate_dependency_upgrade/prioritize_remediation",
+  "maxLength": 214,
+  "minLength": 1,
+  "type": "string"
+}

removedInput schema / required
```
Removed value: -[
-  "name"
-]
```

addedOutput schema / properties / npmscanUrl / description

Added value: +"npmscan package page; null for a non-npm ecosystem."

changedOutput schema / properties / npmscanUrl / type

Previous value: -"string"New value: +[
+  "string",
+  "null"
+]

Changed2 schema fields changedOct 6, 2026

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

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

Changed1 schema field changedOct 2, 2026

changedInput schema / properties / version / description

Previous value: -"Optional exact version to narrow results, e.g. to check one version pinned in a lockfile"New value: +"Optional exact version to narrow results, e.g. to check one version pinned in a lockfile. For the npm ecosystem a dist-tag such as \"latest\" is also accepted and resolved to its exact version first; semver ranges like \"^4.17.0\" are rejected."

Changed3 schema fields changedSep 8, 2026

addedOutput schema / properties / existenceCheckNote

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

addedOutput schema / properties / packageExists

Added value: +{
+  "type": [
+    "boolean",
+    "null"
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "package",
-  "version",
-  "npmscanUrl",
-  "isVulnerable",
-  "highestSeverity",
-  "vulnerabilities"
-]New value: +[
+  "package",
+  "version",
+  "npmscanUrl",
+  "packageExists",
+  "existenceCheckNote",
+  "isVulnerable",
+  "highestSeverity",
+  "vulnerabilities"
+]

Changed16 schema fields changedSep 1, 2026

changedInput schema / properties / version / description

Previous value: -"Optional exact version to narrow results"New value: +"Optional exact version to narrow results, e.g. to check one version pinned in a lockfile"

addedOutput schema / properties / highestSeverity

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

addedOutput schema / properties / isVulnerable
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / version

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

changedOutput schema / properties / vulnerabilities / items / additionalProperties
```
Previous value: -trueNew value: +false
```
removedOutput schema / properties / vulnerabilities / items / properties / details
```
Removed value: -{
-  "type": "string"
-}
```
addedOutput schema / properties / vulnerabilities / items / properties / fixedVersion
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
removedOutput schema / properties / vulnerabilities / items / properties / modified
```
Removed value: -{
-  "type": "string"
-}
```
removedOutput schema / properties / vulnerabilities / items / properties / published
```
Removed value: -{
-  "type": "string"
-}
```
addedOutput schema / properties / vulnerabilities / items / properties / publishedAt
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```

removedOutput schema / properties / vulnerabilities / items / properties / references

Removed value: -{
-  "items": {
-    "additionalProperties": false,
-    "properties": {
-      "type": {
-        "type": "string"
-      },
-      "url": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "url"
-    ],
-    "type": "object"
-  },
-  "type": "array"
-}

removedOutput schema / properties / vulnerabilities / items / properties / severity / items

Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "score": {
-      "type": "string"
-    },
-    "type": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "type",
-    "score"
-  ],
-  "type": "object"
-}

changedOutput schema / properties / vulnerabilities / items / properties / severity / type
```
Previous value: -"array"New value: +[
+  "string",
+  "null"
+]
```
changedOutput schema / properties / vulnerabilities / items / properties / summary / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / vulnerabilities / items / required

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

changedOutput schema / required

Previous value: -[
-  "package",
-  "npmscanUrl",
-  "vulnerabilities"
-]New value: +[
+  "package",
+  "version",
+  "npmscanUrl",
+  "isVulnerable",
+  "highestSeverity",
+  "vulnerabilities"
+]

Changed1 schema field changedSep 1, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "npmscanUrl": {
+      "type": "string"
+    },
+    "package": {
+      "type": "string"
+    },
+    "vulnerabilities": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "aliases": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "details": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          },
+          "modified": {
+            "type": "string"
+          },
+          "npmscanUrl": {
+            "type": "string"
+          },
+          "published": {
+            "type": "string"
+          },
+          "references": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "type": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "url"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "severity": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "score": {
+                  "type": "string"
+                },
+                "type": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type",
+                "score"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "summary": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "package",
+    "npmscanUrl",
+    "vulnerabilities"
+  ],
+  "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?

With readOnlyHint/openWorldHint already declaring the safety profile, the description still adds real behavioral context: it enumerates the response fields (isVulnerable, highestSeverity, severity, summary, CVE aliases, fixedVersion), discloses the npm-registry cross-check and the packageExists/existenceCheckNote flag, and explicitly documents the non-obvious non-error behavior when a package is unpublished/yanked. This is richer than the annotations and prevents a plausible misreading of isVulnerable:false.

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

Conciseness3/5

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

The purpose and return shape are front-loaded well, but the middle passage about registry misses is long and restates the same point twice ('does NOT discard already-fetched OSV data' vs. 'data must still be reported, not hidden behind a 404'). It reads as defensive prose rather than tight specification.

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 four-parameter read tool with annotations and an output schema, nothing needed to call it correctly is missing: scope, version semantics, registry cross-check, and the not-found edge case are all covered. Return-value details are summarized rather than required, which is acceptable given the output schema exists.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents name/packageName aliasing, version format rules, and the ecosystem default. The description adds the motivating intent for the version parameter (lockfile safety check) but no format or behavioral detail beyond the schema, so the baseline 3 applies.

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+resource (query OSV.dev for known vulnerabilities) and the exact scope (npm package, optionally one exact version), which cleanly separates it from siblings like batch_query_vulnerabilities and get_cve. The parenthetical about lockfile version checks makes the intended granularity unambiguous.

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?

Explicitly says when to use it: 'Use before recommending, installing, or upgrading a package,' and gives a concrete scenario for the version parameter. It does not name the alternative sibling tools (e.g. batch_query_vulnerabilities for multi-package sweeps, get_cve for a direct CVE lookup), so routing is clear but not fully disambiguated.

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?