Placetel Web API

placetel-web-api-mcp-server

Servidor MCP (Model Context Protocol) que expone la API web completa de Placetel v2 — los 124 endpoints como herramientas individuales y bien anotadas. Construido con el SDK de TypeScript de MCP (registerTool), validación Zod y un cliente axios compartido con manejo automático de límite de velocidad (HTTP 429 / Retry-After).

• URL base: https://api.placetel.de/v2
• Autenticación: token Bearer mediante PLACETEL_API_KEY
• Transporte: stdio (servidor local para Claude Desktop / Claude Code)

Catálogo de herramientas (124 herramientas)

Las herramientas se nombran placetel_<verb>_<resource> (snake_case). Las herramientas de solo lectura llevan readOnlyHint, las de eliminación llevan destructiveHint. Tabla completa con métodos, rutas y anotaciones: docs/BUILD-PLAN.md.

Dominio	Herramientas	Dominio	Herramientas
AI	1	Prompts	5
Call Center	8	Provisionings	9
Call detail records	1	Recordings	3
Calls	4	Routing plans (+objects)	7
Contacts	5	Routings	5
CTI	15	Sip Users	8
Devices	1	SIM Cards	2
Faxes	4	Sites	2
Groups	5	SMS	1
Microsoft Teams	5	Subscriptions	3
Numbers	8	Webex	14
Users (incl. /me)	8	Total	124

Cada herramienta de datos acepta response_format (markdown por defecto, o json). Las herramientas de listado aceptan page / per_page (nota: no todos los endpoints respetan per_page; los endpoints de listado de Placetel devuelven arrays simples, por lo que has_more es una heurística).

Configuración

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

Obtén tu clave en https://web.placetel.de/integrations/web_api. Nunca confirmes .env — está en gitignore.

Ejecución

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

Registro en un cliente MCP (p. ej. Claude Desktop / Claude Code)

Usando el paquete npm publicado (sin necesidad de clonar localmente):

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

El valor de env puede hacer referencia a una variable de entorno existente del sistema operativo, p. ej. "PLACETEL_API_KEY": "${MY_PLACETEL_KEY}".

Alternativamente, apunta a una compilación local con "command": "node" y "args": ["<absolute-path>/dist/index.js"].

Desarrollo

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

• src/index.ts — punto de entrada, registra todos los módulos de herramientas, conecta stdio.
• src/services/ — cliente compartido, mapeo de errores, paginación, formato.
• src/tools/ — un módulo por dominio de API (contacts.ts es la referencia escrita a mano; el resto se generan con el mismo patrón a partir de la especificación Swagger).
• evaluation.xml — 10 pares de QA de solo lectura (mcp-builder Fase 4).

Notas y limitaciones

• Las herramientas de CTI, Webex, Microsoft Teams y tarjetas SIM requieren los productos adicionales correspondientes de Placetel / dispositivos reales; están implementadas y verificadas por tipos, pero pueden no ser utilizables en todas las cuentas.
• Los mensajes de error son accionables (401 → verifica la clave, 404 → verifica el id, 422 → detalle de validación, 429 → límite de velocidad superado).

Publicación

La publicación en npm está automatizada mediante GitHub Actions (.github/workflows/publish.yml) y se ejecuta cuando se publica una GitHub Release:

1. Incrementa la versión y actualiza CHANGELOG.md: npm version patch|minor|major
2. Sube la etiqueta: git push --follow-tags
3. Publica una GitHub Release para esa etiqueta: gh release create vX.Y.Z --generate-notes

El flujo de trabajo luego compila y ejecuta npm publish --provenance. Requiere el secreto del repositorio NPM_TOKEN — un token de Automatización de npm (Access Tokens → Classic → Automation), que omite la 2FA. Un push simple al repositorio no republica en npm; solo una nueva release con versión incrementada lo hace.