npm package: @iflow-mcp/mcp-prompts
Description: A robust, extensible server for managing, versioning, and serving prompts and templates for LLM applications, built on the Model Context Protocol (MCP) with AWS integration
Author: sparesparrow
Latest version: 3.12.4

# MCP-Prompts

A robust, extensible server for managing, versioning, and serving prompts and templates for LLM applications, built on the Model Context Protocol (MCP) with multi-backend support including AWS, PostgreSQL, and file storage.

## ✨ Features

- **🔄 Multiple Storage Backends**: DynamoDB, PostgreSQL, and local file storage
- **📦 Model Context Protocol**: Full MCP compliance for seamless AI integration
- **🏗️ Hexagonal Architecture**: Clean separation of concerns with adapter pattern
- **⚡ Serverless Ready**: AWS Lambda deployment with API Gateway
- **🔍 Advanced Querying**: Filter by category, tags, and metadata
- **📊 Version Control**: Complete prompt versioning and history
- **🔐 Enterprise Security**: IAM, VPC, and encryption support
- **💳 Subscription Management**: Free and premium tiers with Stripe integration
- **🎯 Slash Commands**: Quick prompt execution with commands like "/code-review"
- **🌐 Web Interface**: Modern web app for prompt management and user accounts
- **📈 Monitoring**: CloudWatch metrics and comprehensive logging
- **🧪 Testing**: Full test suite with local development support

## 🚀 Quick Start

### Prerequisites

- **Node.js 18+** and **PNPM**
- **AWS CLI** (for AWS deployments)
- **PostgreSQL** (for database deployments)
- **Docker** (for containerized deployments)

### Choose Your Deployment

#### 🏠 Local Development (File Storage)
```bash
# Install dependencies
pnpm install

# Start with memory storage (fastest)
STORAGE_TYPE=memory pnpm run dev

# Or use file storage
STORAGE_TYPE=file PROMPTS_DIR=./data/prompts pnpm run dev
```

#### 🐘 PostgreSQL Database
```bash
# Deploy with PostgreSQL
./scripts/deploy-postgres.sh

# Or run locally
STORAGE_TYPE=postgres pnpm run dev
```

#### ☁️ AWS Production (Recommended)
```bash
# One-command AWS deployment
./scripts/deploy-aws-enhanced.sh
```

### 🎯 New Features

#### Subscription Management
- **Free Tier**: Access to 5 public prompts, basic features
- **Premium Tier**: Unlimited access, upload custom prompts, advanced features
- **Stripe Integration**: Secure payment processing with webhooks

#### Slash Commands
Execute prompts quickly using slash commands:
```
/code-review - Review code for best practices
/bug-analyzer - Analyze bug reports
/documentation - Generate documentation
```

#### Web Interface
Modern web application for:
- User registration and login
- Prompt browsing and management
- Subscription management
- Slash command execution

### 🚀 Complete Deployment

```bash
# 1. Deploy infrastructure
cd cdk && cdk deploy --all

# 2. Build application
pnpm run build

# 3. Deploy Lambda functions
./scripts/deploy-aws.sh

# 4. Deploy web interface
./scripts/deploy-web.sh <web-bucket-name>

# 5. Configure Stripe (optional)
export STRIPE_SECRET_KEY=sk_test_...
export STRIPE_WEBHOOK_SECRET=whsec_...
```

## 📋 Table of Contents

