Uberall MCP Server

Integra com a API da Uberall para gerenciar listagens de negócios, locais e presença em redes sociais.

Documentação

[!WARNING]

⚠️ Obsoleto — use o servidor MCP hospedado da Plataforma Uberall

Este projeto está obsoleto e não é mais mantido. Era um servidor MCP local stdio que rodava na sua máquina e chamava a API da Uberall com sua chave de API. Ele foi substituído pelo servidor MCP hospedado da Plataforma Uberall — remoto, compatível com OAuth e que não requer instalação local.

Endpoint: https://mcp.uberall.com/mcp (remoto, HTTP streamable)

Documentação e configuração: https://docs.uberall.com/guides/platform-mcp

Autenticação: OAuth 2.0 para usuários padrão, ou um cabeçalho Authorization: Bearer <API_KEY> para usuários API_ADMIN

Início rápido (Claude):
claude mcp add-json uberall '{"type":"http","url":"https://mcp.uberall.com/mcp"}'
Para acesso com chave de API API_ADMIN:
claude mcp add-json uberall '{"type":"http","url":"https://mcp.uberall.com/mcp","headers":{"Authorization":"Bearer UBERALL_API_KEY"}}'
Por que a mudança: o servidor local stdio não podia ser conectado a plataformas de agentes hospedadas/remotas, que é o que os clientes precisam cada vez mais. O servidor MCP hospedado da Plataforma fornece um único endpoint remoto, OAuth padrão e um catálogo crescente de ferramentas (Locations Hub, Listings, Social, Reviews e muito mais).

Este repositório está arquivado (somente leitura) e mantido apenas para referência histórica. Nenhuma atualização, correção ou versão adicional será publicada aqui. Perguntas: api@uberall.com

_{A documentação original abaixo é mantida apenas para referência.}

🚀 Uberall MCP Server

Um servidor Model Context Protocol (MCP) que se integra à API da Uberall, permitindo que assistentes de IA gerenciem perfeitamente listagens de negócios, locais e presença em redes sociais em múltiplas plataformas.

🎯 O que é MCP?

O Model Context Protocol permite que assistentes de IA como Claude, Cursor ou VS Code Copilot se conectem a ferramentas externas e fontes de dados. Este servidor atua como uma ponte entre assistentes de IA e a poderosa plataforma Uberall.

Isso permite integração perfeita com LLMs como Claude, Cursor ou APIs de Modelos de Linguagem para fluxos de trabalho abrangentes de gerenciamento de negócios.

🚀 Início Rápido

📦 Opção 1: Baixar o JAR Pré-compilado

# Download the latest release
curl -L -o uberall-mcp-server.jar https://github.com/uberall/uberall-mcp-server/releases/latest/download/uberall-mcp-server.jar

# Set your credentials
export UBERALL_URL="https://sandbox.uberall.com"
export UBERALL_ACCESS_TOKEN="your_access_token_here"

# Run the server
java -jar uberall-mcp-server.jar

🐳 Opção 2: Usar Docker

export UBERALL_URL="https://sandbox.uberall.com"
export UBERALL_ACCESS_TOKEN="your_access_token_here"
docker run --rm -i -e UBERALL_ACCESS_TOKEN -e UBERALL_URL uberall/uberall-mcp-server:latest

🛠️ Opção 3: Compilar a partir do Código-Fonte

git clone https://github.com/uberall/uberall-mcp-server.git
cd uberall-mcp-server
./gradlew shadowJar

export UBERALL_URL="https://sandbox.uberall.com"
export UBERALL_ACCESS_TOKEN="your_access_token_here"
java -jar build/libs/uberall-mcp-server.jar

🔧 Configuração Detalhada

Pré-requisitos

Java 17 ou superior (verifique com java -version)
Docker (alternativa à instalação do Java)
Gradle (apenas se for compilar a partir do código-fonte)

⚠️ Importante: Este servidor requer Java 17+. Se você receber UnsupportedClassVersionError, está executando uma versão mais antiga do Java. Use java -version para verificar sua versão.

