Prompts MCP Server

Un servidor MCP para gestionar y servir prompts desde archivos markdown con soporte de frontmatter YAML.

Documentación

Servidor MCP de Prompts

Un servidor de Model Context Protocol (MCP) para gestionar y proporcionar prompts. Este servidor permite a usuarios y LLMs agregar, recuperar y gestionar fácilmente plantillas de prompts almacenadas como archivos markdown con soporte de frontmatter YAML.

Inicio Rápido

# 1. Install from NPM
npm install -g prompts-mcp-server

# 2. Add to your MCP client config (e.g., Claude Desktop)
# Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "prompts-mcp-server": {
      "command": "prompts-mcp-server"
    }
  }
}

# 3. Restart your MCP client and start using the tools!

Características

Agregar Prompts: Almacena nuevos prompts como archivos markdown con frontmatter YAML
Recuperar Prompts: Obtén prompts específicos por nombre
Listar Prompts: Visualiza todos los prompts disponibles con vista previa de metadatos
Eliminar Prompts: Elimina prompts de la colección
Almacenamiento Basado en Archivos: Los prompts se almacenan como archivos markdown en el directorio prompts/
Caché en Tiempo Real: Caché en memoria con monitoreo automático de cambios de archivos
Frontmatter YAML: Soporte para metadatos estructurados (título, descripción, etiquetas, etc.)
TypeScript: Implementación completa en TypeScript con definiciones de tipos exhaustivas
Arquitectura Modular: Separación clara de responsabilidades con inyección de dependencias
Pruebas Integrales: 95 pruebas con 84.53% de cobertura de código

Instalación

Opción 1: Desde NPM (Recomendado)

Instala el paquete globalmente desde NPM:

npm install -g prompts-mcp-server

Esto hará que el comando prompts-mcp-server esté disponible en tu sistema.

Después de la instalación, necesitas configurar tu cliente MCP para usarlo. Consulta Configuración del Cliente MCP.

Opción 2: Desde GitHub (para desarrollo)

# Clone the repository
git clone https://github.com/tanker327/prompts-mcp-server.git
cd prompts-mcp-server

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Test the installation
npm test

Opción 3: Descarga Directa

Descarga la última versión desde GitHub
Extrae en la ubicación deseada
Ejecuta los pasos de instalación de la Opción 2.

Verificación

Después de la instalación, verifica que el servidor funcione:

# Start the server (should show no errors)
npm start

# Or test with MCP Inspector
npx @modelcontextprotocol/inspector prompts-mcp-server

Pruebas

Ejecuta la suite de pruebas integral:

npm test

Ejecuta pruebas con cobertura:

npm run test:coverage

Modo de observación para desarrollo:

npm run test:watch

Herramientas MCP

El servidor proporciona las siguientes herramientas:

`add_prompt`

Agrega un nuevo prompt a la colección. Si no se proporciona frontmatter YAML, se agregarán automáticamente metadatos predeterminados.

name (string): Nombre del prompt
content (string): Contenido del prompt en formato markdown con frontmatter YAML opcional

`create_structured_prompt`

Crea un nuevo prompt con estructura de metadatos guiada y validación.

name (string): Nombre del prompt
title (string): Título legible para el prompt
description (string): Breve descripción de lo que hace el prompt
category (string, opcional): Categoría (por defecto "general")
tags (array, opcional): Array de etiquetas para categorización (por defecto ["general"])
difficulty (string, opcional): "beginner", "intermediate" o "advanced" (por defecto "beginner")
author (string, opcional): Autor del prompt (por defecto "User")
content (string): El contenido real del prompt (markdown)

`get_prompt`

Recupera un prompt por nombre.

name (string): Nombre del prompt a recuperar

`list_prompts`

Lista todos los prompts disponibles con vista previa de metadatos. No requiere parámetros.

`delete_prompt`

Elimina un prompt por nombre.

name (string): Nombre del prompt a eliminar

Ejemplos de Uso

Una vez conectado a un cliente MCP, puedes usar las herramientas de la siguiente manera:

Método 1: Creación rápida de prompts con metadatos automáticos

// Add a prompt without frontmatter - metadata will be added automatically
add_prompt({
  name: "debug_helper",
  content: `# Debug Helper

Help me debug this issue by:
1. Analyzing the error message
2. Suggesting potential causes
3. Recommending debugging steps`
})
// This automatically adds default frontmatter with title "Debug Helper", category "general", etc.

