MCP Prompt Manager

A production-ready, Git-driven Model Context Protocol (MCP) Server for managing and sharing Prompt templates across teams. Store your prompts in Git, sync automatically, and use dynamic templates in Cursor, Claude Desktop, VS Code, and other MCP-compatible AI assistants.

✨ Key Features

🔄 Git-Driven Synchronization

• Automatic synchronization from Git repositories
• Support for multiple repository URLs
• System repository for common prompts
• Watch mode with automatic change detection

🎯 Dynamic Templates

• Handlebars Template Engine: Create powerful, reusable prompts with Handlebars syntax
• Partials Support: Split and reuse prompt fragments (e.g., role settings, output formats)
• Variables & Conditionals: Dynamic content based on context

🚀 Zero-Downtime Updates

• Hot Reload: Update prompts without restarting the server
• Live Sync: Automatic detection of Git and file changes
• Version Management: Built-in prompt versioning and state tracking

📊 Smart Management

• Group Filtering: Load only the prompts you need
• Cache System: LRU eviction with TTL support and statistics
• Error Handling: Comprehensive error reporting and statistics
• Health Monitoring: System health status and prompt statistics

🐳 Production Ready

• Docker Support: Multi-stage builds with production configurations
• Kubernetes: Helm chart for easy deployment
• Type Safe: Full TypeScript with Zod validation
• 87%+ Test Coverage: 463+ tests with comprehensive CI/CD

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 8.0.0 (or npm/yarn)
• Git repository with your prompts (or local path)

Installation

Option 1: Marketplace Installation (Easiest)

If you're installing from this marketplace, follow the marketplace's installation instructions. After installation, configure your MCP client.

Option 2: Docker Deployment (Recommended)

# 1. Clone the repository
git clone https://github.com/CarlLee1983/mcp-prompt-manager.git
cd mcp-prompt-manager

# 2. Copy environment variables
cp .env.docker.example .env

# 3. Edit .env and set your Git repository URL
# PROMPT_REPO_URL=https://github.com/yourusername/your-prompts-repo.git

# 4. Start with Docker Compose
docker-compose up -d

# 5. View logs
docker-compose logs -f

Option 3: Local Installation

# 1. Clone and install
git clone https://github.com/CarlLee1983/mcp-prompt-manager.git
cd mcp-prompt-manager
pnpm install

# 2. Build
pnpm build

# 3. Configure environment variables
cp .env.example .env
# Edit .env with your settings

# 4. Start
pnpm start

⚙️ Configuration

Environment Variables

Required

• PROMPT_REPO_URL - Git repository URL or local path to your prompts

Optional

• MCP_LANGUAGE - Output language (en or zh, default: en)
• MCP_GROUPS - Comma-separated list of prompt groups to load (e.g., laravel,vue,common)
• STORAGE_DIR - Local cache directory (default: .prompts_cache)
• GIT_BRANCH - Git branch to sync (default: main)
• LOG_LEVEL - Logging level (fatal, error, warn, info, debug, trace, silent)
• CACHE_PROVIDER - Cache provider (local or redis, default: local)
• CACHE_MAX_SIZE - Maximum cache size (default: 1000)
• CACHE_TTL - Cache TTL in milliseconds (default: 3600000)

MCP Client Configuration

For Cursor

Edit ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json:

{
    "mcpServers": {
        "mcp-prompt-manager": {
            "command": "node",
            "args": ["/absolute/path/to/mcp-prompt-manager/dist/index.js"],
            "env": {
                "PROMPT_REPO_URL": "https://github.com/yourusername/your-prompts-repo.git",
                "MCP_LANGUAGE": "en",
                "MCP_GROUPS": "common",
                "LOG_LEVEL": "info"
            }
        }
    }
}

For Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "mcp-prompt-manager": {
            "command": "node",
            "args": ["/absolute/path/to/mcp-prompt-manager/dist/index.js"],
            "env": {
                "PROMPT_REPO_URL": "https://github.com/yourusername/your-prompts-repo.git"
            }
        }
    }
}

Note: Replace /absolute/path/to/mcp-prompt-manager/dist/index.js with the actual installation path.

📚 Prompt Repository Structure

