tai42-tools-twilio

Twilio provisioning tools for the TAI ecosystem — manifest-loaded REST tools that list a Twilio account's incoming phone numbers, read a number's inbound-message webhook, and set a number's inbound-message webhook URL.

All Twilio traffic is direct REST through tai42-kit's curl client (no twilio SDK); requests carry HTTP Basic auth (AccountSid:AuthToken). The package registers its tools through the tai42_app handle from tai42_contract.app and never imports the skeleton.

The TAI ecosystem

TAI is an open-source runtime for MCP tools, agents, and workflows. A tool is a callable the host loads from a plugin manifest; this package supplies the Twilio number-provisioning tools. The ecosystem is open-ended, so this repo is these tools' own full doc home, and the documentation site covers the platform-level story:

• Tools concept: https://tai42.ai/concepts/tools
• Build a tool (author guide): https://tai42.ai/guides/authors/tool
• Ecosystem catalog: https://tai42.ai/reference/catalog

The current release line tracks the 7.x contract (tai42-contract>=7,<8).

Install

Requires Python 3.13+. Install from PyPI into the environment that runs the server:

uv add tai42-tools-twilio

Or from source — clone this repo and add it as an editable dependency; the tai42-* dependencies resolve in-tree from the workspace.

git clone https://github.com/tai42ai/tai42   # next to your app checkout
cd /path/to/your/app
uv add --editable ../tai42/plugins/tools-twilio

Catalog

Provisioning a number's inbound webhook

These tools configure the Twilio side of an inbound-message flow: they point a number's "A message comes in" webhook at the platform's inbound endpoint so Twilio POSTs each message there. list_twilio_numbers finds the number's sid, get_twilio_number_webhook reads its current webhook, and set_twilio_number_webhook writes a new one:

{ "sid": "PN...", "phone_number": "+15551234567", "sms_url": "https://app.example/api/channels/twilio/inbound" }

set_twilio_number_webhook requires an https URL and rejects an empty or non-https value before any network call. Every Twilio non-2xx raises loudly with its status and body — never remapped to success — and the Basic-auth header is never echoed into the error.

Configuration

The tools read the same CHANNEL_TWILIO_ credentials as the deployment's Twilio channel — one account SID, auth token, and REST base configure both.

Credentials live only in the environment. A missing or empty required credential raises loudly (fails closed), naming its env var and never the value.

Development

uv venv --python 3.13
uv pip install --no-sources --extra dev --editable .
uv run --no-sync pytest --cov --cov-report=term-missing
uv run --no-sync ruff check .
uv run --no-sync ruff format --check .
uv run --no-sync pyright

License

Apache-2.0. See LICENSE and NOTICE.