php-voip.ms/HANDOFF.md

# Handoff Notes

Last updated: 2026-04-21

## Current State

This repo now contains three related pieces:

- A standalone PHP VoIP.ms library under `src/`.
- A CLI tool at `voipms-cli.php`.
- A test HTTP MCP server under `mcp/`, launched with `bin/serve-mcp.sh`.

The original `phonebook.php` file is intentionally unchanged as a simple cURL
reference example.

## Library

Main files:

- `src/VoipMsClient.php`
- `src/VoipMsResponse.php`
- `src/PhonebookGroupEnsureResult.php`
- `src/PhonebookGroupUpdateResult.php`
- `src/PhonebookNumberGroupResult.php`

The client supports generic raw API access:

```php
$client->request('getDIDsInfo', ['did' => '5551234567']);
$client->call('getBalance');
```

It also has convenience helpers for:

- Balance lookup.
- DID lookup.
- CDR lookup with default call-status flags.
- Account filter lookup through `getAccounts()` / `getCallAccounts()`.
- Call recording listing, retrieval, and email delivery.
- Phonebook entries and groups.
- Idempotently adding a number to a phonebook group.
- Removing matching numbers from a phonebook group.
- CallerID Filtering.
- Call account filters.
- SMS sending.

Important phonebook behavior:

- VoIP.ms phonebook groups store `members` as semicolon-separated phonebook
  entry IDs.
- A group can exist with no entries.
- VoIP.ms may allow duplicate phonebook entries for the same number.
- Library helpers try to avoid creating duplicates and avoid duplicate group
  membership.

## CLI

The CLI can call raw VoIP.ms API methods:

```bash
./voipms-cli.php getBalance
./voipms-cli.php getPhonebookGroups
./voipms-cli.php getPhonebook Spam
```

Useful CLI features:

- `--dry-run`
- `--format pretty|json|raw`
- `help <command>` and `<command> help`
- `list`
- `completion bash`

Friendlier behavior currently implemented:

- `cdr` alias maps normal options to `getCDR` parameters.
- `cdr` defaults to all call statuses to avoid VoIP.ms `no_callstatus`.
- `getPhonebook 16389` maps to `group=16389`.
- `getPhonebook Spam` maps to `group_name=Spam`.
- `getPhonebookGroups Spam` maps to `name=Spam`.

## Test MCP Server

Files:

- `mcp/http-server.php`
- `bin/serve-mcp.sh`
- `docs/mcp.md`

Start it:

```bash
export VOIPMS_API_USERNAME='you@example.com'
export VOIPMS_API_PASSWORD='your-api-password'
export MCP_AUTH_TOKEN='choose-a-long-random-token'

./bin/serve-mcp.sh
```

Defaults:

```text
MCP_HOST=0.0.0.0
MCP_PORT=8787
MCP endpoint: http://0.0.0.0:8787/mcp
Health endpoint: http://0.0.0.0:8787/health
```

For Grok or hosted clients that cannot send custom headers, query-token auth is
available for testing:

```text
http://YOUR_HOST:8787/mcp?token=YOUR_TOKEN
http://YOUR_HOST:8787/sse?token=YOUR_TOKEN
```

Prefer `Authorization: Bearer <token>` when the client supports it.

## MCP Compatibility Work

The first MCP server only handled POST JSON-RPC. It was updated after Grok
could connect over HTTP but reported the server did not work.

Current compatibility support:

- `POST /mcp` JSON-RPC.
- `GET /mcp` Streamable HTTP-style SSE probe.
- `GET /sse` legacy SSE probe with an `endpoint` event pointing to `/mcp`.
- `DELETE /mcp`.
- `OPTIONS` CORS preflight.
- `Mcp-Session-Id` response header.
- Protocol negotiation for `2024-11-05`, `2025-03-26`, and `2025-06-18`.
- JSON-RPC notifications return `202 Accepted`.
- Query-token auth fallback.

Current MCP tools:

- `voipms_get_balance`
- `voipms_get_phonebook_groups`
- `voipms_get_phonebook_entries`
- `voipms_get_callerid_filters`
- `voipms_get_accounts`
- `voipms_get_call_accounts`
- `voipms_get_call_recordings`
- `voipms_get_call_recording`
- `voipms_send_call_recording_email`
- `voipms_get_call_transcript`
- `voipms_get_recent_cdr`
- `voipms_add_number_to_phonebook_group`
- `voipms_remove_number_from_phonebook_group`

Mutation tools default to `dry_run=true`.

`voipms_get_call_transcript` is a placeholder until transcript storage and a
transcription provider are added.

## Last Verification Done

No live VoIP.ms API calls were made during MCP compatibility testing.

Verified locally:

- `php -l mcp/http-server.php`
- `bash -n bin/serve-mcp.sh`
- `POST /mcp initialize`
- `POST /mcp tools/list`
- `POST /mcp notifications/initialized`
- `GET /mcp`
- `GET /sse`
- Query-token auth
- Unauthorized request returns `401`

Temporary local test server was stopped afterward.

## Likely Next Steps

1. Try Grok again with:

   ```text
   http://YOUR_HOST:8787/mcp?token=YOUR_TOKEN
   ```

   If Grok has a separate SSE mode, try:

   ```text
   http://YOUR_HOST:8787/sse?token=YOUR_TOKEN
   ```

2. If Grok still fails, capture server log lines showing:

   - HTTP method
   - path
   - status code
   - whether it hit `/mcp`, `/sse`, `/message`, `/health`, or another path

3. Add more MCP tools after basic connection works:

   - `voipms_inspect_number`
   - `voipms_suggest_spam_numbers`
   - `voipms_mark_number_as_spam`
   - `voipms_unmark_number_as_spam`
   - real transcript generation/storage behind `voipms_get_call_transcript`

4. Consider adding an audit log for MCP mutation tool calls before exposing
   `dry_run=false` to remote agents.

5. Eventually replace the PHP built-in server with a more production-suitable
   deployment if this becomes more than a test endpoint.