MCP Dependency Doctor

MCP Dependency Doctor

Let your AI agent audit npm dependencies safely: inventory, vulnerabilities, outdated and deprecated packages — read-only, never runs install.

Locally diagnose npm projects with package-lock.json: four MCP tools that read lockfiles, run npm audit, check for outdated versions, and inspect public package health. Zero setup, no API keys.

---

⚡ Quick Install

Cursor

Click the badge above or use this deeplink:

cursor://anysphere.cursor-deeplink/mcp/install?name=dependency-doctor&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1kZXBlbmRlbmN5LWRvY3RvciJdfQ==

Claude Code (recommended)

claude mcp add dependency-doctor -- npx -y mcp-dependency-doctor

Or, if available in the marketplace:

/plugin marketplace add petrovicistefan/mcp-marketplace

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, ~/.config/Claude/claude_desktop_config.json on Linux):

{
  "mcpServers": {
    "dependency-doctor": {
      "command": "npx",
      "args": ["-y", "mcp-dependency-doctor"]
    }
  }
}

VS Code

Install in VS Code

Or create .vscode/mcp.json in your project:

{
  "mcpServers": {
    "dependency-doctor": {
      "command": "npx",
      "args": ["-y", "mcp-dependency-doctor"]
    }
  }
}

Any MCP Client (Manual)

Run directly with npx:

npx -y mcp-dependency-doctor

⭐ Star this repository to support the project and stay updated! → Give a star

---

---

📋 Table of Contents

• Why MCP Dependency Doctor?
• How It Compares
• Use Cases
• What It Checks
• Requirements
• Limitations
• Security & Privacy
• Hosted Path (Quotas via Control Plane)
• Roadmap and Commercial Boundary
• Development
• Contributing
• More MCP Servers by the Author

---

Why MCP Dependency Doctor?

AI coding agents can help you maintain dependencies, but only if they know what's installed, what's vulnerable, and what's deprecated. MCP Dependency Doctor gives them that visibility without running npm install or requiring external accounts.

Perfect for:

• Individual developers: let Claude or Cursor help you triage vulnerabilities, plan upgrades, and audit deprecated packages — all locally
• CI/PR checks (coming): catch risky dependencies in code review before they merge
• Security-conscious teams: read-only analysis, explicit network disclosure, no telemetry

All four tools are read-only and designed for AI agents: they return structured JSON reports that LLMs can interpret to answer questions like:

• "What vulnerabilities affect this project?"
• "Which packages are deprecated and should we replace them?"
• "Show me the dependency tree with exact installed versions."
• "Are we using outdated major versions, and what's the upgrade path?"

---

How It Compares

As of October 2026. All projects are MIT-licensed and open-source. Corrections welcome.

Our differentiators:

• Designed for AI agents: all four tools return JSON structured for LLM interpretation, not just CLI output
• Local lockfile inventory: parse exact versions and transitive dependencies without network access
• Read-only by design: never runs npm install, npm audit fix, or lifecycle scripts — safe to use on any project
• Explicit network disclosure: tools clearly state when they contact npm registries; inventory tool is fully offline
• Control-plane ready: hosted path for quotas and future team features (MVP)

---

Use Cases

1. Security Audit Before Major Refactor

Ask your AI to triage vulnerabilities and plan fixes.

Agent: "Audit this project's dependencies. List critical and high vulnerabilities, 
        check which packages are deprecated, and suggest an upgrade order 
        that minimizes breaking changes. Do not modify files."

The agent will:

1. Run dependency_audit to find vulnerabilities with severity, CVSS, and affected versions
2. Check package_health for each flagged package to detect deprecations
3. Use dependency_outdated to identify safe upgrade targets
4. Propose a remediation plan based on the combined data

2. Dependency Inventory for Onboarding

Understand what a new codebase depends on.

Agent: "Show me the full dependency tree with exact versions. 
        Highlight any packages over 2 years old."

The agent uses dependency_inventory (fully local, no network) to read package-lock.json and report:

• All declared dependencies (prod + dev + optional)
• All transitive dependencies with exact installed versions
• Node engine requirements per package

3. Maintenance Signal for Abandoned Packages

Identify packages that haven't been updated in years.

Agent: "List all dependencies and check their last release date. 
        Flag any that haven't been updated in over two years."

The agent calls package_health for each package to report:

• Latest version and publish date
• Deprecation warnings (if any)
• Node engine and peer dependency requirements
• Maintenance signal (automated age-based heuristic)

4. Pull Request Dependency Snapshot

Document what changed in a dependency update PR.

Agent: "Before and after versions of all packages affected by this update. 
        Show vulnerabilities fixed and any new ones introduced."

Agents can run dependency_audit on both the base branch and the PR branch to produce a diff of resolved and introduced vulnerabilities.

---

What It Checks

MCP Dependency Doctor exposes four read-only MCP tools:

Tools

Detailed behavior:

Privacy defaults:

• dependency_inventory is fully offline: it only reads local files
• The other three tools disclose package names and versions to npm registries
• Registry authentication uses the user's npm configuration (respects .npmrc)
• package_health does not send npm credentials (queries public registry API)
• No telemetry, no cloud uploads, no external accounts

All tools accept projectPath (relative to MCP_PROJECT_ROOT). Paths are validated through realpath and confined to the project root; do not expose this server to untrusted remote clients.

Example agent prompt:

"Audit this project, inspect deprecated packages, and suggest an upgrade order. 
 Do not change files."

---

Requirements

