MCP Dependency Health Checker

A Model Context Protocol (MCP) server that performs comprehensive health checks on project dependencies for JavaScript and Python projects.

Features

• 🔍 Automatic Ecosystem Detection: Detects whether your project is JavaScript or Python

• 📦 Package Manager Support:

  • JavaScript: npm-compatible (package.json)

  • Python: pip (requirements.txt)

• 🔄 Real-time Registry Queries: Fetches latest versions from npm and PyPI

• ⚠️ Outdated Dependency Detection: Compares current versions with latest releases

• 🚨 Pre-release Detection: Identifies pre-release versions

• 📊 Detailed Status Reports: Provides comprehensive information about each dependency

• 🤖 LLM-First Design: Clean, text-focused output designed for optimal LLM consumption

• 🚀 Automatic Changelog Fetching: Fetches actual release notes from GitHub releases so LLMs can analyze specific changes, bug fixes, and breaking changes without additional web requests

• 📝 Always Actionable: Every dependency includes meaningful changelog content - either actual release notes or clear explanations when fetching fails

Related MCP server: MCP Package Hero

Installation

Prerequisites

• Python 3.11 or higher

• uv package manager

Setup

1. Clone the repository:

git clone https://github.com/NY5184/mcp-dependency-health.git
cd mcp-dependency-health

2. Install dependencies:

uv sync

Usage

Running the MCP Server

Start the server in development mode:

uv run mcp dev src/server.py

Using with MCP Clients

Configure your MCP client (like Claude Desktop) to connect to this server:

{
  "mcpServers": {
    "dependency-health": {
      "command": "uv",
      "args": ["run", "src/server.py"],
      "cwd": "/path/to/mcp-dependency-health"
    }
  }
}

Available Tools

dependency_health_check

Performs a comprehensive health check on project dependencies.

Input:

• project_path (string): Path to the project directory

• ecosystem (string, optional): "auto", "javascript", or "python" (defaults to "auto")

Output: Returns a list of dependencies with:

• name: Package name

• current: Currently specified version

• latest: Latest version available in registry

• status: "up-to-date", "outdated", or "unknown"

• changelog_content: Always present - contains actual release notes when successfully fetched, or an explanatory message with source link if fetching failed

• note: Additional information (optional)

• release_date: When the latest version was released (optional)

• description: Short package description (optional)

Example Input:

{
  "project_path": "/path/to/your/project",
  "ecosystem": "auto"
}

Example Output:

{
  "dependencies": [
    {
      "name": "react",
      "current": "^18.0.0",
      "latest": "18.2.0",
      "status": "outdated",
      "changelog_content": "Release v18.2.0:\n\n## Fixes\n- Fix memory leak in development mode\n- Fix Suspense bug with nested components\n- Improve TypeScript definitions\n\n## Features\n- Add useId hook\n- Suspense improvements",
      "release_date": "2022-06-14T16:55:41.036Z",
      "description": "React is a JavaScript library for building user interfaces."
    }
  ]
}

LLM-First Design: The output is designed for optimal LLM consumption:

• ✅ No URL clutter - URLs are used internally but not exposed in the output

• ✅ Always actionable - changelog_content always contains meaningful text

• ✅ Self-contained - LLMs can provide specific upgrade advice without additional web requests

• ✅ Clear fallbacks - When changelog fetching fails, the content explains what happened

Example changelog_content values:

• Success: Actual release notes from GitHub

• Fetch failed with source: "Changelog available at: https://github.com/user/repo/releases\n\nThe release notes exist but could not be automatically extracted. Visit the URL above for full details."

• No source found: "Changelog could not be fetched automatically. No official changelog source was found."

With this structure, an LLM can immediately provide specific advice like:

• "React 18.2.0 includes bug fixes for Suspense and fixes a memory leak in development mode. Safe to upgrade."

• "This release was from June 2022, so it's well-tested and stable."

Project Structure

mcp-dependency-health/
├── main.py                      # Entry point (if needed)
├── pyproject.toml       # Project configuration and dependencies
├── uv.lock                     # Locked dependency versions
├── README.md                   # Project documentation
│
├── src/                        # Main source code
│   ├── __init__.py
│   ├── server.py              # MCP server implementation
│   └── services/              # Service layer
│       ├── __init__.py
│       ├── changelog_fetcher.py # Changelog content fetching
│       ├── error_handlers.py  # Error handling utilities
│       └── registry_clients.py # npm/PyPI registry clients
│
├── schemas/                   # Data schemas
│   ├── __init__.py
│   ├── input.py              # Input validation schemas
│   └── output.py             # Output data schemas
│
├── utils/                    # Utility modules
│   ├── __init__.py
│   ├── file_finder.py       # Project file discovery
│   ├── parsers.py           # Dependency file parsers
│   └── versions.py          # Version comparison utilities
│
└── tests/                   # Test suite
    ├── test_file_finder.py
    ├── test_parsers_js.py
    ├── test_parsers_py.py
    ├── test_registry_clients.py
    ├── test_server_sanity.py
    └── test_versions.py

Development

Running Tests

uv run pytest

Code Structure

• FastMCP Framework: Uses FastMCP for easy MCP server creation

• Async Operations: Leverages httpx for efficient async HTTP requests

• Type Safety: Full type hints with Pydantic models

• Version Parsing: Uses packaging library for semantic version comparison

Dependencies

• fastmcp or mcp>=1.25.0: MCP server framework

• httpx>=0.28.1: Async HTTP client

• pydantic>=2.12.5: Data validation

• packaging>=25.0: Version parsing and comparison

How It Works

1. File Discovery: Scans the project directory for package.json or requirements.txt

2. Ecosystem Detection: Automatically determines if it's a JavaScript or Python project

3. Dependency Parsing: Extracts package names and version specifications

4. Registry Queries: Queries npm or PyPI for the latest versions and contextual information

5. Changelog Fetching: Automatically fetches release notes from GitHub releases (when available)

6. Version Comparison: Compares current versions with latest releases

7. Status Report: Returns detailed information about each dependency with actual changelog content and links

Limitations

This tool has limited package manager support. It currently only supports:

Supported Package Managers

• JavaScript: npm (via package.json)

• Python: pip (via requirements.txt)

Unsupported Package Managers

The following package managers are not currently supported:

• Python: Poetry (pyproject.toml), Pipenv (Pipfile), Conda (environment.yml)

• Rust: Cargo (Cargo.toml)

• Go: Go modules (go.mod)

• Java: Maven (pom.xml), Gradle (build.gradle)

• PHP: Composer (composer.json)

• .NET: NuGet (.csproj, packages.config)

• Ruby: Bundler (Gemfile)

• Other: Any other package manager not listed above

When a project uses an unsupported package manager or no supported dependency file is found, the tool will return a dependency result with:

• status: "unknown"

• A clear note explaining that the project uses an unsupported dependency manager and listing the currently supported ones

Troubleshooting

"Failed to canonicalize script path"

If you encounter this error:

1. Ensure you're in the project directory

2. Recreate the virtual environment:

   uv sync

3. Try running directly: uv run python src/server.py

Import Errors

If you see ModuleNotFoundError:

• Ensure all dependencies are installed: uv sync

• Check that you're using the correct virtual environment

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.