MCP Configuration Management

What this skill does

# MCP Configuration Management

This skill provides comprehensive tooling for managing MCP (Model Context Protocol) server configurations, including templates, validation scripts, API key management, and installation helpers.

## What This Skill Provides

### 1. Helper Scripts (13 scripts - v2.1 added 7)

**Registry Management (v2.1+):**
- `scripts/registry-init.sh` - Initialize universal MCP registry at ~/.claude/mcp-registry/
- `scripts/registry-add.sh` - Add server to universal registry
- `scripts/registry-list.sh` - List all servers in registry
- `scripts/registry-sync.sh` - Sync registry to target format(s)
- `scripts/transform-claude.sh` - Transform registry → .mcp.json (Claude Code format)
- `scripts/transform-vscode.sh` - Transform registry → .vscode/mcp.json (VS Code format)

**Configuration Management:**
- `scripts/init-mcp-config.sh` - Initialize .mcp.json with proper structure
- `scripts/add-mcp-server.sh` - Add new MCP server to existing config
- `scripts/validate-mcp-config.sh` - Validate .mcp.json structure and server definitions
- `scripts/manage-api-keys.sh` - Securely manage API keys in project .env files (v2.1: .env-only mode)
- `scripts/install-mcp-server.sh` - Install and configure MCP server packages

### 2. Configuration Templates (8 templates - v2.1 added 2)

**Server Type Templates:**
- `templates/basic-mcp-config.json` - Basic .mcp.json structure
- `templates/stdio-server.json` - stdio MCP server configuration
- `templates/http-server.json` - HTTP MCP server configuration
- `templates/python-fastmcp.json` - Python FastMCP server setup
- `templates/typescript-server.json` - TypeScript MCP server setup
- `templates/multi-server-config.json` - Multiple MCP servers configuration

**Registry Templates (v2.1+):**
- `templates/.env.example` - Complete .env template with all known MCP API keys
- Global: `~/.claude/mcp-registry/marketplace.json` - VS Code marketplace servers reference

### 3. Usage Examples (5 examples)

**Documentation:**
- `examples/basic-setup.md` - Basic MCP configuration setup
- `examples/api-key-management.md` - Secure API key handling patterns
- `examples/multiple-servers.md` - Managing multiple MCP servers
- `examples/troubleshooting.md` - Common issues and solutions
- `examples/production-config.md` - Production-ready MCP configurations

## Instructions

### RECOMMENDED: Universal Registry Workflow (v2.1+)

**Best Practice**: Use the universal registry for managing MCP servers across multiple formats (Claude Code, VS Code, Gemini, Qwen, Codex).

#### Step 1: Initialize Registry (One-time)

```bash
bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/registry-init.sh
```

Creates:
- `~/.claude/mcp-registry/servers.json` - Universal server definitions
- `~/.claude/mcp-registry/marketplace.json` - VS Code marketplace reference
- `~/.claude/mcp-registry/backups/` - Automatic backups
- `~/.claude/mcp-registry/README.md` - Documentation

#### Step 2: Add Servers to Registry

```bash
# stdio server example (most common)
bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/registry-add.sh context7 \
  --transport stdio \
  --command npx \
  --args "-y,@upstash/context7-mcp" \
  --env "CONTEXT7_API_KEY=\${CONTEXT7_API_KEY}" \
  --description "Up-to-date library documentation"

# http-remote server example
bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/registry-add.sh supabase \
  --transport http-remote \
  --url "https://mcp.supabase.com/mcp" \
  --description "Supabase database access"

# http-remote-auth server example (VS Code only)
bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/registry-add.sh github \
  --transport http-remote-auth \
  --url "https://api.githubcopilot.com/mcp/" \
  --header "Authorization: Bearer \${GITHUB_TOKEN}" \
  --description "GitHub Copilot MCP API"
```

#### Step 3: Sync Registry to Project

```bash
# Sync to Claude Code format (.mcp.json)
bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/registry-sync.sh claude

# Sync to VS Code format (.vscode/mcp.json)
bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/registry-sync.sh vscode

# Sync to both formats
bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/registry-sync.sh both
```

#### Step 4: Configure API Keys

```bash
# Add API keys to project .env
bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/manage-api-keys.sh \
  --action add \
  --key-name CONTEXT7_API_KEY

# Use templates/.env.example as reference
```

#### Step 5: List and Search Registry

```bash
# List all servers
bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/registry-list.sh

# Or use jq directly
jq -r '.servers | to_entries[] | "\(.key) - \(.value.transport) - \(.value.description)"' \
  ~/.claude/mcp-registry/servers.json
```

### Initial MCP Configuration Setup (Direct Mode - Backward Compatible)

When user wants to set up MCP configuration:

1. **Check for existing configuration:**
   - Look for `.mcp.json` in project root or `~/.claude/` directory
   - Check if server is already configured

2. **Initialize configuration:**
   ```bash
   bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/init-mcp-config.sh [path]
   ```

3. **Use appropriate template:**
   - Read template from `templates/` directory
   - Customize based on server type (stdio, HTTP, Python, TypeScript)
   - Replace placeholder values with actual configuration

### Adding MCP Servers

To add a new MCP server to existing configuration:

1. **Execute add-mcp-server script:**
   ```bash
   bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/add-mcp-server.sh \
     --name "server-name" \
     --type "stdio|http" \
     --command "python" \
     --args "-m server_module" \
     --config-path ".mcp.json"
   ```

2. **Server types supported:**
   - **stdio**: Local process communication (most common)
   - **http**: Remote HTTP API servers
   - **sse**: Server-sent events (streaming)

3. **Common stdio configurations:**
   - Python FastMCP: `python -m fastmcp server_name`
   - TypeScript: `node dist/index.js`
   - Shell scripts: `bash ./server.sh`

### API Key Management

For servers requiring API keys or secrets:

1. **Create/update .env file:**
   ```bash
   bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/manage-api-keys.sh \
     --action add \
     --key-name "OPENAI_API_KEY" \
     --env-file ".env"
   ```

2. **Reference in MCP config:**
   - Use `${API_KEY}` syntax in .mcp.json
   - Keys are loaded from .env at runtime
   - Script ensures .env is in .gitignore

3. **Security best practices:**
   - Never commit API keys to version control
   - Use .env files for local development
   - Use environment variables in production
   - Rotate keys regularly

### Validating Configuration

Before using MCP configuration:

1. **Run validation script:**
   ```bash
   bash ~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/foundation/skills/mcp-configuration/scripts/validate-mcp-config.sh .mcp.json
   ```

2. **Validation checks:**
   - Valid JSON syntax
   - Required fields present (mcpServers object)
   - Server type is valid (stdio, http, sse)
   - Command paths exist for stdio servers
   - URLs are valid for HTTP servers
   - Environment variables are defined
   - No duplicate server names

3. **Auto-fix common issues:**
   - Script can sugg