Prompt Registry

Un servidor ligero basado en archivos para gestionar y servir prompts a través de stdio.

GitHub
7
Prueba este MCPPatrocinado

Documentación

MseeP.ai Security Assessment Badge

Prompt Registry: Tu Servidor Personal de Registro de Prompts 🏰✍️

smithery badge

MCP Prompt Registry es un servidor de prompts ligero y basado en archivos para el Model Context Protocol (MCP), diseñado para desarrolladores. Se ejecuta mediante stdio, lo que lo hace perfecto para desarrollo local e integración con CLIs o asistentes de IA de escritorio que soporten MCP. Te permite gestionar tus prompts en un único directorio, manteniendo tu flujo de trabajo simple y portátil.

✨ Características

  • Directorio Único de Almacenamiento de Prompts:
    • Todos los prompts se almacenan en un único directorio. Puedes controlar la ubicación con la variable de entorno PROMPT_REGISTRY_PROJECT_DIR. Si no se establece, los prompts se guardan en ~/.promptregistry/ en tu directorio de inicio.
  • Basado en Archivos: Los prompts son archivos JSON simples: fáciles de leer, editar y controlar versiones.
  • Cumplimiento Estándar de MCP:
    • Expone prompts mediante prompts/list estándar (lista todos los prompts).
    • Permite usar prompts mediante prompts/get estándar (aplica variables de plantilla).
    • Notifica a los clientes sobre cambios mediante notifications/prompts/list_changed.
  • Gestión mediante Herramientas MCP:
    • add_prompt: Añadir nuevos prompts.
    • get_prompt_file_content: Ver el JSON crudo de un prompt.
    • update_prompt: Modificar prompts.
    • delete_prompt: Eliminar prompts.
    • filter_prompts_by_tags: Descubrir prompts por etiquetas.
  • Interfaz Stdio: Se comunica a través de entrada/salida estándar, ideal para herramientas locales.
  • Variables de Plantilla: Soporta sintaxis {{variable_name}} en el contenido de los prompts.
  • Validación de Esquema Zod: Validación robusta para los argumentos de las herramientas.

Requisitos Previos

  • Node.js: Versión 18 o superior.
  • npm (o yarn).
  • (Opcional) Docker: Si deseas ejecutar el servidor en un contenedor.

📁 Estructura de Directorios para Prompts

El servidor utiliza un único directorio para todos los prompts:

  1. Si la variable de entorno PROMPT_REGISTRY_PROJECT_DIR está establecida, los prompts se almacenan en ese directorio.
  2. Si no está establecida, los prompts se guardan en ~/.promptregistry/ en tu directorio de inicio. En el primer inicio, o si faltan prompts, el servidor intentará copiar prompts predefinidos desde un directorio local default_prompts_data/ (si está presente) a ~/.promptregistry/.

Estructura del Archivo JSON de Prompt (your-prompt-id.json):

{
  "id": "your-prompt-id",
  "description": "A brief description for MCP listing",
  "content": "Your prompt template, e.g., Explain {{concept}} like I'm {{age}}.",
  "tags": ["tag1", "category_a"],
  "variables": {
    "concept": { "description": "The concept to explain", "required": true },
    "age": { "description": "The target audience's age", "required": false }
  },
  "metadata": { "version": "1.1", "author": "You" }
}

🚀 Instalación y Ejecución

Instalación mediante Smithery

Para instalar Prompt Registry para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @stevengonsalvez/promptregistry-mcp --client claude

1. Usando el Paquete NPM Publicado (Recomendado para Clientes)

Si promptregistry-mcp está publicado en npm, los clientes pueden ejecutarlo fácilmente.

  1. Asegúrate de que Node.js y npx estén instalados.
  2. Configura tu cliente MCP (como Claude Desktop o Amazon Q) para usarlo. Consulta los ejemplos a continuación.

2. Instalación Local/Manual (Para Desarrollo o Uso Directo)

  1. Clona el repositorio o descarga los archivos: (Asumiendo que tienes server.ts, package.json, tsconfig.json y un directorio opcional default_prompts_data/)

  2. Instala las dependencias: Navega al directorio raíz del servidor en tu terminal:

    npm install
# or
# yarn install

  3. Compila el servidor (compilar TypeScript):

    npm run build

    Esto creará un directorio dist/ con el JavaScript compilado.

  4. Ejecuta el servidor:

    • Para desarrollo (usa tsx para ejecutar TypeScript directamente, con reinicio automático en cambios): 
      npm run dev
    • Para ejecutar la versión compilada: 
      npm run start:prod

    El servidor comenzará a escuchar en stdin y a emitir en stdout. Los mensajes de consola del servidor (como "Server is running...") aparecerán en stderr.

    Creará el directorio de prompts (ya sea según lo especificado por PROMPT_REGISTRY_PROJECT_DIR o ~/.promptregistry/) si no existe.

