telnyx-mcp-server-fastmcp 0.1.3__py3-none-any.whl

telnyx_mcp_server/telnyx/services/messaging.py

@@ -0,0 +1,93 @@
+"""Telnyx messaging service."""
+
+from typing import Any, Dict, List, Optional
+
+from ...utils.logger import get_logger
+from ..client import TelnyxClient
+
+logger = get_logger(__name__)
+
+
+class MessagingService:
+    """Telnyx messaging service."""
+
+    def __init__(self, client: Optional[TelnyxClient] = None):
+        """Initialize the service.
+
+        Args:
+            client: Telnyx API client (creates a new one if not provided)
+        """
+        self.client = client or TelnyxClient()
+
+    def send_message(
+        self,
+        from_: str,
+        to: str,
+        text: str,
+        messaging_profile_id: Optional[str] = None,
+        subject: Optional[str] = None,
+        media_urls: Optional[List[str]] = None,
+        webhook_url: Optional[str] = None,
+        webhook_failover_url: Optional[str] = None,
+        use_profile_webhooks: bool = True,
+        type: Optional[str] = None,
+        auto_detect: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """Send a message.
+
+        Args:
+            from_: Sending address (phone number, alphanumeric sender ID, or short code)
+            to: Receiving address(es)
+            text: Message text
+            messaging_profile_id: Messaging profile ID
+            subject: Message subject
+            media_urls: Media URLs
+            webhook_url: Webhook URL
+            webhook_failover_url: Webhook failover URL
+            use_profile_webhooks: Whether to use profile webhooks
+            type: The protocol for sending the message, either SMS or MMS
+            auto_detect: Automatically detect if an SMS message is unusually long
+
+        Returns:
+            Dict[str, Any]: Response data
+        """
+        data = {
+            "from": from_,
+            "to": to if isinstance(to, list) else [to],
+            "text": text,
+            "use_profile_webhooks": use_profile_webhooks,
+        }
+
+        if messaging_profile_id:
+            data["messaging_profile_id"] = messaging_profile_id
+
+        if subject:
+            data["subject"] = subject
+
+        if media_urls:
+            data["media_urls"] = media_urls
+
+        if webhook_url:
+            data["webhook_url"] = webhook_url
+
+        if webhook_failover_url:
+            data["webhook_failover_url"] = webhook_failover_url
+
+        if type:
+            data["type"] = type
+
+        if auto_detect is not None:
+            data["auto_detect"] = auto_detect
+
+        return self.client.post("messages", data=data)
+
+    def get_message(self, message_id: str) -> Dict[str, Any]:
+        """Retrieve a message by ID.
+
+        Args:
+            message_id: The ID of the message to retrieve
+
+        Returns:
+            Dict[str, Any]: Response data containing message details
+        """
+        return self.client.get(f"messages/{message_id}")

telnyx_mcp_server/telnyx/services/messaging_profiles.py

@@ -0,0 +1,196 @@
+"""Telnyx messaging profiles service."""
+
+from typing import Any, Dict, List, Optional
+
+from ...utils.logger import get_logger
+from ..client import TelnyxClient
+
+logger = get_logger(__name__)
+
+
+class MessagingProfilesService:
+    """Telnyx messaging profiles service."""
+
+    def __init__(self, client: Optional[TelnyxClient] = None):
+        """Initialize the service.
+
+        Args:
+            client: Telnyx API client (creates a new one if not provided)
+        """
+        self.client = client or TelnyxClient()
+
+    def list_messaging_profiles(
+        self,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        filter_name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """List messaging profiles.
+
+        Args:
+            page: The page number to load
+            page_size: The size of the page
+            filter_name: Filter by name
+
+        Returns:
+            Dict[str, Any]: Response data containing list of messaging profiles
+        """
+        params = {}
+        if page is not None:
+            params["page[number]"] = page
+        if page_size is not None:
+            params["page[size]"] = page_size
+        if filter_name is not None:
+            params["filter[name]"] = filter_name
+
+        return self.client.get("messaging_profiles", params=params)
+
+    def create_messaging_profile(
+        self,
+        name: str,
+        whitelisted_destinations: List[str],
+        enabled: Optional[bool] = None,
+        webhook_url: Optional[str] = None,
+        webhook_failover_url: Optional[str] = None,
+        webhook_api_version: Optional[str] = None,
+        number_pool_settings: Optional[dict] = None,
+        url_shortener_settings: Optional[dict] = None,
+        alpha_sender: Optional[str] = None,
+        daily_spend_limit: Optional[str] = None,
+        daily_spend_limit_enabled: Optional[bool] = None,
+        mms_fall_back_to_sms: Optional[bool] = None,
+        mms_transcoding: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """Create a messaging profile.
+
+        Args:
+            name: A user friendly name for the messaging profile
+            whitelisted_destinations: Destinations to which the messaging profile is allowed to send
+            enabled: Specifies whether the messaging profile is enabled or not
+            webhook_url: The URL where webhooks related to this messaging profile will be sent
+            webhook_failover_url: The failover URL where webhooks related to this messaging profile will be sent
+            webhook_api_version: Determines which webhook format will be used
+            number_pool_settings: Number Pool settings
+            url_shortener_settings: URL shortener settings
+            alpha_sender: The alphanumeric sender ID
+            daily_spend_limit: The maximum amount of money that can be spent
+            daily_spend_limit_enabled: Whether to enforce the daily spend limit
+            mms_fall_back_to_sms: Enables SMS fallback for MMS messages
+            mms_transcoding: Enables automated resizing of MMS media
+
+        Returns:
+            Dict[str, Any]: Response data containing the created messaging profile
+        """
+        data = {
+            "name": name,
+            "whitelisted_destinations": whitelisted_destinations,
+        }
+
+        if enabled is not None:
+            data["enabled"] = enabled
+        if webhook_url is not None:
+            data["webhook_url"] = webhook_url
+        if webhook_failover_url is not None:
+            data["webhook_failover_url"] = webhook_failover_url
+        if webhook_api_version is not None:
+            data["webhook_api_version"] = webhook_api_version
+        if number_pool_settings is not None:
+            data["number_pool_settings"] = number_pool_settings
+        if url_shortener_settings is not None:
+            data["url_shortener_settings"] = url_shortener_settings
+        if alpha_sender is not None:
+            data["alpha_sender"] = alpha_sender
+        if daily_spend_limit is not None:
+            data["daily_spend_limit"] = daily_spend_limit
+        if daily_spend_limit_enabled is not None:
+            data["daily_spend_limit_enabled"] = daily_spend_limit_enabled
+        if mms_fall_back_to_sms is not None:
+            data["mms_fall_back_to_sms"] = mms_fall_back_to_sms
+        if mms_transcoding is not None:
+            data["mms_transcoding"] = mms_transcoding
+
+        return self.client.post("messaging_profiles", data=data)
+
+    def get_messaging_profile(self, profile_id: str) -> Dict[str, Any]:
+        """Retrieve a messaging profile by ID.
+
+        Args:
+            profile_id: The ID of the messaging profile to retrieve
+
+        Returns:
+            Dict[str, Any]: Response data containing messaging profile details
+        """
+        return self.client.get(f"messaging_profiles/{profile_id}")
+
+    def update_messaging_profile(
+        self,
+        profile_id: str,
+        name: Optional[str] = None,
+        enabled: Optional[bool] = None,
+        webhook_url: Optional[str] = None,
+        webhook_failover_url: Optional[str] = None,
+        webhook_api_version: Optional[str] = None,
+        whitelisted_destinations: Optional[List[str]] = None,
+        v1_secret: Optional[str] = None,
+        number_pool_settings: Optional[dict] = None,
+        url_shortener_settings: Optional[dict] = None,
+        alpha_sender: Optional[str] = None,
+        daily_spend_limit: Optional[str] = None,
+        daily_spend_limit_enabled: Optional[bool] = None,
+        mms_fall_back_to_sms: Optional[bool] = None,
+        mms_transcoding: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """Update a messaging profile.
+
+        Args:
+            profile_id: The ID of the messaging profile to update
+            name: A user friendly name for the messaging profile
+            enabled: Specifies whether the messaging profile is enabled or not
+            webhook_url: The URL where webhooks related to this messaging profile will be sent
+            webhook_failover_url: The failover URL where webhooks related to this messaging profile will be sent
+            webhook_api_version: Determines which webhook format will be used
+            whitelisted_destinations: Destinations to which the messaging profile is allowed to send
+            v1_secret: Secret used to authenticate with v1 endpoints
+            number_pool_settings: Number Pool settings
+            url_shortener_settings: URL shortener settings
+            alpha_sender: The alphanumeric sender ID
+            daily_spend_limit: The maximum amount of money that can be spent
+            daily_spend_limit_enabled: Whether to enforce the daily spend limit
+            mms_fall_back_to_sms: Enables SMS fallback for MMS messages
+            mms_transcoding: Enables automated resizing of MMS media
+
+        Returns:
+            Dict[str, Any]: Response data containing the updated messaging profile
+        """
+        data = {}
+
+        if name is not None:
+            data["name"] = name
+        if enabled is not None:
+            data["enabled"] = enabled
+        if webhook_url is not None:
+            data["webhook_url"] = webhook_url
+        if webhook_failover_url is not None:
+            data["webhook_failover_url"] = webhook_failover_url
+        if webhook_api_version is not None:
+            data["webhook_api_version"] = webhook_api_version
+        if whitelisted_destinations is not None:
+            data["whitelisted_destinations"] = whitelisted_destinations
+        if v1_secret is not None:
+            data["v1_secret"] = v1_secret
+        if number_pool_settings is not None:
+            data["number_pool_settings"] = number_pool_settings
+        if url_shortener_settings is not None:
+            data["url_shortener_settings"] = url_shortener_settings
+        if alpha_sender is not None:
+            data["alpha_sender"] = alpha_sender
+        if daily_spend_limit is not None:
+            data["daily_spend_limit"] = daily_spend_limit
+        if daily_spend_limit_enabled is not None:
+            data["daily_spend_limit_enabled"] = daily_spend_limit_enabled
+        if mms_fall_back_to_sms is not None:
+            data["mms_fall_back_to_sms"] = mms_fall_back_to_sms
+        if mms_transcoding is not None:
+            data["mms_transcoding"] = mms_transcoding
+
+        return self.client.patch(f"messaging_profiles/{profile_id}", data=data)

telnyx_mcp_server/telnyx/services/numbers.py

@@ -0,0 +1,193 @@
+"""Telnyx phone numbers service."""
+
+from typing import Any, Dict, List, Optional
+
+from ...utils.logger import get_logger
+from ..client import TelnyxClient
+
+logger = get_logger(__name__)
+
+
+class NumbersService:
+    """Telnyx phone numbers service."""
+
+    def __init__(self, client: Optional[TelnyxClient] = None):
+        """Initialize the service.
+
+        Args:
+            client: Telnyx API client (creates a new one if not provided)
+        """
+        self.client = client or TelnyxClient()
+
+    def list_phone_numbers(
+        self,
+        page: int = 1,
+        page_size: int = 20,
+        filter_tag: Optional[str] = None,
+        filter_phone_number: Optional[str] = None,
+        filter_status: Optional[str] = None,
+        filter_country_iso_alpha2: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """List phone numbers.
+
+        Args:
+            page: Page number
+            page_size: Page size
+            filter_tag: Filter by phone number tag
+            filter_phone_number: Filter by phone number
+            filter_status: Filter by phone number status
+            filter_country_iso_alpha2: Filter by country ISO alpha-2 code
+
+        Returns:
+            Dict[str, Any]: Response data
+        """
+        params = {
+            "page[number]": page,
+            "page[size]": page_size,
+        }
+
+        if filter_tag:
+            params["filter[tag]"] = filter_tag
+
+        if filter_phone_number:
+            params["filter[phone_number]"] = filter_phone_number
+
+        if filter_status:
+            params["filter[status]"] = filter_status
+
+        if filter_country_iso_alpha2:
+            params["filter[country_iso_alpha2]"] = filter_country_iso_alpha2
+
+        return self.client.get("phone_numbers", params=params)
+
+    def get_phone_number(self, id: str) -> Dict[str, Any]:
+        """Get a phone number by ID.
+
+        Args:
+            id: Phone number ID as string
+
+        Returns:
+            Dict[str, Any]: Response data
+        """
+        return self.client.get(f"phone_numbers/{id}")
+
+    def update_phone_number(
+        self, id: str, data: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Update a phone number.
+
+        Args:
+            id: Phone number ID as string
+            data: Update data
+
+        Returns:
+            Dict[str, Any]: Response data
+        """
+        return self.client.patch(f"phone_numbers/{id}", data=data)
+
+    def list_available_phone_numbers(
+        self,
+        page: int = 1,
+        page_size: int = 20,
+        filter_phone_number_starts_with: Optional[str] = None,
+        filter_phone_number_ends_with: Optional[str] = None,
+        filter_phone_number_contains: Optional[str] = None,
+        filter_locality: Optional[str] = None,
+        filter_administrative_area: Optional[str] = None,
+        filter_country_code: Optional[str] = None,
+        filter_features: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """List available phone numbers.
+
+        Args:
+            page: Page number
+            page_size: Page size
+            filter_phone_number_starts_with: Filter numbers starting with pattern
+            filter_phone_number_ends_with: Filter numbers ending with pattern
+            filter_phone_number_contains: Filter numbers containing pattern
+            filter_locality: Filter by locality (city)
+            filter_administrative_area: Filter by administrative area (state)
+            filter_country_code: Filter by country code
+            filter_features: Filter by features
+
+        Returns:
+            Dict[str, Any]: Response data
+        """
+        params = {
+            "page[number]": page,
+            "page[size]": page_size,
+        }
+
+        if filter_phone_number_starts_with:
+            params["filter[phone_number][starts_with]"] = (
+                filter_phone_number_starts_with
+            )
+
+        if filter_phone_number_ends_with:
+            params["filter[phone_number][ends_with]"] = (
+                filter_phone_number_ends_with
+            )
+
+        if filter_phone_number_contains:
+            params["filter[phone_number][contains]"] = (
+                filter_phone_number_contains
+            )
+
+        if filter_locality:
+            params["filter[locality]"] = filter_locality
+
+        if filter_administrative_area:
+            params["filter[administrative_area]"] = filter_administrative_area
+
+        if filter_country_code:
+            params["filter[country_code]"] = filter_country_code
+
+        if filter_features:
+            params["filter[features]"] = ",".join(filter_features)
+
+        return self.client.get("available_phone_numbers", params=params)
+
+    def buy_phone_number(
+        self, phone_number: str, connection_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Buy a phone number.
+
+        Args:
+            phone_number: Phone number to buy
+            connection_id: Connection ID to associate with the number
+
+        Returns:
+            Dict[str, Any]: Response data
+        """
+        data = {"phone_numbers": [{"phone_number": phone_number}]}
+
+        if connection_id:
+            data["connection_id"] = connection_id
+
+        return self.client.post("number_orders", data=data)
+
+    def update_phone_number_messaging_settings(
+        self,
+        id: str,
+        messaging_profile_id: Optional[str] = None,
+        messaging_product: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Update the messaging profile and/or messaging product of a phone number.
+
+        Args:
+            id: The phone number ID to update
+            messaging_profile_id: Configure the messaging profile this phone number is assigned to
+            messaging_product: Configure the messaging product for this number
+
+        Returns:
+            Dict[str, Any]: Response data containing the updated phone number messaging settings
+        """
+        data = {}
+
+        if messaging_profile_id is not None:
+            data["messaging_profile_id"] = messaging_profile_id
+
+        if messaging_product is not None:
+            data["messaging_product"] = messaging_product
+
+        return self.client.patch(f"phone_numbers/{id}/messaging", data=data)

telnyx_mcp_server/telnyx/services/secrets.py

@@ -0,0 +1,74 @@
+"""Telnyx secrets manager service."""
+
+from typing import Any, Dict, Optional
+
+from ...utils.logger import get_logger
+from ..client import TelnyxClient
+
+logger = get_logger(__name__)
+
+
+class SecretsService:
+    """Telnyx secrets manager service."""
+
+    def __init__(self, client: Optional[TelnyxClient] = None):
+        """Initialize the service.
+
+        Args:
+            client: Telnyx API client (creates a new one if not provided)
+        """
+        self.client = client or TelnyxClient()
+
+    def list_integration_secrets(
+        self,
+        page: int = 1,
+        page_size: int = 25,
+        filter_type: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """List integration secrets.
+
+        Args:
+            page: Page number
+            page_size: Page size
+            filter_type: Filter by secret type (bearer, basic)
+
+        Returns:
+            Dict[str, Any]: Response data
+        """
+        params = {
+            "page[number]": page,
+            "page[size]": page_size,
+        }
+
+        if filter_type:
+            params["filter[type]"] = filter_type
+
+        return self.client.get("integration_secrets", params=params)
+
+    def create_integration_secret(
+        self, request: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Create an integration secret.
+
+        Args:
+            identifier: The unique identifier of the secret
+            type: The type of secret (bearer, basic)
+            token: The token for the secret (required for bearer type)
+            username: The username for the secret (required for basic type)
+            password: The password for the secret (required for basic type)
+
+        Returns:
+            Dict[str, Any]: Response data
+        """
+        return self.client.post("integration_secrets", data=request)
+
+    def delete_integration_secret(self, id: str) -> Dict[str, Any]:
+        """Delete an integration secret.
+
+        Args:
+            id: Secret ID
+
+        Returns:
+            Dict[str, Any]: Response data (empty dict on success)
+        """
+        return self.client.delete(f"integration_secrets/{id}")

telnyx_mcp_server/tools/__init__.py

@@ -0,0 +1,126 @@
+"""MCP tools package."""
+
+# Import resource functions
+from . import sms_conversations, webhooks
+from .assistants import (
+    create_assistant,
+    get_assistant,
+    get_assistant_texml,
+    list_assistants,
+    mcp_telnyx_delete_assistant,
+    start_assistant_call,
+    update_assistant,
+)
+from .call_control import (
+    create_call_control_application,
+    get_call_control_application,
+    hangup,
+    list_call_control_applications,
+    make_call,
+    playback_start,
+    playback_stop,
+    send_dtmf,
+    speak,
+    transfer,
+)
+from .cloud_storage import (
+    cloud_storage_create_bucket,
+    cloud_storage_delete_object,
+    cloud_storage_download_file,
+    cloud_storage_get_bucket_location,
+    cloud_storage_list_buckets,
+    cloud_storage_list_objects,
+    cloud_storage_upload_file,
+)
+from .connections import get_connection, list_connections, update_connection
+from .embeddings import (
+    create_embeddings,
+    embed_url,
+    list_embedded_buckets,
+)
+from .messaging import get_message, send_message
+from .messaging_profiles import (
+    create_messaging_profile,
+    get_messaging_profile,
+    list_messaging_profiles,
+    update_messaging_profile,
+)
+from .phone_numbers import (
+    get_phone_number,
+    initiate_phone_number_order,
+    list_available_phone_numbers,
+    list_phone_numbers,
+    update_phone_number,
+    update_phone_number_messaging_settings,
+)
+from .secrets import (
+    create_integration_secret,
+    delete_integration_secret,
+    list_integration_secrets,
+)
+
+# Import webhook tool functions
+from .webhooks import get_webhook_events
+
+__all__ = [
+    # Assistant tools
+    "create_assistant",
+    "get_assistant",
+    "get_assistant_texml",
+    "list_assistants",
+    "get_webhook_events",
+    "sms_conversations",
+    "webhooks",
+    "mcp_telnyx_delete_assistant",
+    "start_assistant_call",
+    "update_assistant",
+    # Call control tools
+    "create_call_control_application",
+    "get_call_control_application",
+    "hangup",
+    "list_call_control_applications",
+    "make_call",
+    "playback_start",
+    "playback_stop",
+    "send_dtmf",
+    "speak",
+    "transfer",
+    # Cloud storage tools
+    "cloud_storage_create_bucket",
+    "cloud_storage_list_buckets",
+    "cloud_storage_upload_file",
+    "cloud_storage_download_file",
+    "cloud_storage_list_objects",
+    "cloud_storage_delete_object",
+    "cloud_storage_get_bucket_location",
+    "cloud_storage_create_bucket",
+    # Connection tools
+    "get_connection",
+    "list_connections",
+    "update_connection",
+    # Embeddings tools
+    "create_embeddings",
+    "embed_url",
+    "list_embedded_buckets",
+    # Messaging tools
+    "send_message",
+    "get_message",
+    # Messaging profile tools
+    "create_messaging_profile",
+    "get_messaging_profile",
+    "list_messaging_profiles",
+    "update_messaging_profile",
+    # Phone number tools
+    "initiate_phone_number_order",
+    "get_phone_number",
+    "list_available_phone_numbers",
+    "list_phone_numbers",
+    "update_phone_number",
+    "update_phone_number_messaging_settings",
+    # Secrets manager tools
+    "create_integration_secret",
+    "delete_integration_secret",
+    "list_integration_secrets",
+    # Webhook tools
+    "get_webhook_events",
+]