Método 2: Creación estructurada de prompts con control total de metadatos

// Create a prompt with explicit metadata using the structured tool
create_structured_prompt({
  name: "code_review",
  title: "Code Review Assistant",
  description: "Helps review code for best practices and potential issues",
  category: "development",
  tags: ["code", "review", "quality"],
  difficulty: "intermediate",
  author: "Development Team",
  content: `# Code Review Prompt

Please review the following code for:
- Code quality and best practices
- Potential bugs or issues
- Performance considerations
- Security vulnerabilities

## Code to Review
[Insert code here]`
})

Método 3: Frontmatter manual (preserva metadatos existentes)

// Add a prompt with existing frontmatter - no changes made
add_prompt({
  name: "custom_prompt",
  content: `---
title: "Custom Assistant"
category: "specialized"
tags: ["custom", "specific"]
difficulty: "advanced"
---

# Custom Prompt Content
Your specific prompt here...`
})

Otras operaciones

// Get a prompt
get_prompt({ name: "code_review" })

// List all prompts (shows metadata preview)
list_prompts({})

// Delete a prompt
delete_prompt({ name: "old_prompt" })

Estructura de Archivos

prompts-mcp-server/
├── src/
│   ├── index.ts          # Main server orchestration
│   ├── types.ts          # TypeScript type definitions
│   ├── cache.ts          # Caching system with file watching
│   ├── fileOperations.ts # File I/O operations
│   └── tools.ts          # MCP tool definitions and handlers
├── tests/
│   ├── helpers/
│   │   ├── testUtils.ts  # Test utilities
│   │   └── mocks.ts      # Mock implementations
│   ├── cache.test.ts     # Cache module tests
│   ├── fileOperations.test.ts # File operations tests
│   ├── tools.test.ts     # Tools module tests
│   └── index.test.ts     # Integration tests
├── prompts/              # Directory for storing prompt markdown files
│   ├── code_review.md
│   ├── debugging_assistant.md
│   └── api_design.md
├── dist/                 # Compiled JavaScript output
├── CLAUDE.md            # Development documentation
├── package.json
├── tsconfig.json
└── README.md

Arquitectura

El servidor utiliza una arquitectura modular con los siguientes componentes:

PromptCache: Caché en memoria con monitoreo de cambios de archivos en tiempo real mediante chokidar
PromptFileOperations: Operaciones de E/S de archivos con integración de caché
PromptTools: Definiciones de herramientas MCP y manejadores de solicitudes
Sistema de Tipos: Tipos TypeScript exhaustivos para todas las estructuras de datos

Soporte de Frontmatter YAML

Los prompts pueden incluir metadatos estructurados usando frontmatter YAML:

---
title: "Prompt Title"
description: "Brief description of the prompt"
category: "development"
tags: ["tag1", "tag2", "tag3"]
difficulty: "beginner" | "intermediate" | "advanced"
author: "Author Name"
version: "1.0"
---

# Prompt Content

Your prompt content goes here...

Configuración del Cliente MCP

Este servidor se puede configurar con varias aplicaciones compatibles con MCP. Aquí tienes instrucciones de configuración para clientes populares:

Claude Desktop

Agrega esto a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "prompts-mcp-server": {
      "command": "prompts-mcp-server",
      "env": {
        "PROMPTS_FOLDER_PATH": "/path/to/your/prompts/directory"
      }
    }
  }
}

Cline (Extensión de VS Code)

Agrega a tu configuración MCP de Cline en VS Code:

{
  "cline.mcp.servers": {
    "prompts-mcp-server": {
      "command": "prompts-mcp-server",
      "env": {
        "PROMPTS_FOLDER_PATH": "/path/to/your/prompts/directory"
      }
    }
  }
}

Continue.dev

En tu ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "prompts-mcp-server",
      "command": "prompts-mcp-server",
      "env": {
        "PROMPTS_FOLDER_PATH": "/path/to/your/prompts/directory"
      }
    }
  ]
}

Editor Zed

En tu configuración de Zed (~/.config/zed/settings.json):

{
  "assistant": {
    "mcp_servers": {
      "prompts-mcp-server": {
        "command": "prompts-mcp-server",
        "env": {
          "PROMPTS_DIR": "/path/to/your/prompts/directory"
        }
      }
    }
  }
}

Cliente MCP Personalizado

Para cualquier aplicación compatible con MCP, usa estos detalles de conexión:

Protocolo: Model Context Protocol (MCP)
Transporte: stdio
Comando: prompts-mcp-server
Variables de Entorno:
- PROMPTS_FOLDER_PATH: Directorio personalizado para almacenar prompts (opcional, por defecto ./prompts)

Configuración de Desarrollo/Pruebas

Para desarrollo o pruebas con el Inspector MCP:

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run the server with inspector
npx @modelcontextprotocol/inspector prompts-mcp-server

Configuración de Docker

Crea un docker-compose.yml para despliegue en contenedores:

version: '3.8'
services:
  prompts-mcp-server:
    build: .
    environment:
      - PROMPTS_FOLDER_PATH=/app/prompts
    volumes:
      - ./prompts:/app/prompts
    stdin_open: true
    tty: true

Configuración del Servidor

El servidor crea automáticamente el directorio prompts/ si no existe
Los archivos de prompts se sanitizan automáticamente para usar nombres de archivo seguros (solo caracteres alfanuméricos, guiones y guiones bajos)
Los cambios de archivos se monitorean en tiempo real y la caché se actualiza automáticamente
El directorio de prompts se puede personalizar mediante la variable de entorno PROMPTS_FOLDER_PATH

Variables de Entorno

Variable	Descripción	Predeterminado
`PROMPTS_FOLDER_PATH`	Directorio personalizado para almacenar archivos de prompts (anula el predeterminado)	(no establecido)
`NODE_ENV`	Modo de entorno	`production`

Nota: Si PROMPTS_FOLDER_PATH está establecido, se usará como directorio de prompts. Si no está establecido, el servidor usa por defecto ./prompts relativo a la ubicación del servidor.

Requisitos

Node.js 18.0.0 o superior
TypeScript 5.0.0 o superior
Dependencias:
- @modelcontextprotocol/sdk ^1.0.0
- gray-matter ^4.0.3 (análisis de frontmatter YAML)
- chokidar ^3.5.3 (observación de archivos)

Desarrollo

El proyecto incluye herramientas integrales para desarrollo:

TypeScript: Verificación estricta de tipos y módulos ES modernos
Vitest: Marco de pruebas rápido con 95 pruebas y 84.53% de cobertura
ESLint: Linting de código (si está configurado)
Observación de Archivos: Actualizaciones de caché en tiempo real durante el desarrollo

Solución de Problemas

Problemas Comunes

Errores de "Module not found"

# Ensure TypeScript is built
npm run build

# Check that dist/ directory exists and contains .js files
ls dist/

El cliente MCP no puede conectarse

Verifica que el servidor se inicie sin errores: npm start
Verifica que se use la ruta correcta en la configuración del cliente
Asegúrate de que Node.js 18+ esté instalado: node --version
Prueba con el Inspector MCP: npx @modelcontextprotocol/inspector prompts-mcp-server

Errores de permisos con el directorio de prompts

# Ensure the prompts directory is writable
mkdir -p ./prompts
chmod 755 ./prompts

La observación de archivos no funciona

En Linux: Instala inotify-tools
En macOS: No se necesita configuración adicional
En Windows: Asegúrate de tener Windows Subsystem for Linux (WSL) o Node.js nativo

Modo de Depuración

Habilita el registro de depuración estableciendo variables de entorno:

# Enable debug mode
DEBUG=* node dist/index.js

# Or with specific debug namespace
DEBUG=prompts-mcp:* node dist/index.js

Obtener Ayuda

Consulta los Problemas de GitHub
Revisa los archivos de prueba para ejemplos de uso
Usa el Inspector MCP para depurar conexiones de clientes
Consulta la documentación de tu cliente MCP para detalles de configuración

Consejos de Rendimiento

El servidor usa caché en memoria para recuperación rápida de prompts
La observación de archivos actualiza automáticamente la caché cuando los archivos cambian
Colecciones grandes de prompts (1000+ archivos) funcionan eficientemente gracias a la caché
Considera usar almacenamiento SSD para mejor rendimiento de E/S de archivos

Variantes y Extensiones de la Comunidad

Proyecto	Mantenedor	Características Adicionales
smart-prompts-mcp	@jezweb	Bibliotecas de prompts alojadas en GitHub, búsqueda avanzada y composición, tipos TypeScript más ricos, etc.

👉 ¿Has construido algo genial sobre prompts-mcp-server?
¡Abre un issue o PR para agregarlo aquí para que otros puedan descubrir tu variante!

Licencia

MIT