TalkHub Store MCP Server

Servidor MCP (Model Context Protocol) para integração com Supabase, permitindo que assistentes de IA acessem e manipulem dados da loja.

🚀 Funcionalidades

O servidor expõe as seguintes ferramentas via protocolo MCP:

🔍 search_products

Busca produtos no catálogo com filtros avançados:

Busca por nome ou descrição
Filtro por categoria
Filtro por disponibilidade
Paginação com limit e offset

📦 get_product_by_id

Obtém detalhes completos de um produto específico pelo ID.

Lista todas as categorias de produtos disponíveis.

📊 analyze_products

Gera estatísticas detalhadas dos produtos:

Total de produtos
Produtos disponíveis/indisponíveis
Preço médio, mínimo e máximo
Distribuição por faixa de preço

🔎 advanced_search

Busca avançada com múltiplos filtros:

Faixa de preço (mínimo e máximo)
Ordenação por nome, preço, data ou ordem
Direção da ordenação (ascendente/descendente)

📋 Pré-requisitos

Docker e Docker Compose instalados
Stack Supabase em execução
Rede talkhub criada
Volume mcp_node_modules criado

🛠️ Instalação

1. Criar volumes e diretórios necessários

# Criar volume para node_modules
docker volume create mcp_node_modules

# Criar diretório para o servidor MCP
mkdir -p /root/mcp-server
cd /root/mcp-server

2. Criar arquivos do servidor

Copie os seguintes arquivos para /root/mcp-server/:

server.js - Servidor principal
package.json - Dependências do projeto
test-client.js - Cliente de teste (opcional)

3. Deploy da stack

# Copiar docker-compose.yml para o diretório
# Fazer deploy via Portainer ou:
docker stack deploy -c docker-compose.yml mcp-server

4. Verificar logs

# Ver logs do container
docker service logs mcp-server_mcp-server

🔧 Configuração

Variáveis de Ambiente

O servidor utiliza as seguintes variáveis de ambiente (já configuradas no docker-compose.yml):

PORT: Porta do servidor (padrão: 3033)
SUPABASE_URL: URL do Supabase
SUPABASE_ANON_KEY: Chave anônima do Supabase
SUPABASE_SERVICE_KEY: Chave de serviço do Supabase
MCP_SERVER_NAME: Nome do servidor MCP
MCP_SERVER_VERSION: Versão do servidor

Configuração no Claude Desktop

Localize o arquivo de configuração do Claude Desktop:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Adicione a configuração do servidor:

{
  "mcpServers": {
    "talkhub-store": {
      "command": "curl",
      "args": [
        "-N",
        "-H",
        "Accept: text/event-stream",
        "https://mcp.talkhub.me/"
      ]
    }
  }
}

Reinicie o Claude Desktop

🧪 Testes

Testar localmente

# Dentro do container
docker exec -it [container_id] sh
npm test

Testar remotamente

# Teste de saúde
curl https://mcp.talkhub.me/health

# Teste SSE
curl -N -H "Accept: text/event-stream" https://mcp.talkhub.me/

# Teste JSON-RPC
curl -X POST https://mcp.talkhub.me/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

🏗️ Arquitetura

Protocolo MCP

O servidor implementa o Model Context Protocol v2024-11-05 com suporte para:

JSON-RPC 2.0: Comunicação principal
Server-Sent Events (SSE): Streaming de dados
WebSocket: Conexões bidirecionais

Fluxo de Comunicação

Cliente envia initialize com suas capacidades
Servidor responde com suas capacidades e informações
Cliente envia initialized para confirmar
Cliente pode listar ferramentas com tools/list
Cliente executa ferramentas com tools/call

Estrutura de Resposta

Todas as ferramentas retornam respostas no formato:

{
  "content": [{
    "type": "text",
    "text": "{ ... json response ... }"
  }]
}

🔐 Segurança

CORS configurado para permitir origens necessárias
Helmet.js para headers de segurança
Autenticação via Supabase service key
HTTPS obrigatório via Traefik

📊 Monitoramento

Logs via Morgan em formato combined
Health check endpoint em /health
Métricas de uptime disponíveis

🚨 Troubleshooting

Container não inicia

# Verificar logs
docker service logs mcp-server_mcp-server

# Verificar se a rede existe
docker network ls | grep talkhub

# Verificar se o volume existe
docker volume ls | grep mcp_node_modules

Erro de conexão com Supabase

Verificar se as chaves estão corretas
Verificar se o Supabase está acessível
Testar conexão direta: curl https://supatalk.talkhub.me/rest/v1/produtos

Claude Desktop não conecta

Verificar configuração do claude_desktop_config.json
Reiniciar Claude Desktop
Verificar logs do servidor
Testar endpoint SSE manualmente

🔄 Atualizações

Para atualizar o servidor:

Modificar arquivos no diretório /root/mcp-server/
Reiniciar o serviço:

docker service update --force mcp-server_mcp-server

📝 Exemplos de Uso

Buscar produtos com "salgado"

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {
      "query": "salgado",
      "limit": 10
    }
  }
}

Analisar produtos por categoria

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "analyze_products",
    "arguments": {
      "categoria_id": "uuid-da-categoria"
    }
  }
}

🤝 Contribuição

Para adicionar novas ferramentas:

Editar server.js
Adicionar novo método em setupTools()
Registrar com this.registerTool()
Testar com test-client.js
Documentar no README

📄 Licença

MIT License - Veja o arquivo LICENSE para detalhes.