PromptDB MCP Server

<p align="center"> <img src="_assets/banner.gif" alt="banner" width="900" height="350"> </p>

A Model Context Protocol (MCP) server that provides prompt storage and retrieval functionality. Store, version, and manage your prompts with rich metadata and caching for optimal performance.

Features

• Prompt Storage: Store prompts as individual JSON files with rich metadata
• Version Management: Automatic versioning with history preservation
• Caching: In-memory LRU cache for performance optimization
• Rich Metadata: Tags, descriptions, timestamps, and version tracking
• MCP Integration: Full compatibility with MCP-enabled applications
• Dual Transport Support: Both stdio and SSE (Server-Sent Events) transports
• Cloud Deployment: Ready for deployment to Vercel, Netlify, and other cloud platforms

Pre-populated Prompts

The server comes with a set of pre-populated prompts ready for immediate use. You can retrieve them using the getPrompt tool with the following task names:

• assistant
• code-review
• documentation
• summarise-paper
• to-flash-cards

Installation

Global Installation

# Using pnpm (recommended)
pnpm add -g promptdb-mcp-server

# Using npm
npm install -g promptdb-mcp-server

Local Development

# Clone and install dependencies
git clone <repository-url>
cd promptdb-mcp-server
pnpm install

# Build the project
pnpm build

# Start the server
pnpm start

Transport Options

The PromptDB MCP Server supports two transport methods:

1. Stdio Transport (Default)

For local development and MCP clients that support process communication:

# Default stdio transport
promptdb-mcp-server
# or explicitly
promptdb-mcp-server --transport stdio

2. SSE Transport (Server-Sent Events)

For web applications and cloud deployment:

# SSE transport on port 3000
promptdb-mcp-server --transport sse --port 3000

# Using environment variables
export TRANSPORT_TYPE=sse
export PORT=3000
promptdb-mcp-server

MCP Configuration

Stdio Transport Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "promptdb": {
      "command": "promptdb-mcp-server",
      "args": []
    }
  }
}

SSE Transport Configuration

For MCP clients that support HTTP/SSE transport:

{
  "mcpServers": {
    "promptdb": {
      "transport": "sse",
      "url": "http://localhost:3000/sse"
    }
  }
}

Cloud Deployment

Vercel Deployment

# Build and deploy
pnpm build
vercel deploy

# Set environment variables in Vercel dashboard:
# TRANSPORT_TYPE=sse
# PORT=3000

Netlify Deployment

# Build and deploy
pnpm build
netlify deploy --prod --dir=dist

# Set TRANSPORT_TYPE=sse in Netlify dashboard

SSE Endpoints

When running in SSE mode, the server provides:

• SSE Endpoint: http://localhost:3000/sse - MCP communication
• Health Check: http://localhost:3000/health - Server status
• Server Info: http://localhost:3000/ - Server metadata

Tools

listPrompts

List all available prompts with their content and versions.

Parameters: None

Returns: Array of prompts with taskname, content, and version

getPrompt

Retrieve a specific prompt by task name.

Parameters:

• taskname (required): The task name identifier
• version (optional): Specific version (defaults to latest)

Returns: Full prompt metadata including content, timestamps, tags, and description

setPrompt

Create or update a prompt for a task.

Parameters:

• taskname (required): The task name identifier
• content (required): The prompt content
• description (optional): Human-readable description
• tags (optional): Array of searchable tags

Returns: Confirmation with version information

Data Model

Prompt Structure

interface PromptMetadata {
  content: string;      // The prompt content
  created: string;      // ISO timestamp of creation
  updated: string;      // ISO timestamp of last update
  version: string;      // Semantic version (1.0, 1.1, etc.)
  tags: string[];       // Searchable tags
  description: string;  // Human-readable description
}

File Organization

• Latest version: prompts/{taskname}.json
• Historical versions: prompts/{taskname}_v{version}.json
• Automatic archiving of previous versions

Version Management

• New prompts start at version 1.0
• Content updates increment minor version (1.0 → 1.1 → 1.2)
• Previous versions are automatically archived
• Latest version is always accessible without specifying version

Usage Examples

Storing a Prompt

{
  "tool": "setPrompt",
  "arguments": {
    "taskname": "code-review",
    "content": "Review this code for best practices, security issues, and performance optimizations...",
    "description": "Comprehensive code review prompt",
    "tags": ["code", "review", "security", "performance"]
  }
}

Retrieving a Prompt

{
  "tool": "getPrompt",
  "arguments": {
    "taskname": "code-review"
  }
}

Listing All Prompts

{
  "tool": "listPrompts",
  "arguments": {}
}

Development

Project Structure

promptdb-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server setup
│   ├── tools/                # Tool implementations
│   ├── storage/              # File system operations
│   ├── cache/                # In-memory caching
│   └── utils/                # Validation helpers
├── prompts/                  # Prompt storage directory
├── package.json
├── tsconfig.json
└── vite.config.ts

Development Commands

# Install dependencies
pnpm install

# Build project
pnpm build

# Development with watch mode
pnpm dev

# Start server (stdio transport)
pnpm start

# Start with SSE transport
pnpm start:sse

# Development with SSE transport
pnpm dev:sse

# Clean build artifacts
pnpm clean

Testing

Use the MCP Inspector or any MCP-compatible client to test the server:

1. Start the server: pnpm start
2. Connect via MCP Inspector
3. Test the available tools

Performance

Caching Strategy

• Cache Hit: Immediate return from memory
• Cache Miss: Load from file system, cache result
• Cache Invalidation: Automatic on prompt updates
• Memory Management: LRU eviction at 100 items

File System Optimization

• Asynchronous file operations throughout
• On-demand directory creation
• Robust error handling
• Concurrent access safety

Error Handling

The server handles various error conditions gracefully:

• File system permission errors
• Invalid JSON parsing
• Concurrent access conflicts
• Cache consistency issues
• Input validation errors

Troubleshooting

Common Issues

1. Server not starting: Check Node.js version (18+) and dependencies
2. Tool not found: Verify server is properly connected to MCP client
3. Directory creation errors:

• Error: ENOENT: no such file or directory, mkdir '/prompts'
• Solution: The server creates a prompts directory in the current working directory. Ensure the MCP client has write permissions to the directory where it's running.
• Alternative: The server will automatically create the directory with proper permissions

1. File permissions: Ensure write access to prompts directory
2. JSON parsing errors: Validate prompt file format

SSE Transport Issues

1. Port already in use:

   # Find process using port
   lsof -i :3000
   # Kill process
   kill -9 <PID>

1. CORS errors: The server includes CORS headers by default for cross-origin requests

1. Connection timeout: Check firewall settings and ensure the port is accessible

1. Build errors: Ensure all dependencies are installed with pnpm install

1. Cloud deployment issues:

• Verify environment variables are set correctly
• Check build logs for errors
• Ensure dist/ directory is included in deployment

Testing SSE Transport

# Test health endpoint
curl http://localhost:3000/health

# Test server info
curl http://localhost:3000/

# Test SSE connection
curl -N http://localhost:3000/sse

Directory Configuration

The server creates prompts in the current working directory by default:

• When run locally: ./prompts/ in the project directory
• When installed globally: ./prompts/ in the directory where the MCP client runs
• The server automatically creates the directory if it doesn't exist

Validation Errors

• Task names must be alphanumeric with hyphens/underscores only
• Content cannot be empty
• Version format must be X.Y (e.g., 1.0, 2.1)

License

MIT License - see LICENSE file for details

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

• Create an issue on GitHub
• Check the documentation
• Review the implementation plan