Jason Thistlethwaite
128 lines
3.4 KiB
Markdown
128 lines
3.4 KiB
Markdown
# Test MCP Server
|
|
|
|
This project includes a dependency-free HTTP JSON-RPC MCP endpoint for testing
|
|
remote-agent access to the VoIP.ms library.
|
|
|
|
It is intended for development and testing. It binds to `0.0.0.0` by default,
|
|
so use a firewall, VPN, or private network when exposing it beyond this machine.
|
|
|
|
## Start The Server
|
|
|
|
```bash
|
|
cp .env-example .env
|
|
# Edit .env and optionally add MCP_AUTH_TOKEN='choose-a-long-random-token'
|
|
|
|
./bin/serve-mcp.sh
|
|
```
|
|
|
|
The launcher reads the project-root `.env` file when present. Already exported
|
|
environment variables take precedence over `.env` values.
|
|
|
|
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
|
|
```
|
|
|
|
If `MCP_AUTH_TOKEN` is not set, the launcher generates one for that session.
|
|
For local unauthenticated testing only:
|
|
|
|
```bash
|
|
MCP_ALLOW_UNAUTHENTICATED=1 ./bin/serve-mcp.sh
|
|
```
|
|
|
|
The preferred authentication form is:
|
|
|
|
```text
|
|
Authorization: Bearer <MCP_AUTH_TOKEN>
|
|
```
|
|
|
|
For clients that cannot send custom headers during testing, the same token can
|
|
be passed as a query parameter:
|
|
|
|
```text
|
|
http://your-host:8787/mcp?token=<MCP_AUTH_TOKEN>
|
|
```
|
|
|
|
Prefer the `Authorization` header when the client supports it.
|
|
|
|
## Smoke Test
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:8787/health
|
|
```
|
|
|
|
Initialize:
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:8787/mcp \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer $MCP_AUTH_TOKEN" \
|
|
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"test"}}}'
|
|
```
|
|
|
|
Streamable HTTP GET probe:
|
|
|
|
```bash
|
|
curl -sN http://127.0.0.1:8787/mcp \
|
|
-H "Accept: text/event-stream" \
|
|
-H "Authorization: Bearer $MCP_AUTH_TOKEN"
|
|
```
|
|
|
|
Legacy SSE probe:
|
|
|
|
```bash
|
|
curl -sN http://127.0.0.1:8787/sse \
|
|
-H "Accept: text/event-stream" \
|
|
-H "Authorization: Bearer $MCP_AUTH_TOKEN"
|
|
```
|
|
|
|
List tools:
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:8787/mcp \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer $MCP_AUTH_TOKEN" \
|
|
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
|
|
```
|
|
|
|
Call a safe dry-run mutation:
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:8787/mcp \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer $MCP_AUTH_TOKEN" \
|
|
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"voipms_add_number_to_phonebook_group","arguments":{"number":"5553334444","group_name":"Spam","dry_run":true}}}'
|
|
```
|
|
|
|
## Exposed 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` and must be called with
|
|
`dry_run=false` to apply changes.
|
|
|
|
`voipms_get_call_transcript` is currently a placeholder. It is listed so remote
|
|
agents can discover that transcripts are planned, but transcription
|
|
storage/provider support has not been implemented yet.
|
|
|
|
`voipms_get_accounts` is a friendly alias for `voipms_get_call_accounts`. These
|
|
tools return account filter values for CDR and call recording tools. They do
|
|
not list VoIP.ms portal login users. Use the returned `value` field as the
|
|
`account` argument.
|