Put your node_modules on a diet - find unused dependencies, analyze health, and reduce size
io.github.om-tajne/pkgdiet MCP Server
This MCP server provides PkgDiet functionality for dependency governance. Its purpose is to help reduce project size by analyzing node_modules to find unused dependencies and assess package health, based on static analysis of npm package data and bundle size.
🛠️ Key Features
Unused dependency detection in node_modules
Package health analysis
Reduce size via dependency and bundle-size evaluation
🚀 Use Cases
Identify unused entries in npm dependencies
Evaluate dependency health to support smaller bundles
Maintain package.json/npm dependency hygiene using CLI tooling
⚡ Developer Benefits
Static analysis for unused dependencies
Helps reduce bundle size by trimming unused packages
Supports npm-based workflows (npm CLI context)
⚠️ Limitations
Focused on dependency governance for node_modules (not runtime-only auditing)
Described scope emphasizes unused dependencies and health; other behaviors are not specified
The Problem: AI coding agents can propose nonexistent, deprecated, unapproved, or unsuitable packages. Teams need a consistent way to evaluate those choices before and after dependency changes.
The Solution: PkgDiet is a deterministic dependency guardrail. It checks proposed dependencies against registry health, deprecation status, and your local project policy before they are installed, forcing agents to pivot to modern alternatives.
🔄 The 3-Phase Policy Loop
PkgDiet guarantees that a dependency is evaluated identically at every stage of your development lifecycle using a shared core engine (@pkgdiet/core).
Repository Policy: A single .pkgdietrc.json file dictates what is allowed, warned, or blocked for your project.
Agent Guidance (MCP): AI clients connect to PkgDiet via the Model Context Protocol (npx pkgdiet mcp). Before writing npm install, the agent asks PkgDiet if a package is compliant. If blocked, PkgDiet provides curated modern alternatives.
Merge Enforcement (CI): PkgDiet runs in GitHub Actions (npx pkgdiet ci --base origin/main). It diffs package.json to isolate newly requested direct dependencies. If a blocked package bypassed the agent and made it into the PR, CI fails and halts the merge.
🚀 Quick Start
Initialize PkgDiet in your repository. This interactive command creates your .pkgdietrc.json policy, sets up your GitHub Actions CI workflow, and configures your local AI agents (Cursor, Windsurf, Cline) all at once:
bash
npx pkgdiet init
Audit your existing project to see how your current node_modules stack up against your new policy:
bash
npx pkgdiet audit
🛠️ CLI Commands
text
Usage: pkgdiet [options] [command]
Dependency policy for AI-assisted development — audit, check, and enforce npm dependency rules
Options:
-v, --version output the version number
-h, --help display help for command
Commands:
audit [options] Audit existing dependencies for policy, health, size, and unused-package signals
check [options] <packages...> Evaluate npm packages against this repository’s dependency policy
mcp [args...] Start the MCP JSON-RPC server over stdio for MCP-compatible AI coding agents
ci [options] Enforce policy for dependency changes introduced by this branch
alternatives Browse the PkgDiet alternatives dataset
drift [options] Scan project for dependency health drift over time
setup Create a starter .pkgdietrc.json policy
agent-setup [options] Configure PkgDiet for AI coding agents
init [options] Set up PkgDiet in this project — creates policy, CI workflow, and all AI agent configs
pr [options] Generate a reviewer-ready pull request for adding PkgDiet to any GitHub repo
policy-check [options] Validate the repository’s .pkgdietrc.json policy
{"minHealthScore":60,"warnHealthScore":80,"blockDeprecated":true,"maxAddedSizeMB":5.0,"failOn":["BLOCK","UNKNOWN"],"blockedPackages":{"moment":"Deprecated. Use date-fns instead.","request":"Deprecated. Use native fetch."},"environments":{"ci":{"failOn":["BLOCK","UNKNOWN","WARN"]}},"exceptions":{"lodash":{"allow":["HEALTH_SCORE_MIN","PACKAGE_OVERSIZE"],"expires":"2027-01-01","reason":"Legacy dependency; migration planned for Q1."}}}
Note: Exceptions are strictly scoped. They cannot bypass PACKAGE_NOT_FOUND (hallucinations), registry timeouts (UNKNOWN), or explicit entries in blockedPackages.
🤖 MCP Integration
PkgDiet acts as a local Model Context Protocol (MCP) server.
When your AI coding agent connects to PkgDiet, it gains access to:
check_dependency: Evaluates an npm package against your local .pkgdietrc.json policy and returns structured ALLOW, WARN, or BLOCK verdicts.
suggest_alternative: Queries PkgDiet's curated dataset to find modern, lighter, and maintained alternatives for blocked packages.