3. Ejecución con Docker

  1. Construye la imagen Docker: Asegúrate de tener Docker instalado. Desde el directorio raíz del servidor:

    docker build -t mcp-promptregistry .

    (Puedes cambiar mcp-promptregistry a promptregistry-mcp o el nombre de imagen que prefieras)

  2. Ejecuta el contenedor Docker:

    docker run -i -t --rm mcp-promptregistry
    • -i: Mantener STDIN abierto (interactivo).

    El contenedor tendrá su propio directorio de prompts interno. Para persistir prompts fuera del contenedor o usar prompts locales existentes:

    # Example: Mount local directory into the container
docker run -i -t --rm \
  -v "$HOME/.promptregistry:/root/.promptregistry" \
  mcp-promptregistry

    (Nota: El directorio de inicio para el usuario root dentro del contenedor Alpine es /root)

🔌 Conexión con Clientes MCP

Así es como podrías configurar clientes como Claude Desktop o Amazon Q para usar tu MCP Prompt Registry. La estructura JSON exacta puede variar ligeramente según la implementación del cliente, pero la idea central es definir un servidor stdio.

Opción A: Usando el Paquete NPM (Hipotéticamente) Publicado promptregistry-mcp

Si este servidor se publicara en npm como promptregistry-mcp, la configuración sería muy limpia:

// Example client configuration JSON
{
  "mcpServers": {
    "mcp-promptregistry": {
      "command": "npx",
      "args": [
        "mcp-promptregistry"
      ],
      "env": {
        "PROMPT_REGISTRY_PROJECT_DIR": "/path/to/your/prompts" 
      }
    }
  }
}

Esto asume que promptregistry-mcp cuando se ejecuta mediante npx inicia correctamente el servidor stdio.

Opción B: Ejecución desde Código Fuente Local (Compilado)

Si has compilado el servidor localmente y deseas apuntar tu cliente a él:

// Example client configuration JSON
{
  "mcpServers": {
    "localPromptRegistry": {
      "command": "node", 
      "args": [
        "/full/path/to/your/mcp-promptregistry/dist/server.js"
      ],
      "env": {}
    }
  }
}

Reemplaza /full/path/to/your/mcp-promptregistry/ con la ruta absoluta real donde clonaste/compilaste el servidor.

Consideraciones Importantes para la Configuración del Cliente:

  • Rutas Absolutas: Al especificar rutas para comandos locales (Opción B), usa siempre rutas absolutas, ya que la aplicación cliente podría ejecutar el comando desde un directorio de trabajo diferente.
  • Variables de Entorno (env): Usa PROMPT_REGISTRY_PROJECT_DIR para controlar dónde se almacenan los prompts.
  • Estructura Específica del Cliente: La clave de nivel superior (por ejemplo, "mcpServers") y la estructura exacta pueden variar entre diferentes aplicaciones cliente MCP. Adapta command, args y env para ajustarse a los requisitos del cliente. La clave es cómo invoca tu servidor stdio.

🧪 Probando el Servidor

1. Stdio Manual (JSON-RPC)

La forma más directa de probar. Ejecuta tu servidor, luego pega mensajes JSON-RPC en la misma terminal y presiona Enter.

Ejemplo de solicitud prompts/list:

{"jsonrpc":"2.0","id":"list1","method":"prompts/list"}

La respuesta JSON-RPC del servidor aparecerá en stdout. Los registros del servidor aparecerán en stderr.

Ejemplo de llamada a herramienta add_prompt:

{"jsonrpc":"2.0","id":"add1","method":"tools/call","params":{"name":"add_prompt","arguments":{"id":"my-test-prompt","content":"Test content: {{var1}}","tags":["test"],"variables":{"var1":{"description":"A test variable"}}}}}

2. MCP Inspector

El MCP Inspector es una herramienta GUI que puede conectarse a servidores MCP.

  • Para conectarse a un servidor local en ejecución (compilado):

    mcp-inspector --stdio "node /path/to/your/mcp-promptregistry/dist/server.js"

  • Para conectarse al contenedor Docker:

    mcp-inspector --stdio "docker run -i --rm mcp-promptregistry"

    (Reemplaza mcp-promptregistry con el nombre de tu imagen si es diferente. Asegúrate de que mcp-inspector esté instalado y en tu PATH.)

    El Inspector te permite ver los prompts y herramientas disponibles, hacer solicitudes y ver respuestas de forma interactiva.

