Smart Prompts MCP Server

Busca e gerencia prompts de repositórios GitHub com recursos inteligentes de descoberta e composição.

GitHub
12
Experimente este MCPPatrocinado

Documentação

Smart Prompts MCP Server

Tests Coverage Performance Node License

Um servidor MCP (Model Context Protocol) aprimorado que busca prompts de repositórios GitHub com recursos inteligentes de descoberta, composição e gerenciamento. Este é um fork aprimorado do prompts-mcp-server com integração GitHub e recursos avançados.

🌟 Principais Recursos

Capacidades Principais

  • 🔄 Integração GitHub: Busca prompts diretamente de repositórios GitHub (públicos/privados)
  • 🔍 Descoberta Inteligente: Busca avançada com filtros por categoria e tag
  • 🔗 Composição de Prompts: Combina múltiplos prompts em fluxos de trabalho
  • 📊 Rastreamento de Uso: Análises sobre padrões de uso de prompts
  • ⚡ Atualizações em Tempo Real: Sincronização automática com o GitHub
  • 🤖 Orientação de IA: Descrições aprimoradas de ferramentas e recomendações de fluxo de trabalho

Suporte ao Protocolo MCP

  • Ferramentas: 7 ferramentas especializadas para gerenciamento de prompts
  • Recursos: 13+ endpoints de recursos para navegação e descoberta
  • Prompts: Modelos dinâmicos com suporte a Handlebars

📋 Pré-requisitos

Antes da instalação, certifique-se de ter:

  • Node.js 18+ instalado
  • Gerenciador de pacotes npm ou yarn
  • Git instalado e configurado
  • Conta GitHub (para integração com GitHub)
  • Token de Acesso Pessoal do GitHub (para repositórios privados ou para evitar limites de taxa)

🚀 Instalação

Passo 1: Clonar e Instalar

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

# Install dependencies
npm install

# Build the project
npm run build

# Verify installation
./verify-install.sh

Passo 2: Configurar Ambiente

Crie um arquivo .env na raiz do projeto:

# Required: GitHub Configuration
GITHUB_OWNER=your-username          # Your GitHub username or org
GITHUB_REPO=your-prompts-repo      # Repository containing prompts
GITHUB_BRANCH=main                  # Branch to use (default: main)
GITHUB_PATH=                        # Subdirectory path (optional)
GITHUB_TOKEN=ghp_xxxxx             # Personal access token (recommended)

# Optional: Cache Configuration
CACHE_TTL=300000                    # Cache time-to-live in ms (default: 5 min)
CACHE_REFRESH_INTERVAL=60000        # Auto-refresh interval in ms (default: 1 min)

# Optional: Feature Flags
ENABLE_SEMANTIC_SEARCH=true         # Advanced search features
ENABLE_PROMPT_COMPOSITION=true      # Prompt combination features
ENABLE_USAGE_TRACKING=true          # Track prompt usage

Passo 3: Configuração do Cliente MCP

Para Claude Desktop (macOS)

