MCP Prompts Server

A robust, extensible server for managing, versioning, and serving prompts and templates for LLM applications, built on the Model Context Protocol (MCP).

🚀 Features

Dual Mode Operation

HTTP Mode - Traditional REST API server
MCP Mode - Model Context Protocol server for AI assistants

MCP Tools (7 Available)

add_prompt - Add new prompts to collection
get_prompt - Retrieve prompts by ID
list_prompts - List prompts with filtering
update_prompt - Update existing prompts
delete_prompt - Remove prompts
apply_template - Apply variables to template prompts
get_stats - Get prompt statistics

Pre-loaded Templates

Code Review Assistant
Documentation Writer
Bug Analyzer
Architecture Reviewer
Test Case Generator

📦 Installation

npm install @sparesparrow/mcp-prompts

🎯 Quick Start

HTTP Mode

# Start HTTP server
npm start
# or
MODE=http node dist/index.js

# Server runs on http://localhost:3003
# API docs: http://localhost:3003/api-docs
# Health check: http://localhost:3003/health

MCP Mode

# Start MCP server
MODE=mcp node dist/index.js
# or
npm run start:mcp

🔧 Cursor Integration

Configure Cursor MCP: Add to .cursor/mcp.json:
{ "mcpServers": { "mcp-prompts": { "command": "node", "args": ["dist/index.js"], "env": { "MODE": "mcp" } } } }
Restart Cursor to load the MCP server
Use in Cursor:
- The MCP tools will be available in Cursor's AI assistant
- You can ask Cursor to manage prompts using natural language

🐳 Docker Support

Build MCP Docker Image

pnpm run docker:build:mcp

Run with Docker Compose

pnpm run docker:up:mcp

View Logs

pnpm run docker:logs:mcp

📚 Documentation

MCP_README.md - Comprehensive MCP usage guide
API Documentation - Full API reference
Examples - Usage examples and configurations

🛠 Development

Prerequisites

Node.js >= 20.0.0
pnpm >= 9.0.0

Setup

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Start development server
pnpm run dev

Available Scripts

# Build
pnpm run build
pnpm run build:clean

# Start servers
pnpm run start          # Default mode
pnpm run start:http     # HTTP mode
pnpm run start:mcp      # MCP mode

# Docker
pnpm run docker:build:mcp
pnpm run docker:up:mcp
pnpm run docker:down:mcp

# Testing
pnpm run test
pnpm run test:watch

# Linting & Formatting
pnpm run lint
pnpm run format

📊 Project Structure

mcp-prompts/
├── src/
│   ├── index.ts           # Main entry point
│   ├── mcp-server.ts      # MCP server implementation
│   ├── http-server.ts     # HTTP server implementation
│   └── utils.ts           # Utility functions
├── data/
│   └── sample-prompts.json # Pre-loaded templates
├── dist/                  # Compiled output
├── docs/                  # Documentation
├── examples/              # Usage examples
└── docker/                # Docker configurations

🔍 Testing

MCP Server Testing

# Test MCP server functionality
node test-mcp-complete.js

HTTP Server Testing

# Start HTTP server
pnpm run start:http

<<<<<<< HEAD

=======
# Test endpoints
curl http://localhost:3003/health
curl http://localhost:3003/api-docs

📈 Usage Examples

Using MCP Tools

List All Prompts

{
  "method": "tools/call",
  "params": {
    "name": "list_prompts",
    "arguments": {}
  }
}

<<<<<<< HEAD

Build Issues

TypeScript Path Resolution Errors:

# Clear TypeScript cache
rm -rf **/*.tsbuildinfo
pnpm run clean
pnpm run build

SWC Build Failures:

# Ensure SWC is installed
pnpm add -D @swc/cli @swc/core

# Clean and rebuild
pnpm run clean
pnpm run build

Workspace Dependency Issues:

# Reinstall workspace dependencies
pnpm install --force
pnpm run build

Missing Modules or Types:

Ensure you have built @mcp-prompts/core first
Check that all dist/ directories are up to date
If you change the shared config or move files, clean all dist/ directories and rebuild

Runtime Issues

Common Issues:

If you see errors about missing modules or types, ensure you have built @mcp-prompts/core first and that all dist/ directories are up to date.
If you change the shared config or move files, clean all dist/ directories and rebuild.

Architecture

Hexagonal Architecture (Ports & Adapters)

MCP Prompts follows a clean hexagonal architecture pattern:

Core: Pure domain logic without infrastructure dependencies
Ports: Interfaces defined in core package
Adapters: Infrastructure implementations in adapter packages
Apps: Composition and configuration in apps folder

Directory Structure

mcp-prompts/
├── packages/
│   ├── core/                    # Domain logic and ports
│   ├── @sparesparrow/           # Shared packages
│   └── adapters-*/              # Port implementations
├── apps/
│   └── server/                  # MCP server application
└── docs/                        # Documentation

Development

Build Commands

# Build entire workspace
pnpm run build

# Development with watch mode
pnpm run build:watch

# Type checking
pnpm run typecheck

# Clean build artifacts
pnpm run clean

Package-specific Commands

# Core package
pnpm -F @sparesparrow/mcp-prompts-core build
pnpm -F @sparesparrow/mcp-prompts-core test

# Adapter packages
pnpm -F @sparesparrow/mcp-prompts-adapters-file build
pnpm -F @sparesparrow/mcp-prompts-adapters-mdc build

# Server app
pnpm -F apps/server build
pnpm -F apps/server test

Testing

Vitest for unit tests
Playwright for e2e tests
Coverage > 90% for core packages
Integration tests for adapters

API Reference

For detailed API documentation, see:

References

Apply Template

{
  "method": "tools/call",
  "params": {
    "name": "apply_template",
    "arguments": {
      "id": "code_review_assistant",
      "variables": {
        "language": "JavaScript",
        "code": "function hello() { console.log('Hello World'); }"
      }
    }
  }
}

Add New Prompt

{
  "method": "tools/call",
  "params": {
    "name": "add_prompt",
    "arguments": {
      "name": "My Custom Prompt",
      "content": "This is a custom prompt for {{subject}}",
      "isTemplate": true,
      "tags": ["custom", "example"],
      "variables": [
        {
          "name": "subject",
          "description": "The subject to process",
          "required": true,
          "type": "string"
        }
      ]
    }
  }
}

🌟 Features

Template Variables - Use {{variable}} syntax for dynamic content
Tag System - Organize prompts with tags for easy filtering
Metadata Support - Add categories, difficulty, time estimates
Version Control - Track prompt versions and changes
Error Handling - Comprehensive error handling and logging
TypeScript - Full TypeScript support with type definitions
Docker Ready - Containerized deployment support

🤝 Contributing

Fork the repository
Create a feature branch
Implement your changes
Add tests if applicable
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

Issues: GitHub Issues
Documentation: MCP_README.md
Examples: examples/

Version: 3.0.8
Status: ✅ Production Ready
MCP Support: ✅ Full Implementation
Cursor Integration: ✅ Ready

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - not found

quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables creation, management, and templating of prompts through a simplified SOLID architecture, allowing users to organize prompts by category and fill in templates at runtime.

Related Resources

Reddit Discussion about this server

Related MCP Servers

TypeScript Prompt MCP Server
gpaul-mcp
A
security
A
license
A
quality
Provides pre-defined prompt templates for AI assistants to generate comprehensive plans for TypeScript projects, API architectures, and GitHub workflows.
Last updated -
2
1
MIT License
PromptLab MCP Server
iRahulPandey
-
security
A
license
-
quality
Serves prompt templates through a standardized protocol for transforming basic user queries into optimized prompts for AI systems.
Last updated -
6
Apache 2.0
MLflow Prompt Registry MCP Server
B-Step62
-
security
F
license
-
quality
Enables access to prompt templates managed in MLflow through Claude Desktop, allowing users to instruct Claude with saved templates for repetitive tasks or common workflows.
Last updated -
2
Prompts MCP Server
tanker327
A
security
A
license
A
quality
A Model Context Protocol server for managing prompt templates as markdown files with YAML frontmatter, allowing users and LLMs to easily add, retrieve, and manage prompts.
Last updated -
5
3
9
MIT License

View all related MCP servers