Variáveis de Ambiente Necessárias

Antes de executar o servidor, você deve definir estas variáveis de ambiente:

UBERALL_URL (obrigatório): URL base da API da Uberall
- Produção: https://uberall.com
- Sandbox: https://sandbox.uberall.com
UBERALL_ACCESS_TOKEN (obrigatório): Seu token de acesso à API da Uberall

Obtenha seu Token de Acesso à API da Uberall:

Para obter seu token de acesso à API, siga a documentação oficial da Uberall: 📖 Guia de Autenticação da API

📦 Opções de Instalação

Baixe o JAR mais recente em GitHub Releases:

curl -L -o uberall-mcp-server.jar https://github.com/uberall/uberall-mcp-server/releases/latest/download/uberall-mcp-server.jar

Download manual:

Visite GitHub Releases
Baixe uberall-mcp-server.jar da versão mais recente

Em seguida, execute:

# Set environment variables
export UBERALL_URL="https://sandbox.uberall.com"
export UBERALL_ACCESS_TOKEN="your_access_token_here"
java -jar uberall-mcp-server.jar

🧠 Configure com Ferramentas de IA

Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "uberall-mcp-server": {
      "command": ["java", "-jar", "/path/to/uberall-mcp-server.jar"],
      "env": {
        "UBERALL_ACCESS_TOKEN": "your_access_token_here",
        "UBERALL_URL": "https://sandbox.uberall.com"
      }
    }
  }
}

Outros Clientes MCP (Cursor, VS Code, etc.)

Para outras ferramentas compatíveis com MCP, você pode usar esta abordagem de configuração geral:

Crie um arquivo mcp.json no seu projeto:

touch mcp.json

Adicione a seguinte configuração ao arquivo:

{
  "mcpServers": {
    "uberall-mcp-server": {
      "command": "java",
      "args": ["-jar", "/path/to/uberall-mcp-server.jar"],
      "type": "stdio",
      "env": {
        "UBERALL_ACCESS_TOKEN": "your_access_token_here",
        "UBERALL_URL": "https://sandbox.uberall.com"
      }
    }
  }
}

Salve o arquivo e reinicie sua IDE/ferramenta. Você agora deve conseguir acessar todas as ferramentas!

Outros Clientes MCP: A lista de clientes MCP populares está disponível aqui.

💡 Dica: Substitua /path/to/uberall-mcp-server.jar pelo caminho real onde você baixou o arquivo JAR.

🐳 Suporte a Docker

Usando a imagem Docker pré-construída (Recomendado)

export UBERALL_ACCESS_TOKEN="your_access_token_here"
export UBERALL_URL="https://sandbox.uberall.com"
docker run --rm -i -e UBERALL_ACCESS_TOKEN -e UBERALL_URL uberall/uberall-mcp-server:latest

🧠 Uso com Claude Desktop

Configure no seu claude_desktop_config.json:

{
  "mcpServers": {
    "uberall-mcp-server": {
      "command": [
        "docker", "run", "--rm", "-i", 
        "-e", "UBERALL_ACCESS_TOKEN", 
        "-e", "UBERALL_URL", 
        "uberall/uberall-mcp-server:latest"
      ],
      "env": {
        "UBERALL_ACCESS_TOKEN": "your_access_token_here",
        "UBERALL_URL": "https://sandbox.uberall.com"
      }
    }
  }
}

🧠 Uso com Outros Clientes MCP (Cursor, VS Code, etc.)

Para outras ferramentas compatíveis com MCP usando Docker, use esta configuração:

Crie um arquivo mcp.json no seu projeto:

touch mcp.json

Adicione a seguinte configuração ao arquivo:

{
  "mcpServers": {
    "uberall-mcp-server": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
      "-e", "UBERALL_ACCESS_TOKEN", 
      "-e", "UBERALL_URL", 
      "uberall/uberall-mcp-server:latest"],
      "type": "stdio",
      "env": {
        "UBERALL_ACCESS_TOKEN": "your_access_token_here",
        "UBERALL_URL": "https://sandbox.uberall.com"
      }
    }
  }
}

