🚀 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 (ou 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.

Instalação Rápida

Clone o repositório:

git clone [https://github.com/AyrtonFelipe/GroqCloud-MCP_server.git]
cd groq-mcp-server

Instale as dependências do projeto:

npm install
# Instale também a biblioteca para conversão de schemas Zod para JSON Schema
npm install zod-to-json-schema

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):
```
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.)
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 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).
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.
Compile o projeto:
```
npm run build
```
Inicie o servidor:
```
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:

Inicie o Claude Desktop.
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).
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.**

🚀 Groq MCP Server

✨ 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 (ou 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.

Instalação Rápida

Clone o repositório:

git clone [https://github.com/AyrtonFelipe/GroqCloud-MCP_server.git]
cd groq-mcp-server

Instale as dependências do projeto:

npm install
# Instale também a biblioteca para conversão de schemas Zod para JSON Schema
npm install zod-to-json-schema

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):

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.)

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 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).

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.

Compile o projeto:

npm run build

Inicie o servidor:

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:

Inicie o Claude Desktop.

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).

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.**