# placetel-web-api-mcp-server

[![npm version](https://img.shields.io/npm/v/placetel-web-api-mcp-server.svg)](https://www.npmjs.com/package/placetel-web-api-mcp-server)
[![CI](https://github.com/Wagner-Emden-IT-Services/placetel-web-api-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/Wagner-Emden-IT-Services/placetel-web-api-mcp-server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/node/v/placetel-web-api-mcp-server.svg)](package.json)

MCP (Model Context Protocol) server exposing the **complete Placetel Web API v2** — all **124 endpoints** as individual, well-annotated tools. Built with the MCP TypeScript SDK (`registerTool`), Zod validation, and a shared axios client with automatic rate-limit (HTTP 429 / `Retry-After`) handling.

- **Base URL:** `https://api.placetel.de/v2`
- **Auth:** Bearer token via `PLACETEL_API_KEY`
- **Transport:** stdio (local server for Claude Desktop / Claude Code)

## Tool catalog (124 tools)

Tools are named `placetel_<verb>_<resource>` (snake_case). Read-only tools carry `readOnlyHint`, deletes carry `destructiveHint`. Full table with methods, paths and annotations: [`docs/BUILD-PLAN.md`](docs/BUILD-PLAN.md).

| Domain | Tools | Domain | Tools |
|---|--:|---|--:|
| 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** |

Every data tool accepts `response_format` (`markdown` default, or `json`). List tools accept `page` / `per_page` (note: not every endpoint honors `per_page`; Placetel list endpoints return bare arrays, so `has_more` is a heuristic).

## Setup

```bash
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
```

Get your key at https://web.placetel.de/integrations/web_api. **Never commit `.env`** — it is gitignored.

## Run

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

### Register in an MCP client (e.g. Claude Desktop / Claude Code)

Using the published npm package (no local checkout needed):

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

The `env` value may reference an existing OS environment variable, e.g.
`"PLACETEL_API_KEY": "${MY_PLACETEL_KEY}"`.

Alternatively point at a local build with `"command": "node"` and
`"args": ["<absolute-path>/dist/index.js"]`.

## Development

```bash
npm run dev        # tsx watch on src/index.ts
npm run build      # tsc -> dist/
npm test           # build, then the offline test suite (no API key, no network)
```

### Tests

`npm test` calls every tool through a real MCP client (in-memory transport) and checks
the HTTP request it would send against a contract generated from the public Placetel
spec (`test/fixtures/placetel-contract.json`): method, path, query and body fields,
required fields, annotations, and both response formats. Requests are intercepted on the
axios level, so nothing leaves the machine. The run ends with `TOOL_COVERAGE=<passed>/<registered>`
and `SPEC_UNCOVERED=<operations without a tool>`.

To refresh the contract after an API change, run `node scripts/build-contract.mjs`
(fetches `https://api.placetel.de/v2/swagger_doc.json`; not part of `npm test` or CI).

- `src/index.ts` — entry point, registers all tool modules, connects stdio.
- `src/services/` — shared client, error mapping, pagination, formatting.
- `src/tools/` — one module per API domain (`contacts.ts` is the hand-written reference; the rest are generated to the same pattern from the Swagger spec).
- `evaluation.xml` — 10 read-only QA pairs (mcp-builder Phase 4).

## Notes & limits

- CTI, Webex, Microsoft Teams and SIM-card tools require the corresponding Placetel add-on products / real devices; they are implemented and type-checked but may not be exercisable on every account.
- Error messages are actionable (401 → check key, 404 → check id, 422 → validation detail, 429 → rate limited).

## Releasing

Publishing to npm is automated via GitHub Actions (`.github/workflows/publish.yml`) and runs when a **GitHub Release is published**:

1. Bump the version and update `CHANGELOG.md`: `npm version patch|minor|major`
2. Push the tag: `git push --follow-tags`
3. Publish a GitHub Release for that tag: `gh release create vX.Y.Z --generate-notes`

The workflow then builds and runs `npm publish --provenance`. It requires the repository secret **`NPM_TOKEN`** — an npm **Automation** token (Access Tokens → Classic → Automation), which bypasses 2FA. A plain repo push does **not** republish npm; only a new release with a bumped version does.