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.

Features
Installation
Configuration
Usage
Prompt Format
Multi-Format Prompt Support
Storage Adapters
- PostgreSQL Setup
Docker Deployment
- Docker Compose Orchestration
Development
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)

npx -y @sparesparrow/mcp-prompts

Global installation

npm install -g @sparesparrow/mcp-prompts

Using Docker

docker run -p 3003:3003 -v ~/mcp/data:/app/data sparesparrow/mcp-prompts:latest

Verifying Installation

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

Opening Claude Desktop
Typing "/" in the chat input to see if prompts from the server appear
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:

Environment Variable	Description	Default
SERVER_NAME	Server name	MCP Prompts Server
SERVER_VERSION	Server version	package.json version
STORAGE_TYPE	Storage type: 'file', 'postgres', or 'mdc'	file
PROMPTS_DIR	Directory for storing prompts	~/mcp/data/prompts
BACKUPS_DIR	Directory for backups	~/mcp/data/backups
PORT	Port for HTTP server	3003
LOG_LEVEL	Logging level	info
HTTP_SERVER	Enable HTTP server	false
HOST	Host for HTTP server	0.0.0.0

PostgreSQL settings (required if STORAGE_TYPE=postgres)

Environment Variable	Description	Default
PG_HOST	PostgreSQL host	localhost
PG_PORT	PostgreSQL port	5432
PG_DATABASE	PostgreSQL database name	mcp_prompts
PG_USER	PostgreSQL username	postgres
PG_PASSWORD	PostgreSQL password
PG_SSL	Use SSL for PostgreSQL connection	false
POSTGRES_CONNECTION_STRING	Full PostgreSQL connection string (overrides individual settings)

MDC settings (required if STORAGE_TYPE=mdc)

Environment Variable	Description	Default
MDC_RULES_DIR	Directory for MDC rules	./.cursor/rules

Usage

Using with Claude

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

