Prompts MCP Server

Um servidor MCP para gerenciar e servir prompts a partir de arquivos markdown com suporte a frontmatter YAML.

Documentação

Servidor MCP de Prompts

Um servidor Model Context Protocol (MCP) para gerenciar e fornecer prompts. Este servidor permite que usuários e LLMs adicionem, recuperem e gerenciem facilmente modelos de prompts armazenados como arquivos markdown com suporte a frontmatter YAML.

Início 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!

Recursos

Adicionar Prompts: Armazene novos prompts como arquivos markdown com frontmatter YAML
Recuperar Prompts: Obtenha prompts específicos pelo nome
Listar Prompts: Visualize todos os prompts disponíveis com pré-visualização de metadados
Excluir Prompts: Remova prompts da coleção
Armazenamento Baseado em Arquivos: Os prompts são armazenados como arquivos markdown no diretório prompts/
Cache em Tempo Real: Cache em memória com monitoramento automático de alterações de arquivos
Frontmatter YAML: Suporte para metadados estruturados (título, descrição, tags, etc.)
TypeScript: Implementação completa em TypeScript com definições de tipos abrangentes
Arquitetura Modular: Separação clara de responsabilidades com injeção de dependências
Testes Abrangentes: 95 testes com 84,53% de cobertura de código

Instalação

Opção 1: Via NPM (Recomendado)

Instale o pacote globalmente via NPM:

npm install -g prompts-mcp-server

Isso tornará o comando prompts-mcp-server disponível no seu sistema.

Após a instalação, você precisa configurar seu cliente MCP para usá-lo. Veja Configuração do Cliente MCP.

Opção 2: Via GitHub (para desenvolvimento)

# 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

Opção 3: Download Direto

Baixe a versão mais recente do GitHub
Extraia para o local desejado
Execute as etapas de instalação da Opção 2.

Verificação

Após a instalação, verifique se o servidor funciona:

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

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

Testes

Execute a suíte de testes abrangente:

npm test

Execute testes com cobertura:

npm run test:coverage

Modo de observação para desenvolvimento:

npm run test:watch

Ferramentas MCP

O servidor fornece as seguintes ferramentas:

`add_prompt`

Adicione um novo prompt à coleção. Se nenhum frontmatter YAML for fornecido, metadados padrão serão adicionados automaticamente.

name (string): Nome do prompt
content (string): Conteúdo do prompt em formato markdown com frontmatter YAML opcional

`create_structured_prompt`

Crie um novo prompt com estrutura de metadados guiada e validação.

name (string): Nome do prompt
title (string): Título legível para o prompt
description (string): Breve descrição do que o prompt faz
category (string, opcional): Categoria (padrão: "general")
tags (array, opcional): Array de tags para categorização (padrão: ["general"])
difficulty (string, opcional): "beginner", "intermediate" ou "advanced" (padrão: "beginner")
author (string, opcional): Autor do prompt (padrão: "User")
content (string): O conteúdo real do prompt (markdown)

`get_prompt`

Recupere um prompt pelo nome.

name (string): Nome do prompt a ser recuperado

`list_prompts`

Liste todos os prompts disponíveis com pré-visualização de metadados. Nenhum parâmetro necessário.

`delete_prompt`

Exclua um prompt pelo nome.

name (string): Nome do prompt a ser excluído

Exemplos de Uso

Uma vez conectado a um cliente MCP, você pode usar as ferramentas assim:

Método 1: Criação rápida de prompt com metadados 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: Criação estruturada de prompt com controle total de metadados

// 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 metadados 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...`
})

Outras operações

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

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

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

Estrutura de Arquivos

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

Arquitetura

O servidor usa uma arquitetura modular com os seguintes componentes:

PromptCache: Cache em memória com monitoramento em tempo real de alterações de arquivos via chokidar
PromptFileOperations: Operações de I/O de arquivos com integração de cache
PromptTools: Definições de ferramentas MCP e manipuladores de solicitações
Sistema de Tipos: Tipos TypeScript abrangentes para todas as estruturas de dados

Suporte a Frontmatter YAML

Os prompts podem incluir metadados estruturados 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...

Configuração do Cliente MCP

Este servidor pode ser configurado com vários aplicativos compatíveis com MCP. Aqui estão as instruções de configuração para clientes populares:

