# @depfixer/mcp-server

MCP (Model Context Protocol) server that exposes DepFixer dependency analysis tools to AI coding assistants. Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

## What it does

This MCP server gives your AI assistant the ability to:

- **Analyze** a `package.json` for dependency conflicts, version mismatches, and health issues
- **Check compatibility** of a specific package version against a framework version
- **Plan migrations** from one framework version to another with before/after health scores

## Quick Start

### Claude Code

Add to your project's `.claude/settings.json` (or global `~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "depfixer": {
      "command": "npx",
      "args": ["@depfixer/mcp-server"],
      "env": {
        "DEPFIXER_API_KEY": "dfx_live_YOUR_KEY"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "depfixer": {
      "command": "npx",
      "args": ["@depfixer/mcp-server"],
      "env": {
        "DEPFIXER_API_KEY": "dfx_live_YOUR_KEY"
      }
    }
  }
}
```

### Windsurf

Add to your Windsurf MCP configuration:

```json
{
  "mcpServers": {
    "depfixer": {
      "command": "npx",
      "args": ["@depfixer/mcp-server"],
      "env": {
        "DEPFIXER_API_KEY": "dfx_live_YOUR_KEY"
      }
    }
  }
}
```

## Tools

### depfixer_analyze

Analyze a `package.json` for dependency conflicts, version mismatches, and health issues.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `packageJson` | string | Yes | The contents of the package.json file as a JSON string |

**Without API key (audit mode)**: Returns issues found but hides recommended fix versions.
**With API key (full mode)**: Returns full analysis with fix recommendations and install commands.

### depfixer_check_compatibility

Check if a specific npm package version is compatible with a framework version. No API key required.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `packageName` | string | Yes | The npm package name (e.g., `@angular/material`) |
| `packageVersion` | string | Yes | The package version to check (e.g., `17.0.0`) |
| `framework` | string | Yes | The framework name (e.g., `angular`, `react`) |
| `frameworkVersion` | string | Yes | The framework version (e.g., `16.2.0`) |

### depfixer_migrate

Plan a framework migration by analyzing current dependencies and projecting changes needed. Requires API key.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `packageJson` | string | Yes | The contents of the package.json file as a JSON string |
| `targetFramework` | string | Yes | The target framework name (e.g., `angular`, `react`) |
| `targetVersion` | string | Yes | The target framework major version (e.g., `18`) |

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DEPFIXER_API_KEY` | No | - | API key for full analysis and migration features |
| `DEPFIXER_API_URL` | No | `https://api.depfixer.com/api/v1` | Custom API endpoint URL |

### API Key

- **Without API key**: The `depfixer_analyze` tool runs in audit mode (finds issues but does not show recommended versions). The `depfixer_check_compatibility` tool works without a key. The `depfixer_migrate` tool requires a key.
- **With API key**: All tools are fully available with fix recommendations, migration plans, and install commands.

Get your API key at: [https://app.depfixer.com/dashboard/api-keys](https://app.depfixer.com/dashboard/api-keys)

## Local Development

### Prerequisites

- Node.js >= 18
- npm

### Setup

```bash
cd packages/mcp-server
npm install
npm run build
```

### Run locally

```bash
npm start
```

### Watch mode (auto-rebuild on changes)

```bash
npm run dev
```

### Test with MCP Inspector

```bash
npm run inspect
```

This opens the MCP Inspector UI where you can interactively test all tools.

### Local config for Claude Code

To test the local build instead of the published npm package:

```json
{
  "mcpServers": {
    "depfixer": {
      "command": "node",
      "args": ["D:/Mouheb/Project/dep-fixer-claude/packages/mcp-server/dist/index.js"],
      "env": {
        "DEPFIXER_API_URL": "http://localhost:3000/api/v1",
        "DEPFIXER_API_KEY": "your-dev-key"
      }
    }
  }
}
```

## Architecture

```
src/
  index.ts          # Entry point — stdio transport setup
  server.ts         # MCP server creation and tool registration
  api-client.ts     # HTTP client for DepFixer API
  types.ts          # TypeScript interfaces
  tools/
    analyze.ts      # depfixer_analyze tool
    compatibility.ts # depfixer_check_compatibility tool
    migrate.ts      # depfixer_migrate tool
```

All logging uses `console.error()` since stdout is reserved for JSON-RPC communication with the MCP client.