{
  "mcpServers": {
    "prompts": {
      "command": "npx",
      "args": [
        "-y",
        "@sparesparrow/mcp-prompts"
      ],
      "env": {
        "STORAGE_TYPE": "file",
        "PROMPTS_DIR": "/path/to/your/prompts/directory",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

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:

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

To filter by tags:

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

Getting a Specific Prompt

To retrieve a specific prompt by ID:

use_mcp_tool({
  server_name: "prompt-manager",
  tool_name: "get_prompt",
  arguments: {
    id: "development-workflow"
  }
});

Using a Template Prompt

To apply variables to a template prompt:

use_mcp_tool({
  server_name: "prompt-manager",
  tool_name: "apply_template",
  arguments: {
    id: "development-system-prompt",
    variables: {
      "project_type": "web frontend",
      "language": "JavaScript/React",
      "project_name": "TaskManager",
      "project_goal": "create a task management application with drag-and-drop functionality",
      "technical_context": "Using React 18, TypeScript, and Material UI"
    }
  }
});

Managing Prompts

Adding a New Prompt

To add a new prompt:

use_mcp_tool({
  server_name: "prompt-manager",
  tool_name: "add_prompt",
  arguments: {
    name: "Bug Report Template",
    description: "Template for submitting bug reports",
    content: "## Bug Report\n\n### Description\n{{description}}\n\n### Steps to Reproduce\n{{steps}}\n\n### Expected Behavior\n{{expected}}\n\n### Actual Behavior\n{{actual}}\n\n### Environment\n{{environment}}",
    isTemplate: true,
    variables: ["description", "steps", "expected", "actual", "environment"],
    tags: ["bug", "template", "documentation"]
  }
});

Editing an Existing Prompt

To edit an existing prompt:

use_mcp_tool({
  server_name: "prompt-manager",
  tool_name: "edit_prompt",
  arguments: {
    id: "development-workflow",
    content: "Updated workflow content here...",
    tags: ["development", "workflow", "python", "updated"]
  }
});

Using Prompts in Your Workflow

Development Workflow Example

When starting work on a new feature:

Request the development system prompt template
Fill in the template with your project details
Use the resulting system prompt to guide Claude's assistance

Code Review Example

When reviewing code:

Request the code review template
Provide the code to be reviewed
Claude will provide a structured review

Prompt Format

A prompt has the following structure:

{
  "id": "unique-id",
  "name": "Prompt Name",
  "description": "Optional description",
  "content": "The prompt content with {{variables}}",
  "tags": ["tag1", "tag2"],
  "isTemplate": true,
  "variables": ["variable1", "variable2"],
  "metadata": {
    "author": "Your Name",
    "version": "1.0.0"
  }
}

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:

// Create a mutable prompt
const factory = new MutablePromptFactoryImpl();
const prompt = factory.create({
  name: "API Design Guide",
  description: "Template for designing RESTful APIs",
  content: "# API Design for {{service_name}}\n\n## Endpoints\n\n{{endpoints}}\n\n## Authentication\n\n{{auth_method}}",
  isTemplate: true,
  variables: ["service_name", "endpoints", "auth_method"],
  tags: ["api", "design", "rest", "glob:*.md"]
});

// Convert to MDC format
const mdcContent = prompt.toMdc({
  includeVariables: true
});

// Convert to PGAI format with embeddings
const pgaiData = prompt.toPgai({
  generateEmbeddings: true,
  collection: "prompts",
  vectorConfig: {
    dimension: 1536,
    metric: "cosine"
  }
});

// Convert to template format with dollar-style variables
const templateContent = prompt.toTemplate({
  delimiterStyle: "dollar"
});

Applying Templates

You can easily apply variables to template prompts:

const result = prompt.applyVariables({
  service_name: "User Management API",
  endpoints: "GET /users, POST /users, GET /users/{id}, PUT /users/{id}, DELETE /users/{id}",
  auth_method: "JWT Bearer Token"
});

Extracting Variables

Extract variables from template content:

const variables = prompt.extractVariables();
// Returns ["service_name", "endpoints", "auth_method"]

Creating from Different Formats

You can also create prompts from various formats:

// From MDC format
const mdcContent = `---
description: Template for code reviews
globs: ["*.js", "*.ts"]
---

# Code Review Template

## Context
{{context}}

## Patterns
{{patterns}}

## Variables

- \`context\`: Description of the code being reviewed
- \`patterns\`: Common patterns to look for
`;

const promptFromMdc = factory.fromMdc(mdcContent);

// From PGAI format
const pgaiData = {
  id: "api-design",
  name: "API Design Guide",
  content: "# API Design Guide\n\nUse this guide...",
  metadata: {
    description: "Comprehensive API design guide",
    tags: ["api", "rest"],
    isTemplate: false
  }
};

const promptFromPgai = factory.fromPgai(pgaiData);

Integration with Storage Adapters

The MutablePrompt interface works seamlessly with the existing storage adapters:

// Save a prompt in MDC format
const mdcPrompt = factory.fromMdc(mdcContent);
await fileAdapter.savePrompt(mdcPrompt);

// Save a prompt to PostgreSQL with PGAI format
const pgaiPrompt = factory.fromPgai(pgaiData);
await postgresAdapter.savePrompt(pgaiPrompt);

This flexible format handling enables:

Cross-Platform Compatibility: Use prompts in different tools and platforms
Vector Search: Use PGAI format for semantic search capabilities
IDE Integration: Direct compatibility with Cursor Rules
Template Systems: Export templates for use in various programming languages

Storage Adapters

The server supports three types of storage adapters:

File Adapter: Stores prompts as individual JSON files in a directory.
PostgreSQL Adapter: Stores prompts in a PostgreSQL database.
MDC Adapter: Stores prompts in Cursor Rules MDC format.

Storage types can be configured using the STORAGE_TYPE environment variable:

STORAGE_TYPE=file      # Default
STORAGE_TYPE=postgres  # Requires PostgreSQL configuration
STORAGE_TYPE=mdc       # For Cursor Rules format

PostgreSQL Setup

When using PostgreSQL storage, configure the following environment variables:

PG_HOST=localhost
PG_PORT=5432
PG_DATABASE=mcp_prompts
PG_USER=postgres
PG_PASSWORD=your_password
PG_SSL=false

Alternatively, use a connection string:

POSTGRES_CONNECTION_STRING=postgresql://user:password@host:port/database

Docker Deployment

Docker Compose Orchestration

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

Simple Deployment

docker compose up -d

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

PostgreSQL Deployment

docker compose -f docker-compose.postgres.yml up -d

This deploys:

A PostgreSQL database server
The MCP Prompts server configured for PostgreSQL
Adminer for database management at http://localhost:8080

Development Environment

docker compose -f docker-compose.dev.yml up -d

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

Testing Environment

docker compose -f docker-compose.test.yml up --build

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:

# Start development environment
./scripts/docker-manage.sh start dev

# Run tests in Docker
./scripts/docker-manage.sh test

# View logs from production environment
./scripts/docker-manage.sh logs prod

# Clean up test environment
./scripts/docker-manage.sh clean test

# Show help
./scripts/docker-manage.sh help

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:

# custom-compose.yml
version: '3.8'

include:
  - docker-compose.yml

services:
  mcp-prompts:
    environment:
      - CUSTOM_ENV=value

Then run it with:

docker compose -f custom-compose.yml up -d

Development

Development Workflow

Setting Up Development Environment

Clone the repository
git clone https://github.com/user/mcp-prompt-manager.git cd mcp-prompt-manager
Install dependencies
npm install
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:

TypeScript Compilation
npm run build
Make Entry Point Executable
chmod +x dist/index.js

Testing

Run the tests:

npm test

Run the MCP Inspector for testing:

npm run test:inspector

Comprehensive Test Scripts

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

# Run all tests (unit and integration)
./scripts/run-tests.sh

# Run only unit tests
./scripts/run-tests.sh --unit

# Run only integration tests
./scripts/run-tests.sh --integration

# Generate test coverage report
./scripts/run-tests.sh --coverage

# Run tests in Docker
./scripts/run-tests.sh --docker

# Clean up Docker resources after testing
./scripts/run-tests.sh --docker --clean

Docker Container Health Testing

To test the health of Docker containers:

# Run the Docker health check tests
TEST_DOCKER_HEALTH=true npm test -- tests/integration/docker-health.integration.test.ts

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:

mcp-prompt-manager/
├── .github/workflows/    # CI/CD workflow configurations
├── dist/                 # Built files
├── src/                  # Source code
│   ├── adapters.ts       # Storage adapters
│   ├── interfaces.ts     # Core types and interfaces
│   └── index.ts          # Main entry point
├── scripts/              # Maintenance and utility scripts
├── package.json          # Project metadata and scripts
└── README.md             # Project documentation

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

Organize with Tags: Use tags to categorize your prompts for easier retrieval
Use Templates: Create reusable templates with variables for consistent prompting
Include Metadata: Add author, version, and other metadata for better organization
Regular Backups: Use the backup functionality if managing critical prompts
Optimize Large Collections: Use pagination when retrieving large prompt collections
Use Consistent Naming: Name prompts clearly and consistently for easy discovery
Tag Effectively: Use tags to organize prompts by purpose, project, or context
Templatize Reusable Prompts: Create templates for frequently used prompts with variables
Update Regularly: Keep your prompts up-to-date as your needs change
Share with Team: Share effective prompts with your team for consistent interactions

License

MIT

Integrations

MCP Prompts Server

Table of Contents

Features

Installation

Using npx (recommended)

Global installation

Using Docker

Verifying Installation

Configuration

PostgreSQL settings (required if STORAGE_TYPE=postgres)

MDC settings (required if STORAGE_TYPE=mdc)

Usage

Using with Claude

Available Tools

API Usage Examples

Listing Available Prompts

Getting a Specific Prompt

Using a Template Prompt

Managing Prompts

Adding a New Prompt

Editing an Existing Prompt

Using Prompts in Your Workflow

Development Workflow Example

Code Review Example

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

Setting Up Development Environment

Development Commands

Build Process

Testing

Comprehensive Test Scripts

Docker Container Health Testing

Directory Structure

Release Process

Pre-Release Checklist

Version Update

Publishing

Post-Release Verification

Changelog

[1.2.20] - 2025-03-14

[1.2.19] - 2024-03-16

Fixed

Added

[1.2.18] - 2024-03-14

Added

Changed

Fixed

[1.2.0] - 2025-03-14

Changed

Added

Removed

[1.1.0] - 2024-03-01

Added

Changed

[1.0.0] - 2024-02-15

Added

Best Practices

License

Related Resources