🧰 Uso con Claude Desktop (Flujo de Trabajo de Ejemplo)

Una vez que MCP Prompt Registry se agrega como servidor MCP en Claude Desktop (usando una de las configuraciones anteriores):

  1. Descubrir Prompts: Tus prompts personalizados deberían aparecer en la biblioteca de prompts de Claude Desktop o ser accesibles mediante su interfaz de comandos (por ejemplo, escribiendo / o similar, según la interfaz de Claude). El description que estableciste en el archivo JSON de tu prompt será visible.
  2. Seleccionar un Prompt: Elige uno de tus prompts.
  3. Completar Argumentos: Si el prompt tiene variables (por ejemplo, {{concept}}, {{age}}), Claude Desktop debería proporcionar campos de interfaz para que ingreses estos valores. El description para cada variable (desde el JSON de tu prompt) puede guiar al usuario.
  4. Ejecutar: Claude Desktop enviará una solicitud prompts/get a tu servidor con los argumentos completados. Tu servidor aplicará la plantilla y devolverá el contenido final del prompt a Claude.
  5. Herramientas de Gestión: Para usar herramientas como add_prompt o filter_prompts_by_tags desde Claude Desktop, Claude necesitaría una forma de enviar solicitudes tools/call arbitrarias a los servidores MCP conectados. Si esto no se soporta directamente, normalmente usarías MCP Inspector o stdio manual junto con Claude para tareas de gestión.

🛠️ Herramientas de Gestión Disponibles

Tu MCP Prompt Registry expone las siguientes herramientas (invocables mediante solicitudes MCP tools/call):

  • add_prompt: Añade un nuevo prompt al directorio de prompts.
    • Argumentos: id, content, description (opcional), tags (opcional), variables (opcional), metadata (opcional).
  • get_prompt_file_content: Recupera la definición JSON cruda del prompt.
    • Argumentos: id.
  • update_prompt: Actualiza un prompt existente.
    • Argumentos: id, y cualquier campo a actualizar (content, description, etc.).
  • delete_prompt: Elimina un prompt del directorio de prompts.
    • Argumentos: id.
  • filter_prompts_by_tags: Lista los prompts que coinciden con todas las etiquetas especificadas. Devuelve un resumen (id, descripción, etiquetas).
    • Argumentos: tags (array de cadenas).
  • load_default_prompts: Copia todos los prompts del directorio default_prompts_data/ (si está presente) al directorio de prompts activo, omitiendo los que ya existen. Útil para poblar o restaurar prompts predeterminados.
    • Argumentos: Ninguno.

ejemplo

output

⚠️ Solución de Problemas y Advertencias

  • Registro del Servidor Stdio: Recuerda, console.log() en tu server.ts romperá la comunicación MCP a través de stdio porque escribe en stdout. Todos los registros de diagnóstico/estado del servidor deben usar console.error(), que escribe en stderr. Para registros que deseas que el cliente pueda ver, usa la capacidad de registro de MCP mediante context.sendNotification en los manejadores de herramientas (si el cliente lo soporta).
  • Mensajes de Inicio del Servidor en Stderr: Algunos mensajes iniciales de inicio del servidor, como la creación de directorios o la carga automática de prompts predeterminados, aparecerán en stderr (por ejemplo, Attempting to create prompt directory: /Users/stevengonsalvez/.promptregistry o Auto-loaded 2 default prompt(s) into ~/.promptregistry: code-review-assistant, prompt-writing-assistant). Esto se debe a que stdout está reservado para mensajes JSON-RPC de MCP, y estas acciones de inicio ocurren antes de que haya un contexto de cliente disponible para sendNotification.
  • Permisos: Asegúrate de que el proceso del servidor tenga permisos de escritura para el directorio de prompts.
  • Validez JSON: Asegúrate de que tus archivos JSON de prompts sean válidos.
  • Rutas Absolutas para Clientes: Al configurar clientes con rutas de servidor locales, usa siempre rutas absolutas.

🌱 Contribuciones e Ideas Futuras

¡Este es un punto de partida! Las mejoras futuras podrían incluir:

  • Plantillas más sofisticadas.
  • Un modo de vigilancia para recargar automáticamente los prompts cuando los archivos cambian.
  • Soporte para otros backends de almacenamiento (por ejemplo, postgres, github (o gists), sqllite).

¡Las solicitudes de extracción y las ideas son bienvenidas!