check_package
Catch fake packages and risky installs before npm does.
Zephex is a hosted Model Context Protocol (MCP) server that gives AI coding agents a fast package safety gate through check_package—plus nine other developer tools and one API key—so suggested dependencies are verified against live registries before install.
When to use
- Before npm install, pip install, cargo add, or any agent-suggested dependency.
- When the agent names a package you have not heard of in this project.
- After npm audit mentions a package but you need a quick registry snapshot first.
- When reviewing PRs that add new package names to package.json or lockfiles.
When not to use
- You need to persist project decisions across sessions—use project_memory (separate tool).
- You need to scan every transitive dependency in a lockfile—check_package is one name at a time.
- You already ran check_package on the same name/version seconds ago in the same session.
- You need deep code reading—use read_code.
Use from the terminal (no editor)
Package Power Mode in the terminal — no editor required. Subcommands: check-package (primary), loop-guard (upgrade alias), last (recall). Aliases include safe, pkg, package, about, check. Reads package.json/lockfile in --cwd. Run npx zephex check-package --help locally for the full reference.
Terminal commands
# Aliases: check-package, check, safe, lookup, pkg, package, about (+ typos chek, saef, …) # Safety — before npm install (no project folder needed)npx zephex expressnpx zephex safe lodashnpx zephex check-package stripe --verbose # --task modes (one command)npx zephex check-package next --task upgrade --from-version 14.2.0npx zephex check-package axios --task securitynpx zephex check-package react --task migrate --from-version 18.2.0 # Output tiers: default | --verbose | --full | --json (CLI report)npx zephex express --fullnpx zephex github.com/vercel/next.js # 12 ecosystemsnpx zephex check-package django --ecosystem pypinpx zephex check-package tokio --ecosystem cargo # In your repo + CInpx zephex check-package --from-locknpx zephex check-package --from-lock --strict --json # Recallnpx zephex lastSay it in plain English
npx zephex is react safe to installnpx zephex should i install zodnpx zephex what is the latest next versionnpx zephex who maintains lodashnpx zephex how popular is expressnpx zephex is moment deprecatednpx zephex any security issues with axiosnpx zephex upgrade next from 14.2.0npx zephex "npm install stripe"npx zephex tell me about the zod package
Full local help: npx zephex check-package --help · npx zephex cli-guide packages · npx zephex help terminal. CI: --strict exits 1 on your_version_affected, unpublished, exists=false. security_status=vulnerable alone does NOT fail CI (false-alarm fix).
More: Terminal CLI reference, complete terminal guide — packages. Run npx zephex cli-guide packages or npx zephex help terminal.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| package | string | Yes | Package name. |
| task | enum | No | check (default) | upgrade | security | migrate | debug |
| version | string | No | Installed version; scopes your_version_affected. |
| from_version | string | No | Upgrade-from version (upgrade/migrate/security). |
| ecosystem | string | No | npm, pypi, cargo, gem, go, maven, nuget, packagist, pub, hex, cocoapods, spm. |
| source | string | No | github:owner/repo for manifest version. |
Limits: One package per call (or --from-lock for direct deps only). cross_ecosystem_warning checks PyPI/crates.io when npm 404s—not gem/go/maven. weekly_downloads is npm-only. breaking_changes can be empty for canary monorepos. publisher_anomaly needs two versions. No transitive tree scan. GitHub 60 req/hr without PAT → limited_no_token.
Try it — copy a prompt
Paste into Cursor, Claude Code, Windsurf, VS Code, or any editor with a hosted MCP connection.
Before you call it
- Zephex API key; no local registry CLI required.
- Package name (and optional version or ecosystem).
- Optional source: github:owner/repo to infer installed version from manifests.
Token and request cost
check_package usually costs about 150–400 tokens per call and returns in ~200–500 ms from live registries. Run it on every agent-suggested install—cheaper than debugging a bad dependency later.
Example
MCP tools/call
{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "check_package", "arguments": { "package": "express", "version": "4.18.2", "ecosystem": "npm" } }}Response shape
Response shape
{ "task": "check", "focus": "Fast safety gate — registry exists, slopsquat, deprecation, CVE exposure for your version", "summary": "express · exists · CVEs exist — pass version", "hint": "Call before any install. Pass version or source:github:owner/repo to read the pinned version from package.json on GitHub.", "data": { "package": "express", "exists": true, "deprecated": false, "latest_version": "5.2.1", "behind_by": "minor", "your_version_affected": false, "security_status": "vulnerable", "risk_level": "low", "risk_signals": ["CVEs exist in other versions — pass version to confirm exposure"], "has_postinstall": false, "risk_signals": [] }, "related_tasks": ["security", "upgrade"], "next_calls": ["check_package({ package: \"express\", task: \"security\", ecosystem: \"npm\" })"], "meta": { "ecosystem": "npm", "latency_ms": 312, "data_status": "full", "cache_hit": false }}Which Zephex tool when
| Task | Use this tool | Not this tool |
|---|---|---|
| Name exists before install | check_package | project_memory |
| CVE + migration for upgrade | check_package (task=upgrade) | project_memory |
| Search import sites in repo | find_code | check_package |
| Project stack | get_project_context | check_package |
What it can do in your codebase
- One tool, task parameter — check, upgrade, security, migrate, debug
- Verify exists on npm, PyPI, cargo, gem, Go, Maven, NuGet, Packagist, Pub, Hex, CocoaPods, Swift PM
- Block 0.0.1-security malware placeholders and unpublished npm typosquats
- your_version_affected — version-scoped GHSA; avoids false high risk on “what’s latest?”
- Warn on wrong ecosystem (Python name suggested in a Node repo)
- Show deprecated packages and alternatives (moment → dayjs, date-fns, …)
- Compare behind_by: major, minor, patch, or up-to-date
- Flag has_postinstall and postinstall_newly_added in latest version
- Detect publisher_anomaly (size spike, new maintainer, file count jump)
- risk_level + risk_signals compressed for agents (raw downloads/stars stripped from MCP JSON)
- security_status from GitHub Advisories (critical-first snapshot)
- freshness_warning when published under 24 hours ago
- Terminal CLI: 50+ fields via check-package — maintainers, contributors, weekly downloads, repo health
- Terminal: plain English (`is react safe to install`), last recall, --from-lock batch, --strict CI
Common response fields
Why teams use it
Built for AI supply-chain risk
Stops the agent at “install lodash-utils-secure” when the name is fake or malware—before code is written.
Lean MCP + rich terminal
Editor agents get ~15–22 fields. Terminal `npx zephex check-package` returns a fuller CLI report on the same backend.
Curated reality check
Catches packages npm forgets to mark deprecated (moment, create-react-app, tslint, …).
Fast enough for every suggestion
Designed to run on every new package name in agent chat—not only quarterly audits.
What it looks at vs skips
- Live registry metadata (version, license, description, repo URL)
- npm weekly download stats
- GitHub Advisory snapshot (sorted by severity)
- Version diff vs your installed version
- Cross-ecosystem HEAD check when npm 404s
- Full migration briefs and breaking_changes lists
- Entire lockfile transitive analysis
- Guarantee against every attack vector
Fields agents should read first
| Field | Meaning |
|---|---|
| exists | false if not on registry or malware-removed (0.0.1-security). |
| unpublished | true for npm security-holding / typosquat placeholders. |
| deprecated | npm flag or curated list (moment, create-react-app, …). |
| behind_by | major | minor | patch | up-to-date vs your version. |
| your_version_affected | true | false | null — whether GHSA CVEs hit your installed version. |
| risk_level | low | medium | high — high only when your version is affected or supply-chain red flags. |
| risk_signals | Human-readable reasons (adoption, postinstall, archived repo, …). |
| has_postinstall | Latest version runs install scripts—supply-chain risk signal. |
| postinstall_newly_added | Script appeared only in latest publish. |
| security_status | clean | vulnerable | unknown from GitHub Advisories snapshot. |
| alternatives | Suggested replacements when deprecated. |
| publisher_anomaly | size_spike, file_count_spike, or new_maintainer between versions. |
| cross_ecosystem_warning | npm 404 but package exists on PyPI/crates.io — wrong ecosystem trap. |
| freshness_warning | Published under 24 hours—review before adopting. |
| weekly_downloads | npm last-7-day downloads (null on other ecosystems). |
| maintainer_count | npm maintainers array length. |
| unpacked_size_kb | npm dist.unpackedSize in KB. |
| repo_health | archived, last_commit_days_ago, stars, open_issues from GitHub. |
| data_status | full | limited_no_token — GitHub API depth without server PAT. |
| latency_ms | Round-trip time for the lookup. |
| installed_version_source | user_input | github_manifest | auto | unavailable. |
| new_dependency_added | Deps added in latest version (max 5). |
| published_hours_ago | Hours since latest publish. |
Task modes
| task | What you get |
|---|---|
| check | Default — exists, deprecation, behind_by, your_version_affected, risk_level. |
| upgrade | Advisories, breaking_changes, migration_steps, code_example, release_url. |
| security | CVE-focused advisories with patched_in; version-scoped when version/from_version set. |
| migrate | Same as upgrade for explicit version jumps. |
| debug | Advisories + code_example snippets from releases. |
How it fits your workflow
- check_package task=check — exists, deprecation, quick risk
- check_package task=upgrade — CVEs, breaking changes, migration steps
- read_code — implementation of your wrapper around the dependency
- project_memory — persist project decisions, gotchas, and conventions across sessions
Troubleshooting
- exists: false but name looks right → wrong ecosystem; try pypi/cargo or check cross_ecosystem_warning.
- security_status: unknown → limited_no_token; advisories need GitHub API access on the server.
- unpublished: true on npm → often 0.0.1-security malware placeholder—do not install.
- Stale behind_by → pass your installed version or source github:owner/repo.
How to verify it works
- Connect Zephex MCP; confirm check_package in tools/list.
- Ask: “check_package express—report exists, behind_by, and security_status.”
- exists must be true for real packages; a fake name should return exists: false.
Common questions
Billing and plan limits: FAQ, usage limits.
Which MCP tool should I use before adding a dependency?
Use check_package first on every new package name the agent suggests. If exists is false or unpublished is true, do not install. If security_status is vulnerable or you plan a major upgrade, call check_package with task=upgrade or task=security.
What is slopsquatting and how does check_package help?
Slopsquatting is when attackers publish packages under names LLMs hallucinate. check_package verifies the name exists on the intended registry and flags npm security-holding placeholders. It is the fastest gate in Zephex’s package tool pair.
Is check_package a replacement for npm audit?
No. It complements npm audit with registry truth, deprecation, adoption signals, and cross-ecosystem checks. Use check_package task=upgrade or task=security for CVE patched_in and release-note migration detail.
How many ecosystems does check_package support?
Twelve: npm, PyPI, cargo, gem, Go modules, Maven, NuGet, Packagist, Pub, Hex, CocoaPods, and Swift PM. Pass ecosystem when not using npm.
What is the 0.0.1-security npm placeholder?
When malware is removed, npm may leave a security-holding version. check_package treats latest === 0.0.1-security (or similar) as exists: false with unpublished: true so agents do not treat the name as a real installable package.
How do I use check_package with Claude Code or Cursor?
Add Zephex hosted MCP, then ask the agent to run check_package before any install it suggests. Copy prompts on this page work in any MCP editor. See Quickstart for the API key and editor config paths.
Can I run check_package from the terminal without an AI agent?
Yes. Use npx zephex express, npx zephex safe lodash, or npx zephex check-package <name>. Plain-English phrases work too: npx zephex is react safe to install. For upgrades use --task upgrade --from-version. See the terminal section above.
After the upgrade lands: check_test verifies tests and lint pass before you call it done.
Billing: Each tool call counts as one request on your Zephex plan (Free includes 555 requests/month). See usage limits for tier details. Usage limits.
npm audit scans your lockfile; check_package verifies registry truth and slopsquatting for one name before install—use task=upgrade for CVE and migration detail, then check_test.
For AI agents (JSON)
{"tool":"check_package","before_install":true,"if_vulnerable":"task=upgrade"}