Salve o arquivo e reinicie sua IDE/ferramenta. Você agora deve conseguir acessar todas as ferramentas!

✨ Recursos

🔌 Compatível com o Protocolo MCP - Funciona com qualquer assistente de IA compatível com MCP
🏢 Gerenciamento de Negócios - Encontre e gerencie suas listagens de negócios
📍 Gerenciamento de Locais - Acesse e gerencie dados de locais
📱 Integração com Redes Sociais - Crie publicações em múltiplas plataformas (Google, Facebook, etc.)
🔍 Busca Avançada - Filtre negócios, locais e publicações sociais
🐳 Pronto para Docker - Imagens Docker multi-plataforma pré-construídas
⚡ Rápido e Leve - Construído com corrotinas Kotlin para desempenho ideal

🛠️ Ferramentas Disponíveis

O servidor MCP fornece as seguintes ferramentas para interagir com a API da Uberall:

`find_businesses`

Encontre negócios aos quais o usuário tem acesso. Os IDs de negócios podem ser usados para criar publicações sociais e encontrar locais.

Parâmetros:

query (obrigatório): Consulta de busca para filtrar por nome, endereço, CEP, cidade, país ou identificador

Retorna: Lista de negócios com seus IDs e nomes

`find_locations`

Encontre locais que pertencem a negócios. Os IDs de locais são necessários para criar publicações sociais.

Parâmetros:

query (opcional): Filtre locais por vários campos
businessIds (opcional): Matriz de IDs de negócios para filtrar locais

Retorna: Lista de locais com IDs, nomes, informações do negócio e cidade Nota: Os IDs de locais retornados devem ser usados em create_social_post salvo indicação em contrário

`create_social_post`

Crie uma publicação em redes sociais para locais e plataformas especificados.

Parâmetros:

title (opcional): Título da publicação (padrão: "Social Post")
description (obrigatório): Conteúdo/descrição da publicação
directories (obrigatório): Matriz de plataformas sociais em MAIÚSCULAS (ex.: ["GOOGLE", "FACEBOOK"])
publicationDate (obrigatório): String de data ISO 8601 (YYYY-MM-dd'T'HH:mm:ssXXXXX)
locations (obrigatório): Matriz de IDs de locais de find_locations

Retorna: Objeto de publicação social criado com links específicos da plataforma e status

`search_social_posts`

Busque e filtre publicações sociais existentes acessíveis pelo usuário.

Parâmetros (todos opcionais):

max: Número máximo de publicações a retornar (padrão: 50)
offset: Deslocamento de paginação (padrão: 0)
locationIds: Matriz de IDs de locais para filtrar
businessIds: Matriz de IDs de negócios para filtrar
statuses: Matriz de status de publicações: ["SCHEDULED", "ACTIVE", "APPROVAL_NEEDED", "ENDED"]
directories: Matriz de plataformas sociais em MAIÚSCULAS
minPublicationDate: Filtro de data mínima (YYYY-MM-dd)
maxPublicationDate: Filtro de data máxima (YYYY-MM-dd)

Retorna: Matriz de publicações sociais que correspondem aos critérios de filtro

📚 Exemplos

Uso Básico com Claude Desktop

Após a configuração, você pode usar linguagem natural para interagir com seus dados da Uberall:

"Find all my coffee shop locations in Berlin"
→ Uses find_businesses + find_locations

"Create a holiday promotion post for all my restaurants, scheduled for December 25th"
→ Uses find_businesses + find_locations + create_social_post

"Show me all my social posts from last month that are still active"
→ Uses search_social_posts with date filters

Fluxo de Trabalho Típico

Encontre seus negócios: "Show me my business listings"
Obtenha locais: "What locations do I have for [business name]?"
Crie publicações sociais: "Create a promotional post for Black Friday at all my retail locations"
Monitore publicações: "Show me all scheduled social posts for this week"

