mcp-prompts

mcp-prompts

Model Context Protocol server for managing, storing, and providing prompts and prompt templates for LLM interactions.

Stars: 74

Visit
 screenshot

mcp-prompts is a Python library that provides a collection of prompts for generating creative writing ideas. It includes a variety of prompts such as story starters, character development, plot twists, and more. The library is designed to inspire writers and help them overcome writer's block by offering unique and engaging prompts to spark creativity. With mcp-prompts, users can access a wide range of writing prompts to kickstart their imagination and enhance their storytelling skills.

README:

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)

  1. add_prompt - Add new prompts to collection
  2. get_prompt - Retrieve prompts by ID
  3. list_prompts - List prompts with filtering
  4. update_prompt - Update existing prompts
  5. delete_prompt - Remove prompts
  6. apply_template - Apply variables to template prompts
  7. 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

  1. Configure Cursor MCP: Add to .cursor/mcp.json:

    {
      "mcpServers": {
        "mcp-prompts": {
          "command": "node",
          "args": ["dist/index.js"],
          "env": {
            "MODE": "mcp"
          }
        }
      }
    }
  2. Restart Cursor to load the MCP server

  3. 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

🛠 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

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

📄 License

MIT License - see LICENSE file for details.

🆘 Support


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

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for mcp-prompts

Similar Open Source Tools

For similar tasks

For similar jobs