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

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.