MCP Prompts Server

An MCP server for managing prompts and templates with project orchestration capabilities. Part of the Model Context Protocol ecosystem.

This server provides a simple way to store, retrieve, and apply templates for AI prompts, making it easier to maintain consistent prompting patterns across your AI applications.

Table of Contents

• Features

• Installation

• Configuration

• Usage

  • Using with Claude

  • Available Tools

  • API Usage Examples

  • Managing Prompts

  • Using Prompts in Your Workflow

• Prompt Format

• Multi-Format Prompt Support

  • Converting Between Formats

  • Applying Templates

  • Extracting Variables

  • Creating from Different Formats

  • Integration with Storage Adapters

• Storage Adapters

  • PostgreSQL Setup

• Docker Deployment

  • Docker Compose Orchestration

    • Simple Deployment

    • PostgreSQL Deployment

    • Development Environment

    • Testing Environment

    • Docker Management Script

    • Custom Configurations

• Development

  • Development Workflow

  • Development Commands

  • Build Process

  • Testing

  • Directory Structure

• Release Process

• Changelog

• Best Practices

• License

Features

• Store and retrieve prompts

• Create and use templates with variables

• List prompts with filtering by tags

• Apply variables to templates

• Multiple storage backends (file system, PostgreSQL, and MDC format)

• Easy to use with Claude and other AI assistants

• Project orchestration capabilities

• Health check endpoints

Installation

Using npx (recommended)

Global installation

Using Docker

Verifying Installation

After installation, you can verify that the server is working by:

1. Opening Claude Desktop

2. Typing "/" in the chat input to see if prompts from the server appear

3. Testing with a simple tool call:

   use_mcp_tool({ server_name: "prompt-manager", tool_name: "list_prompts", arguments: {} });

Configuration

The server can be configured using environment variables:

PostgreSQL settings (required if STORAGE_TYPE=postgres)

MDC settings (required if STORAGE_TYPE=mdc)

Usage

Using with Claude

In Claude 3 Desktop app, you can configure the MCP Prompts server in your claude_desktop_config.json:

Available Tools

The MCP Prompts server provides the following tools:

• add_prompt: Add a new prompt

• get_prompt: Get a prompt by ID

• update_prompt: Update an existing prompt

• list_prompts: List all prompts

• delete_prompt: Delete a prompt by ID

• apply_template: Apply variables to a prompt template

API Usage Examples

Listing Available Prompts

To see what prompts are available:

To filter by tags:

Getting a Specific Prompt

To retrieve a specific prompt by ID:

Using a Template Prompt

To apply variables to a template prompt:

Managing Prompts

Adding a New Prompt

To add a new prompt:

Editing an Existing Prompt

To edit an existing prompt:

Using Prompts in Your Workflow

Development Workflow Example

When starting work on a new feature:

1. Request the development system prompt template

2. Fill in the template with your project details

3. Use the resulting system prompt to guide Claude's assistance

Code Review Example

When reviewing code:

1. Request the code review template

2. Provide the code to be reviewed

3. Claude will provide a structured review

Prompt Format

A prompt has the following structure:

Multi-Format Prompt Support

The MCP Prompts Server includes a powerful MutablePrompt interface that allows prompts to be converted between multiple formats:

• JSON Format: Standard internal format used by the server

• MDC Format: Cursor Rules Markdown format (.mdc files)

• PGAI Format: Format with embedding support for PostgreSQL AI

• Template Format: Dynamic format with variable placeholders

Converting Between Formats

The MutablePrompt interface provides methods to convert prompts between these formats:

Applying Templates

You can easily apply variables to template prompts:

Extracting Variables

Extract variables from template content:

Creating from Different Formats

You can also create prompts from various formats:

Integration with Storage Adapters

The MutablePrompt interface works seamlessly with the existing storage adapters:

This flexible format handling enables:

1. Cross-Platform Compatibility: Use prompts in different tools and platforms

2. Vector Search: Use PGAI format for semantic search capabilities

3. IDE Integration: Direct compatibility with Cursor Rules

4. Template Systems: Export templates for use in various programming languages

Storage Adapters

The server supports three types of storage adapters:

1. File Adapter: Stores prompts as individual JSON files in a directory.

2. PostgreSQL Adapter: Stores prompts in a PostgreSQL database.

3. MDC Adapter: Stores prompts in Cursor Rules MDC format.

Storage types can be configured using the STORAGE_TYPE environment variable:

PostgreSQL Setup

When using PostgreSQL storage, configure the following environment variables:

Alternatively, use a connection string:

Docker Deployment

Docker Compose Orchestration

The MCP Prompts Server offers various Docker Compose configurations for different deployment scenarios:

Simple Deployment

This will deploy the MCP Prompts server using file storage on port 3003.

PostgreSQL Deployment

This deploys:

• A PostgreSQL database server

• The MCP Prompts server configured for PostgreSQL

• Adminer for database management at http://localhost:8080

Development Environment

This sets up a development environment with hot reloading. It mounts the source code from your local directory and includes Adminer.

Testing Environment

This creates a dedicated testing environment with:

• A temporary PostgreSQL instance with test data

• An isolated test runner container that executes all tests

• Test results saved to the ./test-results directory

Docker Management Script

