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:

$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:

./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:

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:

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:

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:

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

   If Grok has a separate SSE mode, try:

   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.