Account-Link/mcp-prompt-library

MCP Prompt Manager

A simple, focused prompt manager built on the Model Context Protocol (MCP). This project extracts the core functionality from the larger MCP Prompts ecosystem into a minimal, well-tested implementation.

🎯 Motivation

The original MCP Prompts project offers many features but has grown complex over time. This project takes a different approach by focusing on the core functionality that users actually need:

• Extract the working core - reliable storage with atomic operations
• Focus on simplicity - do one thing well
• Ensure test coverage - every feature has working tests
• Provide clear value - a prompt manager that's easy to understand and use

🏗️ Architecture

Core Components

src/
├── types.ts          # Prompt interface and schemas
├── postgres-storage.ts # PostgreSQL storage implementation
├── prompt-service.ts # Business logic and validation
├── template-engine.ts # Variable substitution engine
├── mcp-server.ts     # MCP protocol integration
└── index.ts          # Entry point and server startup

tests/
├── template-engine.test.ts

Key Features

1. PostgreSQL Storage

   • Full database persistence with versioning
   • Atomic transactions for data integrity
   • Efficient querying with indexes

2. Schema Validation

   • Zod schemas for all data
   • Type-safe operations
   • Clear error messages

3. MCP Integration

   • Full MCP server implementation
   • Tools: add, get, list, update, delete prompts
   • Resources: expose prompts as MCP resources

4. Template System

   • Variable substitution with {{variables}}
   • Validation of required variables
   • Support for default values

🚀 Quick Start

Option 1: Docker (Recommended)

The easiest way to run the MCP Prompt Library is using Docker:

# Clone the repository
git clone <repository>
cd mcp-prompt-library

# Start the services (PostgreSQL + MCP Server)
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs mcp-server
docker-compose logs postgres

# Stop services
docker-compose down

The MCP server will be available at http://localhost:8080/mcp for HTTP clients.

Note: Docker uses a default password (mcp_password_123) for PostgreSQL. To use a custom password, set the POSTGRES_PASSWORD environment variable.

Option 2: Local Development

For development and testing:

cd mcp-prompt-library
npm install

Test Database Setup

The project uses a separate test database in the same PostgreSQL container to avoid affecting your actual prompts during testing:

• Test Database: mcp_prompts_test (same container as main database)
• Main Database: mcp_prompts (same container as test database)

The test database uses the exact same schema as the main database and is automatically managed by the test runner, but you can also manage it manually:

# Set up test database manually
npm run test:db:setup

# Check test database status
npm run test:db:status

# Clean test database (removes test database)
npm run test:db:clean

Note: Your actual prompts are stored in the main database and are completely isolated from tests.

Development

# Run tests (uses separate test database)
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Test database management
npm run test:db:setup    # Set up test database
npm run test:db:status   # Check test database status
npm run test:db:clean    # Clean test database

# Run linting
npm run lint

# Test MCP server (spawns server once for testing)
npm run dev:test

# Run server once (for manual testing)
npm run dev

# Build for production
npm run build

Usage

# Start the MCP server (production)
npm start

# Or with npx
npx mcp-prompt-library

MCP Development Workflow

Important: MCP servers are designed to be stateless and spawned fresh for each request. The server should not be kept alive persistently.

• For testing: Use npm run dev:test to test MCP communication
• For manual testing: Use npm run dev to run the server once
• For production: Use npm start or npx mcp-prompt-library

Docker vs Local Development

Note: Both Docker and local development work well with Cursor's MCP client.

📋 Implementation Plan

Phase 1: Core Foundation ✅ COMPLETED

• Set up project structure and dependencies
• Implement Prompt interface and Zod schemas
• Create PostgresPromptRepository with database operations
• Add comprehensive tests for PostgreSQL storage
• Basic MCP server integration

Phase 2: Features ✅ COMPLETED

• Template variable substitution engine
• Complete MCP tools and resources
• CLI commands for basic operations
• Health check endpoint
• Configuration management