🔧 Tratamento de Erros

O servidor implementa tratamento abrangente de erros com mensagens claras e acionáveis:

Erros de Configuração

Variáveis de Ambiente Ausentes: Mensagens claras indicando quais variáveis são necessárias
URLs Inválidas: Validação dos endpoints da API da Uberall

Problemas de Versão do Java

UnsupportedClassVersionError: Você está executando uma versão mais antiga do Java

# Check your Java version
java -version
# Should show version 17.x.x or higher

# If you see version 8, 11, etc., install Java 17+
# macOS: brew install openjdk@17
# Ubuntu: apt install openjdk-17-jre
# Windows: Download from https://adoptium.net/

Erros de Validação

Parâmetros Obrigatórios: Mensagens específicas para parâmetros obrigatórios ausentes nas ferramentas
Erros de Formato de Data: Orientação clara sobre formatos de data esperados (ISO 8601)
Matrizes Vazias: Validação de que matrizes obrigatórias contêm pelo menos um item

Erros de API

Autenticação: Mensagens claras para tokens de acesso inválidos
Problemas de Rede: Tratamento de tempo limite e erros de conectividade
Limitação de Taxa: Tratamento adequado dos limites de taxa da API com lógica de nova tentativa

Exemplo de Resposta de Erro

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error: Publication date is required"
    }
  ]
}

🔍 Solução de Problemas

Problemas Comuns

"Erro de Configuração: a variável de ambiente UBERALL_URL é obrigatória"

Solução: Defina as variáveis de ambiente necessárias antes de executar:

export UBERALL_URL="https://sandbox.uberall.com"
export UBERALL_ACCESS_TOKEN="your_token_here"

"Erro: a variável de ambiente UBERALL_ACCESS_TOKEN é obrigatória"

Solução: Certifique-se de que seu token de acesso seja válido e esteja definido corretamente:

export UBERALL_ACCESS_TOKEN="your_valid_token"

A compilação falha com erro do wrapper Gradle

Solução: Use o Gradle do sistema em vez disso:

gradle build
gradle shadowJar

O contêiner Docker falha ao iniciar

Solução: Certifique-se de que as variáveis de ambiente sejam passadas corretamente:

docker run --rm -i -e UBERALL_ACCESS_TOKEN="$UBERALL_ACCESS_TOKEN" -e UBERALL_URL="$UBERALL_URL" uberall-mcp-server

Erro "Formato de data de publicação inválido"

Solução: Use o formato ISO 8601 com fuso horário:

2024-12-06T14:30:00+01:00

Resposta vazia de chamadas de API

Possíveis causas:

Token de acesso inválido
Sem permissões para os recursos solicitados
Problemas de conectividade de rede
Endpoint da API temporariamente indisponível

Solução: Verifique as permissões do seu token de acesso e a conectividade de rede.

Modo de Depuração

Para informações adicionais de depuração, verifique os logs do aplicativo para mensagens de erro detalhadas e rastreamentos de pilha.

Obtendo Ajuda

Se você encontrar problemas não abordados aqui:

Verifique a configuração das suas variáveis de ambiente
Verifique se seu token de acesso tem as permissões necessárias
Certifique-se de estar usando um endpoint compatível da API da Uberall
Verifique os logs do aplicativo para informações detalhadas de erro

🤝 Contribuindo

Aceitamos contribuições! Consulte nosso Guia de Contribuição para detalhes.

Configuração Rápida de Desenvolvimento

git clone https://github.com/uberall/uberall-mcp-server.git
cd uberall-mcp-server
cp src/test/resources/test-config-example.properties src/test/resources/test-config.properties
# Edit test-config.properties with your test credentials
./gradlew test

📄 Licença

🔗 Links

Model Context Protocol - Saiba mais sobre MCP
Claude Desktop - Assistente de IA com suporte a MCP
Documentação da API da Uberall - Documentação oficial da API
GitHub Issues - Reporte bugs ou solicite recursos