beplus-mcp 0.8.0

package/README.md

@@ -0,0 +1,125 @@
+# BePlus MCP
+
+Servidor [MCP](https://modelcontextprotocol.io) da equipe BePlus que dá ao Claude Code / Claude Desktop / Cursor acesso à sua conta da plataforma para **gerar mídia** (imagens, vídeos e áudio) e **consultar dados** (calls gravadas/transcritas, projetos e clientes) — tudo passando pela sua conta.
+
+Diferente de chamar Gemini/BytePlus direto, toda ação roteia pelo backend da BePlus e **herda automaticamente**: débito de diamantes, limites por usuário, visibilidade da equipe e histórico/monitoramento no admin. A chave do provider nunca toca a sua máquina.
+
+## Como funciona
+
+```
+Claude Code/Desktop/Cursor  ──stdio──▶  beplus-mcp  ──HTTPS (Bearer pat_…)──▶  BePlus /api/v1/mcp
+```
+
+Você se autentica com um **Personal Access Token (PAT)** gerado no painel da BePlus. O MCP só age em nome da SUA conta.
+
+## 1. Gere um Personal Access Token
+
+No app da BePlus → **Configurações da conta → Tokens de acesso** → *Criar token*. Copie o token (`pat_…`) — ele só aparece uma vez.
+
+## 2. Configure no seu cliente
+
+### Claude Code (CLI)
+```bash
+claude mcp add beplus \
+  --env BEPLUS_API_TOKEN=pat_seu_token \
+  --env BEPLUS_API_URL=https://api.beplus.academy \
+  -- npx -y beplus-mcp
+```
+
+### Claude Desktop (`claude_desktop_config.json`) / Cursor (`.cursor/mcp.json`)
+
+**macOS / Linux:**
+```json
+{
+  "mcpServers": {
+    "beplus": {
+      "command": "npx",
+      "args": ["-y", "beplus-mcp"],
+      "env": {
+        "BEPLUS_API_URL": "https://api.beplus.academy",
+        "BEPLUS_API_TOKEN": "pat_seu_token"
+      }
+    }
+  }
+}
+```
+
+**Windows** — o `npx` precisa do wrapper `cmd /c` (senão o servidor não inicia):
+```json
+{
+  "mcpServers": {
+    "beplus": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "beplus-mcp"],
+      "env": {
+        "BEPLUS_API_URL": "https://api.beplus.academy",
+        "BEPLUS_API_TOKEN": "pat_seu_token"
+      }
+    }
+  }
+}
+```
+
+Caminho do config (Claude Desktop): macOS `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows `%APPDATA%\Claude\claude_desktop_config.json`.
+
+Reinicie o cliente. Rode a tool **`whoami`** para confirmar o vínculo.
+
+## Variáveis de ambiente
+
+| Var | Obrigatória | Default | Descrição |
+|-----|-------------|---------|-----------|
+| `BEPLUS_API_TOKEN` | ✅ | — | Seu Personal Access Token (`pat_…`). |
+| `BEPLUS_API_URL` | — | `https://api.beplus.academy` | Origem da API BePlus. |
+| `BEPLUS_INLINE_IMAGES` | — | `1` | `0` desativa imagens inline (só URLs). |
+| `BEPLUS_VERIFY_ON_START` | — | `0` | `1` valida o token no startup e loga a conta (stderr). |
+| `BEPLUS_COST_WARN_THRESHOLD` | — | — | Avisa quando o custo passa de N 💎. |
+| `BEPLUS_ACTIVE_PROJECT` | — | — | Projeto ativo padrão da sessão (uuid ou code). |
+
+## Tools
+
+### Geração de mídia
+| Tool | O que faz |
+|------|-----------|
+| `generate_image` | Gera imagem (nano-banana / gpt-image-2). Bloqueante ~90s; retorna URL + imagem inline. Suporta refs, tamanho/qualidade, e extras do gpt-image-2 (background, moderation, output_format/compression). |
+| `generate_video` | Gera vídeo (Seedance / Kling). Aguarda ~120s; senão devolve o id pra `check_generation`. Suporta first/last frame, refs de imagem/vídeo/áudio, prompt negativo, áudio gerado, mode e motion-control. |
+| `generate_audio` | Sintetiza fala (Gemini TTS, ~30 vozes, multi-locutor). Síncrono. |
+| `generate_music` | Gera música completa (Suno v5.5 / v4.5) — modo descrição ou letra própria, tags, instrumental, vocal_gender, controles criativos. Async. |
+| `check_generation` | Status de uma geração async por id. |
+| `cancel_generation` | Cancela uma geração em fila/processamento (estorna diamantes). |
+| `estimate_cost` | Custo em diamantes antes de gerar. |
+| `read_image_metadata` / `analyze_media` | Lê a proveniência embutida numa imagem / analisa mídia (imagem/vídeo/áudio/PDF) com prompt. |
+
+### Calls (reuniões gravadas e transcritas)
+| Tool | O que faz |
+|------|-----------|
+| `search_calls` | Busca nas calls visíveis (suas, da equipe, compartilhadas). Filtros: `query`, `project`, `client`, `visibility`, `speaker`. |
+| `get_call` | Conteúdo completo de uma call por id: resumo, falantes, projeto/cliente, mídia e a transcrição inteira. |
+
+### Projetos / Clientes / Conta
+| Tool | O que faz |
+|------|-----------|
+| `list_projects` · `create_project` · `set_active_project` | Lista/cria projetos e define o ativo (mesma fonte da web). |
+| `list_clients` · `create_client` · `set_active_client` | Clientes/marcas (container acima dos projetos). |
+| `list_models` | Modelos disponíveis + preços + limites (fonte de verdade em runtime). |
+| `get_balance` | Saldo de diamantes. |
+| `whoami` | Conta vinculada (link check do PAT). |
+
+Toda geração mostra `Custo: N 💎 · Saldo: M 💎`. As tools de calls e listagem respeitam a visibilidade da equipe — só retornam o que a sua conta pode ver.
+
+## Desenvolvimento
+
+```bash
+npm install
+npm run typecheck
+npm run build      # gera dist/index.js (bin)
+npm run dev        # roda via tsx
+
+# Smoke-test com o MCP Inspector:
+BEPLUS_API_TOKEN=pat_… npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+## Notas
+
+- **stdout** é o canal JSON-RPC — todo log vai pra **stderr** e o token nunca é logado.
+- Limites, créditos, visibilidade e logging são enforçados pelo backend; um PAT vazado é limitado aos caps/diamantes do dono e pode ser revogado no painel.
+- `list_models` é a fonte de verdade em runtime; os enums do pacote podem ficar atrás quando o backend adiciona modelos.