Placetel Web API

placetel-web-api-mcp-server

Servidor MCP (Model Context Protocol) que expõe a API Web completa do Placetel v2 — todos os 124 endpoints como ferramentas individuais e bem anotadas. Construído com o SDK TypeScript do MCP (registerTool), validação Zod e um cliente axios compartilhado com tratamento automático de limite de taxa (HTTP 429 / Retry-After).

• URL base: https://api.placetel.de/v2
• Autenticação: token Bearer via PLACETEL_API_KEY
• Transporte: stdio (servidor local para Claude Desktop / Claude Code)

Catálogo de ferramentas (124 ferramentas)

As ferramentas são nomeadas placetel_<verb>_<resource> (snake_case). Ferramentas somente leitura carregam readOnlyHint, exclusões carregam destructiveHint. Tabela completa com métodos, caminhos e anotações: docs/BUILD-PLAN.md.

Domínio	Ferramentas	Domínio	Ferramentas
IA	1	Prompts	5
Central de atendimento	8	Provisionamentos	9
Registros de detalhes de chamadas	1	Gravações	3
Chamadas	4	Planos de roteamento (+objetos)	7
Contatos	5	Roteamentos	5
CTI	15	Usuários SIP	8
Dispositivos	1	Cartões SIM	2
Faxes	4	Sites	2
Grupos	5	SMS	1
Microsoft Teams	5	Assinaturas	3
Números	8	Webex	14
Usuários (incl. /me)	8	Total	124

Toda ferramenta de dados aceita response_format (padrão markdown, ou json). Ferramentas de listagem aceitam page / per_page (observação: nem todo endpoint honra per_page; os endpoints de listagem do Placetel retornam arrays simples, então has_more é uma heurística).

Configuração

npm install
cp .env.example .env        # then put your Placetel API key into .env
npm run build

.env:

PLACETEL_API_KEY=your_api_key_here

Obtenha sua chave em https://web.placetel.de/integrations/web_api. Nunca faça commit de .env — ele está no gitignore.

Execução

npm start          # runs dist/index.js over stdio
npm run smoke      # starts the server, lists tools, prints TOOL_COUNT

Registrar em um cliente MCP (ex.: Claude Desktop / Claude Code)

Usando o pacote npm publicado (sem necessidade de checkout local):

{
  "mcpServers": {
    "placetel": {
      "command": "npx",
      "args": ["-y", "placetel-web-api-mcp-server"],
      "env": { "PLACETEL_API_KEY": "your_api_key_here" }
    }
  }
}

O valor de env pode referenciar uma variável de ambiente do sistema existente, ex.: "PLACETEL_API_KEY": "${MY_PLACETEL_KEY}".

Alternativamente, aponte para uma build local com "command": "node" e "args": ["<absolute-path>/dist/index.js"].

Desenvolvimento

npm run dev        # tsx watch on src/index.ts
npm run build      # tsc -> dist/

• src/index.ts — ponto de entrada, registra todos os módulos de ferramentas, conecta stdio.
• src/services/ — cliente compartilhado, mapeamento de erros, paginação, formatação.
• src/tools/ — um módulo por domínio da API (contacts.ts é a referência escrita à mão; os demais são gerados no mesmo padrão a partir da especificação Swagger).
• evaluation.xml — 10 pares de QA somente leitura (mcp-builder Fase 4).

Notas e limites

• Ferramentas de CTI, Webex, Microsoft Teams e cartões SIM exigem os produtos complementares correspondentes do Placetel / dispositivos reais; elas estão implementadas e com verificação de tipos, mas podem não ser utilizáveis em todas as contas.
• Mensagens de erro são acionáveis (401 → verifique a chave, 404 → verifique o id, 422 → detalhe de validação, 429 → limite de taxa atingido).

Publicação

A publicação no npm é automatizada via GitHub Actions (.github/workflows/publish.yml) e é executada quando uma Release do GitHub é publicada:

1. Aumente a versão e atualize CHANGELOG.md: npm version patch|minor|major
2. Envie a tag: git push --follow-tags
3. Publique uma Release do GitHub para essa tag: gh release create vX.Y.Z --generate-notes

O fluxo de trabalho então compila e executa npm publish --provenance. Ele requer o segredo do repositório NPM_TOKEN — um token npm Automation (Access Tokens → Classic → Automation), que ignora a 2FA. Um push simples no repositório não republica no npm; apenas uma nova release com versão atualizada o faz.