# W3J Telnyx MCP

MCP server exposing the **full Telnyx API** as Model Context Protocol tools, plus an **autonomous voice agent builder** that deploys live AI receptionists from a YAML spec.

## Quick start

```bash
# Install
git clone https://github.com/mnjbold/w3j-telnyx-mcp.git
cd w3j-telnyx-mcp
uv venv .venv --python 3.12 --seed
source .venv/bin/activate  # Linux/macOS
# or: .venv\Scripts\Activate.ps1  (Windows)

uv sync --all-extras

# Health check
python -m telnyx_mcp.utils.env
python -m telnyx_mcp.clients.telnyx_client

# Start MCP server (stdio — for Claude Desktop / Cursor / Windsurf)
python -m telnyx_mcp.server

# Start MCP server (HTTP — for remote MCP clients)
python -m telnyx_mcp.server --transport http --host 0.0.0.0 --port 8765

# Deploy an agent from YAML
python agent_builder/builder.py agents/my-agent/spec.yaml --dry-run
python agent_builder/builder.py agents/my-agent/spec.yaml
```

## What you get

| Tool surface | Tools |
|---|---|
| `numbers` | search, order, list, get, update |
| `voice` | dial, transfer, hangup, answer, reject, start/stop AI assistant, recordings |
| `assistants` | CRUD AI Assistants |
| `infrastructure` | Call Control Apps, Outbound Voice Profiles, Messaging Profiles, Voice Clones |
| `messaging` | send SMS |
| `utility` | balance, account summary, health check |

## Deploy a voice agent

```bash
# From YAML spec
python agent_builder/builder.py agents/w3j-llc-concierge/spec.yaml
```

```yaml
# agents/my-agent/spec.yaml
name: My Agent
instructions: |
  You are a friendly receptionist for Acme Corp...
country_code: US
area_code: "415"
buy_number: true
webhook_url: https://your-server/webhooks/telnyx
model: openai/gpt-4o
voice: Telnyx.KokoroTTS.af_heart
```

## CI/CD

Push to `main` → GitHub Actions CI runs pytest + type check + lint.
See `.github/workflows/ci.yml`.

## License

MIT