Claude Desktop

Adicione isso ao seu arquivo de configuração do 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 (Extensão VS Code)

Adicione às suas configurações MCP do Cline no VS Code:

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

Continue.dev

No seu ~/.continue/config.json:

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

Editor Zed

Nas suas configurações do 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 qualquer aplicativo compatível com MCP, use estes detalhes de conexão:

Protocolo: Model Context Protocol (MCP)
Transporte: stdio
Comando: prompts-mcp-server
Variáveis de Ambiente:
- PROMPTS_FOLDER_PATH: Diretório personalizado para armazenar prompts (opcional, padrão: ./prompts)

Configuração de Desenvolvimento/Testes

Para desenvolvimento ou testes com o MCP Inspector:

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

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

Configuração Docker

Crie um docker-compose.yml para implantação em contêiner:

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

Configuração do Servidor

O servidor cria automaticamente o diretório prompts/ se ele não existir
Os arquivos de prompt são automaticamente sanitizados para usar nomes de arquivo seguros (apenas caracteres alfanuméricos, hífens e sublinhados)
As alterações de arquivos são monitoradas em tempo real e o cache é atualizado automaticamente
O diretório de prompts pode ser personalizado via variável de ambiente PROMPTS_FOLDER_PATH

Variáveis de Ambiente

Variável	Descrição	Padrão
`PROMPTS_FOLDER_PATH`	Diretório personalizado para armazenar arquivos de prompt (substitui o padrão)	(não definido)
`NODE_ENV`	Modo de ambiente	`production`

Nota: Se PROMPTS_FOLDER_PATH estiver definido, ele será usado como diretório de prompts. Se não estiver definido, o servidor usa o padrão ./prompts relativo ao local do servidor.

Requisitos

Node.js 18.0.0 ou superior
TypeScript 5.0.0 ou superior
Dependências:
- @modelcontextprotocol/sdk ^1.0.0
- gray-matter ^4.0.3 (análise de frontmatter YAML)
- chokidar ^3.5.3 (monitoramento de arquivos)

Desenvolvimento

O projeto inclui ferramentas abrangentes para desenvolvimento:

TypeScript: Verificação estrita de tipos e módulos ES modernos
Vitest: Framework de testes rápido com 95 testes e 84,53% de cobertura
ESLint: Linting de código (se configurado)
Monitoramento de Arquivos: Atualizações de cache em tempo real durante o desenvolvimento

Solução de Problemas

Problemas Comuns

Erros de "Módulo não encontrado"

# Ensure TypeScript is built
npm run build

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

Cliente MCP não consegue conectar

Verifique se o servidor inicia sem erros: npm start
Verifique se o caminho correto é usado na configuração do cliente
Garanta que Node.js 18+ esteja instalado: node --version
Teste com MCP Inspector: npx @modelcontextprotocol/inspector prompts-mcp-server

Erros de permissão com o diretório de prompts

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

Monitoramento de arquivos não funcionando

No Linux: Instale inotify-tools
No macOS: Nenhuma configuração adicional necessária
No Windows: Garanta o Windows Subsystem for Linux (WSL) ou Node.js nativo

Modo de Depuração

Habilite o registro de depuração definindo variáveis de ambiente:

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

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

Obtendo Ajuda

Verifique as Issues do GitHub
Revise os arquivos de teste para exemplos de uso
Use o MCP Inspector para depurar conexões de clientes
Verifique a documentação do seu cliente MCP para detalhes de configuração

Dicas de Desempenho

O servidor usa cache em memória para recuperação rápida de prompts
O monitoramento de arquivos atualiza automaticamente o cache quando os arquivos mudam
Grandes coleções de prompts (1000+ arquivos) funcionam eficientemente devido ao cache
Considere usar armazenamento SSD para melhor desempenho de I/O de arquivos

Variantes e Extensões da Comunidade

Projeto	Mantenedor	Recursos Extras
smart-prompts-mcp	@jezweb	Bibliotecas de prompts hospedadas no GitHub, busca avançada e composição, tipos TypeScript mais ricos, etc.

👉 Você construiu algo legal em cima do prompts-mcp-server?
Abra uma issue ou PR para adicioná-lo aqui para que outros possam descobrir sua variante!

Licença

MIT