Initial commit
This commit is contained in:
Zhongwei Li
676
commands/deploy-mcp.md
Normal file
676
commands/deploy-mcp.md
Normal file
@@ -0,0 +1,676 @@
|
||||
---
|
||||
description: Deploy MCP server locally or with Docker
|
||||
argument-hint: 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:
|
||||
1. **Language**: Python or TypeScript?
|
||||
2. **Server Type**: stdio, SSE, or both?
|
||||
3. **Dependencies**: What external services are needed?
|
||||
4. **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:**
|
||||
|
||||
1. **Verify pyproject.toml:**
|
||||
```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"
|
||||
```
|
||||
|
||||
2. **Create distribution:**
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
1. **Verify package.json:**
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Build and test:**
|
||||
```bash
|
||||
# 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):**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-mcp-server": {
|
||||
"command": "uvx",
|
||||
"args": ["my-mcp-server"],
|
||||
"env": {
|
||||
"API_KEY": "your-api-key-here",
|
||||
"LOG_LEVEL": "info"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Python (local installation):**
|
||||
```json
|
||||
{
|
||||
"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):**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-mcp-server": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "my-mcp-server"],
|
||||
"env": {
|
||||
"API_KEY": "your-api-key-here",
|
||||
"LOG_LEVEL": "info"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**TypeScript (local installation):**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```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:**
|
||||
```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:**
|
||||
```yaml
|
||||
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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with actual values
|
||||
```
|
||||
|
||||
### Step 7: Create Comprehensive Documentation
|
||||
|
||||
**README.md:**
|
||||
```markdown
|
||||
# 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
|
||||
```
|
||||
|
||||
2. Configure Claude Desktop:
|
||||
|
||||
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-server": {
|
||||
"command": "uvx",
|
||||
"args": ["my-mcp-server"],
|
||||
"env": {
|
||||
"API_KEY": "your-api-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Restart Claude Desktop
|
||||
|
||||
### Local Installation
|
||||
|
||||
**Python:**
|
||||
```bash
|
||||
pip install my-mcp-server
|
||||
my-mcp-server
|
||||
```
|
||||
|
||||
**Node.js:**
|
||||
```bash
|
||||
npm install -g my-mcp-server
|
||||
my-mcp-server
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
1. Go to [service provider]
|
||||
2. Create account
|
||||
3. Generate API key
|
||||
4. 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
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
1. **Test package installation:**
|
||||
```bash
|
||||
# Python
|
||||
pip install -e .
|
||||
my-mcp-server --help
|
||||
|
||||
# TypeScript
|
||||
npm install
|
||||
npm run build
|
||||
node build/index.js --help
|
||||
```
|
||||
|
||||
2. **Test with MCP Inspector:**
|
||||
```bash
|
||||
mcp-inspector python -m my_mcp_server
|
||||
# or
|
||||
mcp-inspector node build/index.js
|
||||
```
|
||||
|
||||
3. **Test in Claude Desktop:**
|
||||
- Add to configuration
|
||||
- Restart Claude Desktop
|
||||
- Verify tools appear
|
||||
- Test tool execution
|
||||
|
||||
**Docker Testing:**
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```markdown
|
||||
# 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.
|
||||
Reference in New Issue
Block a user