📌Overview

Purpose: The MCP Prompts Server is designed to manage prompts and templates efficiently while providing project orchestration capabilities within the Model Context Protocol ecosystem.

Overview: This server simplifies the storage, retrieval, and application of AI prompt templates, ensuring consistency across various AI applications. It seamlessly integrates with multiple storage backends and offers robust features for managing templates and prompts.

Key Features:

Prompt Management: Enables the addition, retrieval, updating, and deletion of prompts while maintaining organization through tags and templates.
Template Processing: Facilitates the creation and application of templates with variable support for dynamic content generation.
Multi-Storage Support: Offers flexibility in storage options, allowing the use of file systems, PostgreSQL databases, or Cursor Rules (MDC format) for backing prompt data.
Integration-Friendly: Designed to work effortlessly with AI assistants like Claude, and includes support for Docker deployment and various MCP servers for enhanced functionality.
Health Check Endpoints: Ensures operational reliability and allows for monitoring of server health status.

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
- 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
- Purpose-Driven Container Architecture
- Docker Compose Orchestration
  - Base Deployment
  - Development Environment
  - PostgreSQL Integration
  - Testing Environment
  - Multiple MCP Servers Integration
  - Building and Publishing Docker Images
Development
- Development Workflow
- Development Commands
- Build Process
- Testing
- Directory Structure
Release Process
Changelog
Best Practices
License
Architecture
MCP Resources Integration
- The resources/list Method
- Using Resources in Prompts
- Integration Pattern with Multiple MCP Servers
- Configuring Resource Integration
MCP Server Integration
- Integration with Mermaid Diagram Server
- Integration with Orchestrator Server
- Advanced Integration with MCP Router
  - Router Configuration
- Use Cases and Integration Examples
  - 1. Project Documentation Generator
  - 1. Prompt Visualization Dashboard
  - 1. 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

Implementation Updates

The MCP Prompts Server has been refactored to use the new registration methods from MCP SDK version 1.6.1:

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").

These changes simplify the codebase, improve maintainability, and ensure better compatibility with the latest MCP SDK.

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, verify the server 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 via environment variables:

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 (for STORAGE_TYPE=postgres)

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 connection string (overrides others)

MDC settings (for STORAGE_TYPE=mdc)

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

Usage

Using with Claude

In Claude 3 Desktop, configure MCP Prompts server in 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

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

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

Filter by tags:

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

Getting a Specific Prompt

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

Using 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

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

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

For new features, request a development system prompt template, fill in details, and use the prompt for assistance.
For code reviews, request the review template, provide code, and get structured feedback.

Prompt Format

Example structure of a prompt:

{
  "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

Supports multiple prompt formats via MutablePrompt:

JSON (standard internal)
MDC (Cursor Rules Markdown)
PGAI (PostgreSQL AI format with embeddings)
Template format (variable placeholders)

Converting Between Formats

Example usage in TypeScript:

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"]
});

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

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

// To template format
const templateContent = prompt.toTemplate({ delimiterStyle: "dollar" });

Applying Templates

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

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

Creating from Different Formats

// From MDC
const promptFromMdc = factory.fromMdc(mdcContent);

// From PGAI
const promptFromPgai = factory.fromPgai(pgaiData);

Integration with Storage Adapters

Compatible with file, PostgreSQL, and MDC adapters:

await fileAdapter.savePrompt(factory.fromMdc(mdcContent));
await postgresAdapter.savePrompt(factory.fromPgai(pgaiData));

Storage Adapters

Three storage types supported:

File Adapter: stores JSON files
PostgreSQL Adapter: stores prompts in PostgreSQL
MDC Adapter: stores prompts in Cursor Rules MDC format

Set with STORAGE_TYPE environment variable (file default).

PostgreSQL Setup

Configure PostgreSQL connection using environment variables as described above.

Docker Deployment

Docker Compose Manager

Use provided manager script with profiles for easy deployment:

./docker/scripts/docker-compose-manager.sh up             # file storage
./docker/scripts/docker-compose-manager.sh up -p postgres # PostgreSQL backend
./docker/scripts/docker-compose-manager.sh up -e development -p postgres  # dev environment
./docker/scripts/docker-compose-manager.sh up -p sse      # SSE support
./docker/scripts/docker-compose-manager.sh up -p integration  # multiple MCP integration

Purpose-Driven Container Architecture

Production: performance and security optimized
Development: hot reload and debugging
Testing: test environment
PostgreSQL: backend storage
Multi-server 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: basic server with file storage
Development Environment: hot reloading and debugging tools
PostgreSQL Integration: adds PostgreSQL and Adminer
Testing Environment: optimized for tests
Multiple MCP Servers Integration: interoperates with other MCP servers

Multiple MCP Servers Integration Example

Client can request from MCP Prompts Server which also interacts with:

MCP Memory Server
MCP Filesystem Server
MCP GitHub Server
MCP Sequential Thinking
MCP ElevenLabs Server
PostgreSQL AI Server

Building and Publishing Docker Images

./docker/scripts/build-and-publish.sh 1.0.0  # build all images
./docker/scripts/docker-compose-manager.sh image -e production -t 1.0.0  # build production image

Data Persistence

Docker volumes used by default. Use local directory mounting for custom data persistence.

Development

Development Workflow

Clone repository:

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

Install dependencies:

npm install

Create a .env file with configuration as needed.

Development Commands

