quickerspot-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- quickerspot_mcp-0.1.0/PKG-INFO +163 -0
- quickerspot_mcp-0.1.0/README.md +148 -0
- quickerspot_mcp-0.1.0/pyproject.toml +34 -0
- quickerspot_mcp-0.1.0/setup.cfg +4 -0
- quickerspot_mcp-0.1.0/src/__init__.py +3 -0
- quickerspot_mcp-0.1.0/src/client.py +119 -0
- quickerspot_mcp-0.1.0/src/quickerspot_mcp.egg-info/PKG-INFO +163 -0
- quickerspot_mcp-0.1.0/src/quickerspot_mcp.egg-info/SOURCES.txt +15 -0
- quickerspot_mcp-0.1.0/src/quickerspot_mcp.egg-info/dependency_links.txt +1 -0
- quickerspot_mcp-0.1.0/src/quickerspot_mcp.egg-info/entry_points.txt +2 -0
- quickerspot_mcp-0.1.0/src/quickerspot_mcp.egg-info/requires.txt +9 -0
- quickerspot_mcp-0.1.0/src/quickerspot_mcp.egg-info/top_level.txt +3 -0
- quickerspot_mcp-0.1.0/src/server.py +228 -0
- quickerspot_mcp-0.1.0/tests/test_client.py +166 -0
- quickerspot_mcp-0.1.0/tests/test_e2e_mcp_campaign.py +197 -0
- quickerspot_mcp-0.1.0/tests/test_e2e_mcp_recado.py +101 -0
- quickerspot_mcp-0.1.0/tests/test_server.py +140 -0
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: quickerspot-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Servidor MCP oficial para o QuickerSpot
|
|
5
|
+
Requires-Python: >=3.10
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
Requires-Dist: mcp<2.0.0,>=1.0.0
|
|
8
|
+
Requires-Dist: httpx>=0.27.0
|
|
9
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
10
|
+
Provides-Extra: dev
|
|
11
|
+
Requires-Dist: pytest>=8.0.0; extra == "dev"
|
|
12
|
+
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
|
|
13
|
+
Requires-Dist: respx>=0.21.0; extra == "dev"
|
|
14
|
+
Requires-Dist: ruff>=0.3.0; extra == "dev"
|
|
15
|
+
|
|
16
|
+
# Servidor MCP QuickerSpot
|
|
17
|
+
|
|
18
|
+
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.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 🚀 Requisitos
|
|
23
|
+
|
|
24
|
+
- **Python 3.10** ou superior
|
|
25
|
+
- Backend do QuickerSpot rodando e acessível (ex: `http://localhost:8000`)
|
|
26
|
+
- Uma **API Key M2M** válida gerada no backend (`QUICKERSPOT_M2M_API_KEY`)
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 📦 Instalação
|
|
31
|
+
|
|
32
|
+
1. Clone o repositório e navegue até a pasta do servidor MCP:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
cd mcp-server
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
2. Crie e ative um ambiente virtual Python:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
python -m venv venv
|
|
42
|
+
# No Windows PowerShell:
|
|
43
|
+
.\venv\Scripts\activate
|
|
44
|
+
# No Linux/macOS:
|
|
45
|
+
source venv/bin/activate
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
3. Instale as dependências:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pip install -e .
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## ⚙️ Configuração
|
|
57
|
+
|
|
58
|
+
Copie o arquivo `.env.example` para `.env` e ajuste os valores:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
cp .env.example .env
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Configurações disponíveis:
|
|
65
|
+
|
|
66
|
+
| Variável | Descrição | Valor Padrão |
|
|
67
|
+
|----------|-----------|--------------|
|
|
68
|
+
| `QUICKERSPOT_API_URL` | URL base do backend FastAPI | `http://localhost:8000` |
|
|
69
|
+
| `QUICKERSPOT_M2M_API_KEY` | Chave de API Machine-to-Machine | `sua-chave-api-m2m-aqui` |
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 💻 Configuração em Clientes MCP
|
|
74
|
+
|
|
75
|
+
### Configuração para Claude Desktop / Antigravity
|
|
76
|
+
|
|
77
|
+
Adicione o servidor no seu arquivo de configuração do Claude Desktop (`claude_desktop_config.json`) ou Antigravity (`mcp.json`):
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"mcpServers": {
|
|
82
|
+
"quickerspot": {
|
|
83
|
+
"command": "python",
|
|
84
|
+
"args": ["-m", "src.server"],
|
|
85
|
+
"cwd": "/caminho/para/narrador-comercial/mcp-server",
|
|
86
|
+
"env": {
|
|
87
|
+
"QUICKERSPOT_API_URL": "http://localhost:8000",
|
|
88
|
+
"QUICKERSPOT_M2M_API_KEY": "sua-chave-api-m2m-aqui"
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 🛠️ Ferramentas MCP Disponíveis (`tools`)
|
|
98
|
+
|
|
99
|
+
1. **`list_voices`** — Retorna o catálogo de vozes comerciais disponíveis.
|
|
100
|
+
2. **`create_campaign`** — Cria uma nova campanha com lista de produtos e gera o roteiro síncrono via IA.
|
|
101
|
+
3. **`approve_script`** — Aprova (ou edita) o roteiro de uma campanha e dispara a produção de áudio em background.
|
|
102
|
+
4. **`get_campaign_status`** — Consulta o status (`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`), roteiro e URLs de áudio de uma campanha.
|
|
103
|
+
5. **`list_campaigns`** — Lista todas as campanhas ativas do usuário.
|
|
104
|
+
6. **`create_recado`** — Gera áudio instantâneo de recado curto (fast-lane TTS com vinheta, sem HITL).
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 🧪 Guia de Teste Local e Validação Passo a Passo
|
|
109
|
+
|
|
110
|
+
Você pode validar o funcionamento do **Servidor MCP QuickerSpot** no seu ambiente local seguindo o passo a passo abaixo:
|
|
111
|
+
|
|
112
|
+
### Passo 1: Iniciar o Backend FastAPI
|
|
113
|
+
|
|
114
|
+
1. No arquivo `backend/.env`, garanta que as variáveis M2M estejam configuradas:
|
|
115
|
+
```env
|
|
116
|
+
QUICKERSPOT_M2M_API_KEY=sua-chave-m2m-local
|
|
117
|
+
QUICKERSPOT_M2M_USER_ID=m2m_test_user
|
|
118
|
+
```
|
|
119
|
+
2. Inicie o servidor FastAPI:
|
|
120
|
+
```bash
|
|
121
|
+
cd backend
|
|
122
|
+
python main.py
|
|
123
|
+
```
|
|
124
|
+
*O backend ficará acessível em `http://localhost:8000`.*
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
### Passo 2: Executar a Suíte de Testes Automatizados (E2E e Unitários)
|
|
129
|
+
|
|
130
|
+
No diretório `mcp-server/`, execute a suíte de testes que valida todos os endpoints M2M e as ferramentas do MCP:
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
cd mcp-server
|
|
134
|
+
pytest tests/ -v
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Você deverá ver todos os 20 testes passarem (`20 passed`).
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
### Passo 3: Testar com o MCP Inspector (Interface Visual de Debug)
|
|
142
|
+
|
|
143
|
+
O **MCP Inspector** é uma ferramenta oficial do Model Context Protocol que permite testar visualmente todas as ferramentas e respostas via navegador web.
|
|
144
|
+
|
|
145
|
+
1. No terminal da pasta `mcp-server`, execute:
|
|
146
|
+
```bash
|
|
147
|
+
npx @modelcontextprotocol/inspector python -m src.server
|
|
148
|
+
```
|
|
149
|
+
2. Defina as variáveis de ambiente na interface ou no terminal:
|
|
150
|
+
- `QUICKERSPOT_API_URL`: `http://localhost:8000`
|
|
151
|
+
- `QUICKERSPOT_M2M_API_KEY`: `sua-chave-m2m-local`
|
|
152
|
+
3. Acesse a URL informada (ex: `http://localhost:5173`) para testar chamadas como `list_voices`, `create_campaign`, `create_recado`, etc.
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
### Passo 4: Validar no Antigravity / Claude Desktop
|
|
157
|
+
|
|
158
|
+
1. Adicione a configuração do servidor MCP no seu cliente (veja a seção **Configuração em Clientes MCP** acima).
|
|
159
|
+
2. Abra uma conversa e peça ao assistente de IA:
|
|
160
|
+
- *"Liste as vozes disponíveis na QuickerSpot."*
|
|
161
|
+
- *"Crie uma campanha de oferta de café para supermercado."*
|
|
162
|
+
- *"Gere um recado instantâneo: 'Atenção clientes, loja fechando em 15 minutos'."*
|
|
163
|
+
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# Servidor MCP QuickerSpot
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 🚀 Requisitos
|
|
8
|
+
|
|
9
|
+
- **Python 3.10** ou superior
|
|
10
|
+
- Backend do QuickerSpot rodando e acessível (ex: `http://localhost:8000`)
|
|
11
|
+
- Uma **API Key M2M** válida gerada no backend (`QUICKERSPOT_M2M_API_KEY`)
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 📦 Instalação
|
|
16
|
+
|
|
17
|
+
1. Clone o repositório e navegue até a pasta do servidor MCP:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
cd mcp-server
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
2. Crie e ative um ambiente virtual Python:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
python -m venv venv
|
|
27
|
+
# No Windows PowerShell:
|
|
28
|
+
.\venv\Scripts\activate
|
|
29
|
+
# No Linux/macOS:
|
|
30
|
+
source venv/bin/activate
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
3. Instale as dependências:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install -e .
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## ⚙️ Configuração
|
|
42
|
+
|
|
43
|
+
Copie o arquivo `.env.example` para `.env` e ajuste os valores:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
cp .env.example .env
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Configurações disponíveis:
|
|
50
|
+
|
|
51
|
+
| Variável | Descrição | Valor Padrão |
|
|
52
|
+
|----------|-----------|--------------|
|
|
53
|
+
| `QUICKERSPOT_API_URL` | URL base do backend FastAPI | `http://localhost:8000` |
|
|
54
|
+
| `QUICKERSPOT_M2M_API_KEY` | Chave de API Machine-to-Machine | `sua-chave-api-m2m-aqui` |
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## 💻 Configuração em Clientes MCP
|
|
59
|
+
|
|
60
|
+
### Configuração para Claude Desktop / Antigravity
|
|
61
|
+
|
|
62
|
+
Adicione o servidor no seu arquivo de configuração do Claude Desktop (`claude_desktop_config.json`) ou Antigravity (`mcp.json`):
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
{
|
|
66
|
+
"mcpServers": {
|
|
67
|
+
"quickerspot": {
|
|
68
|
+
"command": "python",
|
|
69
|
+
"args": ["-m", "src.server"],
|
|
70
|
+
"cwd": "/caminho/para/narrador-comercial/mcp-server",
|
|
71
|
+
"env": {
|
|
72
|
+
"QUICKERSPOT_API_URL": "http://localhost:8000",
|
|
73
|
+
"QUICKERSPOT_M2M_API_KEY": "sua-chave-api-m2m-aqui"
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 🛠️ Ferramentas MCP Disponíveis (`tools`)
|
|
83
|
+
|
|
84
|
+
1. **`list_voices`** — Retorna o catálogo de vozes comerciais disponíveis.
|
|
85
|
+
2. **`create_campaign`** — Cria uma nova campanha com lista de produtos e gera o roteiro síncrono via IA.
|
|
86
|
+
3. **`approve_script`** — Aprova (ou edita) o roteiro de uma campanha e dispara a produção de áudio em background.
|
|
87
|
+
4. **`get_campaign_status`** — Consulta o status (`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`), roteiro e URLs de áudio de uma campanha.
|
|
88
|
+
5. **`list_campaigns`** — Lista todas as campanhas ativas do usuário.
|
|
89
|
+
6. **`create_recado`** — Gera áudio instantâneo de recado curto (fast-lane TTS com vinheta, sem HITL).
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## 🧪 Guia de Teste Local e Validação Passo a Passo
|
|
94
|
+
|
|
95
|
+
Você pode validar o funcionamento do **Servidor MCP QuickerSpot** no seu ambiente local seguindo o passo a passo abaixo:
|
|
96
|
+
|
|
97
|
+
### Passo 1: Iniciar o Backend FastAPI
|
|
98
|
+
|
|
99
|
+
1. No arquivo `backend/.env`, garanta que as variáveis M2M estejam configuradas:
|
|
100
|
+
```env
|
|
101
|
+
QUICKERSPOT_M2M_API_KEY=sua-chave-m2m-local
|
|
102
|
+
QUICKERSPOT_M2M_USER_ID=m2m_test_user
|
|
103
|
+
```
|
|
104
|
+
2. Inicie o servidor FastAPI:
|
|
105
|
+
```bash
|
|
106
|
+
cd backend
|
|
107
|
+
python main.py
|
|
108
|
+
```
|
|
109
|
+
*O backend ficará acessível em `http://localhost:8000`.*
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
### Passo 2: Executar a Suíte de Testes Automatizados (E2E e Unitários)
|
|
114
|
+
|
|
115
|
+
No diretório `mcp-server/`, execute a suíte de testes que valida todos os endpoints M2M e as ferramentas do MCP:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
cd mcp-server
|
|
119
|
+
pytest tests/ -v
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Você deverá ver todos os 20 testes passarem (`20 passed`).
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
### Passo 3: Testar com o MCP Inspector (Interface Visual de Debug)
|
|
127
|
+
|
|
128
|
+
O **MCP Inspector** é uma ferramenta oficial do Model Context Protocol que permite testar visualmente todas as ferramentas e respostas via navegador web.
|
|
129
|
+
|
|
130
|
+
1. No terminal da pasta `mcp-server`, execute:
|
|
131
|
+
```bash
|
|
132
|
+
npx @modelcontextprotocol/inspector python -m src.server
|
|
133
|
+
```
|
|
134
|
+
2. Defina as variáveis de ambiente na interface ou no terminal:
|
|
135
|
+
- `QUICKERSPOT_API_URL`: `http://localhost:8000`
|
|
136
|
+
- `QUICKERSPOT_M2M_API_KEY`: `sua-chave-m2m-local`
|
|
137
|
+
3. Acesse a URL informada (ex: `http://localhost:5173`) para testar chamadas como `list_voices`, `create_campaign`, `create_recado`, etc.
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
### Passo 4: Validar no Antigravity / Claude Desktop
|
|
142
|
+
|
|
143
|
+
1. Adicione a configuração do servidor MCP no seu cliente (veja a seção **Configuração em Clientes MCP** acima).
|
|
144
|
+
2. Abra uma conversa e peça ao assistente de IA:
|
|
145
|
+
- *"Liste as vozes disponíveis na QuickerSpot."*
|
|
146
|
+
- *"Crie uma campanha de oferta de café para supermercado."*
|
|
147
|
+
- *"Gere um recado instantâneo: 'Atenção clientes, loja fechando em 15 minutos'."*
|
|
148
|
+
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "quickerspot-mcp"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Servidor MCP oficial para o QuickerSpot"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
dependencies = [
|
|
12
|
+
"mcp>=1.0.0,<2.0.0",
|
|
13
|
+
"httpx>=0.27.0",
|
|
14
|
+
"python-dotenv>=1.0.0",
|
|
15
|
+
]
|
|
16
|
+
|
|
17
|
+
[project.scripts]
|
|
18
|
+
quickerspot-mcp = "src.server:main"
|
|
19
|
+
|
|
20
|
+
[project.optional-dependencies]
|
|
21
|
+
dev = [
|
|
22
|
+
"pytest>=8.0.0",
|
|
23
|
+
"pytest-asyncio>=0.23.0",
|
|
24
|
+
"respx>=0.21.0",
|
|
25
|
+
"ruff>=0.3.0",
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
[tool.ruff]
|
|
29
|
+
line-length = 100
|
|
30
|
+
target-version = "py310"
|
|
31
|
+
|
|
32
|
+
[tool.pytest.ini_options]
|
|
33
|
+
asyncio_mode = "auto"
|
|
34
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Cliente HTTP assíncrono para a API M2M do QuickerSpot.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
import logging
|
|
6
|
+
from typing import Any, Self
|
|
7
|
+
|
|
8
|
+
import httpx
|
|
9
|
+
|
|
10
|
+
logger = logging.getLogger(__name__)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class QuickerSpotAPIError(Exception):
|
|
14
|
+
"""Exceção personalizada para erros amigáveis da API do QuickerSpot."""
|
|
15
|
+
|
|
16
|
+
def __init__(self, message: str, status_code: int | None = None) -> None:
|
|
17
|
+
super().__init__(message)
|
|
18
|
+
self.message = message
|
|
19
|
+
self.status_code = status_code
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class QuickerSpotClient:
|
|
23
|
+
"""Cliente HTTP assíncrono wrapper do httpx para os endpoints M2M."""
|
|
24
|
+
|
|
25
|
+
def __init__(
|
|
26
|
+
self,
|
|
27
|
+
base_url: str,
|
|
28
|
+
api_key: str,
|
|
29
|
+
timeout: float = 30.0,
|
|
30
|
+
client: httpx.AsyncClient | None = None,
|
|
31
|
+
) -> None:
|
|
32
|
+
self.base_url = base_url.rstrip("/")
|
|
33
|
+
self.api_key = api_key
|
|
34
|
+
self.timeout = timeout
|
|
35
|
+
self._client = client
|
|
36
|
+
|
|
37
|
+
@property
|
|
38
|
+
def client(self) -> httpx.AsyncClient:
|
|
39
|
+
"""Obtém ou inicializa a instância do AsyncClient."""
|
|
40
|
+
if self._client is None or self._client.is_closed:
|
|
41
|
+
self._client = httpx.AsyncClient(
|
|
42
|
+
base_url=self.base_url,
|
|
43
|
+
headers={"X-API-Key": self.api_key},
|
|
44
|
+
timeout=self.timeout,
|
|
45
|
+
)
|
|
46
|
+
return self._client
|
|
47
|
+
|
|
48
|
+
async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
|
|
49
|
+
"""Executa uma requisição HTTP e trata erros de status e conexão."""
|
|
50
|
+
try:
|
|
51
|
+
response = await self.client.request(method, path, **kwargs)
|
|
52
|
+
response.raise_for_status()
|
|
53
|
+
return response.json()
|
|
54
|
+
except httpx.HTTPStatusError as exc:
|
|
55
|
+
status_code = exc.response.status_code
|
|
56
|
+
detail = None
|
|
57
|
+
try:
|
|
58
|
+
body = exc.response.json()
|
|
59
|
+
if isinstance(body, dict):
|
|
60
|
+
detail = body.get("detail")
|
|
61
|
+
except (ValueError, TypeError):
|
|
62
|
+
detail = exc.response.text
|
|
63
|
+
|
|
64
|
+
if status_code == 401:
|
|
65
|
+
msg = f"Erro de Autenticação (401): API Key M2M inválida. ({detail or 'Não autorizado'})"
|
|
66
|
+
elif status_code == 403:
|
|
67
|
+
msg = f"Erro de Permissão (403): {detail or 'Acesso negado à campanha.'}"
|
|
68
|
+
elif status_code == 404:
|
|
69
|
+
msg = f"Não Encontrado (404): {detail or 'Recurso ou campanha não encontrada.'}"
|
|
70
|
+
elif status_code == 402:
|
|
71
|
+
msg = f"Saldo Insuficiente (402): {detail or 'Créditos insuficientes.'}"
|
|
72
|
+
elif status_code == 400:
|
|
73
|
+
msg = f"Requisição Inválida (400): {detail or 'Dados enviados incorretos.'}"
|
|
74
|
+
elif status_code == 503:
|
|
75
|
+
msg = f"Serviço Indisponível (503): {detail or 'Autenticação M2M não configurada no backend.'}"
|
|
76
|
+
else:
|
|
77
|
+
msg = f"Erro na API QuickerSpot ({status_code}): {detail or exc!s}"
|
|
78
|
+
|
|
79
|
+
logger.error(f"[M2M Client] HTTP {status_code}: {msg}")
|
|
80
|
+
raise QuickerSpotAPIError(msg, status_code=status_code) from exc
|
|
81
|
+
except httpx.RequestError as exc:
|
|
82
|
+
msg = f"Erro de conexão com o backend QuickerSpot: {exc!s}"
|
|
83
|
+
logger.error(f"[M2M Client] RequestError: {msg}")
|
|
84
|
+
raise QuickerSpotAPIError(msg) from exc
|
|
85
|
+
|
|
86
|
+
async def list_voices(self) -> dict[str, Any]:
|
|
87
|
+
"""Obtém o catálogo de vozes disponíveis para sintetização comercial."""
|
|
88
|
+
return await self._request("GET", "/v1/m2m/voices")
|
|
89
|
+
|
|
90
|
+
async def create_campaign(self, payload: dict[str, Any]) -> dict[str, Any]:
|
|
91
|
+
"""Cria uma nova campanha comercial e gera o roteiro via IA."""
|
|
92
|
+
return await self._request("POST", "/v1/m2m/campaigns", json=payload)
|
|
93
|
+
|
|
94
|
+
async def approve_script(self, campaign_id: str, payload: dict[str, Any]) -> dict[str, Any]:
|
|
95
|
+
"""Aprova ou edita o roteiro de uma campanha e dispara a produção do áudio."""
|
|
96
|
+
return await self._request("POST", f"/v1/m2m/campaigns/{campaign_id}/approve", json=payload)
|
|
97
|
+
|
|
98
|
+
async def get_campaign_status(self, campaign_id: str) -> dict[str, Any]:
|
|
99
|
+
"""Consulta o status e detalhes de uma campanha específica pelo ID."""
|
|
100
|
+
return await self._request("GET", f"/v1/m2m/campaigns/{campaign_id}")
|
|
101
|
+
|
|
102
|
+
async def list_campaigns(self) -> list[dict[str, Any]]:
|
|
103
|
+
"""Lista todas as campanhas do usuário associado à API Key M2M."""
|
|
104
|
+
return await self._request("GET", "/v1/m2m/campaigns")
|
|
105
|
+
|
|
106
|
+
async def create_recado(self, payload: dict[str, Any]) -> dict[str, Any]:
|
|
107
|
+
"""Gera áudio instantâneo de um recado curto (fast-lane TTS sem HITL)."""
|
|
108
|
+
return await self._request("POST", "/v1/m2m/recados", json=payload)
|
|
109
|
+
|
|
110
|
+
async def close(self) -> None:
|
|
111
|
+
"""Fecha o cliente HTTP se estiver aberto."""
|
|
112
|
+
if self._client is not None and not self._client.is_closed:
|
|
113
|
+
await self._client.aclose()
|
|
114
|
+
|
|
115
|
+
async def __aenter__(self) -> Self:
|
|
116
|
+
return self
|
|
117
|
+
|
|
118
|
+
async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
|
|
119
|
+
await self.close()
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: quickerspot-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Servidor MCP oficial para o QuickerSpot
|
|
5
|
+
Requires-Python: >=3.10
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
Requires-Dist: mcp<2.0.0,>=1.0.0
|
|
8
|
+
Requires-Dist: httpx>=0.27.0
|
|
9
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
10
|
+
Provides-Extra: dev
|
|
11
|
+
Requires-Dist: pytest>=8.0.0; extra == "dev"
|
|
12
|
+
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
|
|
13
|
+
Requires-Dist: respx>=0.21.0; extra == "dev"
|
|
14
|
+
Requires-Dist: ruff>=0.3.0; extra == "dev"
|
|
15
|
+
|
|
16
|
+
# Servidor MCP QuickerSpot
|
|
17
|
+
|
|
18
|
+
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.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 🚀 Requisitos
|
|
23
|
+
|
|
24
|
+
- **Python 3.10** ou superior
|
|
25
|
+
- Backend do QuickerSpot rodando e acessível (ex: `http://localhost:8000`)
|
|
26
|
+
- Uma **API Key M2M** válida gerada no backend (`QUICKERSPOT_M2M_API_KEY`)
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 📦 Instalação
|
|
31
|
+
|
|
32
|
+
1. Clone o repositório e navegue até a pasta do servidor MCP:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
cd mcp-server
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
2. Crie e ative um ambiente virtual Python:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
python -m venv venv
|
|
42
|
+
# No Windows PowerShell:
|
|
43
|
+
.\venv\Scripts\activate
|
|
44
|
+
# No Linux/macOS:
|
|
45
|
+
source venv/bin/activate
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
3. Instale as dependências:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pip install -e .
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## ⚙️ Configuração
|
|
57
|
+
|
|
58
|
+
Copie o arquivo `.env.example` para `.env` e ajuste os valores:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
cp .env.example .env
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Configurações disponíveis:
|
|
65
|
+
|
|
66
|
+
| Variável | Descrição | Valor Padrão |
|
|
67
|
+
|----------|-----------|--------------|
|
|
68
|
+
| `QUICKERSPOT_API_URL` | URL base do backend FastAPI | `http://localhost:8000` |
|
|
69
|
+
| `QUICKERSPOT_M2M_API_KEY` | Chave de API Machine-to-Machine | `sua-chave-api-m2m-aqui` |
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 💻 Configuração em Clientes MCP
|
|
74
|
+
|
|
75
|
+
### Configuração para Claude Desktop / Antigravity
|
|
76
|
+
|
|
77
|
+
Adicione o servidor no seu arquivo de configuração do Claude Desktop (`claude_desktop_config.json`) ou Antigravity (`mcp.json`):
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"mcpServers": {
|
|
82
|
+
"quickerspot": {
|
|
83
|
+
"command": "python",
|
|
84
|
+
"args": ["-m", "src.server"],
|
|
85
|
+
"cwd": "/caminho/para/narrador-comercial/mcp-server",
|
|
86
|
+
"env": {
|
|
87
|
+
"QUICKERSPOT_API_URL": "http://localhost:8000",
|
|
88
|
+
"QUICKERSPOT_M2M_API_KEY": "sua-chave-api-m2m-aqui"
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 🛠️ Ferramentas MCP Disponíveis (`tools`)
|
|
98
|
+
|
|
99
|
+
1. **`list_voices`** — Retorna o catálogo de vozes comerciais disponíveis.
|
|
100
|
+
2. **`create_campaign`** — Cria uma nova campanha com lista de produtos e gera o roteiro síncrono via IA.
|
|
101
|
+
3. **`approve_script`** — Aprova (ou edita) o roteiro de uma campanha e dispara a produção de áudio em background.
|
|
102
|
+
4. **`get_campaign_status`** — Consulta o status (`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`), roteiro e URLs de áudio de uma campanha.
|
|
103
|
+
5. **`list_campaigns`** — Lista todas as campanhas ativas do usuário.
|
|
104
|
+
6. **`create_recado`** — Gera áudio instantâneo de recado curto (fast-lane TTS com vinheta, sem HITL).
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 🧪 Guia de Teste Local e Validação Passo a Passo
|
|
109
|
+
|
|
110
|
+
Você pode validar o funcionamento do **Servidor MCP QuickerSpot** no seu ambiente local seguindo o passo a passo abaixo:
|
|
111
|
+
|
|
112
|
+
### Passo 1: Iniciar o Backend FastAPI
|
|
113
|
+
|
|
114
|
+
1. No arquivo `backend/.env`, garanta que as variáveis M2M estejam configuradas:
|
|
115
|
+
```env
|
|
116
|
+
QUICKERSPOT_M2M_API_KEY=sua-chave-m2m-local
|
|
117
|
+
QUICKERSPOT_M2M_USER_ID=m2m_test_user
|
|
118
|
+
```
|
|
119
|
+
2. Inicie o servidor FastAPI:
|
|
120
|
+
```bash
|
|
121
|
+
cd backend
|
|
122
|
+
python main.py
|
|
123
|
+
```
|
|
124
|
+
*O backend ficará acessível em `http://localhost:8000`.*
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
### Passo 2: Executar a Suíte de Testes Automatizados (E2E e Unitários)
|
|
129
|
+
|
|
130
|
+
No diretório `mcp-server/`, execute a suíte de testes que valida todos os endpoints M2M e as ferramentas do MCP:
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
cd mcp-server
|
|
134
|
+
pytest tests/ -v
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Você deverá ver todos os 20 testes passarem (`20 passed`).
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
### Passo 3: Testar com o MCP Inspector (Interface Visual de Debug)
|
|
142
|
+
|
|
143
|
+
O **MCP Inspector** é uma ferramenta oficial do Model Context Protocol que permite testar visualmente todas as ferramentas e respostas via navegador web.
|
|
144
|
+
|
|
145
|
+
1. No terminal da pasta `mcp-server`, execute:
|
|
146
|
+
```bash
|
|
147
|
+
npx @modelcontextprotocol/inspector python -m src.server
|
|
148
|
+
```
|
|
149
|
+
2. Defina as variáveis de ambiente na interface ou no terminal:
|
|
150
|
+
- `QUICKERSPOT_API_URL`: `http://localhost:8000`
|
|
151
|
+
- `QUICKERSPOT_M2M_API_KEY`: `sua-chave-m2m-local`
|
|
152
|
+
3. Acesse a URL informada (ex: `http://localhost:5173`) para testar chamadas como `list_voices`, `create_campaign`, `create_recado`, etc.
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
### Passo 4: Validar no Antigravity / Claude Desktop
|
|
157
|
+
|
|
158
|
+
1. Adicione a configuração do servidor MCP no seu cliente (veja a seção **Configuração em Clientes MCP** acima).
|
|
159
|
+
2. Abra uma conversa e peça ao assistente de IA:
|
|
160
|
+
- *"Liste as vozes disponíveis na QuickerSpot."*
|
|
161
|
+
- *"Crie uma campanha de oferta de café para supermercado."*
|
|
162
|
+
- *"Gere um recado instantâneo: 'Atenção clientes, loja fechando em 15 minutos'."*
|
|
163
|
+
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
pyproject.toml
|
|
3
|
+
src/__init__.py
|
|
4
|
+
src/client.py
|
|
5
|
+
src/server.py
|
|
6
|
+
src/quickerspot_mcp.egg-info/PKG-INFO
|
|
7
|
+
src/quickerspot_mcp.egg-info/SOURCES.txt
|
|
8
|
+
src/quickerspot_mcp.egg-info/dependency_links.txt
|
|
9
|
+
src/quickerspot_mcp.egg-info/entry_points.txt
|
|
10
|
+
src/quickerspot_mcp.egg-info/requires.txt
|
|
11
|
+
src/quickerspot_mcp.egg-info/top_level.txt
|
|
12
|
+
tests/test_client.py
|
|
13
|
+
tests/test_e2e_mcp_campaign.py
|
|
14
|
+
tests/test_e2e_mcp_recado.py
|
|
15
|
+
tests/test_server.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|