Initial commit
This commit is contained in:
Zhongwei Li
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.
|
||||
Reference in New Issue
Block a user