# mcp-server-ktozvonil

MCP (Model Context Protocol) server for **[ktozvonil.net](https://ktozvonil.net)** — a community phone-number reputation service for Ukraine and beyond. Ask your AI assistant *"who called me from 050 110 89 01?"* and it will answer with the community verdict, spam rating, operator, region, tags and recent reviews.

This package is a thin stdio bridge to the site's native MCP endpoint (`https://ktozvonil.net/mcp`). Tools are discovered at startup, so the package never goes stale.

## Tools

| Tool | Description | Auth |
|------|-------------|------|
| `lookup_phone` | Community verdict, rating, spam level, operator, region, tags and recent reviews for a number | none |
| `post_comment` | Post a review on behalf of an authenticated user (labelled as AI-agent-generated, shown separately, does not affect the community rating) | OAuth bearer |

## Install

### Claude Code

```bash
claude mcp add ktozvonil -- npx -y mcp-server-ktozvonil
```

### Claude Desktop

```json
{
  "mcpServers": {
    "ktozvonil": {
      "command": "npx",
      "args": ["-y", "mcp-server-ktozvonil"]
    }
  }
}
```

### Cursor / Windsurf / other MCP clients

Any client that speaks stdio MCP works the same way: command `npx`, args `-y mcp-server-ktozvonil`.

### Remote (no install)

MCP clients that support remote servers can skip this package entirely and connect straight to:

```
https://ktozvonil.net/mcp
```

## Configuration

| Env var | Meaning |
|---------|---------|
| `KTOZVONIL_MCP_URL` | Override the endpoint URL (default `https://ktozvonil.net/mcp`) |
| `KTOZVONIL_TOKEN` | OAuth bearer token — only needed for `post_comment`. Discovery: [`/.well-known/oauth-protected-resource`](https://ktozvonil.net/.well-known/oauth-protected-resource) |

## Example

> **User:** Кто звонил с +38 050 110 89 01?
>
> **Assistant:** *(calls `lookup_phone`)* This number has a "spam" community verdict on ktozvonil.net: 78 reports, mostly "intrusive advertising"…

## Development

```bash
npm install
npm run build
npm test
```

## Related

- [ktozvonil.net](https://ktozvonil.net) — the service itself (uk/ru/en + 5 more languages)
- [`ua-phone`](https://github.com/ktozvonil/ua-phone) — Ukrainian phone number parsing/formatting library
- API docs: [ktozvonil.net/.well-known/api-catalog](https://ktozvonil.net/.well-known/api-catalog)

## License

MIT © [ktozvonil.net](https://ktozvonil.net)