zhongwei/gh-phaezer-claude-mkt-plugins-mcp

Files

Zhongwei Li 589fd01cad Initial commit

2025-11-30 08:47:15 +08:00

13 KiB

Raw Permalink Blame History

description, argument-hint

description	argument-hint
Deploy MCP server locally or with Docker	Deployment target (local/docker/both)

Deploy MCP Server

Deploy an MCP server for local usage (Claude Desktop, pip/npm) or Docker containers.

Usage

/deploy-mcp [target]

Arguments:

target: Deployment target - local, docker, or both (optional, defaults to local)

Examples:

/deploy-mcp local
/deploy-mcp docker
/deploy-mcp both

What This Command Does

This command handles the complete deployment workflow for MCP servers:

Local deployment (Claude Desktop integration, pip/npm packages)
Docker containerization
Configuration management
Documentation creation
Troubleshooting guides

Workflow Steps

Step 1: Detect Project Details

Analyze the project:

Language: Python or TypeScript?
Server Type: stdio, SSE, or both?
Dependencies: What external services are needed?
Configuration: What environment variables required?

Step 2: Launch Deployment Engineer Agent

Use the Task tool to launch mcp-deployment-engineer agent.

Agent Task:

Create deployment configuration for MCP server:

Project: [project name]
Location: [project path]
Language: [Python/TypeScript]
Transport: [stdio/SSE/both]
Target: [local/docker/both]

Requirements:
1. Local Deployment:
   - Claude Desktop configuration
   - Package configuration (pip/npm)
   - Installation documentation
   - Environment variable management

2. Docker Deployment (if requested):
   - Dockerfile optimized for size and security
   - Docker Compose configuration
   - Health checks
   - Volume management

3. Documentation:
   - Installation guide
   - Configuration guide
   - Troubleshooting guide
   - Usage examples

Deliverables:
- Claude Desktop config example
- Package configuration (pyproject.toml/package.json)
- Dockerfile and docker-compose.yml (if requested)
- .env.example with all variables
- Complete README.md
- Troubleshooting guide

Step 3: Prepare for Local Deployment

Python Package Preparation:

Verify pyproject.toml:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-mcp-server"
version = "0.1.0"
description = "MCP server for [purpose]"
requires-python = ">=3.11"
dependencies = [
    "fastmcp>=0.1.0",
    # other dependencies
]

[project.scripts]
my-mcp-server = "my_mcp_server.__main__:main"

Create distribution:

# Install build tools
pip install build

# Build package
python -m build

# Test installation locally
pip install dist/my_mcp_server-0.1.0-py3-none-any.whl

# Test running
my-mcp-server

TypeScript Package Preparation:

Verify package.json:

{
  "name": "my-mcp-server",
  "version": "0.1.0",
  "main": "./build/index.js",
  "bin": {
    "my-mcp-server": "./build/index.js"
  },
  "files": [
    "build",
    "README.md"
  ],
  "scripts": {
    "build": "tsc",
    "prepare": "npm run build"
  }
}

Build and test:

# Build
npm run build

# Test locally
npm link
my-mcp-server

# Or test with npx
npx .

Step 4: Create Claude Desktop Configuration

Generate Claude Desktop config for both uvx/npx and local installations:

Python (uvx - Recommended):

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "uvx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "your-api-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Python (local installation):

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "API_KEY": "your-api-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

TypeScript (npx - Recommended):

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": {
        "API_KEY": "your-api-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

TypeScript (local installation):

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/path/to/project/build/index.js"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

Step 5: Create Docker Configuration (if requested)

Python Dockerfile:

FROM python:3.11-slim as builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Copy and install
COPY pyproject.toml README.md ./
COPY src/ ./src/
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir .

# Production stage
FROM python:3.11-slim

WORKDIR /app

# Copy from builder
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin

# Non-root user
RUN useradd -m -u 1000 mcpuser && \
    chown -R mcpuser:mcpuser /app

USER mcpuser

# Health check
HEALTHCHECK --interval=30s --timeout=10s \
    CMD python -c "import sys; sys.exit(0)"

CMD ["my-mcp-server"]

TypeScript Dockerfile:

# Build stage
FROM node:18-slim as builder

WORKDIR /app

COPY package*.json tsconfig.json ./
COPY src/ ./src/
RUN npm ci && npm run build && npm prune --production

# Production stage
FROM node:18-slim

WORKDIR /app

COPY --from=builder /app/build ./build
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

# Non-root user
RUN useradd -m -u 1000 mcpuser && \
    chown -R mcpuser:mcpuser /app

USER mcpuser

HEALTHCHECK --interval=30s --timeout=10s \
    CMD node -e "process.exit(0)"

CMD ["node", "build/index.js"]

docker-compose.yml:

version: '3.8'

services:
  mcp-server:
    build: .
    container_name: my-mcp-server
    restart: unless-stopped
    environment:
      - API_KEY=${API_KEY}
      - LOG_LEVEL=${LOG_LEVEL:-info}
    # For stdio
    stdin_open: true
    tty: true
    # For SSE
    # ports:
    #   - "3000:3000"
    volumes:
      - ./data:/app/data
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

Step 6: Create Environment Configuration

Create .env.example:

# API Keys (REQUIRED)
API_KEY=your-api-key-here
GITHUB_TOKEN=ghp_your_github_token

# Database (if applicable)
DATABASE_URL=postgresql://user:pass@localhost:5432/db

# Server Configuration
SERVER_NAME=my-mcp-server
LOG_LEVEL=info

# Rate Limiting
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60

# Feature Flags
ENABLE_CACHING=true
CACHE_TTL=300

Create .env for local development:

cp .env.example .env
# Edit .env with actual values

Step 7: Create Comprehensive Documentation

README.md:

