# MCP-Prompts AWS Deployment
A production-ready AWS deployment of the MCP-Prompts ecosystem using serverless architecture with S3, SQS, and DynamoDB.
## 🏗️ Architecture
This implementation follows the hexagonal architecture pattern and deploys to AWS using:
- **AWS Lambda** - Serverless compute for MCP server and processing
- **API Gateway** - RESTful API endpoints with CORS support
- **DynamoDB** - NoSQL database for prompt metadata and caching
- **S3** - Object storage for prompt catalog and static assets
- **SQS** - Message queuing for asynchronous processing
- **CloudFront** - Global CDN for performance optimization
- **CloudWatch** - Monitoring, logging, and metrics
## 🚀 Quick Start
### Prerequisites
- Node.js 18+ and PNPM
- AWS CLI configured with appropriate permissions
- AWS CDK CLI (`npm install -g aws-cdk`)
### One-Command Deployment
Deploy everything to AWS
```
./scripts/deploy-aws.sh
```
### Manual Deployment
Install dependencies
```
pnpm install
```
Build project
```
pnpm run build
```
Deploy infrastructure
```
cd cdk
pnpm install
cdk bootstrap
cdk deploy --all
```
## 🔧 Configuration
### Environment Variables
AWS Configuration
```
AWS_REGION=us-east-1
AWS_ACCOUNT_ID=123456789012
```
DynamoDB Tables
```
PROMPTS_TABLE=mcp-prompts
SESSIONS_TABLE=mcp-sessions
```
S3 Buckets
```
PROMPTS_BUCKET=mcp-prompts-catalog-{account}-{region}
```
SQS Queues
```
PROCESSING_QUEUE=mcp-prompts-processing
CATALOG_SYNC_QUEUE=mcp-catalog-sync
```
Application
```
NODE_ENV=production
LOG_LEVEL=info
```
### AWS Permissions
The deployment creates minimal IAM roles with these permissions:
- **Lambda Execution Role**: CloudWatch Logs, VPC (if needed)
- **API Gateway Role**: Lambda invoke permissions
- **DynamoDB**: Read/write access to prompt tables
- **S3**: Read/write access to catalog bucket
- **SQS**: Send/receive/delete messages
- **CloudWatch**: PutMetricData permissions
## 📊 API Endpoints
### Health & Status
- `GET /health` - Service health check
- `GET /mcp` - MCP capabilities
### Prompts Management
- `GET /v1/prompts` - List prompts (supports ?category= and ?limit=)
- `POST /v1/prompts` - Create new prompt
- `GET /v1/prompts/{id}` - Get specific prompt
- `PUT /v1/prompts/{id}` - Update prompt
- `DELETE /v1/prompts/{id}` - Delete prompt
- `POST /v1/prompts/{id}/apply` - Apply template variables
### MCP Tools
- `GET /mcp/tools` - List available MCP tools
- `POST /mcp/tools` - Execute MCP tool
## 🔍 Monitoring
### CloudWatch Metrics
The deployment automatically creates custom metrics:
- **PromptAccessCount** - Prompt usage by ID and category
- **OperationLatency** - API response times
- **ApiSuccess/ApiError** - Success/error rates by endpoint
- **ProcessingLatency** - Background processing times
- **PromptCreated/Updated/Deleted** - CRUD operation counts
### CloudWatch Dashboards
After deployment, create dashboards to monitor:
1. **API Performance** - Latency, throughput, error rates
2. **DynamoDB Metrics** - Read/write capacity, throttles
3. **Lambda Metrics** - Duration, errors, concurrency
4. **S3 Usage** - Requests, data transfer, storage
### Alarms
Set up CloudWatch alarms for:
- API error rate > 5%
- Average latency > 1000ms
- DynamoDB throttling events
- Lambda error rate > 1%
- SQS dead letter queue messages
## 💰 Cost Optimization
### AWS Free Tier Usage
This deployment is optimized for AWS Free Tier:
- **Lambda**: 1M requests/month free
- **DynamoDB**: 25GB storage + 25 RCU/WCU free
- **S3**: 5GB storage + 20K GET + 2K PUT requests free
- **API Gateway**: 1M requests/month free
- **CloudWatch**: Basic monitoring free
### Estimated Monthly Costs
For moderate usage (beyond free tier):
| Service | Usage | Monthly Cost |
|---------|-------|--------------|
| Lambda | 2M requests | ~$4.00 |
| DynamoDB | 50GB + 100 RCU/WCU | ~$15.00 |
| S3 | 20GB storage | ~$0.50 |
| API Gateway | 2M requests | ~$7.00 |
| CloudWatch | Standard monitoring | ~$3.00 |
| **Total** | | **~$29.50** |
### Cost Reduction Tips
1. **Use DynamoDB On-Demand** for unpredictable workloads
2. **Enable S3 Intelligent Tiering** for automatic cost optimization
3. **Set up Lambda Provisioned Concurrency** only for critical functions
4. **Use CloudWatch Logs retention policies** to control log storage costs
5. **Monitor and right-size Lambda memory** allocation
## 🔒 Security
### Network Security
- **VPC Endpoints** for private AWS service access
- **Security Groups** restricting Lambda network access
- **WAF** protection for API Gateway (optional)
### Data Security
- **Encryption at rest** for DynamoDB and S3
- **Encryption in transit** via HTTPS/TLS
- **IAM roles** following least-privilege principle
- **API Gateway authentication** via Cognito (optional)
### Secrets Management
- **AWS Systems Manager Parameter Store** for configuration
- **AWS Secrets Manager** for sensitive data
- **Environment variables** for Lambda configuration
## 🧪 Testing
### Local Testing
Run unit tests
```
pnpm test
Test with local DynamoDB
```
docker run -p 8000:8000 amazon/dynamodb-local
export DYNAMODB_ENDPOINT=http://localhost:8000
pnpm run dev
```
### Integration Testing
Test deployed API
```
curl https://your-api-gateway-url/health
```
Test prompt creation
```
curl -X POST https://your-api-gateway-url/v1/prompts
-H "Content-Type: application/json"
-d '{"name": "test", "template": "Hello {{name}}", "category": "greeting"}'
```
## 🚨 Troubleshooting
### Common Issues
1. **403 Access Denied**
- Check IAM permissions
- Verify resource policies
- Check VPC configuration if using private subnets
2. **Lambda Timeout**
- Increase timeout in CDK stack
- Optimize cold start performance
- Check DynamoDB/S3 connection latency
3. **DynamoDB Throttling**
- Switch to On-Demand billing
- Optimize partition key distribution
- Implement exponential backoff
4. **High Costs**
- Review CloudWatch cost analysis
- Optimize Lambda memory allocation
- Implement S3 lifecycle policies
- Review DynamoDB read/write patterns
### Debug Commands
Check Lambda logs
```
aws logs describe-log-groups --log-group-name-prefix "/aws/lambda/McpPromptsStack"
```
Check DynamoDB table
```
aws dynamodb describe-table --table-name mcp-prompts
```
Check S3 bucket
```
aws s3 ls s3://your-bucket-name --recursive
```
Check SQS queue
```
aws sqs get-queue-attributes --queue-url your-queue-url --attribute-names All
```
## 🔄 CI/CD Pipeline
### GitHub Actions Workflow
```
name: Deploy to AWS
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- run: pnpm install
- run: pnpm run build
- run: pnpm run deploy
env:
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
```
## 📚 Further Reading
- [AWS CDK Documentation](https://docs.aws.amazon.com/cdk/)
- [DynamoDB Best Practices](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html)
- [Lambda Performance Optimization](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html)
- [API Gateway Throttling](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html)
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request
## 📄 License
MIT License - see LICENSE file for details.
