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.

📂 list_categories

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

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

2. Adicione a configuração do servidor:

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

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

1. Cliente envia initialize com suas capacidades
2. Servidor responde com suas capacidades e informações
3. Cliente envia initialized para confirmar
4. Cliente pode listar ferramentas com tools/list
5. 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

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

Claude Desktop não conecta

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

🔄 Atualizações

Para atualizar o servidor:

1. Modificar arquivos no diretório /root/mcp-server/
2. 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:

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

📄 Licença

MIT License - Veja o arquivo LICENSE para detalhes.