Metadata-Version: 2.4
Name: quickerspot-mcp
Version: 0.1.1
Summary: Servidor MCP oficial para o QuickerSpot
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: respx>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"

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

```bash
cd mcp-server
```

2. Crie e ative um ambiente virtual Python:

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

3. Instale as dependências:

```bash
pip install -e .
```

---

## ⚙️ Configuração

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

```bash
cp .env.example .env
```

Configurações disponíveis:

| Variável | Descrição | Valor Padrão |
|----------|-----------|--------------|
| `QUICKERSPOT_API_URL` | URL base do backend FastAPI | `http://localhost:8000` |
| `QUICKERSPOT_M2M_API_KEY` | Chave de API Machine-to-Machine | `sua-chave-api-m2m-aqui` |

---

## 💻 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`):

```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:
   ```env
   QUICKERSPOT_M2M_API_KEY=sua-chave-m2m-local
   QUICKERSPOT_M2M_USER_ID=m2m_test_user
   ```
2. Inicie o servidor FastAPI:
   ```bash
   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:

```bash
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:
   ```bash
   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'."*

