Groq MCP Server

# 🚀 Groq MCP Server Um servidor **Model Context Protocol (MCP)** inteligente e completo, projetado para integrar sua aplicação com a poderosa API Groq, oferecendo acesso otimizado aos modelos de IA mais rápidos do mundo. Atua como uma ponte inteligente, permitindo que clientes compatíveis (como o Claude Desktop) utilizem os diversos modelos da Groq para completação de texto, transcrição de áudio, análise de visão e processamento em lote. ## ✨ Características Principais ### 🧠 **Modelos Suportados** Este servidor está configurado para gerenciar e rotear requisições para uma ampla gama de modelos Groq, incluindo: * **Completamento de Texto (LLMs):** * `llama-3.1-8b-instant` * `llama-3.3-70b-versatile` * `deepseek-r1-distill-llama-70b` * `qwen/qwen3-32b` (e `qwen-qwq-32b` para matemática) * `compound-beta`, `compound-beta-mini` * `allam-2-7b`, `gemma2-9b-it`, `llama3-70b-8192`, `llama3-8b-8192` * `mistral-saba-24b` * **Segurança (Prompt/Content Guard):** * `meta-llama/llama-guard-4-12b` * `meta-llama/llama-prompt-guard-2-22m`, `meta-llama/llama-prompt-guard-2-86m` * **Visão (Multimodal):** * `meta-llama/llama-4-maverick-17b-128e-instruct` * `meta-llama/llama-4-scout-17b-16e-instruct` * **Áudio (Speech-to-Text):** * `whisper-large-v3`, `whisper-large-v3-turbo` * `distil-whisper-large-v3-en` * **Texto para Fala (Text-to-Speech):** * `playai-tts`, `playai-tts-arabic` ### ⚡ **Recursos Avançados** * **Roteamento Inteligente (ModelRouter)**: Seleção dinâmica do modelo ideal com base em prioridades (velocidade, qualidade, custo, raciocínio, matemática, multilíngue), complexidade do prompt e capacidades específicas (visão, áudio). * **Rate Limiting Controlado**: Gerenciamento inteligente de limites de requisições e tokens por minuto (RPM/TPM) configuráveis para cada modelo, otimizando o uso da API. * **Cache Otimizado**: Sistema de cache em memória com TTL (Time-To-Live) configurável para respostas de LLMs, reduzindo latência e chamadas redundantes à API. * **Métricas Detalhadas**: Coleta abrangente de métricas de uso, desempenho (latência, throughput), erros e distribuição de modelos para análise e monitoramento. * **Tratamento de Erros Robusto**: Sistema centralizado de tratamento de erros com capacidade de re-tentativas automáticas (retry) para requisições de API, aumentando a resiliência. * **Processamento em Lote**: Suporte à ferramenta de processamento em lote da Groq, permitindo o envio eficiente de grandes volumes de requisições com economia de custo. * **Logging Estruturado e Depuração**: Sistema de logs profissional com Winston, que gera logs estruturados e direciona a saída colorida para `stderr` em desenvolvimento, facilitando a depuração e o monitoramento. ## 🛠️ Instalação ### Pré-requisitos * **Node.js**: Versão `v20.17.0` ou superior, ou `v22.9.0` ou superior. Recomenda-se usar [NVM](https://github.com/nvm-sh/nvm) (ou [nvm-windows](https://github.com/coreybutler/nvm-windows)) para gerenciar as versões do Node.js. * **npm**: Gerenciador de pacotes Node.js (geralmente incluído com o Node.js e compatível com as versões recomendadas). * **TypeScript**: Versão 5 ou superior. * **Chave API do Groq**: Necessária para autenticar as requisições à API Groq. Obtenha a sua em [https://console.groq.com/keys](https://console.groq.com/keys). ### Instalação Rápida 1. **Clone o repositório:** ```bash git clone [https://github.com/AyrtonFelipe/GroqCloud-MCP_server.git] cd groq-mcp-server ``` 2. **Instale as dependências do projeto:** ```bash npm install # Instale também a biblioteca para conversão de schemas Zod para JSON Schema npm install zod-to-json-schema ``` 3. **Configure as variáveis de ambiente:** Crie um arquivo `.env` na raiz do projeto (se não existir, você pode copiar do `.env.example` se fornecido): ```bash cp .env.example .env ``` Edite o arquivo `.env` com sua chave API do Groq: ``` GROQ_API_KEY="sua_chave_api_groq_aqui" ``` *(Opcional: configure outras variáveis como `LOG_LEVEL` conforme necessário.)* 4. **Atualize `src/config/models.json`:** Este arquivo define os modelos Groq que seu servidor irá usar e expor. * **Remova** entradas de modelos que não estão mais disponíveis ou que não se deseja usar (verifique as listas mais recentes no console Groq). * **Adicione** todos os modelos da lista de "Modelos Suportados" (acima) que ainda não estão presentes. Para cada novo modelo, você deve **preencher todas as suas propriedades** (nome, descrição, capacidades, `costPer1kTokens`, `rateLimits`, etc.) consultando a [documentação oficial da Groq](https://console.groq.com/docs/) para obter os valores precisos. * **Ajuste as seções `modelSelectionRules` e `complexityThresholds`** em `models.json` para refletir os modelos que você tem e a lógica de seleção desejada (ex: para prioridades de `reasoning`, `mathematical`, `multilingual`). 5. **Atualize `src/config/constants.ts`:** * Sincronize a constante `RATE_LIMITS` com os modelos presentes no seu `models.json`. Certifique-se de que cada modelo em `models.json` tenha uma entrada correspondente em `RATE_LIMITS` com `rpm` (requests per minute) e `tpm` (tokens per minute) precisos (consulte a documentação da Groq para os valores mais recentes). * Atualize também os `z.enum` nos arquivos das suas ferramentas (`src/tools/*.ts`) para incluir os novos modelos que você deseja expor ao cliente. 6. **Compile o projeto:** ```bash npm run build ``` 7. **Inicie o servidor:** ```bash npm start ``` Seu servidor estará ativo e aguardando conexões via `stdin/stdout`. ## 🤝 Uso com o Claude Desktop Uma vez que seu servidor MCP esteja rodando localmente, o Claude Desktop deve ser capaz de descobri-lo e usar suas ferramentas: 1. **Inicie o Claude Desktop.** 2. **Verifique as Ferramentas:** As ferramentas Groq (`groq_text_completion`, `groq_audio_transcription`, `groq_vision_analysis`, `groq_batch_processing`) devem aparecer ativadas na interface do Claude Desktop (geralmente no menu de ferramentas ou integração). 3. **Interaja:** Comece a conversar com o Claude e peça para ele usar as ferramentas. Exemplos: * `Use groq_text_completion para gerar um texto sobre as capacidades do Groq para IA.` * `Com a ferramenta groq_text_completion, analise os dados financeiros { dados: [100, 250, 80, 400] } e use o modelo: llama-3.3-70b-versatile` * `groq_audio_transcription: transcreva o arquivo 'caminho/para/seu/audio.mp3' usando 'whisper-large-v3-turbo'.` * `groq_vision_analysis: descreva a imagem em 'https://example.com/sua-imagem.jpg' usando 'meta-llama/llama-4-scout-17b-16e-instruct'.` ## 📊 Estrutura do Projeto ```` . ├── src/ │ ├── config/ │ │ ├── constants.ts \# Constantes do sistema (RATE\_LIMITS, API\_ENDPOINTS, etc.) │ │ └── models.json \# Definições detalhadas dos modelos Groq │ ├── tools/ │ │ ├── audio-transcription.ts \# Ferramenta para transcrição de áudio │ │ ├── batch-processing.ts \# Ferramenta para processamento em lote │ │ ├── model-router.ts \# Lógica central para seleção de modelos │ │ ├── text-completion.ts \# Ferramenta para completação de texto │ │ └── vision-analysis.ts \# Ferramenta para análise de visão │ │ └── ... (novas ferramentas como Text-to-Speech, se implementadas) │ ├── types/ │ │ └── groq-types.ts \# Definições de tipos TypeScript para modelos Groq │ ├── utils/ │ │ ├── cache-manager.ts \# Gerenciador de cache │ │ ├── error-handler.ts \# Tratamento centralizado de erros e retries │ │ ├── logger.ts \# Configuração de logging com Winston │ │ ├── metrics-tracker.ts \# Coleta de métricas de uso e desempenho │ │ └── rate-limiter.ts \# Implementação de rate limiting │ └── server.ts \# Ponto de entrada principal do servidor MCP ├── dist/ \# Saída da compilação TypeScript ├── logs/ \# Logs da aplicação ├── .env \# Variáveis de ambiente (ex: GROQ\_API\_KEY) ├── .gitignore \# Arquivos e pastas a serem ignorados pelo Git ├── package.json \# Metadados e dependências do projeto ├── tsconfig.json \# Configurações do compilador TypeScript └── README.md \# Este arquivo ``` ## 📈 Próximos Passos (Escalabilidade para Web) Este projeto está configurado para uso local com `StdioServerTransport`. Para escalar para um ambiente de servidor web (e.g., produção), as seguintes considerações seriam cruciais: * **Transporte de Comunicação:** Migrar de `StdioServerTransport` para um transporte web como **Server-Sent Events (SSE)** ou WebSockets para comunicação com clientes web. * **Mecanismo de Start:** Adaptar o ciclo de vida do servidor para um framework web (e.g., Express, Fastify) que escuta em portas HTTP/HTTPS. * **Protocolagem:** Implementar rotas HTTP que mapeiam para chamadas JSON-RPC do MCP. * **Segurança:** Adicionar autenticação (e.g., JWT), autorização, HTTPS, e configuração de CORS para proteger o servidor. * **Escalabilidade:** Implementar estratégias para lidar com múltiplos clientes e alto tráfego (e.g., load balancing, clusters Node.js, caches distribuídos como Redis para `CacheManager` e `RateLimiter`). --- **Desenvolvido por Ayrton Felipe.**