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.
@@ -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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """
2
+ Pacote do Servidor MCP QuickerSpot.
3
+ """
@@ -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,2 @@
1
+ [console_scripts]
2
+ quickerspot-mcp = src.server:main
@@ -0,0 +1,9 @@
1
+ mcp<2.0.0,>=1.0.0
2
+ httpx>=0.27.0
3
+ python-dotenv>=1.0.0
4
+
5
+ [dev]
6
+ pytest>=8.0.0
7
+ pytest-asyncio>=0.23.0
8
+ respx>=0.21.0
9
+ ruff>=0.3.0
@@ -0,0 +1,3 @@
1
+ __init__
2
+ client
3
+ server