Adicione ao ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "smart-prompts": {
      "command": "node",
      "args": ["/absolute/path/to/smart-prompts-mcp/dist/index.js"],
      "env": {
        "GITHUB_OWNER": "your-username",
        "GITHUB_REPO": "your-prompts-repo",
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Para Roo Cline (VS Code)

Adicione às configurações MCP do Roo Cline:

"smart-prompts": {
  "command": "node",
  "args": ["/absolute/path/to/smart-prompts-mcp/dist/index.js"],
  "env": {
    "GITHUB_OWNER": "your-username",
    "GITHUB_REPO": "your-prompts-repo",
    "GITHUB_TOKEN": "ghp_your_token_here"
  }
}

📁 Melhores Práticas de Organização de Prompts

Estrutura de Pastas Recomendada

your-prompts-repo/
├── README.md                    # Repository overview
├── ai-prompts/                  # AI and meta-prompts
│   ├── meta-prompt-builder.md
│   └── prompt-engineer.md
├── development/                 # Development prompts
│   ├── backend/
│   │   ├── api-design.md
│   │   └── database-schema.md
│   ├── frontend/
│   │   ├── react-component.md
│   │   └── vue-composition.md
│   └── testing/
│       ├── unit-test-writer.md
│       └── e2e-test-suite.md
├── content-creation/           # Content prompts
│   ├── blog-post-writer.md
│   └── youtube-metadata.md
├── business/                   # Business prompts
│   ├── proposal-generator.md
│   └── email-templates.md
└── INDEX.md                    # Optional: Category index

Convenções de Nomenclatura

  • Arquivos: Use kebab-case (ex.: api-documentation-generator.md)
  • Nomes de Prompts: Use snake_case no frontmatter (ex.: api_documentation_generator)
  • Categorias: Use minúsculas com hífens (ex.: content-creation)
  • Mantenha nomes descritivos, mas concisos

📝 Formato do Arquivo de Prompt

---
name: api_documentation_generator
title: REST API Documentation Generator
description: Generate comprehensive API documentation with examples
category: documentation
tags: [api, rest, documentation, openapi, swagger]
difficulty: intermediate
author: jezweb
version: 1.0
arguments:
  - name: api_spec
    description: The API specification or endpoint details
    required: true
  - name: format
    description: Output format (markdown, openapi, etc)
    required: false
    default: markdown
---

# API Documentation Generator

Generate comprehensive documentation for {{api_spec}} in {{format}} format.

Include:
- Endpoint descriptions
- Request/response examples
- Authentication details
- Error codes
- Rate limiting information

🛠️ Ferramentas Disponíveis

  1. 🔍 search_prompts - Sempre comece aqui! Busque por palavra-chave, categoria ou tags
  2. 📋 list_prompt_categories - Navegue pelas categorias disponíveis com contagens
  3. 📖 get_prompt - Recupere um prompt específico (use o nome exato da busca)
  4. ✨ create_github_prompt - Crie novos prompts no GitHub
  5. 🔗 compose_prompts - Combine múltiplos prompts
  6. ❓ prompts_help - Obtenha ajuda contextual e orientação
  7. ✅ check_github_status - Verifique a conexão com o GitHub

Fluxo de Trabalho Recomendado

1. search_prompts → Find existing prompts
2. get_prompt → View full content
3. compose_prompts → Combine if needed
4. create_github_prompt → Only if nothing exists

🔧 Solução de Problemas

Problemas Comuns

1. Erro "Falha no acesso ao GitHub"

# Check your token has repo scope
# Verify token in .env file
GITHUB_TOKEN=ghp_your_actual_token

# Test GitHub access
GITHUB_TOKEN=your_token node test-server.js

2. Erro "Limite de taxa excedido"

  • Adicione um token GitHub para aumentar os limites de taxa
  • Reduza o intervalo de atualização do cache
  • Use CACHE_TTL para armazenar em cache por mais tempo

3. "Nenhum prompt encontrado"

  • Verifique se a estrutura do repositório corresponde ao formato esperado
  • Verifique o GITHUB_PATH se estiver usando um subdiretório
  • Garanta que os arquivos .md tenham frontmatter YAML

4. Cliente MCP Não Conectando

  • Use caminhos absolutos na configuração
  • Verifique se o Node.js está no PATH
  • Verifique todas as variáveis de ambiente
  • Verifique os logs: tail -f ~/.claude/logs/mcp.log

5. Desempenho Lento

  • Aumente CACHE_TTL para atualizações menos frequentes
  • Reduza o tamanho do repositório (arquive prompts antigos)
  • Use categorias para limitar o escopo da busca

📈 Considerações de Escala

Limitações Atuais

  1. Limites de Taxa da API GitHub

    • 60 requisições/hora (não autenticado)
    • 5.000 requisições/hora (autenticado)
    • Cada busca de diretório = 1 requisição

  2. Limitações de Busca

    • Sem busca semântica nativa no GitHub
    • Busca linear em todos os arquivos
    • Desempenho degrada com 100+ prompts

Estratégias de Escala

Para 50-200 Prompts

  • ✅ A implementação atual funciona bem
  • Use categorias e tags para organização
  • Implemente cache local
  • Adicione token GitHub para limites de taxa mais altos

Para 200-1000 Prompts

  • 🔄 Implementar Arquivo de Índice 
    # INDEX.md in repo root
prompts:
  - name: api_generator
    path: development/api-generator.md
    category: development
    tags: [api, codegen]
  • 📊 Adicionar Índice de Busca
    • Gere índice de busca na compilação
    • Armazene em search-index.json
    • Atualize via GitHub Actions

Para 1000+ Prompts

  • 🗄️ Camada de Banco de Dados
    • SQLite para cache local
    • Recursos de busca em texto completo
    • Sincronize com o GitHub periodicamente
  • 🔍 Integração Elasticsearch/Algolia
    • Infraestrutura de busca adequada
    • Busca facetada
    • Classificação por relevância

Recursos Futuros de Escala (Roadmap)

  1. Geração de Índice de Busca

    • GitHub Action para construir índice
    • Baixar arquivo de índice único
    • Busca semântica local

  2. Carregamento Preguiçoso

    • Buscar categorias sob demanda
    • Aprimoramento progressivo
    • Rolagem virtual para listas grandes

  3. Suporte a CDN

    • Armazenar prompts em cache na borda
    • Reduzir chamadas à API GitHub
    • Acesso global mais rápido

🚀 Ideias Futuras para Servidores MCP

Com base no padrão de integração GitHub, aqui estão possíveis servidores MCP:

1. Servidor MCP de Snippets de Código

Armazene e gerencie snippets de código reutilizáveis no GitHub

  • Organização por linguagem
  • Destaque de sintaxe
  • Gerenciamento de dependências
  • Histórico de versões

2. MCP de Modelos de Documentação

Biblioteca de modelos de documentação baseada no GitHub

  • Geradores de README
  • Modelos de documentação de API
  • Documentação de projetos
  • Gerado automaticamente a partir do código

3. Servidor MCP de Personas de IA

Gerencie configurações de personalidade de IA

  • Definições de especialização
  • Estilos de comunicação
  • Características comportamentais
  • Compartilhamento em equipe

4. MCP de Estruturação de Projetos

Gerenciamento completo de modelos de projetos

  • Pilhas de tecnologia
  • Código boilerplate
  • Melhores práticas
  • Predefinições de configuração

5. MCP de Recursos de Aprendizagem

Conteúdo educacional selecionado

  • Tutoriais e guias
  • Exemplos de código
  • Rastreamento de progresso
  • Recomendações baseadas em habilidades

6. MCP de Gerenciador de Configurações

Configurações de aplicativos com controle de versão

  • Gerenciamento de ambientes
  • Tratamento de segredos
  • Sincronização em equipe
  • Suporte a rollback

7. MCP de Automação de Fluxos de Trabalho

Integração com GitHub Actions

  • Modelos de fluxos de trabalho
  • Pipelines CI/CD
  • Scripts de automação
  • Orquestração entre repositórios

8. MCP de Base de Conhecimento

Gerenciamento de conhecimento da equipe

  • Pares de perguntas e respostas
  • Guias de solução de problemas
  • Melhores práticas
  • Wiki pesquisável

🧪 Testes

O servidor inclui testes abrangentes para garantir confiabilidade e desempenho.

Recursos do Conjunto de Testes

  • 100% de cobertura de testes das funcionalidades críticas
  • Benchmarks de desempenho com métricas detalhadas
  • Relatórios visuais de testes com gráficos interativos
  • CI/CD automatizado via GitHub Actions

Executando Testes

# Run full test suite
npm test

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run performance benchmark
npm run test:perf

# Verify installation
npm run test:verify

Relatórios de Testes

Os resultados dos testes são gerados automaticamente em múltiplos formatos:

  • JSON: Resultados detalhados para análise (test-results/latest.json)
  • Markdown: Relatórios legíveis por humanos (test-results/latest.md)
  • HTML: Relatórios visuais interativos (test-results/latest.html)

Veja os resultados de testes mais recentes:

🧪 Desenvolvimento

# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

🤝 Contribuindo

Aceitamos contribuições! Veja CONTRIBUTING.md para diretrizes.

Áreas Prioritárias

  1. Melhorias de Busca

    • Implementar busca difusa
    • Adicionar classificação de resultados de busca
    • Suporte a padrões regex

  2. Otimização de Desempenho

    • Implementar pooling de conexões
    • Adicionar agrupamento de requisições
    • Otimizar estratégias de cache

  3. UI/Visualização

    • Interface web para navegação
    • Ferramenta de pré-visualização de prompts
    • Painel de análise de uso

📄 Licença

Licença MIT - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

📞 Suporte

Feito com ❤️ para a comunidade MCP