Skip to content
Back to search

npmscan

MarketplaceWorks with Claude CodeGitHub

NPMScan: npm package and vulnerability lookups (search, maintainer/provenance/install-script inspection, license compliance, PR diffs, CI merge gates, SBOMs, OSV.dev + GitHub Security Advisories + NIST NVD/CVE) for Claude Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/salemalem/npmscan-mcp-plugin with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/salemalem/npmscan-mcp-plugin'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/salemalem--npmscan-mcp-plugin/badge.svg)](/listings/salemalem--npmscan-mcp-plugin)

HTML

<a href="/listings/salemalem--npmscan-mcp-plugin"><img src="/api/listings/salemalem--npmscan-mcp-plugin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: add this repo as a marketplace

/plugin marketplace add salemalem/npmscan-mcp-plugin
/plugin install npmscan@npmscan
/reload-plugins

Option 2: point Claude Code at a local checkout

claude --plugin-dir ./npmscan-mcp-plugin

Useful for testing changes before pushing them.

Option 3: skip the plugin, add the MCP server directly

If you only want the tools (no bundled skills), you don't need this repo at all:

claude mcp add --transport http npmscan https://npmscan.com/api/mcp

or in `.mcp.json` / `~/.claude.json`:

{
  "mcpServers": {
    "npmscan": {
      "type": "http",
      "url": "https://npmscan.com/api/mcp"
    }
  }
}

(The `"type": "http"` field is required — Claude Code treats an entry with a `url` but no `type` as misconfigured and skips it.)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 29 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "npmscan",
  3. "owner": {
  4. "name": "BlockHacks.io",
  5. "email": "shyngys@blockhacks.io",
  6. "url": "https://npmscan.com"
  7. },
  8. "description": "NPMScan: npm package and vulnerability lookups (search, maintainer/provenance/install-script inspection, license compliance, PR diffs, CI merge gates, SBOMs, OSV.dev + GitHub Security Advisories + NIST NVD/CVE) for Claude Code.",
  9. "metadata": {
  10. "description": "NPMScan: npm package and vulnerability lookups (search, maintainer/provenance/install-script inspection, license compliance, PR diffs, CI merge gates, SBOMs, OSV.dev + GitHub Security Advisories + NIST NVD/CVE) for Claude Code."
  11. },
  12. "plugins": [
  13. {
  14. "name": "npmscan",
  15. "source": "./",
  16. "description": "Detect malicious, vulnerable, or typosquatted npm packages from a conversation via npmscan.com's free, read-only MCP server.",
  17. "category": "security",
  18. "tags": [
  19. "npm",
  20. "security",
  21. "supply-chain",
  22. "vulnerability",
  23. "dependency-audit",
  24. "provenance",
  25. "license-compliance"
  26. ]
  27. }
  28. ]
  29. }
