# Dependency Health Monitor MCP Server

A Model Context Protocol (MCP) server that monitors and analyzes dependency health across your Node.js projects. This server provides intelligent tools to check for outdated packages, security vulnerabilities, license compliance, and suggests safe upgrade paths.

**Important**: Each MCP server instance is configured to monitor a specific project. The project path is specified when starting the server, and all tools operate only on that configured project for security and clarity.

## Features

- 🔍 **Check Outdated Packages** - Find packages with newer versions available
- 🛡️ **Security Audit** - Identify vulnerabilities in your dependencies
- 📊 **Dependency Analysis** - Get statistics about your dependency tree
- ⚖️ **License Compliance** - Check for restrictive licenses that may require attention
- 💡 **Smart Update Suggestions** - Get prioritized recommendations for safe updates
- 🔄 **Automated Upgrades** - Safely upgrade dependencies with fine-grained control

## Prerequisites

- Node.js >= 18.0.0
- npm, yarn, or pnpm package manager
- A project with package.json

## Installation

### Option 1: Local Development/Testing

Clone this repository and install dependencies:

```bash
git clone https://github.com/pramodyadav/dependency-health-mcp.git
cd dependency-health-mcp
npm install
```

### Option 2: Install from npm

Since this library is already published to npm, you can install globally:

```bash
npm install -g @pramodyadav027/dependency-health-mcp
```

## Configuration

Each MCP server instance monitors **one specific project**. You specify the project path when configuring the server.

### For Local Development (Claude Desktop)

Add to your Claude Desktop configuration file:

__macOS__: `~/Library/Application Support/Claude/claude_desktop_config.json`
__Windows__: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "dependency-health-myproject": {
      "command": "node",
      "args": [
        "/absolute/path/to/dependency-health-mcp/index.js",
        "/path/to/your/project"
      ]
    }
  }
}
```

**To monitor multiple projects**, add separate server entries:

```json
{
  "mcpServers": {
    "dependency-health-project1": {
      "command": "node",
      "args": [
        "/absolute/path/to/dependency-health-mcp/index.js",
        "/path/to/project1"
      ]
    },
    "dependency-health-project2": {
      "command": "node",
      "args": [
        "/absolute/path/to/dependency-health-mcp/index.js",
        "/path/to/project2"
      ]
    }
  }
}
```

### For npm Package (After Publishing)

```json
{
  "mcpServers": {
    "dependency-health": {
      "command": "npx",
      "args": [
        "@pramodyadav027/dependency-health-mcp",
        "/path/to/your/project"
      ]
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "dependency-health": {
      "command": "dependency-health-mcp",
      "args": [
        "/path/to/your/project"
      ]
    }
  }
}
```

## Available Tools

All tools operate on the project configured when the server was started.

### 1. check_outdated_packages

Check for outdated packages and get version comparison.

**Parameters:**

- `packageManager` (optional): npm, yarn, or pnpm (default: npm)

### 2. check_vulnerabilities

Scan for security vulnerabilities using npm/yarn/pnpm audit.

**Parameters:**

- `packageManager` (optional): npm, yarn, or pnpm (default: npm)

### 3. analyze_dependencies

Get detailed statistics about your dependency tree.

**Parameters:** None

### 4. check_license_compliance

Identify packages with restrictive licenses (GPL, AGPL, etc.).

**Parameters:** None

### 5. suggest_updates

Get prioritized update recommendations based on semantic versioning.

**Parameters:** None

### 6. upgrade_dependencies

Automatically upgrade dependencies with fine-grained control.

**Parameters:**

- `packageManager` (optional): npm, yarn, or pnpm (default: npm)
- `packages` (optional): Array of specific packages to upgrade
- `updateType` (optional): patch, minor, major, or latest (default: latest)

## Usage Examples

Once configured with an MCP client (like Claude Desktop or VS Code Copilot), you can ask:

- "Check for outdated packages in this project"
- "Are there any security vulnerabilities?"
- "Analyze my project dependencies"
- "Check license compliance"
- "Suggest safe updates for my dependencies"
- "Upgrade all patch versions"
- "Upgrade only the react package"

The tools will automatically operate on the project you configured for this server instance.

## Development

## Architecture

The codebase is organized into modular components for better maintainability:

- **index.js** - Clean entry point (10 lines)
- **server.js** - Server orchestration and MCP protocol handling
- **tools/** - Individual tool implementations (~80 lines each)
- **utils/** - Shared utilities for validation and package manager abstraction

This modular structure makes it easy to:
- Add new tools
- Test individual components
- Understand the codebase
- Maintain and update existing functionality

### Running Locally

```bash
# Start the server for a specific project
node index.js /path/to/your/project

# Or use npm scripts (operates on current directory)
npm start

# Development mode with auto-reload
npm run dev
```

### Testing

You can test the server by configuring it in Claude Desktop or VS Code and asking questions about the configured Node.js project.

## Publishing to npm (For Maintainers)

```bash
# Build/test first
npm install
npm start  # Verify it works

# Login to npm
npm login

# Publish
npm publish --access public
```

## Project Structure

```ini
dependency-health-mcp/
├── index.js               # Entry point
├── server.js              # MCP server orchestration
├── cli.js                 # CLI entry point (for bin)
├── tools/                 # Tool implementations
│   ├── outdated.js        # Check outdated packages
│   ├── vulnerabilities.js # Security audit
│   ├── analyze.js         # Dependency analysis
│   ├── licenses.js        # License compliance
│   ├── suggest.js         # Update suggestions
│   └── upgrade.js         # Automated upgrades
├── utils/                 # Shared utilities
│   ├── validation.js      # Input validation
│   └── package-manager.js # Package manager abstraction
├── package.json           # Package configuration
├── README.md             # This file
├── CHANGELOG.md          # Version history
├── QUICKSTART.md         # Quick start guide
├── LICENSE               # MIT License
├── example-config.json   # Configuration examples
├── .gitignore            # Git ignore rules
└── .npmignore            # npm ignore rules
```

## Security

This server only operates on the specific project path configured at startup. Tools cannot access or modify files outside the configured project directory. For enhanced security:

- Use absolute paths in your MCP configuration
- Create separate server instances for each project you want to monitor
- Review the configured project path before running any upgrade operations

## License

MIT

## Author

Pramod Kumar Yadav

## Contributing

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

## Support

For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/pramodyadav/dependency-health-mcp).