To simplify Docker Compose operations, use the provided management script:

The management script supports the following commands:

• start: Start Docker containers

• stop: Stop Docker containers

• restart: Restart Docker containers

• logs: Show logs from containers

• clean: Remove containers, networks, and volumes

• build: Build Docker images

• test: Run tests in Docker containers

And the following environments:

• dev: Development environment (default)

• test: Testing environment

• prod: Production environment

Custom Configurations

You can create your own custom Docker Compose configuration by extending the base configurations:

Then run it with:

Development

Development Workflow

Setting Up Development Environment

1. Clone the repository

   git clone https://github.com/user/mcp-prompt-manager.git cd mcp-prompt-manager

2. Install dependencies

   npm install

3. Set up environment variables Create a .env file with the necessary configuration.

Development Commands

• Start development server with hot reloading

  npm run dev

• Build the project

  npm run build

• Run unit tests

  npm test

• Run integration tests

  npm run test:integration

• Test build process

  npm run test:build

• Test Docker build

  npm run test:docker

• Build Docker image

  npm run docker:build

Build Process

The build process includes several important steps:

1. TypeScript Compilation

   npm run build

2. Make Entry Point Executable

   chmod +x dist/index.js

Testing

Run the tests:

Run the MCP Inspector for testing:

Comprehensive Test Scripts

For more advanced testing options, use the provided test script:

Docker Container Health Testing

To test the health of Docker containers:

This test verifies that the health check endpoint is working correctly when the MCP-Prompts server is running in a Docker container.

Directory Structure

The project follows a structured organization to maintain clean separation of concerns:

Release Process

Pre-Release Checklist

• All TypeScript errors are resolved

• Code linting passes with no errors

• Code is properly formatted according to project standards

• Unit tests pass

• Integration tests pass

• Build test passes

• Docker build test passes

• Package installation test passes

• README is up-to-date with the latest features and changes

• CHANGELOG is updated with all notable changes

Version Update

• Update version in package.json according to semantic versioning

• Ensure dependencies are up-to-date

• Update any version references in documentation

Publishing

• Create a git tag for the new version

• Push changes and tag to GitHub

• Publish to npm (npm publish)

• Build and push Docker image

Post-Release Verification

• Verify installation from npm

• Verify package can be run with npx

• Verify Docker image works as expected

• Verify integration with Claude Desktop

Changelog

[1.2.20] - 2025-03-14

• Automated version bump

[1.2.19] - 2024-03-16

Fixed

• Fixed TypeScript errors in PostgresAdapter implementation

• Enhanced savePrompt method to properly return the created prompt

• Added updatePrompt method to the PostgresAdapter

• Fixed StorageAdapter interface to include listPrompts and clearAll methods

• Improved error handling in database-tools.ts for the clearAll method

• Enhanced health check endpoint with more detailed information

Added

• Added better documentation and error handling for health check endpoint

[1.2.18] - 2024-03-14

Added

• Added HTTP server with health check endpoint

• Added Docker container health checks

• Added ESM module compatibility for Node.js 18-23+

• Enhanced database tools with better error handling

Changed

• Improved Docker build process with multi-stage builds

• Streamlined configuration management

• Optimized PostgreSQL adapter connection handling

• Updated dependencies to latest versions

Fixed

• Fixed issues with file adapter on certain file systems

• Improved error messages for better debugging

• Fixed template variable extraction

[1.2.0] - 2025-03-14

Changed

• Reorganized codebase structure for better maintainability

• Moved Docker-related files to docker/ directory

• Moved build scripts to scripts/build/ directory

• Moved test scripts to scripts/test/ directory

• Updated GitHub workflows to use new file paths

• Updated Docker Compose configuration to use new file paths

• Added comprehensive development documentation

Added

• Created development documentation with detailed instructions

• Created release checklist for release preparation

• Added CHANGELOG.md to track changes

Removed

• Removed duplicate and redundant files

• Removed incomplete scripts

[1.1.0] - 2024-03-01

Added

• PGAI vector search for semantic prompt discovery

• Support for embeddings in PostgreSQL

• Improved prompts collection with professional templates

• Batch processing capabilities for prompt collections

Changed

• Enhanced prompt processing pipeline

• Improved command-line interface with more options

• Better error handling and validation

[1.0.0] - 2024-02-15

Added

• Initial release of MCP Prompts Server

• Basic prompt management capabilities (add, edit, get, list, delete)

• Template variable substitution

• Tag-based organization

• File-based storage

• Import/export functionality

• MCP protocol compatibility

Best Practices

1. Organize with Tags: Use tags to categorize your prompts for easier retrieval

2. Use Templates: Create reusable templates with variables for consistent prompting

3. Include Metadata: Add author, version, and other metadata for better organization

4. Regular Backups: Use the backup functionality if managing critical prompts

5. Optimize Large Collections: Use pagination when retrieving large prompt collections

6. Use Consistent Naming: Name prompts clearly and consistently for easy discovery

7. Tag Effectively: Use tags to organize prompts by purpose, project, or context

8. Templatize Reusable Prompts: Create templates for frequently used prompts with variables

9. Update Regularly: Keep your prompts up-to-date as your needs change

10. Share with Team: Share effective prompts with your team for consistent interactions

License

MIT