Prompt Registry

Um servidor leve baseado em arquivos para gerenciar e servir prompts via stdio.

GitHub
7
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

Prompt Registry: Seu Servidor Pessoal de Registro de Prompts 🏰✍️

smithery badge

MCP Prompt Registry é um servidor de prompts leve e baseado em arquivos, projetado para desenvolvedores, que segue o Model Context Protocol (MCP). Ele é executado via stdio, sendo perfeito para desenvolvimento local e integração com CLIs ou assistentes de IA desktop que suportam MCP. Ele permite gerenciar seus prompts em um único diretório, mantendo seu fluxo de trabalho simples e portátil.

✨ Recursos

  • Diretório Único de Armazenamento de Prompts:
    • Todos os prompts são armazenados em um único diretório. Você pode controlar a localização com a variável de ambiente PROMPT_REGISTRY_PROJECT_DIR. Se não for definida, os prompts são armazenados em ~/.promptregistry/ no seu diretório pessoal.
  • Baseado em Arquivos: Os prompts são arquivos JSON simples – fáceis de ler, editar e versionar.
  • Conformidade Padrão com MCP:
    • Expõe prompts via prompts/list padrão (lista todos os prompts).
    • Permite que prompts sejam usados via prompts/get padrão (aplica variáveis de template).
    • Notifica clientes sobre alterações via notifications/prompts/list_changed.
  • Gerenciamento via Ferramentas MCP:
    • add_prompt: Adicionar novos prompts.
    • get_prompt_file_content: Visualizar o JSON bruto de um prompt.
    • update_prompt: Modificar prompts.
    • delete_prompt: Remover prompts.
    • filter_prompts_by_tags: Descobrir prompts por tags.
  • Interface Stdio: Comunica-se via entrada/saída padrão, ideal para ferramentas locais.
  • Variáveis de Template: Suporta sintaxe {{variable_name}} no conteúdo dos prompts.
  • Validação de Schema Zod: Validação robusta para argumentos de ferramentas.

Pré-requisitos

  • Node.js: Versão 18 ou superior.
  • npm (ou yarn).
  • (Opcional) Docker: Se você quiser executar o servidor em um contêiner.

📁 Estrutura de Diretórios para Prompts

O servidor usa um único diretório para todos os prompts:

  1. Se a variável de ambiente PROMPT_REGISTRY_PROJECT_DIR estiver definida, os prompts são armazenados nesse diretório.
  2. Se não estiver definida, os prompts são armazenados em ~/.promptregistry/ no seu diretório pessoal. Na primeira inicialização, ou se os prompts estiverem ausentes, o servidor tentará copiar prompts predefinidos de um diretório local default_prompts_data/ (se presente) para ~/.promptregistry/.

Estrutura do Arquivo 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" }
}

🚀 Instalação e Execução

Instalação via Smithery

Para instalar o Prompt Registry para Claude Desktop automaticamente via Smithery:

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

1. Usando o Pacote NPM Publicado (Recomendado para Clientes)

Se promptregistry-mcp for publicado no npm, os clientes podem executá-lo facilmente.

  1. Garanta que Node.js e npx estejam instalados.
  2. Configure seu cliente MCP (como Claude Desktop ou Amazon Q) para usá-lo. Veja exemplos abaixo.

2. Instalação Local/Manual (Para Desenvolvimento ou Uso Direto)

  1. Clone o repositório ou baixe os arquivos: (Supondo que você tenha server.ts, package.json, tsconfig.json e um diretório opcional default_prompts_data/)

  2. Instale as dependências: Navegue até o diretório raiz do servidor no seu terminal:

    npm install