# My MCP Server

[Brief description]

## Features

- ✅ [Feature 1]
- ✅ [Feature 2]
- ✅ [Feature 3]

## Installation

### Quick Start (Claude Desktop)

1. Install the server:
   ```bash
   uvx my-mcp-server  # Python
   # or
   npx my-mcp-server  # Node.js

Configure Claude Desktop:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Restart Claude Desktop

Local Installation

Python:

pip install my-mcp-server
my-mcp-server

Node.js:

npm install -g my-mcp-server
my-mcp-server

Docker

# Build
docker build -t my-mcp-server .

# Run with stdio
docker run -i \
  -e API_KEY=your-key \
  my-mcp-server

# Or use docker-compose
docker-compose up -d

Configuration

Environment Variables

Variable	Required	Description	Default
API_KEY	Yes	API key for service	-
LOG_LEVEL	No	Logging level	info
RATE_LIMIT	No	Requests per minute	100

Getting API Keys

Go to [service provider]
Create account
Generate API key
Add to configuration

Available Tools

[List and document all tools]

Troubleshooting

Server not starting

Check environment variables are set
Verify API key is valid
Check logs for specific errors

Tools not appearing in Claude

Restart Claude Desktop
Check configuration file syntax
Verify server starts manually

Development

# Clone
git clone [repo]

# Install
pip install -e .[dev]  # or npm install

# Run tests
pytest  # or npm test

# Run locally
python -m my_mcp_server  # or npm run dev

License

MIT


**TROUBLESHOOTING.md:**
```markdown
# Troubleshooting Guide

## Installation Issues

### Python: Command not found

**Problem**: `my-mcp-server: command not found`

**Solutions**:
1. Verify installation: `pip list | grep my-mcp-server`
2. Check PATH includes pip bin directory
3. Reinstall: `pip install --force-reinstall my-mcp-server`

### Node.js: Module not found

**Problem**: `Cannot find module 'my-mcp-server'`

**Solutions**:
1. Verify installation: `npm list -g my-mcp-server`
2. Reinstall: `npm install -g my-mcp-server`
3. Try with npx: `npx my-mcp-server`

## Configuration Issues

[More troubleshooting content...]

Step 8: Test Deployment

Local Testing:

Test package installation:

# Python
pip install -e .
my-mcp-server --help

# TypeScript
npm install
npm run build
node build/index.js --help

Test with MCP Inspector:

mcp-inspector python -m my_mcp_server
# or
mcp-inspector node build/index.js

Test in Claude Desktop:

Add to configuration
Restart Claude Desktop
Verify tools appear
Test tool execution

Docker Testing:

# Build image
docker build -t my-mcp-server:test .

# Test stdio
docker run -i -e API_KEY=test my-mcp-server:test

# Test with inspector
docker run -i my-mcp-server:test | mcp-inspector -

# Check image size
docker images my-mcp-server:test

Step 9: Create Deployment Checklist

# Deployment Checklist

## Pre-Deployment
- [ ] All tests passing
- [ ] Security review complete
- [ ] Documentation complete
- [ ] Version number updated
- [ ] CHANGELOG updated

## Package Configuration
- [ ] pyproject.toml/package.json correct
- [ ] Dependencies specified
- [ ] Entry points configured
- [ ] Build succeeds
- [ ] Package installs locally

## Claude Desktop
- [ ] Config example created
- [ ] Environment variables documented
- [ ] Installation instructions clear
- [ ] Tested with real Claude Desktop

## Docker (if applicable)
- [ ] Dockerfile optimized
- [ ] Image builds successfully
- [ ] Image size reasonable (<500MB)
- [ ] Health check works
- [ ] Non-root user configured
- [ ] docker-compose.yml provided

## Documentation
- [ ] README complete
- [ ] API documentation clear
- [ ] Configuration documented
- [ ] Troubleshooting guide provided
- [ ] Examples included

## Testing
- [ ] Tested locally
- [ ] Tested with MCP Inspector
- [ ] Tested in Claude Desktop
- [ ] Tested with Docker (if applicable)

Step 10: Provide Deployment Summary

✓ Deployment Configuration Complete: [project-name]

Local Deployment:
  ✓ Claude Desktop config created
  ✓ Package configuration ready
  ✓ Installation instructions documented

  Installation:
    Python: uvx my-mcp-server
    Node.js: npx my-mcp-server

  Claude Desktop Config:
    Location: ~/Library/Application Support/Claude/claude_desktop_config.json
    Example: ./claude-desktop-config.example.json

Docker Deployment:
  ✓ Dockerfile created (optimized, 180MB)
  ✓ docker-compose.yml created
  ✓ Health checks configured
  ✓ Non-root user configured

  Build: docker build -t my-mcp-server .
  Run: docker-compose up -d

Documentation:
  ✓ README.md complete
  ✓ TROUBLESHOOTING.md created
  ✓ .env.example provided
  ✓ Usage examples included

Next Steps:
1. Test deployment locally:
   - Install: uvx my-mcp-server
   - Configure Claude Desktop
   - Restart Claude Desktop
   - Test tools

2. (Optional) Publish package:
   Python: python -m build && twine upload dist/*
   Node.js: npm publish

3. (Optional) Deploy Docker:
   docker-compose up -d

Files created:
  - claude-desktop-config.example.json
  - Dockerfile
  - docker-compose.yml
  - .env.example
  - README.md
  - TROUBLESHOOTING.md

Success Criteria

Deployment configuration created
Claude Desktop config example provided
Package configuration verified
Docker configuration created (if requested)
Environment variables documented
Comprehensive documentation created
Installation tested
User has clear deployment instructions

This command provides production-ready deployment configuration for MCP servers across multiple platforms.

13 KiB Raw Permalink Blame History