At this stage, the code is known to work and has been thoroughly tested
This commit is contained in:
Jason Thistlethwaite
+208
@@ -0,0 +1,208 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user