update-mcp-servers

What this skill does

# Update MCP Servers

Comprehensive one-stop shop for MCP server management. Dynamically discovers all MCP servers, detects installation methods, identifies missing dependencies, offers installation assistance, and updates servers using best practices.

## When to Use

- After a fresh Claude Code installation
- When MCP server tools return connection errors
- Periodically to get latest package versions
- After seeing "package outdated" warnings
- When setting up a new development environment
- To install missing dependencies for MCP servers

## Arguments

| Argument | Description | Default |
|----------|-------------|---------|
| `--all` | Update all updateable servers | Default if no args |
| `--enabled-only` | Only update currently connected servers | |
| `--server NAME` | Update specific server(s) | Can be repeated |
| `--dry-run` | Show what would be updated without executing | false |
| `--interactive` | Force interactive selection mode | Auto if <10 servers |
| `--non-interactive` / `--yes` | Skip all prompts, proceed with updates | |
| `--help` | Show comprehensive help and supported methods | |

## Workflow

### Step 1: Session-Aware Discovery

Discover all configured MCP servers by parsing configuration files directly. This avoids the limitation that `claude mcp list` cannot run inside an active Claude Code session.

#### Primary: File-Based Discovery (MANDATORY)

1. **Plugin configs**: Use `Glob` to find `plugins/*/.mcp.json` files
2. **Project config**: Read `.mcp.json` in the project root
3. **User config**: Read `~/.claude/settings.json` (or `$APPDATA/Claude/settings.json` on Windows)

Parse the `mcpServers` key from each file. Each entry has:

```json
{
  "mcpServers": {
    "server-name": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "perplexity-mcp"],
      "env": {}
    }
  }
}
```

**For each server, extract:**

- `server_name`: The JSON key
- `command`: The `command` field
- `args`: The `args` array (join for pattern matching)
- `source_file`: Which config file defined it
- `is_http`: `type` is `"url"` or command/args contain an HTTP URL
- `is_plugin_vendored`: `args` contain `${CLAUDE_PLUGIN_ROOT}` (treat as literal pattern, do not expand)

**Merge servers across files**, noting source. If a server appears in multiple files, note all sources.

#### Secondary: CLI Validation (Best-Effort)

Attempt `CLAUDECODE= claude mcp list` to get live connection status:

- If the command succeeds, merge `status` (Connected/Disconnected/Error) into each server entry
- If the command fails (e.g., inside active session), proceed with file-based discovery and set `status` to `unknown`
- Do NOT block on CLI failure -- file-based discovery is sufficient for updates

### Step 2: Detect Installation Methods

For each server, determine the update method based on the command pattern:

#### Package Manager Patterns (Direct Update)

| Pattern | Method | Update Command |
|---------|--------|----------------|
| Contains `npx -y` | npm | `npm install -g <package>` |
| Contains `npm exec` | npm | `npm install -g <package>` |
| Contains `uvx` | uvx | `uv tool upgrade <package>` |
| Contains `pipx run` | pipx | `pipx upgrade <package>` |
| Contains `python -m` or `.py` (not in repo) | python | `pip install --upgrade <package>` |
| Contains `uv run` (not in repo) | python (uv) | `uv pip install --upgrade <package>` |
| Contains `dotnet tool run` | dotnet-tool | `dotnet tool update -g <tool>` |
| Contains `dnx` | dnx (.NET 10) | None (auto-managed) |
| Contains `docker run` | docker | `docker pull <image>` |
| Starts with `https://` or has `(HTTP)` | remote | None (server-managed) |

#### dnx (Auto-Managed .NET Packages)

`dnx` is .NET 10 SDK's equivalent of `npx`. Packages auto-resolve to the latest version on each run -- there is no local install to update.

- **Detection**: Command or args contain `dnx`
- **Classification**: `dnx (auto-managed)` in report
- **Prerequisite**: .NET 10+ SDK must be installed (check via `dotnet --version`, major >= 10)
- **Update action**: None required. If .NET SDK < 10, provide install guidance (see Step 6.5)
- **Report note**: Show `.NET SDK version` and confirm auto-resolution is active