README.md · README · 459 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # NPMScan plugin for Claude Code
  2. A [Claude Code plugin](https://code.claude.com/docs/en/plugins) that gives
  3. Claude read-only npm package and vulnerability lookups, backed by
  4. [npmscan.com](https://npmscan.com)'s free, unauthenticated MCP server.
  5. NPMScan is also officially listed for both ChatGPT and Claude on
  6. [npmscan.com's MCP page](https://npmscan.com/mcp), so users can verify that
  7. this plugin points at the same public service.
  8. ## Official listings
  9. - **Claude** (Anthropic's official Claude directory):
  10. [claude.ai/customize/skills/…/npmscan](https://claude.ai/customize/skills/id/aa8fcafe-0bcd-41b6-9e07-6c7ebbb71153%40anthropic-plugin-directory)
  11. - **ChatGPT** (install npmscan as an app for one-click setup):
  12. [chatgpt.com/plugins/…/npmscan](https://chatgpt.com/plugins/plugin_asdk_app_6a6a699e6f3481918d5e6034432894f2?q=npm)
  13. - **mcpHQ**: [mcphq.org](https://github.com/mcpHQ/awesome-mcp-servers)
  14. - **TensorBlock MCP Index**: [tensorblock.co/mcp](https://github.com/TensorBlock/awesome-mcp-servers)
  15. - **Awesome Gemini CLI**: [Piebald-AI/awesome-gemini-cli](https://github.com/Piebald-AI/awesome-gemini-cli)
  16. - **Awesome Gemini CLI Extensions**: [Piebald-AI/awesome-gemini-cli-extensions](https://github.com/Piebald-AI/awesome-gemini-cli-extensions)
  17. - **Awesome Codex Plugins**: [hashgraph-online/awesome-codex-plugins](https://github.com/hashgraph-online/awesome-codex-plugins)
  18. - **Setup docs for other clients**: [npmscan.com/mcp](https://npmscan.com/mcp)
  19. Pending:
  20. - **Grok Build** (xAI's official plugin marketplace): submitted in
  21. [xai-org/plugin-marketplace#1506](https://github.com/xai-org/plugin-marketplace/pull/1506),
  22. awaiting xAI review. See [Using it with Grok Build](#using-it-with-grok-build).
  23. - **GitHub Copilot** (Awesome Copilot marketplace): submitted in
  24. [github/awesome-copilot#5142](https://github.com/github/awesome-copilot/issues/5142).
  25. - **Gemini CLI** (extension gallery): indexed automatically from this repo. See
  26. [Using it with Gemini CLI](#using-it-with-gemini-cli).
  27. ## What it adds
  28. - **MCP server** (`npmscan`, `https://npmscan.com/api/mcp`) with
  29. twenty-three tools — see [Tools](#tools) below. Every tool result includes
  30. an `npmscanUrl` linking back to the full write-up on npmscan.com. No API
  31. key or auth required — same public data as the website. The server is
  32. stateless and rate-limited to 30 requests/minute per IP. Every
  33. vulnerability finding carries `isMalware`, so a confirmed-malicious
  34. package is reported as malware to remove, never as an ordinary bug.
  35. - **`/npmscan:dependency-audit` skill** — chains `batch_query_vulnerabilities`
  36. → `get_package`/`get_package_version` → `analyze_transitive_dependencies`
  37. → the maintainer/provenance/license/remediation/alternative tools into one
  38. dependency-audit report, instead of leaving that tool sequencing to Claude
  39. each time. Also handles PR-style before/after diffs via
  40. `diff_dependencies`, raw `npm audit --json` output via `enrich_npm_audit`,
  41. and a bare GitHub repo URL via `audit_github_repository`. Triggers
  42. automatically when you paste a `package.json`/lockfile/SBOM, give a GitHub
  43. repo URL, or ask to check/audit your dependencies, or invoke it directly.
  44. See [`skills/dependency-audit/SKILL.md`](skills/dependency-audit/SKILL.md).
  45. - **`/npmscan:package-trust-check` skill** — a deep, single-package
  46. investigation for "is X safe / was X compromised" questions: a malware
  47. check (including versions npm has since removed for being malicious),
  48. maintainer add/remove history (account-takeover patterns),
  49. publish-provenance cross-checks, and install-script scanning, in one
  50. report. Triggers
  51. automatically on a trust question about one named package; not for
  52. auditing a whole dependency list (that's `dependency-audit`). See
  53. [`skills/package-trust-check/SKILL.md`](skills/package-trust-check/SKILL.md).
  54. - **`/npmscan:new-dependency-evaluation` skill** — for a forward-looking
  55. choice about what to *add*, not what's already installed: comparing 2-5
  56. named candidates ("axios vs got vs node-fetch"), evaluating one candidate
  57. against its real peers, or shortlisting candidates from a described need.
  58. Orchestrates `compare_packages`/`suggest_alternative`/`search_packages`
  59. into a structured side-by-side with a deterministic pick. See
  60. [`skills/new-dependency-evaluation/SKILL.md`](skills/new-dependency-evaluation/SKILL.md).
  61. - **`/npmscan:incident-response` skill** — turns an existing finding, or
  62. just a vague symptom description ("npm install did something weird"),
  63. into concrete `get_remediation_playbook` steps: real incident references,
  64. severity, and prevention tips, not improvised advice. See
  65. [`skills/incident-response/SKILL.md`](skills/incident-response/SKILL.md).
  66. - **`/npmscan:ci-pr-gate` skill** — turns a dependency change (a
  67. before/after snapshot, or one or more named "bump X from A to B"
  68. upgrades) into one deterministic PASS/WARN/FAIL verdict formatted for a
  69. CI check or PR-comment bot, applying a fixed policy on top of
  70. `diff_dependencies`/`simulate_dependency_upgrade` — not a conversational
  71. report (that's `dependency-audit`'s job). See
  72. [`skills/ci-pr-gate/SKILL.md`](skills/ci-pr-gate/SKILL.md).
  73. ## Tools
  74. NPMScan provides twenty-three tools:
  75. | Tool | Description |
  76. |---|---|
  77. | `search_packages` | Search the npm registry by name or keywords. Each result includes weekly/monthly download counts, dependent-package counts, and rank among npmscan's own top-100k-by-downloads snapshot, so you can tell an established package from an abandoned or squatted one that merely matches the query text — flags `possibleTyposquatOf` when a low-popularity result's name is one typo away from a top-5,000 package. |
  78. | `get_package` | Latest version, install scripts (`preinstall`/`install`/`postinstall`/`prepare`), maintainers, license, recent version history, weekly downloads, GitHub stars, TypeScript support, days since last publish, ecosystem-wide download rank, a 3-month download trend, and an `isLatestVersionVulnerable`/`highestSeverity` verdict (with fixed versions and `isMalware` per finding) — plus a rule-based (not model-generated) maintenance/popularity summary and typosquat flag computed from those numbers. |
  79. | `get_package_version` | Metadata for one exact version plus an OSV.dev check scoped to that version — `isVulnerable`/`highestSeverity` as a direct safe/not-safe answer, with each finding's severity, summary, fixed version and `isMalware`. For checking a version pinned in a lockfile. A version npm has removed but OSV still has advisories for (usually one pulled for being malicious) comes back with `versionExists: false` and those findings, not a bare "not found". |
  80. | `get_maintainer_profile` | Packages an npm username currently maintains via npm's own `maintainer:<username>` search index, plus precomputed download/dependent totals across all of them. Lists the most-downloaded `limit` packages (default 50, max 250); totals still cover every package found. A plain info lookup, not a security check — pair it with `check_maintainer_blast_radius` for the actual compromised-account signal. |
  81. | `query_vulnerabilities` | OSV.dev lookup for known vulnerabilities affecting a package, optionally scoped to a version, with `isVulnerable`/`highestSeverity` as a direct verdict and each finding's severity, summary, fixed version and `isMalware`. For npm it also cross-checks the name/version against the registry: a name or version that isn't on npm still returns its OSV data, with `packageExists: false` and an `existenceCheckNote` — so a typo doesn't read as "clean", and a version removed for malware still shows its findings. Accepts `packageName` as an alias for `name`, and other ecosystems via `ecosystem` (e.g. `"PyPI"`). |
  82. | `batch_query_vulnerabilities` | OSV.dev lookup across a whole dependency inventory at once — pass a flat `packages` list, or paste raw `package.json`/lockfile/CycloneDX JSON/SPDX JSON content via `content` and it parses that for you. Chunks large inventories internally, with severity, summary, CVE aliases, fixed version and `isMalware` per finding. Also reports names/versions that aren't on npm (`unresolvedPackages`/`nonexistentVersions` — never read those as clean), per-package `signals` (deprecated, install scripts, popularity, typosquat), and for lockfiles a `source` check that flags a tarball from an unexpected host or one that is a different package than declared (`identityMismatch`). |
  83. | `get_latest_advisories` | Recently published npm advisories from one of three sources (one per call): `type: "reviewed"` (default) is GitHub's curated, mostly CVE-backed set, filterable by severity, vulnerability category, affected package name, or an exact GHSA/CVE ID; `type: "malware"` is GitHub's own malicious-package advisories; `type: "osv"` is OSV.dev's OpenSSF malicious-packages feed (`MAL-` ids). Cursor-paginated. These are feeds of recent advisories, not a package's full history — to check whether a package is or was malware, use `query_vulnerabilities` and its `isMalware` flags. |
  84. | `get_cve` | NIST NVD lookup for one exact CVE ID (authoritative CVSS score/vector, CWEs, references), or a keyword/severity/CWE/date-range search. Enriched with CISA KEV status (actively exploited in the wild?) and FIRST.org EPSS (30-day exploitation probability). Falls back to the raw MITRE CVE record when NVD has no data yet. Not npm-scoped — NVD covers every ecosystem. |
  85. | `analyze_install_script` | Fetches a package's published tarball and statically scans its `preinstall`/`install`/`postinstall`/`prepare` lifecycle scripts — and the files they reference, pulled from the tarball itself — against npmscan's red-flags rubric (`child_process` use, network calls, sensitive-path/env access, obfuscation, untrusted remote binaries, exfil hosts, eval on decoded strings, CI telemetry) plus a typosquat check. Returns a `totalScore` and `riskTier`. A `prepare`-only package scores 0 unless its command does something alarming, since npm never runs a dependency's `prepare` on install. A heuristic static scan, not proof of malice — it doesn't execute code or check maintainer history. |
  86. | `analyze_transitive_dependencies` | Recursively resolves 1-15 direct/root packages' dependency graphs to a configurable depth (default 2, max 3) and batch-checks every resolved package against OSV.dev — surfaces vulnerabilities buried several levels deep that a flat `batch_query_vulnerabilities` call would miss, with `vulnerablePaths` naming which direct dependency pulled in each vulnerable transitive package. A total-node budget caps runaway graphs, reported via `truncated`/`truncationNote` rather than silently returning a partial scan as complete. |
  87. | `check_package_provenance` | Checks a version's npm/Sigstore publish provenance against reality: flags a non-GitHub-hosted builder or an attested source repo that doesn't match `package.json`'s own `repository` field; flags a package missing provenance while its npm-scope/maintainer peers consistently have it (skipped for versions published before npm provenance existed, 2023-04-19); and diffs the published tarball's install scripts/dependencies against the source repository at the attested commit — the pattern of a stolen-npm-token publish that bypasses CI. For a version npm has removed, the error names any OSV advisories for it. Structural only, not a cryptographic re-verification of the Sigstore bundle. |
  88. | `check_maintainer_changes` | Reconstructs a package's maintainer-add/remove history from the npm packument and flags account-takeover patterns — a new maintainer who published shortly after being added, a sudden full maintainer-list replacement, a long-standing maintainer quietly dropped, or a maintainer change not yet tied to any release. Also cross-checks the declared GitHub repository for transfers/archival. |
  89. | `check_maintainer_blast_radius` | Given an npm username, finds the packages that account currently maintains and flags a tight cluster of packages published within a short rolling window of each other — the compromised-account pattern behind incidents like the 2025 chalk/debug ("qix") compromise and the 2026 keyv/cacheable ("Shai-Hulud") worm. Clusters over a year old count for a quarter, as do clusters at least 30 days old whose versions have no malware advisory, and clusters of near-unused packages don't count. A large total package count alone is never the signal. Lists the most-downloaded `limit` packages (default 50), always including every package in a cluster. |
  90. | `get_remediation_playbook` | Maps a finding's `rule` value from `analyze_install_script`/`check_maintainer_changes`/`check_package_provenance` (or an `id` slug guessed from a plain-language description) to a human-authored incident-response playbook — concrete steps, severity, real-incident references, and prevention tips, not just a link. Includes `compromised-publisher` for when your own npm account or tokens were used to publish malware (token revocation, credential rotation, deprecating the bad versions). Pure local lookup, batches up to 10 rules per call. |
  91. | `check_license_compliance` | Given a package list and an optional allow/deny license policy, classifies each declared SPDX license (permissive/weak-copyleft/copyleft/network-copyleft/proprietary/public-domain/unknown), understands simple SPDX expressions (`OR`/`AND`/`WITH`), and reports a compliance verdict per package. With no policy given, applies a default rule flagging only copyleft/network-copyleft/proprietary. Ambiguous expressions are reported as `needsReview`, not silently guessed at. |
  92. | `diff_dependencies` | Compares two raw snapshots of a `package.json`, `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml` — e.g. before/after a PR — and reports added/removed/version-bumped packages. For every added or bumped package: a newly introduced `preinstall`/`install`/`postinstall` script (`installScriptIntroduced`; a new `prepare` is listed but never runs on a registry install), `vulnerabilityDelta` (introduced/fixed/still-vulnerable/still-clean), `sourceIntegrityChanged` (same version, different tarball or hash — `changeType: "source-swap"`), and `identityMismatch` (the tarball is a different package or version than declared, with vulnerabilities checked for the real one). Also diffs the project's own root lifecycle scripts and overrides. Ideal for a CI gate reviewing a dependency-changing PR. |
  93. | `prioritize_remediation` | Given a batch of already-flagged vulnerability findings, ranks them by what to actually fix first, into a `remove-now`/`patch-now`/`patch-soon`/`scheduled`/`monitor` tier per finding. Confirmed malware (a `MAL-` id, or an advisory whose OSV record is a malware advisory — looked up automatically) is `remove-now`; CISA KEV status (active exploitation) is `patch-now`; otherwise FIRST.org EPSS (30-day exploitation probability) leads, with severity as a fallback, and an EPSS of 10% or more is at least `patch-soon`. A fix-order ranking across a backlog, not a merge gate. |
  94. | `simulate_dependency_upgrade` | Classifies a specific version jump (e.g. a suggested `fixedVersion`) as safe/low-risk/review-recommended/breaking-change-likely/unknown/do-not-upgrade by semver bump, a newly-deprecated target, a newly-introduced `preinstall`/`install`/`postinstall` script, a tightened Node engine requirement, and a before/after OSV.dev check reporting `vulnerabilityDelta`. `do-not-upgrade` means the target is known malware, or npm no longer lists it while OSV still has advisories for it. Accepts a single `packageName` (or `name`)/`currentVersion`/`targetVersion`, or a `packages` batch of up to 100 upgrades in one call. Doesn't fetch changelogs or diff source — a fast deterministic pre-check. |
  95. | `suggest_alternative` | Suggests better-maintained replacements for a deprecated, vulnerable, abandoned, or suspicious package by combining maintainer-provided deprecation hints, a hand-checked list of known successors for well-known packages (e.g. `request` → got/undici/ky, `colors` → @colors/colors), and deterministic npm search/category ranking — filtering out typosquats, deprecated, vulnerable and unverifiable candidates, and returning plain-language `whySuggested` notes, or a `nonPackageAlternatives` entry when a language built-in supersedes the package entirely. |
  96. | `compare_packages` | Given 2-5 candidate packages for the same job (e.g. "axios vs got vs node-fetch"), fans the same registry/popularity/maintenance/vulnerability enrichment `get_package` computes out across every candidate in parallel, adds a lightweight install-script risk signal (a `prepare`-only candidate isn't penalized) and an install-size rollup (own + transitive), and returns a structured side-by-side plus a deterministic, reasoned pick — never a deprecated or typosquat-flagged candidate. A name that fails to resolve still appears with `found:false` rather than failing the whole call. |
  97. | `audit_github_repository` | Given a GitHub repo URL, fetches its `package.json`/lockfile from the default branch (auto-detecting monorepos via workspace globs) and checks every lockfile entry for known vulnerabilities, then gives up to 100 packages — vulnerable ones first — the license-compliance, install-script and, for up to 5 elevated-risk packages (one slot per package, not per version), ownership-risk checks, in one call, no copy-pasting file contents required. `coverage` and a summary starting `PARTIAL AUDIT` say when not everything got every check. The most expensive tool in the suite; avoid calling it in a tight loop across many repos. |
  98. | `generate_sbom` | Generates a spec-valid CycloneDX or SPDX SBOM from the same `packages`/`content` inputs `batch_query_vulnerabilities` accepts, with npmscan's own vulnerability and license findings embedded in each format's native fields (CycloneDX's top-level `vulnerabilities[]`, SPDX's `externalRefs[]`). Every finding's VEX state is `in_triage` — an honest "OSV/GHSA match found, not manually assessed," never a stronger claim. |
  99. | `enrich_npm_audit` | Ingests raw `npm audit --json` output directly (npm 7+ or legacy npm 6 format) and ranks it with the same CISA KEV + FIRST.org EPSS + severity scoring as `prioritize_remediation`, resolving each finding's GHSA advisory to a CVE alias first (npm audit JSON almost never carries a CVE id on its own). `yarn audit --json`/`pnpm audit --json` are rejected rather than misparsed — use `batch_query_vulnerabilities` with the manifest/lockfile for those. |
  100. ## Install
  101. ### Option 1: add this repo as a marketplace
  102. ```
  103. /plugin marketplace add salemalem/npmscan-mcp-plugin
  104. /plugin install npmscan@npmscan
  105. /reload-plugins
  106. ```
  107. ### Option 2: point Claude Code at a local checkout
  108. ```
  109. claude --plugin-dir ./npmscan-mcp-plugin
  110. ```
  111. Useful for testing changes before pushing them.
  112. ### Option 3: skip the plugin, add the MCP server directly
  113. If you only want the tools (no bundled skills), you don't need this repo at
  114. all:
  115. ```
  116. claude mcp add --transport http npmscan https://npmscan.com/api/mcp
  117. ```
  118. or in `.mcp.json` / `~/.claude.json`:
  119. ```json
  120. {
  121. "mcpServers": {
  122. "npmscan": {
  123. "type": "http",
  124. "url": "https://npmscan.com/api/mcp"
  125. }
  126. }
  127. }
  128. ```
  129. (The `"type": "http"` field is required — Claude Code treats an entry with a
  130. `url` but no `type` as misconfigured and skips it.)
  131. ## Try it
  132. ```
  133. Does lodash have any known vulnerabilities?
  134. Find npm packages for parsing CSV files
  135. Before I install left-pad, tell me about its maintainers and install scripts.
  136. Is chalk 5.6.1 safe? I heard there was a supply-chain incident.
  137. What changed between these two package-lock.json snapshots?
  138. Should we use axios, got, or node-fetch for our new HTTP client?
  139. Audit https://github.com/expressjs/express for dependency issues.
  140. ```
  141. Or paste a `package.json` and ask "audit my dependencies for vulnerabilities."
  142. ## Repo layout
  143. ```
  144. npmscan-mcp-plugin/
  145. ├── .claude-plugin/
  146. │ ├── plugin.json # plugin manifest
  147. │ └── marketplace.json # lets this repo be added directly as a marketplace
  148. ├── .mcp.json # bundles the npmscan MCP server
  149. ├── README.md
  150. ├── CHANGELOG.md # what changed in each plugin version
  151. ├── LICENSE
  152. ├── .github/plugin/
  153. │ └── plugin.json # GitHub Copilot plugin manifest
  154. ├── gemini-extension.json # Gemini CLI extension manifest
  155. ├── llms-install.md # setup steps for Cline's one-click installer
  156. ├── assets/logo-400.png # 400×400 logo for the Cline marketplace
  157. ├── assets/screenshot-*.png # Codex listing screenshots (npmscan.com pages)
  158. ├── .codex-plugin/
  159. │ └── plugin.json # Codex plugin manifest (ignored by Claude Code)
  160. ├── .agents/plugins/
  161. │ └── marketplace.json # lets Codex add this repo as a marketplace
  162. ├── .codexignore # paths the plugin scanner skips
  163. ├── .plugin-scanner.toml # HOL plugin-scanner config (see Using it with Codex)
  164. ├── SECURITY.md # how to report a security problem
  165. ├── kimi.plugin.json # Kimi plugin manifest (ignored by Claude Code)
  166. ├── icon.png # Kimi plugin icon (dark tile, npmscan.com branding)
  167. ├── locales/ # Kimi interface translations (zh-CN)
  168. │ └── zh-CN.json
  169. ├── outreach/ # directory listings: tracker, per-directory notes, scripts
  170. └── skills/ # shared by both clients; generated, don't edit here (see below)
  171. ├── dependency-audit/
  172. │ ├── SKILL.md
  173. │ └── references/test-prompts.md
  174. ├── package-trust-check/
  175. │ ├── SKILL.md
  176. │ └── references/test-prompts.md
  177. ├── new-dependency-evaluation/
  178. │ ├── SKILL.md
  179. │ └── references/test-prompts.md
  180. ├── incident-response/
  181. │ ├── SKILL.md
  182. │ └── references/test-prompts.md
  183. └── ci-pr-gate/
  184. ├── SKILL.md
  185. └── references/test-prompts.md
  186. ```
  187. ## Validate and test locally
  188. ```bash
  189. claude plugin validate .
  190. claude --plugin-dir .
  191. ```
  192. Then in the session, run `/npmscan:dependency-audit`,
  193. `/npmscan:package-trust-check`, `/npmscan:new-dependency-evaluation`,
  194. `/npmscan:incident-response`, or `/npmscan:ci-pr-gate` (or just paste a
  195. `package.json`/name a package and ask) to exercise each skill, and try the
  196. prompts in each skill's `references/test-prompts.md`.
  197. ## Submitting to a marketplace
  198. NPMScan is already listed in Anthropic's plugin directory (see
  199. [Official listings](#official-listings)). The values used for that submission form
  200. are in [outreach/targets/claude.md](outreach/targets/claude.md); update them there when the plugin
  201. changes.
  202. - **Self-hosted (this repo)**: nothing further to do — anyone can
  203. `/plugin marketplace add` this repo directly, as shown above.
  204. - **`claude-plugins-community`**: submit via
  205. [claude.ai/admin-settings/directory/submissions/plugins/new](https://claude.ai/admin-settings/directory/submissions/plugins/new)
  206. (Team/Enterprise orgs) or
  207. [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)
  208. (individual authors). Run `claude plugin validate .` first — the review
  209. pipeline runs the same check.
  210. - **`claude-plugins-official`**: curated directly by Anthropic; there's no
  211. application form for it.
  212. See Anthropic's [plugin docs](https://code.claude.com/docs/en/plugins) for
  213. the full development and distribution guide.
  214. ## Using it with Kimi
  215. This same repo is also a [Kimi plugin](https://moonshotai.github.io/kimi-code/en/customization/plugins.html):
  216. [`kimi.plugin.json`](kimi.plugin.json) declares the same MCP server and
  217. points at the same `skills/` directory. Claude Code ignores that file, and
  218. Kimi prefers it over `.claude-plugin/plugin.json`, so each client reads its
  219. own manifest and both load the same five skills.
  220. - **Kimi Code CLI**: `/plugins install https://github.com/salemalem/npmscan-mcp-plugin`
  221. (or `/plugins install ./` from a local checkout).
  222. - **Kimi Work**: in the plugin marketplace, click "Custom plugin" and ask
  223. Plugin Builder to import `https://github.com/salemalem/npmscan-mcp-plugin`.
  224. It appears under the **Personal** tab; click **+** to install.
  225. The manifest is prepared for the official Kimi marketplace: full
  226. `zh-CN` locale, `brandColor` (#ef4444, npmscan.com's primary red), a dark
  227. rounded-tile `icon.png` built from the site's dark-mode logo, and
  228. `hostKind: hosted`. Kimi's local validation passed with 0 errors / 0
  229. warnings on v3.0.2 (the last version imported into Kimi; see [outreach/targets/kimi.md](outreach/targets/kimi.md)).
  230. Official-marketplace publication goes through a Kimi review step — see
  231. [outreach/targets/kimi.md](outreach/targets/kimi.md) for the status and the application steps.
  232. Test results and marketplace submission steps: [outreach/targets/kimi.md](outreach/targets/kimi.md).
  233. When editing, keep Kimi-only settings inside `kimi.plugin.json`. Don't add
  234. root-level `commands/`, `agents/`, or `hooks/` directories for Kimi, because
  235. Claude Code auto-loads those too.
  236. ## Using it with Grok Build
  237. Grok Build reads this repo as-is (`.claude-plugin/plugin.json`, `.mcp.json`
  238. and `skills/`), so it needs no Grok-specific manifest.
  239. - **Status**: submitted to xAI's official marketplace in
  240. [xai-org/plugin-marketplace#1506](https://github.com/xai-org/plugin-marketplace/pull/1506)
  241. as a remote source pinned to commit `5cbf977` (v3.1.2). It's waiting for
  242. xAI to approve the CI run and do a code-owner review. The source stays on
  243. this personal-account repo rather than the NPMscan org, so the Claude and
  244. ChatGPT listings don't have to move.
  245. - **After merge**: install with `/marketplace` or
  246. `grok plugin install npmscan` inside Grok Build.
  247. - **Updating**: Grok Build installs the pinned commit only. To ship a new
  248. release, open a PR to `xai-org/plugin-marketplace` that bumps the `sha` of
  249. the `npmscan` entry in `.grok-plugin/marketplace.json`, then run
  250. `python3 scripts/generate-plugin-index.py`, `scripts/validate-catalog.py`
  251. and `scripts/generate-plugin-index.py --check` there. The index script
  252. fetches every plugin in the catalog and takes several minutes.
  253. ## Using it with Gemini CLI
  254. This repo is also a [Gemini CLI extension](https://geminicli.com/docs/extensions/):
  255. [`gemini-extension.json`](gemini-extension.json) declares the same MCP server
  256. (`httpUrl`, streamable HTTP), and Gemini CLI loads the same five skills from
  257. `skills/`.
  258. ```bash
  259. gemini extensions install https://github.com/salemalem/npmscan-mcp-plugin
  260. ```
  261. The install follows `main`, so each push offers installed users an update.
  262. The [extension gallery](https://geminicli.com/extensions/) finds the repo
  263. by its `gemini-cli-extension` GitHub topic and re-crawls it daily; there's
  264. nothing to submit. Check a change with
  265. `gemini extensions validate .` before pushing.
  266. Antigravity CLI users (which replaced Gemini CLI for free and Google AI
  267. Pro/Ultra accounts) can bring the extension over with
  268. `agy plugin import gemini` after installing it in Gemini CLI.
  269. ## Using it with Cline
  270. Cline connects to the hosted server directly; there's nothing to build and
  271. no API key:
  272. ```bash
  273. cline mcp install npmscan --transport http https://npmscan.com/api/mcp --yes
  274. ```
  275. or in `cline_mcp_settings.json`:
  276. ```json
  277. {
  278. "mcpServers": {
  279. "npmscan": {
  280. "type": "streamableHttp",
  281. "url": "https://npmscan.com/api/mcp"
  282. }
  283. }
  284. }
  285. ```
  286. [`llms-install.md`](llms-install.md) has the same steps for Cline's one-click
  287. installer. Cline's marketplace logo is
  288. [`assets/logo-400.png`](assets/logo-400.png).
  289. ## Using it with Factory (Droid)
  290. Droid installs Claude Code plugins as they are: it translates
  291. `.claude-plugin/` and `.mcp.json` into its own layout when it caches the
  292. plugin. Add this repo as a marketplace, then install the plugin:
  293. ```bash
  294. droid plugin marketplace add salemalem/npmscan-mcp-plugin
  295. droid plugin install npmscan@npmscan-mcp-plugin --scope user
  296. ```
  297. The marketplace takes its name from the repo (`npmscan-mcp-plugin`), not
  298. from the `name` in `.claude-plugin/marketplace.json`, so the plugin ID is
  299. `npmscan@npmscan-mcp-plugin`. Check it with `droid mcp list`: `npmscan`
  300. should show as `http connected`, and the five skills come with it.
  301. ## Using it with Codex
  302. This repo is also a [Codex plugin](https://developers.openai.com/codex/plugins/build):
  303. [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json) points at the same
  304. `skills/` and the same [`.mcp.json`](.mcp.json), and
  305. [`.agents/plugins/marketplace.json`](.agents/plugins/marketplace.json) lets
  306. you add the repo as a marketplace:
  307. ```bash
  308. codex plugin marketplace add salemalem/npmscan-mcp-plugin
  309. codex plugin add npmscan@npmscan
  310. ```
  311. Check it with `codex mcp list`: `npmscan` should show as enabled at
  312. `https://npmscan.com/api/mcp`. The other clients ignore `.codex-plugin/` and
  313. `.agents/`.
  314. Before changing the Codex manifest, run the
  315. [HOL plugin-scanner](https://github.com/hashgraph-online/hol-guard) that
  316. [awesome-codex-plugins](https://github.com/hashgraph-online/awesome-codex-plugins)
  317. uses (it needs 80 or more with no critical or high findings):
  318. ```bash
  319. pipx install --force "plugin-scanner==3.57.0"
  320. plugin-scanner scan . --format text
  321. ```
  322. [`.plugin-scanner.toml`](.plugin-scanner.toml) turns off one Kimi rule that
  323. misreads `kimi.plugin.json`
  324. ([hol-guard#6032](https://github.com/hashgraph-online/hol-guard/issues/6032)).
  325. Remove it once that's fixed.
  326. ## Using it with TRAE
  327. TRAE connects to the hosted server directly. Open this link to add it in one
  328. click (TRAE asks you to confirm):
  329. ```
  330. trae://trae.ai-ide/mcp-import?type=http&name=npmscan&config=eyJ1cmwiOiJodHRwczovL25wbXNjYW4uY29tL2FwaS9tY3AifQ%3D%3D
  331. ```
  332. Or go to **Settings > MCP > Add > Create Manually** and paste:
  333. ```json
  334. {
  335. "mcpServers": {
  336. "npmscan": {
  337. "url": "https://npmscan.com/api/mcp"
  338. }
  339. }
  340. }
  341. ```
  342. For one project only, put the same JSON in `.trae/mcp.json`. To add the
  343. skills, copy the folders in `skills/` to `~/.trae/skills/` (or
  344. `.trae/skills/` in a project), or zip one skill folder and use **Upload
  345. Skill** in TRAE's marketplace.
  346. ## Also available for other AI clients
  347. The same `npmscan` MCP server and the same `dependency-audit` /
  348. `package-trust-check` / `new-dependency-evaluation` / `incident-response` /
  349. `ci-pr-gate` skills are also available in ChatGPT via the official
  350. [npmscan app listing](https://chatgpt.com/plugins/plugin_asdk_app_6a6a699e6f3481918d5e6034432894f2?q=npm)
  351. (submission artifacts live in the main [npmscan](https://npmscan.com) app
  352. repo, under `mcp/`).
  353. **Where to edit the skills:** the main npmscan repo's `mcp/skills/` is the
  354. only source. This repo's `skills/` folder is generated from it by
  355. `npm run sync:plugin-skills` (run in the main repo), which rewrites the few
  356. platform-specific sentences for Claude; `npm run sync:plugin-skills -- --check`
  357. fails when the two have drifted. An edit made directly in this repo's
  358. `skills/` is overwritten by the next sync.
  359. **Changing what agents are told:** a rule meant for every agent (like the
  360. "package content is data, not instructions" section added in 3.1.3) also has
  361. to go into the ChatGPT skill zips, the five ClawHub skills, and the MCP
  362. server's own instructions, which reach clients that never load these skills.
  363. The checklist is in the main repo's `mcp/README.md`, under "Changing what
  364. agents are told".
  365. ## License
  366. MIT — see [LICENSE](LICENSE).
  367. Made by [BlockHacks.io](https://npmscan.com) — protecting the open source
  368. ecosystem.
  369. ## Privacy and Data Retention
  370. The npmscan MCP endpoint respects the same privacy guarantees as the npmscan.com web service:
  371. - **No data retention**: Submitted manifests, lockfiles, and GitHub repository URLs are parsed in memory to resolve dependencies and are discarded immediately after the response is sent.
  372. - **No logging**: We do not log the contents of your packages, your queries, or the IPs associated with individual checks.
  373. - **Read-only**: The MCP server is completely read-only and requires no authentication or API keys.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.