MCP Prompts Server

Table of Contents

• Features

• Installation

• Configuration

• Usage

• Prompt Format

• Multi-Format Prompt Support

• Storage Adapters

• Docker Deployment

• Development

• Release Process

• Changelog

• Best Practices

• License

• Architecture

• MCP Resources Integration

• MCP Server Integration

• Server-Sent Events (SSE) Support

Implementation Updates

• server.resource for defining resource endpoints (e.g., for prompts and templates).

• server.tool for registering tool operations (e.g., add, get, update, list, delete, and apply_template).

• server.prompt for prompt-specific operations (e.g., "review-code").

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

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:

Configuration

PostgreSQL settings (required if STORAGE_TYPE=postgres)

MDC settings (required if STORAGE_TYPE=mdc)

Usage

Using with Claude

Available 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

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

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

1. Request the code review template

2. Provide the code to be reviewed

3. Claude will provide a structured review

Prompt Format

Multi-Format Prompt Support

• 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

Applying Templates

Extracting Variables

Creating from Different Formats

Integration with Storage Adapters

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

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.

PostgreSQL Setup

Docker Deployment

Using the Docker Compose Manager

Purpose-Driven Container Architecture

1. Production Environment: Optimized for performance and security

2. Development Environment: Includes hot-reloading and debugging tools

3. Test Environment: For running automated tests

4. PostgreSQL Integration: Adds PostgreSQL storage backend

5. Multiple MCP Servers Integration: Connects with other MCP servers

Available Docker Images

• Production: sparesparrow/mcp-prompts:latest

• Development: sparesparrow/mcp-prompts:dev

• Test: sparesparrow/mcp-prompts:test

Docker Compose Configurations

Base Deployment

Development Environment

PostgreSQL Integration

Testing Environment

Multiple MCP Servers Integration

Data Flow Architecture

Configuration for Multi-Server Setup

1. Start the required MCP servers using Docker Compose:

1. Configure your MCP client (such as Claude Desktop) with the appropriate server URLs:

Server-Specific Environment Variables

Integration Use Cases

1. Template Variables with Memory Server:

2. Prompt Synchronization with GitHub Server:

3. Filesystem Management:

4. Advanced Reasoning with Sequential Thinking:

5. Voice Feedback with ElevenLabs:

6. Vector Search with PostgreSQL AI:

Building and Publishing Docker Images

Data Persistence

• mcp-prompts-data: For prompt storage

• mcp-prompts-postgres-data: For PostgreSQL data

Development

Development Workflow

Setting Up Development Environment

1. Clone the repository

2. Install dependencies

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

Development Commands

• Start development server with hot reloading

• Build the project

• Run unit tests

• Run integration tests

• Test build process

• Test Docker build

• Build Docker image

Build Process

1. TypeScript Compilation

2. Make Entry Point Executable

Testing

Comprehensive Test Scripts

Docker Container Health Testing

Directory Structure

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

Architecture

Core Architecture

Multiple MCP Servers Integration

Data Flow for Prompt Management

Resource Integration Pattern

Docker Deployment Architecture

MCP Resources Integration

MCP Resources Architecture

Resource URI Format

• @filesystem:/path/to/file.js - Access a local file

• @memory:session/12345 - Retrieve data from memory

• @github:owner/repo/path/to/file - Get content from a GitHub repository

• @sequential-thinking:analysis-1234 - Reference a reasoning chain

• @elevenlabs:text-to-speak - Generate audio from text

Integration with Templates

Available Resource Types

Resource Fallback Strategies

Setting Up MCP Resource Servers

MCP Server Integration

Integration with Mermaid Diagram Server

Use Cases for Mermaid Integration

1. Prompt Relationship Visualization: Generate diagrams showing how different prompts are related and categorized.

2. Template Structure Representation: Visualize the structure of complex templates with their variables and conditional blocks.

3. Variable Usage Analysis: Create charts showing how variables are used across different templates.

4. Resource Dependencies Graph: Visualize which prompts depend on which MCP resources.

5. Prompt Flow Diagrams: Create sequence diagrams showing the flow of prompt processing.

Integration with Orchestrator Server

Orchestration Workflows

Multi-Server Project Analysis Pattern

Setting Up Integration

1. Configure Server Connections:

2. Enable Resource Sharing: Set the ENABLE_RESOURCES environment variable to true for the MCP Prompts Server.

3. Set Up Docker Compose: Create a docker-compose.yml file that includes all required servers:

Router Configuration

Use Cases and Integration Examples

1. Project Documentation Generator

2. Prompt Visualization Dashboard

3. Template-Based Project Generator

Docker Compose for Full Integration

Server-Sent Events (SSE) Support

Running with SSE Support

Configuring Claude Desktop to Use SSE

SSE API

1. Connect Event: Sent when a client connects to the SSE endpoint

2. Heartbeat Event: Sent every 30 seconds to keep the connection alive

