Servidor MCP QuickerSpot

Este repositório contém o Servidor MCP (Model Context Protocol) oficial do QuickerSpot. Ele permite que assistentes e agentes de IA (como Claude Desktop, Antigravity e Cursor) interajam programaticamente com a plataforma QuickerSpot para criar campanhas comerciais, gerar roteiros via IA, sintetizar áudios TTS e disparar recados instantâneos.

🚀 Requisitos

• Python 3.10 ou superior
• Backend do QuickerSpot rodando e acessível (ex: http://localhost:8000)
• Uma API Key M2M válida gerada no backend (QUICKERSPOT_M2M_API_KEY)

📦 Instalação

1. Clone o repositório e navegue até a pasta do servidor MCP:

cd mcp-server

2. Crie e ative um ambiente virtual Python:

python -m venv venv
# No Windows PowerShell:
.\venv\Scripts\activate
# No Linux/macOS:
source venv/bin/activate

3. Instale as dependências:

pip install -e .

⚙️ Configuração

Copie o arquivo .env.example para .env e ajuste os valores:

cp .env.example .env

Configurações disponíveis:

💻 Configuração em Clientes MCP

Configuração para Claude Desktop / Antigravity

Adicione o servidor no seu arquivo de configuração do Claude Desktop (claude_desktop_config.json) ou Antigravity (mcp.json):

{
  "mcpServers": {
    "quickerspot": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/caminho/para/narrador-comercial/mcp-server",
      "env": {
        "QUICKERSPOT_API_URL": "http://localhost:8000",
        "QUICKERSPOT_M2M_API_KEY": "sua-chave-api-m2m-aqui"
      }
    }
  }
}

🛠️ Ferramentas MCP Disponíveis (tools)

1. list_voices — Retorna o catálogo de vozes comerciais disponíveis.
2. create_campaign — Cria uma nova campanha com lista de produtos e gera o roteiro síncrono via IA.
3. approve_script — Aprova (ou edita) o roteiro de uma campanha e dispara a produção de áudio em background.
4. get_campaign_status — Consulta o status (PENDING, PROCESSING, COMPLETED, FAILED), roteiro e URLs de áudio de uma campanha.
5. list_campaigns — Lista todas as campanhas ativas do usuário.
6. create_recado — Gera áudio instantâneo de recado curto (fast-lane TTS com vinheta, sem HITL).

🧪 Guia de Teste Local e Validação Passo a Passo

Você pode validar o funcionamento do Servidor MCP QuickerSpot no seu ambiente local seguindo o passo a passo abaixo:

Passo 1: Iniciar o Backend FastAPI

1. No arquivo backend/.env, garanta que as variáveis M2M estejam configuradas:

   QUICKERSPOT_M2M_API_KEY=sua-chave-m2m-local
   QUICKERSPOT_M2M_USER_ID=m2m_test_user
   

2. Inicie o servidor FastAPI:

   cd backend
   python main.py
   

   O backend ficará acessível em http://localhost:8000.

Passo 2: Executar a Suíte de Testes Automatizados (E2E e Unitários)

No diretório mcp-server/, execute a suíte de testes que valida todos os endpoints M2M e as ferramentas do MCP:

cd mcp-server
pytest tests/ -v

Você deverá ver todos os 20 testes passarem (20 passed).

Passo 3: Testar com o MCP Inspector (Interface Visual de Debug)

O MCP Inspector é uma ferramenta oficial do Model Context Protocol que permite testar visualmente todas as ferramentas e respostas via navegador web.

1. No terminal da pasta mcp-server, execute:

   npx @modelcontextprotocol/inspector python -m src.server
   

2. Defina as variáveis de ambiente na interface ou no terminal:
   • QUICKERSPOT_API_URL: http://localhost:8000
   • QUICKERSPOT_M2M_API_KEY: sua-chave-m2m-local
3. Acesse a URL informada (ex: http://localhost:5173) para testar chamadas como list_voices, create_campaign, create_recado, etc.

Passo 4: Validar no Antigravity / Claude Desktop

1. Adicione a configuração do servidor MCP no seu cliente (veja a seção Configuração em Clientes MCP acima).
2. Abra uma conversa e peça ao assistente de IA:
   • "Liste as vozes disponíveis na QuickerSpot."
   • "Crie uma campanha de oferta de café para supermercado."
   • "Gere um recado instantâneo: 'Atenção clientes, loja fechando em 15 minutos'."