Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@sandcheck/mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@sandcheck/mcp

Model Context Protocol server for Sandcheck. Lets AI coding assistants check npm packages against a curated list of known-compromised versions before they suggest installing them.

The server is stdio-based and works with any MCP-aware coding assistant, including Claude Code, Cursor, and Windsurf.

What it exposes

Tool	Purpose
`check_package`	Look up a single `name@version`.
`check_packages`	Look up many `name@version` pairs in one call (use this before a bulk install).
`check_lockfile`	Detect and scan `package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock` in a project directory.
`get_recent_compromises`	Return recent dataset entries, newest first. Defaults to sorting by `published_at` (upstream advisory date); pass `by: "first_seen"` for "what's new to our dataset" instead. Use it to brief the model on fresh incidents at the start of a session.

Install

pnpm add -g @sandcheck/mcp
# or run on demand:
npx -y @sandcheck/mcp

The published binary is sandcheck-mcp.

Claude Code

Add this to your ~/.config/claude-code/mcp.json (or run claude mcp add sandcheck):

{
  "mcpServers": {
    "sandcheck": {
      "command": "npx",
      "args": ["-y", "@sandcheck/mcp"]
    }
  }
}

Then try: "Use sandcheck to check whether a recent npm package version I'm thinking of installing is safe." — the assistant should call check_package and report back.

Cursor

In Cursor settings → MCP, add a new server:

Name: sandcheck
Command: npx
Args: -y @sandcheck/mcp

Cursor will list the four Sandcheck tools under the server.

Windsurf

In ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sandcheck": {
      "command": "npx",
      "args": ["-y", "@sandcheck/mcp"]
    }
  }
}

Make your AI assistant actually use Sandcheck

Installing the MCP server makes the four tools available — but the model still has to decide to call them. To make auto-invocation reliable, drop a short rules snippet into your project so the assistant has explicit instructions to consult Sandcheck before any npm install.

See docs/ai-rules.md for the recommended snippet and per-editor file locations:

Claude Code → CLAUDE.md at the repo root
Cursor → .cursorrules at the repo root
Windsurf → .windsurfrules at the repo root

Copy the snippet from docs/ai-rules.md into the relevant file once and the assistant will start calling check_package / check_lockfile automatically on installs and audits.

How the dataset is fetched

The server fetches the canonical Sandcheck dataset from the raw GitHub URL on startup and refreshes once per hour. There is no telemetry, no analytics, and no phone-home. You can pin a specific dataset by setting the SANDCHECK_DATASET_URL environment variable to a different URL or to a file:// path.

Security posture

No install-time lifecycle scripts.
ESM only, strict TypeScript, no any.
The server runs entirely over stdio — no inbound network listener.
Releases are published with npm provenance via GitHub Actions OIDC.

Disclaimer

Provided "as is", without warranty of any kind. The dataset is a best-effort aggregation and may be incomplete, lag behind newly-disclosed compromises, or contain errors propagated from upstream sources. Use Sandcheck as one signal in your supply-chain hygiene, not the only one. To the maximum extent permitted by law, the maintainers and contributors are not liable for any damages arising from use of this tool or its data. See the Apache-2.0 license for the full warranty and liability disclaimers.

License

Apache-2.0.