Start dev server: npm run dev
Build: npm run build
Unit tests: npm test
Integration tests: npm run test:integration
Test build: npm run test:build
Test Docker build: npm run test:docker
Build Docker image: npm run docker:build

Build Process

Compile TypeScript and set executable flag:

npm run build
chmod +x dist/index.js

Testing

Run all tests:

npm test

For comprehensive testing:

./scripts/run-tests.sh           # all tests
./scripts/run-tests.sh --unit    # unit only
./scripts/run-tests.sh --integration  # integration only
./scripts/run-tests.sh --coverage # coverage report
./scripts/run-tests.sh --docker  # run in Docker
./scripts/run-tests.sh --docker --clean  # cleanup Docker

Test Docker container health:

TEST_DOCKER_HEALTH=true npm test -- tests/integration/docker-health.integration.test.ts

Directory Structure

mcp-prompt-manager/
├── .github/workflows/    # CI/CD workflows
├── dist/                 # Built files
├── src/                  # Source code
│   ├── adapters.ts       # Storage adapters
│   ├── interfaces.ts     # Core types and interfaces
│   └── index.ts          # Main entry
├── scripts/              # Utility scripts
├── package.json          # Metadata and scripts
└── README.md             # Documentation

Release Process

Resolve TypeScript errors
Pass lint and formatting checks
Pass unit and integration tests
Pass build and Docker tests
Update README and CHANGELOG
Update package version in package.json
Tag and push to GitHub
Publish to npm
Build and push Docker images
Verify installations and integrations

Changelog

Selected recent releases:

1.2.20 - Automated version bump
1.2.19 & 1.2.18 - Bug fixes, health checks, HTTP server, and Docker improvements
1.2.0 - Codebase restructuring, documentation, and release checklist added
1.1.0 - Added PGAI vector search, embedding support, and batch processing
1.0.0 - Initial release with basic prompt management features

Best Practices

Organize prompts with tags
Use templates with variables for reuse
Include metadata for authorship and versioning
Regularly back up prompts
Use pagination for large prompt sets
Consistent and clear naming conventions
Share prompts with your team for consistency

License

MIT

Architecture

The MCP Prompts Server integrates seamlessly with other MCP servers for advanced prompt management, variable substitution, and storage.

MCP Resources Integration

Enhances prompt capabilities by referencing external data through resources with URIs like:

@filesystem:/path/to/file
@memory:key
@github:owner/repo/path
@sequential-thinking:id
@elevenlabs:text-to-speak

Templates can include such URIs for dynamic, contextual prompts.

Resource Fallback Strategies

Implement fallback caching and error handling for resource availability.

Setting up Resource Servers

Use Docker Compose scripts to start MCP resource servers like memory, GitHub, filesystem, etc.

MCP Server Integration

Integration with Mermaid Diagram Server

Visualize prompt relationships, template structures, variable usage, and resource dependencies using the Mermaid Diagram Server.

Integration with Orchestrator Server

Coordinate tasks across MCP servers (prompts, mermaid, filesystem, GitHub) for complex workflows.

Multi-Server Project Analysis Pattern

Leverage multiple MCP servers to analyze, document, and visualize project structures.

Setting Up Integration

Configure MCP Router with JSON config listing server URLs and capabilities; enable resource sharing environment variable.

Advanced Integration with MCP Router

Use MCP Router as centralized routing and discovery point for all MCP servers.

Use Cases and Integration Examples

Project Documentation Generator: Automate documentation with diagrams.
Prompt Visualization Dashboard: Manage and visualize prompt relationships.
Template-Based Project Generator: Generate projects with templates and visualize structure.

Server-Sent Events (SSE) Support

Enables real-time updates without polling.

Running with SSE Support

Run MCP Prompts server with SSE enabled via Docker Compose:

docker-compose up mcp-prompts-sse

Configuring Claude Desktop to Use SSE

Configure Claude Desktop with the following snippet in claude_desktop_config.json (replace paths accordingly):

"prompts": {
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-p",
    "3003:3003",
    "-v",
    "/path/to/your/prompts:/app/data/prompts",
    "-v",
    "/path/to/your/backups:/app/data/backups",
    "--name",
    "mcp-prompts-sse",
    "-e",
    "STORAGE_TYPE=file",
    "-e",
    "PROMPTS_DIR=/app/data/prompts",
    "-e",
    "BACKUPS_DIR=/app/data/backups",
    "-e",
    "HTTP_SERVER=true",
    "-e",
    "PORT=3003",
    "-e",
    "HOST=0.0.0.0",
    "-e",
    "ENABLE_SSE=true",
    "-e",
    "SSE_PATH=/events",
    "-e",
    "CORS_ORIGIN=*",
    "sparesparrow/mcp-prompts:latest"
  ]
}

SSE API

Connect Event: On connection to /events:

{ "type": "connect", "message": "Connected to MCP Prompts SSE stream" }

Heartbeat Event: Sent periodically to keep connection alive:

{ "type": "heartbeat", "timestamp": "2023-03-15T12:34:56.789Z" }

Example JavaScript client listening to SSE:

const eventSource = new EventSource('http://localhost:3003/events');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received SSE event:', data);
};

eventSource.onerror = (error) => {
  console.error('SSE error:', error);
  eventSource.close();
};

This structured summary preserves key details and instructions for installing, configuring, using, and integrating the MCP Prompts Server, while removing images, local markdown links, and unimportant info.

mcp-prompts