Your prompt repository should follow this structure:

your-prompts-repo/
├── common/              # Common prompts (always loaded)
│   ├── prompt1.yaml
│   └── prompt2.yaml
├── laravel/            # Laravel-specific prompts
│   └── code-review.yaml
├── vue/                # Vue-specific prompts
│   └── component-review.yaml
└── partials/           # Handlebars partials
    ├── role-expert.hbs
    └── output-format.hbs

Prompt YAML Format

id: 'laravel:code-review'
title: 'Laravel Code Review'
version: '1.0.0'
status: 'stable'
group: 'laravel'
description: 'Review Laravel code for best practices'
template: |
  Please review the following Laravel code:
  
  {{code}}
  
  Focus on:
  - Laravel best practices
  - Security considerations
  - Performance optimization
arguments:
  - name: code
    description: The code to review
    required: true
    type: string
  - name: language
    description: Programming language
    required: false
    type: string
    default: 'php'

🛠️ Available MCP Tools

Management Tools

• mcp_reload / mcp_reload_prompts - Hot-reload all prompts
• mcp_stats / mcp_prompt_stats - Get prompt statistics
• mcp_list / mcp_prompt_list - List all prompts with filtering
• mcp_inspect - Inspect detailed information for a specific prompt
• mcp_repo_switch - Switch to a different prompt repository
• preview_prompt - Preview/render prompt templates (debug utility)

MCP Resources

• system://health - System health status
• prompts://list - Complete prompts list

💡 Use Cases

Team Collaboration

Ensure all team members use the same prompt versions through Git version control. No more prompt drift or version conflicts.

Dynamic Prompts

Create reusable prompt templates with Handlebars. Use variables, conditionals, and partials to build flexible prompts.

Centralized Management

Store all prompts in a Git repository. Update once, sync everywhere. Perfect for organizations with multiple teams.

Production Deployment

Deploy with Docker or Kubernetes. Production-ready configurations with health checks, monitoring, and logging.

🔧 Advanced Features

Multiple Repositories

Support for multiple repository URLs:

PROMPT_REPO_URLS="https://github.com/org/repo1.git,https://github.com/org/repo2.git"

System Repository

Separate repository for system-level prompts:

SYSTEM_REPO_URL="https://github.com/org/system-prompts.git"

Group Filtering

Load only specific prompt groups:

MCP_GROUPS="laravel,vue,common"

Cache Configuration

Configure cache behavior:

CACHE_PROVIDER=local
CACHE_MAX_SIZE=2000
CACHE_TTL=7200000
CACHE_CLEANUP_INTERVAL=30000

📊 Statistics

• Total Tests: 463+ (all passing)
• Test Coverage: 87%+
• MCP Tools: 8 management tools + dynamic prompt tools
• MCP Resources: 2
• Documentation: English + Traditional Chinese
• Type Coverage: 100% TypeScript

🔒 Security

• Input validation for all environment variables
• Path traversal attack prevention
• Group name format validation
• CodeQL security scanning
• Dependabot for dependency updates

📖 Documentation

• README: English | 繁體中文
• Docker Guide: DOCKER.md
• Changelog: CHANGELOG.md
• Security Policy: SECURITY.md

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

ISC License - see LICENSE file for details.

🔗 Links

• GitHub: https://github.com/CarlLee1983/mcp-prompt-manager
• Issues: https://github.com/CarlLee1983/mcp-prompt-manager/issues
• Releases: https://github.com/CarlLee1983/mcp-prompt-manager/releases
• MCP Documentation: https://modelcontextprotocol.io/

🎯 Quick Reference

Configuration Example

{
    "mcpServers": {
        "mcp-prompt-manager": {
            "command": "node",
            "args": ["/path/to/mcp-prompt-manager/dist/index.js"],
            "env": {
                "PROMPT_REPO_URL": "https://github.com/yourusername/your-prompts-repo.git",
                "MCP_LANGUAGE": "en",
                "MCP_GROUPS": "common",
                "LOG_LEVEL": "info"
            }
        }
    }
}

Environment Variables Quick Reference

*Required if PROMPT_REPO_URLS is not set

Version: v1.1.0
Last Updated: 2025-01-06