# or
# yarn install

  3. Compile o servidor (compilar TypeScript):

    npm run build

    Isso criará um diretório dist/ com o JavaScript compilado.

  4. Execute o servidor:

    • Para desenvolvimento (usa tsx para executar TypeScript diretamente, com reinício automático em alterações): 
      npm run dev
    • Para executar a versão compilada: 
      npm run start:prod

    O servidor começará a escutar em stdin e a enviar saída para stdout. Mensagens de console do servidor (como "Server is running...") aparecerão em stderr.

    Ele criará o diretório de prompts (conforme especificado por PROMPT_REGISTRY_PROJECT_DIR ou ~/.promptregistry/) se não existir.

3. Executando com Docker

  1. Construa a imagem Docker: Garanta que o Docker esteja instalado. A partir do diretório raiz do servidor:

    docker build -t mcp-promptregistry .

    (Você pode alterar mcp-promptregistry para promptregistry-mcp ou o nome de imagem de sua preferência)

  2. Execute o contêiner Docker:

    docker run -i -t --rm mcp-promptregistry
    • -i: Mantém STDIN aberto (interativo).

    O contêiner terá seu próprio diretório de prompts interno. Para persistir prompts fora do contêiner ou usar prompts locais existentes:

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

    (Nota: O diretório pessoal do usuário root dentro do contêiner Alpine é /root)

🔌 Conectando com Clientes MCP

Veja como você pode configurar clientes como Claude Desktop ou Amazon Q para usar seu MCP Prompt Registry. A estrutura JSON exata pode variar ligeiramente dependendo da implementação do cliente, mas a ideia central é definir um servidor stdio.

Opção A: Usando o Pacote NPM (Hipoteticamente) Publicado promptregistry-mcp

Se este servidor fosse publicado no npm como promptregistry-mcp, a configuração seria muito limpa:

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

Isso assume que promptregistry-mcp quando executado via npx inicia corretamente o servidor stdio.

Opção B: Executando a Partir do Código-Fonte Local (Compilado)

Se você compilou o servidor localmente e deseja apontar seu cliente para ele:

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

Substitua /full/path/to/your/mcp-promptregistry/ pelo caminho absoluto real onde você clonou/compilou o servidor.

Considerações Importantes para Configuração do Cliente:

  • Caminhos Absolutos: Ao especificar caminhos para comandos locais (Opção B), sempre use caminhos absolutos, pois o aplicativo cliente pode executar o comando a partir de um diretório de trabalho diferente.
  • Variáveis de Ambiente (env): Use PROMPT_REGISTRY_PROJECT_DIR para controlar onde os prompts são armazenados.
  • Estrutura Específica do Cliente: A chave de nível superior (por exemplo, "mcpServers") e a estrutura exata podem variar entre diferentes aplicativos clientes MCP. Adapte command, args e env para atender aos requisitos do cliente. O importante é como ele invoca seu servidor stdio.

🧪 Testando o Servidor

1. Stdio Manual (JSON-RPC)

A maneira mais direta de testar. Execute seu servidor, cole mensagens JSON-RPC no mesmo terminal e pressione Enter.

Exemplo de solicitação prompts/list:

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

A resposta JSON-RPC do servidor aparecerá em stdout. Os logs do servidor aparecerão em stderr.

Exemplo de chamada de ferramenta 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

O MCP Inspector é uma ferramenta GUI que pode se conectar a servidores MCP.

  • Para conectar a um servidor em execução local (compilado):

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

  • Para conectar ao contêiner Docker:

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

    (Substitua mcp-promptregistry pelo nome da sua imagem, se diferente. Garanta que mcp-inspector esteja instalado e no seu PATH.)

    O Inspector permite que você veja prompts e ferramentas disponíveis, faça solicitações e visualize respostas interativamente.

🧰 Usando com Claude Desktop (Exemplo de Fluxo de Trabalho)

