# PhoneCheck

> Offline phone-number validation and formatting (libphonenumber metadata): E.164, international, national and RFC 3966 formats, region, calling code and allocated line type. Public JSON API plus a remote MCP server for AI agents. No carrier, HLR, porting or reachability lookup; numbers are not stored or logged.

## For AI agents

- [MCP server](https://phonecheck.mike-tusa.workers.dev/mcp): remote MCP over Streamable HTTP (POST only, stateless, JSON responses). Protocol versions: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Tools: `parse_phone_number` (number, default_country), `get_example_number` (country). Read-only. Client config (most MCP clients accept this; some use a different format, for example VS Code uses a `servers` key): `{"mcpServers":{"phonecheck":{"type":"http","url":"https://phonecheck.mike-tusa.workers.dev/mcp"}}}`
- [OpenAPI 3.1 spec](https://phonecheck.mike-tusa.workers.dev/openapi.json): machine-readable description of the JSON API
- [Docs](https://phonecheck.mike-tusa.workers.dev/docs): human-readable API docs

## JSON API

- `POST https://phonecheck.mike-tusa.workers.dev/v1/parse` with JSON `{"number": "+44 20 7946 0018", "defaultCountry": "GB"}`: validity, formats, region, calling code, line type. Send numbers in the POST body only (GET /v1/parse/{number} returns 405). "Valid" means the number matches an allocated range, not that the line is connected or reachable.
- `POST https://phonecheck.mike-tusa.workers.dev/v1/bulk`: up to 500 numbers per request, Pro keys only (Pro is not on sale yet).
- `GET https://phonecheck.mike-tusa.workers.dev/v1/example/{country}`, `GET https://phonecheck.mike-tusa.workers.dev/v1/countries`, `GET https://phonecheck.mike-tusa.workers.dev/v1/meta`.
- Errors: { "error": { "code", "message" } } with 400 (invalid_json, invalid_body, missing_number, input_too_long, invalid_default_country, number_in_url, bad_encoding, invalid_bulk, empty_bulk, bulk_too_large), 401 (invalid_api_key, api_key_required), 403 (paid_plan_required), 404 (not_found, unknown_country), 405 (method_not_allowed), 413 (body_too_large), 429 (rate_limited, daily_capacity_reached, monthly_quota_exceeded), 503 (storage_unavailable).

## Limits, keys and pricing

- Anonymous: about 20/min per IP. Free key: about 300/min and 1000 calls per month (send `Authorization: Bearer pc_live_...` or `X-Api-Key`). Pro (planned, not on sale): 50000 calls per month and bulk. A global daily soft cap applies. The MCP endpoint uses the same keys and counters: each `tools/call` is one call. Non-call messages don't count as calls, but are capped at about 120/min per IP (HTTP 429 + Retry-After).

## Optional

- [Privacy](https://phonecheck.mike-tusa.workers.dev/docs#privacy)
- Contact: digitalpromohub.support@gmail.com