Pkgdiet MCP Server

🥗 PkgDiet

Dependency policy for AI-assisted JavaScript and TypeScript development.
Put your node_modules on a diet.

The Problem: AI coding agents (Claude Code, Codex, Cursor, Windsurf, Cline) propose nonexistent, deprecated, vulnerable, or typosquatted packages. There is no built-in mechanism to stop them from running the install.

The Solution: PkgDiet intercepts every npm install / pnpm add / yarn add command your AI agent generates — using native agent hook APIs — and blocks unapproved installs before they execute.

---

🔒 Live Proof

Run this to see PkgDiet block real risky AI-generated dependencies in your terminal:

npx pkgdiet demo

Example output:

🔒 PkgDiet — Live AI Dependency Enforcement Demo
   Simulating what happens when an AI agent tries to install these packages.

🟡  WARNING — moment
   Context:   AI suggested this for date formatting
   Score:     100/100
   Reason:    Efficiency Flag: Better alternatives exist for moment.
   Use this:  dayjs, date-fns

🔴  BLOCKED — request
   Context:   AI suggested this for HTTP requests
   Score:     15/100
   Reason:    Health score 15 is below minimum allowed (60).
   Use this:  undici, native fetch
   CVEs:      GHSA-p8p7-x288-28g6

   🔒 PkgDiet blocked this risky AI-generated dependency before install.

🔴  BLOCKED — node-uuid
   Context:   AI suggested this for UUID generation
   Score:     15/100
   Reason:    Health score 15 is below minimum allowed (60).
   Use this:  crypto.randomUUID(), uuid

   🔒 PkgDiet blocked this risky AI-generated dependency before install.

🟡  WARNING — lodash
   Context:   AI suggested this for array utilities
   Score:     80/100
   Reason:    Efficiency Flag: Better alternatives exist for lodash.
   Use this:  lodash-es, native JS

📊 Demo Summary: 2 blocked, 2 warned
   These checks run automatically before every npm install in your AI agent.
   Setup: npx pkgdiet init

For machine-readable CI proof:

npx pkgdiet demo --json

---

🚀 One-Command Setup

npx pkgdiet init

This single command creates:

---

🛡️ Enforcement by Agent

PkgDiet uses each agent's native hook API to block installs — not just advisory rules:

How PreToolUse hooks work: When Claude Code or Codex generates a Bash tool call containing npm install, the registered hook script runs first. If PkgDiet returns a non-zero exit code (exit code 2 for Claude Code), the agent sees the denial reason and aborts the install — the command never runs.

Claude Code Plugin

PkgDiet is packaged as a Claude Code plugin featuring bundled MCP tools, slash commands (/pkgdiet:check, /pkgdiet:audit), skill definitions, and PreToolUse execution hooks:

/plugin install github:om-tajne/pkgdiet

(Or /plugin install pkgdiet@claude-plugins-official once listed in the official directory)

---

🔄 The 3-Phase Policy Loop

PkgDiet uses a shared core engine (@pkgdiet/core) so all interfaces apply the same evaluation logic.

1. Repository Policy: A single .pkgdietrc.json file dictates what is allowed, warned, or blocked for your project.
2. Agent Hook (Enforce): Native PreToolUse hooks for Claude Code and Codex intercept install commands before execution. MCP check_dependency instructs other agents before they write the command.
3. CI Gate (Fallback): npx pkgdiet ci runs in GitHub Actions, diffs package.json against the base commit, and fails the PR if any added package violates policy.

---

🛠️ CLI Commands

---

⚙️ Configuration (.pkgdietrc.json)

{
  "minHealthScore": 70,
  "warnHealthScore": 80,
  "blockDeprecated": true,
  "blockKnownVulnerabilities": true,
  "blockTyposquats": false,
  "requirePinnedVersions": true,
  "maxPackageSizeBytes": 15728640,
  "failOn": "BLOCK",
  "securityMode": "fail-open",
  "blockedPackages": ["moment", "request"],
  "internalNamePrefixes": [],
  "environments": {
    "ci": { "minHealthScore": 80, "failOn": "BLOCK", "securityMode": "fail-closed" },
    "dev": { "minHealthScore": 60, "failOn": "BLOCK", "securityMode": "fail-open" },
    "staging": { "minHealthScore": 70, "failOn": "BLOCK", "securityMode": "fail-open" }
  }
}

---

🤖 MCP Integration

PkgDiet acts as a local Model Context Protocol (MCP) server over stdio.

When your AI coding agent connects to PkgDiet, it gains access to 5 read-only tools:

• check_dependency: Evaluates an npm package against your local .pkgdietrc.json policy and returns structured ALLOW, WARN, or BLOCK verdicts with evidence.
• check_dependencies: Bounded batch evaluation of up to 50 dependencies in a single tool call.
• suggest_alternative: Queries PkgDiet's curated dataset to find modern, lighter, and maintained alternatives for blocked packages.
• get_policy: Retrieves the active repository dependency policy rules and thresholds.
• explain_verdict: Detailed breakdown of package scoring, maintenance signals, and diagnostic codes.

Built-in Verification (all free, zero paid API keys):

• OSV vulnerability database — checks known CVEs via the public OSV advisory API
• npm registry provenance — verifies signed npm attestations
• Typosquat detection — edit-distance checks against popular package namespaces
• Lockfile pinning validation — enforces deterministic package resolution
• Dependency confusion detection — blocks internal-prefix packages found on public registries

---

💻 Requirements & Runtime Controls

• Node.js: Requires Node.js 20 or later (Node.js >=20).
• PKGDIET_NO_NETWORK=1: Runs completely offline using cached metadata; never contacts the external registry.
• PKGDIET_TELEMETRY_DISABLED=1: Disables local telemetry and metrics collection.
• PKGDIET_REGISTRY_URL: Overrides the default npm registry with a custom or private enterprise registry endpoint.
• .pkgdiet-cache.json: Local cache file storing validated package metadata and advisory results.
• .pkgdiet-metrics.json: Local metrics file for tracking audit performance and check history.

---

📦 Monorepo Architecture

---

⚖️ Legal, Privacy & Trademark Notice

• Advisory Tooling: PkgDiet is open-source software provided under the MIT License. It evaluates publicly available npm metadata and local project configurations according to user-defined policy. It provides advisory analysis only and does not constitute formal legal, cybersecurity, compliance, or procurement advice.
• Nominative Fair Use & Trademarks: All third-party trademarks, product names, logos, and brands (including npm, GitHub, GitHub Copilot, Claude / Claude Code, Cursor, Windsurf, Cline, Codex / OpenAI, and Google) are the property of their respective owners. Their mention in this repository is strictly for integration identification and compatibility under nominative fair use. No affiliation, endorsement, sponsorship, or partnership is claimed or implied.
• Local-First Privacy: PkgDiet operates locally via stdio and local caching. It does not inspect, collect, or transmit proprietary codebase source code or credentials. For full terms, see LEGAL.md.

---

🔗 Documentation & Support

• Legal & Privacy Notice: LEGAL.md

• Architecture Guide: ARCHITECTURE.md

• Threat Model & Security: docs/THREAT-MODEL.md & SECURITY.md

• Enterprise Adoption: docs/ENTERPRISE-ADOPTION.md

• CI Integration: docs/CI.md

• MCP Integration Guide: docs/MCP.md

• GitHub Repository: om-tajne/pkgdiet

• Report an Issue: Issue Tracker

• License: MIT