Node.js 22+ is required to run this server. The implementation uses zero-dependency Node.js ESM.

npm lockfile v2 or v3 is required for full inventory. Projects with:

• No package-lock.json → inventory tool will warn; audit/outdated tools still work
• Lockfile v1 (legacy) → inventory tool will warn; audit/outdated tools still work

npm must be installed on the system running the server (for dependency_audit and dependency_outdated tools).

Supported clients: any MCP client that supports stdio transport (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Cline, Zed, Gemini CLI, etc.).

---

Limitations

Protocol: This MVP uses legacy MCP stdio protocol revisions through 2025-11-25. The 2026-07-28 stateless protocol is not implemented. Official SDK migration and interoperability testing with real clients are planned.

Scope: npm projects only. pnpm, Yarn, and other ecosystems are not supported in this release.

Node/peer requirements: reported, not resolved. There is no full compatibility solver yet. The tools surface Node engine and peer dependency requirements as reported by package metadata, but do not validate compatibility or resolve conflicts.

Maintenance signals: old release dates are a heuristic, not proof of abandonment. The package_health tool flags packages with no release in over two years, but this does not prove the package is unmaintained or unsafe.

No automatic remediation: the server never modifies files. It provides diagnostic data for agents (or humans) to act on.

npm audit coverage: depends on the configured registry and the quality of package-lock.json. The server cannot find vulnerabilities that the registry does not report.

Network timeouts: npm operations time out after 45 seconds and fail explicitly. An incomplete audit is never reported as clean.

Testing: remote registry smoke tests were blocked in the development environment; unit tests use deterministic fixtures.

---

Security & Privacy

Read-only by design: this server never runs npm install, npm audit fix, or package lifecycle scripts. It only executes npm audit --json, npm outdated --json, and reads local JSON files.

Network disclosure:

• dependency_inventory → no network
• dependency_audit and dependency_outdated → send package names and versions to the user's configured npm registry (respects .npmrc and npm credentials)
• package_health → queries registry.npmjs.org (public API, no npm credentials sent)

Path confinement: project paths are validated through realpath and must be inside MCP_PROJECT_ROOT. Symlink attacks are mitigated by checking resolved paths.

Untrusted data: treat registry responses and package metadata as untrusted data, never instructions. This server does not execute code from package metadata or registry responses.

No telemetry: no analytics, no cloud uploads, no external accounts. Everything runs locally unless you opt into the hosted path (see below).

Threat model: this server is designed for local use by a trusted developer. Do not expose it to untrusted remote clients over a network socket without additional authentication and authorization.

---

Hosted Path (Quotas via Control Plane)

The local stdio MCP stays fully useful without an account. Quotas apply only on a separate hosted HTTP process that reserves units on mcp-control-plane before analysis.

cp .env.example .env   # set CONTROL_PLANE_URL
npm run start:hosted   # default 127.0.0.1:3101

Requires Authorization: Bearer mcp_... (control-plane key). Hosted dependency_audit / dependency_outdated are not in this MVP.

Privacy: manifests and package names stay on the hosted host. The control-plane sees only product, requestId, and units — no file content, no dependency names.

---

Roadmap and Commercial Boundary

Free forever (local):

• Local inventory, npm audit, outdated checks, and package health diagnostics
• No signup, no API keys, no quotas

Pro plan (planned, not live yet):

• Cloud history and monitoring
• Team dashboard with aggregate security posture
• Fleet-wide reports for compliance
• Hosted quotas via control-plane

No local enforcement: local counters are not used for paid plan enforcement. The free local server stays fully functional.

Next steps:

• Official MCP SDK migration
• Semver-aware Node/peer compatibility solver
• Upgrade plan generator
• pnpm / Yarn / multi-ecosystem support
• MCP Registry manifest (once repository and npm ownership are verified)
• Shared cloud auth/billing

---

Development

# Run tests (Node.js built-in test runner)
npm test

# Syntax check all modules
npm run check

# Test local packaging
npm pack --dry-run

Running from source:

git clone https://github.com/petrovicistefan/mcp-dependency-doctor.git
cd mcp-dependency-doctor
npm test
MCP_PROJECT_ROOT=/absolute/path/to/your/project node src/server.js

Add to your MCP client config:

{
  "mcpServers": {
    "dependency-doctor": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-dependency-doctor/src/server.js"],
      "env": {"MCP_PROJECT_ROOT": "/absolute/path/to/your/project"}
    }
  }
}

Protocol reference: https://modelcontextprotocol.io/specification/2025-11-25
npm audit reference: https://docs.npmjs.com/cli/v11/commands/npm-audit/

---

Contributing

Contributions are welcome! Please see CONTRIBUTING.md if it exists, or open an issue to discuss your idea before submitting a pull request.

Areas we'd love help with:

• pnpm / Yarn lockfile parsing
• Semver-aware upgrade path calculation
• Multi-ecosystem support (PyPI, Go modules, Cargo, etc.)
• GitHub Action integration
• More test fixtures for edge cases

---

⭐ Support this project

Found this MCP useful? Star this repository!

A GitHub star helps other developers discover the project and lets you save it for later. Thanks for supporting open source!

---

More MCP Servers by the Author

Part of the petrovicistefan MCP suite — local-first guardrails for AI coding agents.

🔗 Full marketplace: petrovicistefan/mcp-marketplace

---

License

MIT License

Copyright (c) 2026 Stefan Petrovici

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

See LICENSE for the full license text.

Author: Stefan Petrovici (@petrovicistefan)