- [Architecture](#-architecture)
- [Storage Types](#-storage-types)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [API Reference](#-api-reference)
- [MCP Integration](#-mcp-integration)
- [AWS Deployment](#-aws-deployment)
- [Monitoring](#-monitoring)
- [Testing](#-testing)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)

## 🏗️ Architecture

This project follows **hexagonal architecture** (ports & adapters) with clean separation between:

- **Core Business Logic**: Prompt management, versioning, and validation
- **Ports**: Interfaces for storage, events, and external services
- **Adapters**: Concrete implementations (DynamoDB, PostgreSQL, S3, etc.)
- **Infrastructure**: AWS services, HTTP servers, and CLI tools

### Component Diagram

```
┌─────────────────────────────────────┐
│           Presentation Layer        │
│  ┌─────────────┐ ┌────────────────┐ │
│  │   CLI Tool  │ │  HTTP Server   │ │
│  └─────────────┘ └────────────────┘ │
└─────────────────────────────────────┘
                 │
┌─────────────────────────────────────┐
│         Application Layer           │
│  ┌────────────────────────────────┐ │
│  │  Prompt Service & Use Cases   │ │
│  └────────────────────────────────┘ │
└─────────────────────────────────────┘
                 │
┌─────────────────────────────────────┐
│            Domain Layer             │
│  ┌────────────────────────────────┐ │
│  │  Prompt Entities & Business   │ │
│  │        Logic                  │ │
│  └────────────────────────────────┘ │
└─────────────────────────────────────┘
                 │
┌─────────────────────────────────────┐
│         Infrastructure Layer        │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐    │
│  │DDB  │ │PG   │ │S3   │ │SQS  │    │
│  │Adapter│ │Adapter│ │Adapter│ │Adapter│   │
│  └─────┘ └─────┘ └─────┘ └─────┘    │
└─────────────────────────────────────┘
```

## 🔄 Storage Types

### 1. 📁 File Storage (Development)

**Best for:** Development, testing, offline usage

**Features:**
- Simple JSON file-based storage
- No external dependencies
- Easy backup and migration
- Perfect for local development

**Configuration:**
```bash
STORAGE_TYPE=file
PROMPTS_DIR=./data/prompts
```

**Usage:**
```bash
STORAGE_TYPE=file pnpm run dev
```

### 2. 🐘 PostgreSQL Database

**Best for:** Production applications, complex queries, ACID compliance

**Features:**
- Full ACID compliance
- Complex queries and indexing
- Session management
- Backup and restore capabilities
- Concurrent access support

**Configuration:**
```bash
STORAGE_TYPE=postgres
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mcp_prompts
DB_USER=mcp_user
DB_PASSWORD=secure_password
```

**Deployment:**
```bash
./scripts/deploy-postgres.sh
```

### 3. ☁️ AWS Services (Production)

**Best for:** Scalable production, cloud-native deployments

**Features:**
- DynamoDB for metadata storage
- S3 for catalog and assets
- SQS for event processing
- API Gateway for HTTP endpoints
- CloudFront for global CDN
- CloudWatch for monitoring

**Configuration:**
```bash
STORAGE_TYPE=aws
AWS_REGION=us-east-1
PROMPTS_TABLE=mcp-prompts
PROMPTS_BUCKET=mcp-prompts-catalog
PROCESSING_QUEUE=mcp-prompts-processing
```

**Deployment:**
```bash
./scripts/deploy-aws-enhanced.sh
```

### 4. 💾 Memory Storage (Testing)

**Best for:** Unit testing, CI/CD pipelines, temporary deployments

**Features:**
- In-memory storage
- No persistence
- Fastest performance
- Sample data included

**Configuration:**
```bash
STORAGE_TYPE=memory
```

## 📦 Installation

### NPM Package

```bash
# Install globally
npm install -g @sparesparrow/mcp-prompts

# Or use with npx
npx @sparesparrow/mcp-prompts --help
```

### From Source

```bash
# Clone repository
git clone https://github.com/sparesparrow/mcp-prompts.git
cd mcp-prompts

# Install dependencies
pnpm install

# Build project
pnpm run build

# Run locally
STORAGE_TYPE=memory pnpm run dev
```

### Docker

```bash
# Build image
docker build -t mcp-prompts .

# Run with different storage types
docker run -p 3000:3000 -e STORAGE_TYPE=memory mcp-prompts
docker run -p 3000:3000 -e STORAGE_TYPE=file -v $(pwd)/data:/app/data mcp-prompts
```

## ⚙️ Configuration

### Environment Variables

#### Core Configuration

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `STORAGE_TYPE` | Storage backend (memory/file/postgres/aws) | `memory` | Yes |
| `NODE_ENV` | Environment (development/production) | `development` | No |
| `LOG_LEVEL` | Logging level (debug/info/warn/error) | `info` | No |
| `PORT` | HTTP server port | `3000` | No |

#### File Storage Configuration

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `PROMPTS_DIR` | Directory for prompt files | `./data/prompts` | No |

#### PostgreSQL Configuration

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `DB_HOST` | Database host | `localhost` | Yes |
| `DB_PORT` | Database port | `5432` | No |
| `DB_NAME` | Database name | `mcp_prompts` | No |
| `DB_USER` | Database user | - | Yes |
| `DB_PASSWORD` | Database password | - | Yes |
| `DB_SSL` | Enable SSL connection | `false` | No |

#### AWS Configuration

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `AWS_REGION` | AWS region | `us-east-1` | Yes (for AWS storage) |
| `AWS_PROFILE` | AWS profile name | `default` | No |
| `PROMPTS_TABLE` | DynamoDB table name | `mcp-prompts` | No |
| `SESSIONS_TABLE` | Sessions table name | `mcp-sessions` | No |
| `PROMPTS_BUCKET` | S3 bucket name | `mcp-prompts-catalog-{account}-{region}` | No |
| `PROCESSING_QUEUE` | SQS queue URL | - | No |
| `CATALOG_SYNC_QUEUE` | Catalog sync queue URL | - | No |

## 🔌 API Reference

### REST API Endpoints

#### Health & Status
- `GET /health` - Service health check with component status
- `GET /mcp` - MCP server capabilities and supported features

#### Prompts Management
- `GET /v1/prompts` - List prompts with optional filtering
  - Query parameters: `?category=`, `?limit=`, `?offset=`, `?tags=`
- `POST /v1/prompts` - Create new prompt
- `GET /v1/prompts/{id}` - Get specific prompt by ID
- `PUT /v1/prompts/{id}` - Update existing 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 with parameters

### Request/Response Examples

#### Create Prompt
```bash
curl -X POST http://localhost:3000/v1/prompts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Review Assistant",
    "description": "Advanced code review helper",
    "template": "Please review this {{language}} code:\n\n```{{language}}\n{{code}}\n```\n\nFocus on:\n- Security issues\n- Performance\n- Best practices",
    "category": "development",
    "tags": ["code-review", "security", "performance"],
    "variables": [
      {"name": "language", "description": "Programming language", "type": "string", "required": true},
      {"name": "code", "description": "Code to review", "type": "string", "required": true}
    ]
  }'
```

#### Apply Template
```bash
curl -X POST http://localhost:3000/v1/prompts/code_review_assistant/apply \
  -H "Content-Type: application/json" \
  -d '{
    "language": "typescript",
    "code": "function hello() { console.log(\"Hello World\"); }"
  }'
```

## 🤖 MCP Integration

### Model Context Protocol Support

MCP-Prompts implements the full Model Context Protocol specification, making it compatible with any MCP-compatible AI assistant or IDE.

#### MCP Server Modes

1. **HTTP Mode** (Default): REST API server
2. **MCP Mode**: Native MCP protocol server
3. **CLI Mode**: Command-line interface

#### Connecting to AI Assistants

**Claude Desktop:**
```json
{
  "mcpServers": {
    "mcp-prompts": {
      "command": "npx",
      "args": ["@sparesparrow/mcp-prompts"],
      "env": {
        "STORAGE_TYPE": "aws",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}
```

**VS Code Extension:**
```json
{
  "mcp": {
    "servers": {
      "prompts": {
        "command": "npx",
        "args": ["@sparesparrow/mcp-prompts"],
        "options": {
          "env": {
            "STORAGE_TYPE": "aws",
            "AWS_REGION": "us-east-1"
          }
        }
      }
    }
  }
}
```

#### Available MCP Tools

- **list_prompts**: Browse available prompts by category
- **get_prompt**: Retrieve specific prompt with full details
- **create_prompt**: Create new prompts programmatically
- **update_prompt**: Modify existing prompts
- **delete_prompt**: Remove prompts
- **apply_prompt**: Apply template variables to generate final prompts

## ☁️ AWS Deployment

### Architecture Overview

The AWS deployment creates a production-ready serverless architecture:

- **API Gateway** - RESTful API endpoints with CORS
- **Lambda Functions** - Serverless compute (MCP server, processing, catalog sync)
- **DynamoDB** - NoSQL storage with global secondary indexes
- **S3** - Object storage for catalog and assets
- **SQS** - Message queuing for async processing
- **CloudFront** - Global CDN for performance
- **CloudWatch** - Monitoring, logging, and metrics

### Quick AWS Deployment

```bash
# Prerequisites: AWS CLI configured
aws configure

# One-command deployment
./scripts/deploy-aws-enhanced.sh
```

### Manual AWS Deployment

```bash
# Install dependencies
pnpm install

# Build project
pnpm run build

# Deploy CDK infrastructure
cd cdk
pnpm install
cdk bootstrap aws://$AWS_ACCOUNT/$AWS_REGION
cdk deploy --all --require-approval never
```

### AWS Configuration

### AWS Permissions

The deployment creates minimal IAM roles following least-privilege:

| Service | Permissions | Purpose |
|---------|-------------|---------|
| **Lambda** | CloudWatch Logs, VPC access | Function execution and logging |
| **DynamoDB** | Read/write access to tables | Prompt and session storage |
| **S3** | Read/write access to bucket | Catalog storage and assets |
| **SQS** | Send/receive/delete messages | Async processing queues |
| **CloudWatch** | PutMetricData, CreateLogGroups | Monitoring and metrics |

### AWS Cost Optimization

**Free Tier Usage:**
- Lambda: 1M requests/month
- DynamoDB: 25GB storage + 25 RCU/WCU
- S3: 5GB storage + 20K GET + 2K PUT requests
- API Gateway: 1M requests/month

**Estimated Monthly Costs** (beyond free tier):
- **$25-35/month** for moderate usage
- Scales with usage, no fixed costs

### AWS Security Features

- **Encryption at rest** (DynamoDB, S3)
- **Encryption in transit** (HTTPS/TLS)
- **IAM roles** with minimal permissions
- **CloudTrail** audit logging
- **VPC support** (optional)

## 📊 Monitoring

### CloudWatch Metrics

Automatic custom metrics:

- **PromptAccessCount** - Usage tracking by prompt/category
- **OperationLatency** - API response times
- **ApiSuccess/ApiError** - Success/error rates
- **ProcessingLatency** - Background processing times
- **PromptCreated/Updated/Deleted** - CRUD operations

### Health Checks

```bash
# Check all services
curl https://your-api-gateway-url/health

# Expected response
{
  "status": "healthy",
  "services": {
    "dynamodb": {"status": "healthy"},
    "s3": {"status": "healthy"},
    "sqs": {"status": "healthy"}
  }
}
```

### CloudWatch Alarms

Recommended alarms:
- API error rate > 5%
- Average latency > 1000ms
- DynamoDB throttling events
- Lambda error rate > 1%
- SQS dead letter messages > 0

## 🔒 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 Development Testing

```bash
# Run unit tests
pnpm test

# Test with local DynamoDB
docker run -p 8000:8000 amazon/dynamodb-local
export DYNAMODB_ENDPOINT=http://localhost:8000
STORAGE_TYPE=memory pnpm run dev
```

### Integration Testing

```bash
# Test health endpoint
curl http://localhost:3000/health

# Test prompts API
curl http://localhost:3000/v1/prompts

# Test prompt creation
curl -X POST http://localhost:3000/v1/prompts \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "template": "Hello {{name}}", "category": "greeting"}'
```

### AWS Integration Testing

```bash
# Test deployed API
curl https://your-api-gateway-url/health

# Test with AWS credentials
AWS_REGION=us-east-1 npx @sparesparrow/mcp-prompts list
```

## 🚨 Troubleshooting

### Common Issues

#### AWS Deployment Issues

1. **403 Access Denied**
   - Check IAM permissions for your AWS user/role
   - Verify resource policies on DynamoDB/S3
   - Check VPC configuration if using private subnets

2. **CDK Bootstrap Required**
   ```bash
   cdk bootstrap aws://ACCOUNT/REGION
   ```

3. **Lambda Timeout**
   - Increase timeout in CDK stack (default: 30s)
   - Optimize cold start performance
   - Check DynamoDB/S3 connection latency

4. **DynamoDB Throttling**
   - Switch to On-Demand billing mode
   - Optimize partition key distribution
   - Implement exponential backoff in clients

#### Storage Issues

5. **PostgreSQL Connection Failed**
   - Verify database credentials
   - Check network connectivity
   - Ensure database is running and accessible

6. **File Storage Permissions**
   ```bash
   chmod -R 755 data/
   ```

#### MCP Integration Issues

7. **MCP Server Not Connecting**
   - Verify environment variables are set
   - Check AWS credentials for cloud storage
   - Ensure correct MCP server mode

### Debug Commands

#### AWS Services
```bash
# 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
```

#### Local Development
```bash
# Check application logs
tail -f logs/mcp-prompts.log

# Test database connectivity
STORAGE_TYPE=postgres pg_isready -h localhost -p 5432

# Check Node.js processes
ps aux | grep mcp-prompts
```

### Performance Tuning

#### Lambda Optimization
- Increase memory allocation (more CPU)
- Use provisioned concurrency for latency-sensitive functions
- Optimize package size and dependencies

#### Database Optimization
- Use appropriate indexes
- Implement connection pooling
- Monitor query performance

## 🔄 CI/CD Pipeline

### GitHub Actions Workflows

The repository includes several CI/CD workflows:

1. **CI/CD Pipeline** (`.github/workflows/ci-cd.yml`)
   - Tests on multiple storage types
   - Builds and pushes Docker images
   - Deploys to AWS
   - Publishes to NPM

2. **Multi-Platform Docker Build** (`.github/workflows/docker-multi-platform.yml`)
   - Builds for multiple architectures
   - Pushes to GitHub Container Registry

3. **AWS Deployment** (`.github/workflows/aws-deploy.yml`)
   - Automated AWS deployment
   - Health checks and smoke tests

### Required Secrets

Configure these secrets in your GitHub repository:

```bash
# AWS Deployment
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REGION

# NPM Publishing
NPM_TOKEN

# Security Scanning
SNYK_TOKEN
```

### Manual Deployment

```bash
# Install dependencies
pnpm install

# Build project
pnpm run build

# Run tests
pnpm test

# Deploy to AWS
./scripts/deploy-aws-enhanced.sh

# Or deploy to Docker
./scripts/deploy-docker.sh
```

## 📚 Further Reading

### AWS Documentation
- [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)

### MCP Protocol
- [Model Context Protocol Specification](https://github.com/modelcontextprotocol/specification)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)

### Development
- [Hexagonal Architecture](https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cunning-architect/)
- [TypeScript Best Practices](https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html)

## 🤝 Contributing

### Development Setup

1. **Fork the repository**
2. **Clone your fork**
   ```bash
   git clone https://github.com/your-username/mcp-prompts.git
   cd mcp-prompts
   ```
3. **Install dependencies**
   ```bash
   pnpm install
   ```
4. **Create feature branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```
5. **Make changes and test**
   ```bash
   pnpm test
   pnpm run build
   ```
6. **Submit pull request**

### Guidelines

- Follow existing code style and patterns
- Add tests for new functionality
- Update documentation for API changes
- Use conventional commit messages
- Test across all storage backends

### Architecture Decisions

- **Hexagonal Architecture**: Ports & Adapters pattern
- **Storage Adapters**: Pluggable storage implementations
- **MCP Compliance**: Full protocol implementation
- **TypeScript**: Strict typing throughout

## 📄 License

**MIT License** - see [LICENSE](LICENSE) file for details.

Copyright (c) 2024 Sparre Sparrow

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.