README.md•6.11 kB
# Promptopia MCP
[](https://smithery.ai/server/@lumile/promptopia-mcp)
A powerful Model Context Protocol (MCP) server for managing, organizing, and reusing prompt templates with variable substitution and multi-message conversation structures.
## Introduction
Promptopia MCP is a comprehensive MCP server that enables AI applications to efficiently manage prompt templates through the Model Context Protocol. The server provides persistent storage for both single-content prompts and sophisticated multi-message conversation templates, complete with automatic variable detection, substitution capabilities, and seamless integration with MCP-compatible AI clients.
Built with TypeScript and designed for scalability, Promptopia MCP transforms how you work with AI prompts by providing a centralized, reusable prompt management system that integrates directly into your AI workflow through the standardized MCP protocol.
## Why Use This Server?
- **Centralized Prompt Management**: Store, organize, and version all your prompt templates in one secure location with filesystem persistence, eliminating scattered prompt files and ensuring consistency across projects.
- **Advanced Multi-Message Support**: Create sophisticated conversation templates with role-based message structures (user/assistant) that support both text and image content, enabling complex AI interaction patterns.
- **Intelligent Variable Substitution**: Automatically detect variables using `{{variable}}` syntax and apply dynamic values at runtime, making your prompts flexible and reusable across different contexts and use cases.
- **Seamless MCP Integration**: Native MCP protocol support means your prompts automatically become available as first-class resources in Claude Desktop, IDEs, and other MCP-compatible applications without additional configuration.
- **Future-Proof Architecture**: Built with extensibility in mind, supporting prompt chains, conditional logic, versioning, and advanced workflow patterns for evolving AI interaction needs.
## Features
### Core Prompt Management
- **Create and Store Prompts**: Add both single-content and multi-message prompts with automatic variable detection
- **Retrieve and List**: Access individual prompts by ID or browse all available templates with metadata
- **Update and Delete**: Modify existing prompts or remove outdated templates with full CRUD operations
- **Variable Application**: Replace template variables with actual values for immediate use
### Multi-Message Conversation Support
- **Role-Based Messages**: Structure conversations with explicit user and assistant message roles
- **Mixed Content Types**: Support for text and image content within the same conversation template
- **Cross-Message Variables**: Extract and apply variables across multiple messages in a conversation
- **Format Conversion**: Seamlessly convert between single-content and multi-message formats as needed
### MCP Protocol Integration
- **Native MCP Prompts**: Expose stored prompts as MCP prompts for direct use in compatible applications
- **Tool-Based Access**: Complete set of MCP tools for prompt management operations
- **Standardized Communication**: Full compliance with MCP protocol specifications for reliable integration
- **Real-Time Variable Resolution**: Apply variables through the MCP protocol for dynamic prompt execution
### Advanced Capabilities
- **Automatic Variable Detection**: Parse `{{variable}}` patterns from prompt content with intelligent extraction
- **Backward Compatibility**: Maintain support for existing single-content prompts while adding new features
- **File System Persistence**: Reliable JSON-based storage with organized directory structure
- **Error Handling**: Comprehensive error management with informative MCP-compliant error responses
- **Type Safety**: Full TypeScript implementation with robust type definitions and validation
### Planned Features
- **Conditional Logic**: Add branching and conditional execution to prompt templates
- **Version Control**: Track changes and maintain prompt history with rollback capabilities
- **Search and Tagging**: Organize prompts with metadata and full-text search functionality
- **Import/Export**: Backup and share prompt collections across different environments
## Installation
### Installing via Smithery
To install Promptopia for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@lumile/promptopia-mcp):
```bash
npx -y @smithery/cli install @lumile/promptopia-mcp --client claude
```
#### Option 1: NPX (Recommended)
Add this configuration to your Claude Desktop config file:
```json
{
"mcpServers": {
"promptopia-mcp": {
"command": "npx",
"args": [
"-y",
"promptopia-mcp"
],
"env": {
"PROMPTS_DIR": "<YOUR_PROMPTS_DIR>"
}
}
}
}
```
#### Option 2: Local Installation
1. Clone the repository
2. Install dependencies:
```bash
npm install
```
3. Build the server:
```bash
npm run build
```
4. Add this configuration to your Claude Desktop config:
```json
{
"mcpServers": {
"promptopia-mcp": {
"command": "node",
"args": [
"/path/to/promptopia-mcp/build/index.js"
],
"env": {
"PROMPTS_DIR": "<YOUR_PROMPTS_DIR>"
}
}
}
}
```
### Debugging
Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
```bash
npm run inspector
```
The Inspector will provide a URL to access debugging tools in your browser.
## Contributing
Contributions are extremely welcome! Please open a PR with new MCP servers or any other improvements to the codebase.
## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
------
<p align="center">
Made with ❤️ by Lumile
</p>
<p align="center">
<a href="https://www.lumile.com.ar">Contact us</a> for any questions or feedback.
</p>