#### Git Clone / Local Repository Patterns (Multi-Step Update)

These patterns require detecting when an MCP server points to a local file path that is inside a git repository.

| Pattern | Method | Update Sequence |
|---------|--------|-----------------|
| `node /path/to/repo/...` (with .git) | git-node | `git pull && npm install && npm run build` |
| `python /path/to/repo/...` (with .git) | git-python | `git pull && pip install -r requirements.txt` |
| `uv run --directory /path/to/repo ...` (with .git) | git-python-uv | `git pull && uv sync` |
| `dotnet run --project /path/to/repo` (with .git) | git-dotnet | `git pull && dotnet build` |
| `dotnet /path/to/repo/bin/...` (with .git) | git-dotnet | `git pull && dotnet build` |

**Git Repository Detection:**

1. Extract the directory path from the command arguments
2. Check if the directory contains a `.git` folder
3. If yes, classify as `git-*` method based on runtime (node/python/dotnet)
4. If no `.git` folder, classify as `unknown` (manual update required)

#### Plugin-Vendored Patterns

Detect `${CLAUDE_PLUGIN_ROOT}` in command or args as plugin-vendored servers. These are managed by their owning plugin, not by this command.

**Detection:**

1. Check if `args` (joined) or `command` contains `${CLAUDE_PLUGIN_ROOT}` as a literal string
2. Extract the plugin name from the source file path (e.g., `plugins/microsoft/.mcp.json` -> `microsoft`)

**For each plugin-vendored server:**

- Check for a `VERSION` file in the vendor root (e.g., `plugins/<plugin>/vendor/<server>/VERSION`)
- Look for a plugin update command (e.g., `/microsoft:mssql update`)
- If `--check` is passed, run the plugin's update command with `--check` to see if upstream has changes

**Classification**: `plugin-vendored` -- delegate to the plugin's own update command.

**Report format**: Show server name, owning plugin, current version/commit, and the update command to run.

#### Dotnet Tool Name Resolution

Binary names used in MCP configs may differ from dotnet tool package names (e.g., `aspire` binary is installed as `aspire.cli` package). Resolve the correct package name before updating.

**Resolution process:**

1. Run `dotnet tool list -g` to get the installed tools table (`Package Id | Version | Commands`)
2. Build a command-to-package lookup map: `aspire` -> `aspire.cli`, etc.
3. When updating a dotnet tool, use the resolved **package name** (not the binary name) for `dotnet tool update -g <package-name>`
4. If resolution fails (binary not found in tool list), warn and fall back to binary name

**Package Name Extraction:**

- For `npx -y package-name@latest` -> extract `package-name` (strip `@latest`)
- For `cmd /c npx -y package` -> extract `package` (ignore Windows wrapper)
- For scoped packages `@org/package@version` -> extract `@org/package`
- For git repos: extract repo name from path for display purposes
- For dotnet tools: use resolved package name from `dotnet tool list -g`

**Group servers by updateable status:**

- `updateable`: Servers with npm, python, uvx, pipx, dotnet-tool, docker, or git methods
- `remote`: HTTP/SSE servers (no local update needed)
- `dnx`: Auto-managed by .NET SDK (no update needed, verify SDK version)
- `plugin-vendored`: Managed by plugin update commands (delegate, not auto-updated here)
- `unknown`: Unrecognized command patterns (report for manual handling)

### Step 2.5: Dependency Detection & Setup Assistance

Before attempting updates, check if required tools are available. If missing, offer installation assistance with best practices.

#### Dependency Check Matrix

| Runtime/Tool | Detection Command | Required For |
|--------------|-------------------|--------------|
| node | `node --version` | npm, npx, git-node |
| npm | `npm --version` | npm packages |
| nvm | `nvm