Phase 3: Polish ✅ COMPLETED

• Better error handling and logging
• Security hardening (path traversal protection)
• Documentation and examples
• Performance optimizations

🧪 Testing Strategy

Unit Tests

• PostgreSQL storage operations (CRUD, versioning)
• Schema validation with Zod 3.22.4
• Template variable substitution
• Error handling
• Database transaction safety

Integration Tests

• MCP server communication
• End-to-end prompt operations
• CLI command execution

Test Coverage

• 117 tests passing across all core functionality
• 58.35% overall coverage with 100% coverage on critical business logic
• 91.63% coverage on PostgreSQL storage (core functionality)
• 100% coverage on prompt service and template engine
• Security tests for path traversal protection
• Performance: Tests complete in ~2.34 seconds
• Code Quality: 0 errors, 12 warnings (acceptable for error handling)

🎯 Success Criteria

A successful implementation will:

1. Store prompts safely - No data corruption, atomic database transactions
2. Validate everything - Reject invalid data with clear errors using Zod schemas
3. Work with MCP clients - Claude Desktop, Cursor, etc. via JSON-RPC
4. Have comprehensive tests - Every feature tested (117 tests passing)
5. Be simple to understand - Clear, focused codebase with minimal dependencies
6. Be easy to extend - Well-defined interfaces and modular architecture
7. Be secure - Protected against SQL injection and input validation

🔄 Comparison with Original

📚 MCP Integration

This server implements the Model Context Protocol to provide:

Tools

• add_prompt - Create a new prompt
• get_prompt - Retrieve a prompt by ID
• list_prompts - List all prompts with filtering
• update_prompt - Update an existing prompt
• delete_prompt - Delete a prompt
• search_prompts - Search prompts by content, name, or tags
• get_stats - Get statistics about stored prompts
• apply_template - Apply variables to a template

Resources

• prompts - List of all prompts
• prompt/{id} - Individual prompt details

Configuration

For Cursor (Local Development)

Add to your MCP client configuration:

{
  "mcpServers": {
    "mcp-prompt-library": {
      "command": "node",
      "args": ["/path/to/mcp-prompt-library/dist/index.js"],
      "cwd": "/path/to/mcp-prompt-library"
    }
  }
}

For Cursor (Docker/HTTP)

For HTTP-based MCP server (Docker deployment):

{
  "mcpServers": {
    "mcp-prompt-library": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

For HTTP Clients (Docker)

The containerized server is available at http://localhost:8080/mcp and accepts standard MCP JSON-RPC requests.

Note: Both Docker and local development configurations work well with Cursor's MCP client.

🛠️ Development

Prerequisites

• Node.js 20+ (for local development)
• Docker and Docker Compose (for containerized deployment)
• npm or pnpm

Setup

Local Development

git clone <repository>
cd mcp-prompt-library
npm install
npm test

Docker Development

git clone <repository>
cd mcp-prompt-library

# Build and start services
docker-compose up -d --build

# View logs
docker-compose logs -f mcp-server

# Rebuild after changes
docker-compose build mcp-server
docker-compose up -d

Adding Features

1. Write tests first
2. Implement the feature
3. Ensure all tests pass
4. Update documentation

Docker Troubleshooting

Verify Container Status

# Check if containers are running
docker-compose ps

# Check container logs
docker-compose logs mcp-server
docker-compose logs postgres

# Check container health
docker exec mcp-prompt-server ps aux

Common Issues

1. Port conflicts: Ensure ports 8080 and 5433 are available
2. Database connection: Check if PostgreSQL container is healthy
3. Build issues: Rebuild with docker-compose build --no-cache mcp-server
4. Password issues: Docker uses default password mcp_password_123. To customize, set POSTGRES_PASSWORD environment variable

Reset Everything

# Stop and remove everything
docker-compose down -v

# Remove all images
docker rmi mcp-prompt-library-mcp-server

# Start fresh
docker-compose up -d --build

📄 License

MIT License - see LICENSE file for details.