Depois que o MCP Prompt Registry for adicionado como servidor MCP no Claude Desktop (usando uma das configurações acima):

  1. Descobrir Prompts: Seus prompts personalizados devem aparecer na biblioteca de prompts do Claude Desktop ou ser acessíveis via sua interface de comando (por exemplo, digitando / ou similar, dependendo da interface do Claude). O description que você definiu no arquivo JSON do seu prompt será visível.
  2. Selecionar um Prompt: Escolha um dos seus prompts.
  3. Preencher Argumentos: Se o prompt tiver variáveis (por exemplo, {{concept}}, {{age}}), o Claude Desktop deve fornecer campos de interface para você inserir esses valores. O description para cada variável (do JSON do seu prompt) pode orientar o usuário.
  4. Executar: O Claude Desktop enviará uma solicitação prompts/get ao seu servidor com os argumentos preenchidos. Seu servidor aplicará o template e retornará o conteúdo final do prompt ao Claude.
  5. Ferramentas de Gerenciamento: Para usar ferramentas como add_prompt ou filter_prompts_by_tags a partir do Claude Desktop, o Claude precisaria de uma maneira de enviar solicitações tools/call arbitrárias aos servidores MCP conectados. Se isso não for suportado diretamente, você normalmente usaria o MCP Inspector ou stdio manual junto com o Claude para tarefas de gerenciamento.

🛠️ Ferramentas de Gerenciamento Disponíveis

Seu MCP Prompt Registry expõe as seguintes ferramentas (chamáveis via solicitações MCP tools/call):

  • add_prompt: Adiciona um novo prompt ao diretório de prompts.
    • Args: id, content, description (opcional), tags (opcional), variables (opcional), metadata (opcional).
  • get_prompt_file_content: Recupera a definição JSON bruta do prompt.
    • Args: id.
  • update_prompt: Atualiza um prompt existente.
    • Args: id e quaisquer campos a atualizar (content, description, etc.).
  • delete_prompt: Exclui um prompt do diretório de prompts.
    • Args: id.
  • filter_prompts_by_tags: Lista prompts que correspondem a todas as tags especificadas. Retorna um resumo (id, descrição, tags).
    • Args: tags (array de strings).
  • load_default_prompts: Copia todos os prompts do diretório default_prompts_data/ (se presente) para o diretório de prompts ativo, ignorando os que já existem. Útil para popular ou restaurar prompts padrão.
    • Args: Nenhum.

exemplo

output

⚠️ Solução de Problemas e Armadilhas

  • Registro de Logs do Servidor Stdio: Lembre-se, console.log() no seu server.ts quebrará a comunicação MCP via stdio porque escreve em stdout. Todos os logs de diagnóstico/status do lado do servidor devem usar console.error(), que escreve em stderr. Para logs que você deseja que o cliente potencialmente veja, use o recurso de logging do MCP via context.sendNotification nos manipuladores de ferramentas (se o cliente suportar).
  • Mensagens de Inicialização do Servidor no Stderr: Algumas mensagens iniciais de inicialização do servidor, como criação de diretório ou carregamento automático de prompts padrão, aparecerão em stderr (por exemplo, Attempting to create prompt directory: /Users/stevengonsalvez/.promptregistry ou Auto-loaded 2 default prompt(s) into ~/.promptregistry: code-review-assistant, prompt-writing-assistant). Isso ocorre porque stdout é reservado para mensagens JSON-RPC do MCP, e essas ações de inicialização ocorrem antes que um contexto de cliente esteja disponível para sendNotification.
  • Permissões: Garanta que o processo do servidor tenha permissões de escrita para o diretório de prompts.
  • Validade do JSON: Garanta que seus arquivos JSON de prompt sejam válidos.
  • Caminhos Absolutos para Clientes: Ao configurar clientes com caminhos de servidor locais, sempre use caminhos absolutos.

🌱 Contribuindo e Ideias Futuras

Este é um ponto de partida! Aprimoramentos futuros podem incluir:

  • Templates mais sofisticados.
  • Um modo de observação para recarregar prompts automaticamente quando os arquivos mudarem.
  • Suporte para outros backends de armazenamento (por exemplo, postgres, github (ou gists), sqllite).

Pull requests e ideias são bem-vindos!