MCP Prompts Server

Table of Contents

• Features

• Installation

• Configuration

• Usage

• Prompt Format

• Multi-Format Prompt Support

• Storage Adapters

• Docker Deployment

• Development

• Release Process

• Changelog

• Best Practices

• License

• Architecture

• MCP Resources Integration

• MCP Server Integration

• Server-Sent Events (SSE) Support

Implementation Updates

• server.resource for defining resource endpoints (e.g., for prompts and templates).

• server.tool for registering tool operations (e.g., add, get, update, list, delete, and apply_template).

• server.prompt for prompt-specific operations (e.g., "review-code").

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

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:

Configuration

PostgreSQL settings (required if STORAGE_TYPE=postgres)

MDC settings (required if STORAGE_TYPE=mdc)

Usage

Using with Claude

Available 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

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

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

1. Request the code review template

2. Provide the code to be reviewed

3. Claude will provide a structured review

Prompt Format

Multi-Format Prompt Support

• 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

Applying Templates

Extracting Variables

Creating from Different Formats

Integration with Storage Adapters

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

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.

PostgreSQL Setup

Docker Deployment

Using the Docker Compose Manager

Purpose-Driven Container Architecture

1. Production Environment: Optimized for performance and security

2. Development Environment: Includes hot-reloading and debugging tools

3. Test Environment: For running automated tests

4. PostgreSQL Integration: Adds PostgreSQL storage backend

5. Multiple MCP Servers Integration: Connects with other MCP servers

Available Docker Images

• Production: sparesparrow/mcp-prompts:latest

• Development: sparesparrow/mcp-prompts:dev

• Test: sparesparrow/mcp-prompts:test

Docker Compose Configurations

Base Deployment

Development Environment

PostgreSQL Integration

Testing Environment

Multiple MCP Servers Integration

Data Flow Architecture

Configuration for Multi-Server Setup

1. Start the required MCP servers using Docker Compose:

1. Configure your MCP client (such as Claude Desktop) with the appropriate server URLs:

Server-Specific Environment Variables

Integration Use Cases

1. Template Variables with Memory Server:

2. Prompt Synchronization with GitHub Server:

3. Filesystem Management:

4. Advanced Reasoning with Sequential Thinking:

5. Voice Feedback with ElevenLabs:

6. Vector Search with PostgreSQL AI:

Building and Publishing Docker Images

Data Persistence

• mcp-prompts-data: For prompt storage

• mcp-prompts-postgres-data: For PostgreSQL data

Development

Development Workflow

Setting Up Development Environment

1. Clone the repository

2. Install dependencies

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

Development Commands

• Start development server with hot reloading

• Build the project

• Run unit tests

• Run integration tests

• Test build process

• Test Docker build

• Build Docker image

Build Process

1. TypeScript Compilation

2. Make Entry Point Executable

Testing

Comprehensive Test Scripts

Docker Container Health Testing

Directory Structure

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

Architecture

Core Architecture

Multiple MCP Servers Integration

Data Flow for Prompt Management

Resource Integration Pattern

Docker Deployment Architecture

MCP Resources Integration

MCP Resources Architecture

Resource URI Format

• @filesystem:/path/to/file.js - Access a local file

• @memory:session/12345 - Retrieve data from memory

• @github:owner/repo/path/to/file - Get content from a GitHub repository

• @sequential-thinking:analysis-1234 - Reference a reasoning chain

• @elevenlabs:text-to-speak - Generate audio from text

Integration with Templates

Available Resource Types

Resource Fallback Strategies

Setting Up MCP Resource Servers

MCP Server Integration

Integration with Mermaid Diagram Server

Use Cases for Mermaid Integration

1. Prompt Relationship Visualization: Generate diagrams showing how different prompts are related and categorized.

2. Template Structure Representation: Visualize the structure of complex templates with their variables and conditional blocks.

3. Variable Usage Analysis: Create charts showing how variables are used across different templates.

4. Resource Dependencies Graph: Visualize which prompts depend on which MCP resources.

5. Prompt Flow Diagrams: Create sequence diagrams showing the flow of prompt processing.

Integration with Orchestrator Server

Orchestration Workflows

Multi-Server Project Analysis Pattern

Setting Up Integration

1. Configure Server Connections:

2. Enable Resource Sharing: Set the ENABLE_RESOURCES environment variable to true for the MCP Prompts Server.

3. Set Up Docker Compose: Create a docker-compose.yml file that includes all required servers:

Router Configuration

Use Cases and Integration Examples

1. Project Documentation Generator

2. Prompt Visualization Dashboard

3. Template-Based Project Generator

Docker Compose for Full Integration

Server-Sent Events (SSE) Support

Running with SSE Support

Configuring Claude Desktop to Use SSE

SSE API

1. Connect Event: Sent when a client connects to the SSE endpoint

2. Heartbeat Event: Sent every 30 seconds to keep the connection alive