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

telnyx_mcp_server/tools/cloud_storage.py

@@ -0,0 +1,183 @@
+"""Cloud storage related MCP tools."""
+
+import os
+from typing import Any, Dict, List
+
+from ..mcp import mcp
+from ..telnyx.services.cloud_storage import BucketInfo, CloudStorageService
+from ..utils.error_handler import handle_telnyx_error
+from ..utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def instantiate_cloud_storage() -> CloudStorageService:
+    api_key = os.getenv("TELNYX_API_KEY", "")
+    if not api_key:
+        raise ValueError("TELNYX_API_KEY environment variable must be set")
+    return CloudStorageService(
+        access_key_id=api_key,
+        secret_access_key=api_key,
+    )
+
+
+@mcp.tool()
+async def cloud_storage_create_bucket(request: Dict[str, Any]) -> str:
+    """Create a new bucket.
+
+    Args:
+        bucket_name: Required. Name of the bucket to create
+        region: Required. Region to create the bucket in (us-east-1, us-west-1, us-central-1)
+    Returns:
+        str: `Success!!` if it uploaded, otherwise returns an exception message
+    """
+    try:
+        cloud_storage_service = instantiate_cloud_storage()
+        if not cloud_storage_service:
+            raise RuntimeError(f"Cloud storage service not initialized")
+        return cloud_storage_service.create_bucket(
+            bucket_name=request["bucket_name"], region=request.get("region")
+        )
+    except Exception as e:
+        logger.error(f"Error creating bucket: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def cloud_storage_list_buckets() -> List[BucketInfo]:
+    """List all buckets across all regions.
+
+    Returns:
+        List[Dict[str, str]]: List of dictionaries containing bucket information:
+            - name: Name of the bucket
+            - region: Region where the bucket is located
+    """
+    try:
+        cloud_storage_service = instantiate_cloud_storage()
+        if not cloud_storage_service:
+            raise RuntimeError(f"Cloud storage service not initialized")
+        return cloud_storage_service.list_buckets()
+    except Exception as e:
+        logger.error(f"Error listing buckets: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def cloud_storage_upload_file(request: Dict[str, Any]) -> str:
+    """Upload a file to cloud storage.
+
+    Args:
+        absolute_file_path: Required. Absolute File Path to the file to upload
+        object_name: Optional. Name to give the object in storage (defaults to file name)
+        bucket_name: Optional. Bucket to upload to (defaults to instance default)
+    Returns:
+        str: `Success!!` if it uploaded, otherwise returns an exception message
+    """
+    try:
+        cloud_storage_service = instantiate_cloud_storage()
+        if not cloud_storage_service:
+            raise RuntimeError(f"Cloud storage service not initialized")
+        return cloud_storage_service.upload_file(
+            file_path=request["absolute_file_path"],
+            object_name=request.get("object_name"),
+            bucket_name=request.get("bucket_name"),
+        )
+    except Exception as e:
+        logger.error(f"Error uploading file: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def cloud_storage_download_file(request: Dict[str, Any]) -> str:
+    """Download a file from cloud storage.
+
+    Args:
+        object_name: Required. Name of the object to download
+        file_path: Required. Path where to save the downloaded file
+        bucket_name: Optional. Bucket to download from (defaults to instance default)
+    Returns:
+        str: 'Success' if the file was downloaded successfully
+    """
+    try:
+        cloud_storage_service = instantiate_cloud_storage()
+        if not cloud_storage_service:
+            raise RuntimeError(f"Cloud storage service not initialized")
+        cloud_storage_service.download_file(
+            object_name=request["object_name"],
+            file_path=request["file_path"],
+            bucket_name=request.get("bucket_name"),
+        )
+        return "Success"
+    except Exception as e:
+        logger.error(f"Error downloading file: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def cloud_storage_list_objects(request: Dict[str, Any]) -> List[str]:
+    """List objects in a bucket with optional prefix filtering.
+
+    Args:
+        prefix: Optional. Only list objects beginning with this prefix. Defaults to "".
+        bucket_name: Optional. Bucket to list from (defaults to instance default)
+
+    Returns:
+        List[str]: List of object names
+    """
+    try:
+        cloud_storage_service = instantiate_cloud_storage()
+        if not cloud_storage_service:
+            raise RuntimeError(f"Cloud storage service not initialized")
+        return cloud_storage_service.list_objects(
+            prefix=request.get("prefix", ""),
+            bucket_name=request.get("bucket_name"),
+        )
+    except Exception as e:
+        logger.error(f"Error listing objects: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def cloud_storage_delete_object(request: Dict[str, Any]) -> str:
+    """Delete an object from cloud storage.
+
+    Args:
+        object_name: Required. Name of the object to delete
+        bucket_name: Optional. Bucket to delete from (defaults to instance default)
+    Returns:
+        str: 'Success' if the object was deleted successfully
+    """
+    try:
+        cloud_storage_service = instantiate_cloud_storage()
+        if not cloud_storage_service:
+            raise RuntimeError(f"Cloud storage service not initialized")
+        cloud_storage_service.delete_object(
+            object_name=request["object_name"],
+            bucket_name=request.get("bucket_name"),
+        )
+        return "Success"
+    except Exception as e:
+        logger.error(f"Error deleting object: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def cloud_storage_get_bucket_location(request: Dict[str, Any]) -> str:
+    """Get the region where a bucket is located.
+
+    Args:
+        bucket_name: Optional. Name of the bucket. If None, uses default bucket.
+
+    Returns:
+        str: The region where the bucket is located
+    """
+    try:
+        cloud_storage_service = instantiate_cloud_storage()
+        if not cloud_storage_service:
+            raise RuntimeError(f"Cloud storage service not initialized")
+        return cloud_storage_service.get_bucket_location(
+            bucket_name=request.get("bucket_name")
+        )
+    except Exception as e:
+        logger.error(f"Error getting bucket location: {e}")
+        raise handle_telnyx_error(e)

telnyx_mcp_server/tools/connections.py

@@ -0,0 +1,78 @@
+"""Connection related MCP tools."""
+
+from typing import Any, Dict
+
+from ..mcp import mcp
+from ..telnyx.services.connections import ConnectionsService
+from ..utils.error_handler import handle_telnyx_error
+from ..utils.logger import get_logger
+from ..utils.service import get_authenticated_service
+
+logger = get_logger(__name__)
+
+
+@mcp.tool()
+async def list_connections(request: Dict[str, Any]) -> Dict[str, Any]:
+    """List connections.
+
+    Args:
+        page: Optional integer. Page number. Defaults to 1.
+        page_size: Optional integer. Page size. Defaults to 20.
+        filter_connection_name_contains: Optional. Filter by connection name.
+        filter_outbound_voice_profile_id: Optional. Filter by outbound voice profile ID.
+        sort: Optional. Sort order (created_at, connection_name, active).
+
+    Returns:
+        Dict[str, Any]: Response data
+    """
+    try:
+        service = get_authenticated_service(ConnectionsService)
+        return service.list_connections(request)
+    except Exception as e:
+        logger.error(f"Error listing connections: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def get_connection(id: str) -> Dict[str, Any]:
+    """Get a connection by ID.
+
+    Args:
+        id: Required. Connection ID.
+
+    Returns:
+        Dict[str, Any]: Response data
+    """
+    try:
+        service = get_authenticated_service(ConnectionsService)
+        return service.get_connection(connection_id=id)
+    except Exception as e:
+        logger.error(f"Error getting connection: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def update_connection(id: str, data: Dict[str, Any]) -> Dict[str, Any]:
+    """Update a connection.
+
+    Note:
+        The Telnyx API does not support updating connections directly.
+        Only GET, HEAD, and OPTIONS methods are allowed.
+        Please create a new connection with the desired settings instead.
+
+    Args:
+        id: Required. Connection ID.
+        data: Required. Update data.
+
+    Returns:
+        Dict[str, Any]: Response data
+
+    Raises:
+        Exception: The Telnyx API does not support updating connections directly.
+    """
+    try:
+        service = get_authenticated_service(ConnectionsService)
+        return service.update_connection(connection_id=id, data=data)
+    except Exception as e:
+        logger.error(f"Error updating connection: {e}")
+        raise handle_telnyx_error(e)

telnyx_mcp_server/tools/embeddings.py

@@ -0,0 +1,80 @@
+"""Embeddings related MCP tools."""
+
+from typing import Any, Dict
+
+from ..mcp import mcp
+from ..telnyx.services.embeddings import EmbeddingsService
+from ..utils.error_handler import handle_telnyx_error
+from ..utils.logger import get_logger
+from ..utils.service import get_authenticated_service
+
+logger = get_logger(__name__)
+
+
+@mcp.tool()
+async def list_embedded_buckets() -> Dict[str, Any]:
+    """List user embedded buckets.
+
+    Returns:
+        Dict[str, Any]: Response data eg:
+        {
+            "data": {
+                "buckets": [
+                "string"
+                ]
+            }
+        }
+    """
+    try:
+        service = get_authenticated_service(EmbeddingsService)
+        return service.list_embedded_buckets()
+    except Exception as e:
+        logger.error(f"Error listing embedded buckets: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def embed_url(request: Dict[str, Any]) -> Dict[str, Any]:
+    """Scrape and embed a given URL. For a given website, this tool will scrape
+    the content of the pages and save the content in a new bucket. That bucket will
+    be automatically embedded.
+
+    Args:
+        url: Required. URL to be scraped and embedded.
+
+    Returns:
+        Dict[str, Any]: Response data containing bucket information
+    """
+    try:
+        service = get_authenticated_service(EmbeddingsService)
+        return service.embed_url(request)
+    except Exception as e:
+        logger.error(f"Error embedding URL: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def create_embeddings(request: Dict[str, Any]) -> Dict[str, Any]:
+    """Embed a bucket that containe files.
+
+    Args:
+        bucket_name: Required. Bucket Name. The bucket must exist (string)
+        document_chunk_size: Optional. Document Chunk Size (integer)
+        document_chunk_overlap_size: Optional. Document Chunk Overlap Size (integer)
+        embedding_model: Optional. Supported models (thenlper/gte-large,
+        intfloat/multilingual-e5-large, sentence-transformers/all-mpnet-base-v2)
+        to vectorize and embed documents.
+        loader: Optional. (default, intercom) (string)
+
+    Agent should prefer only rely on required fields unless user explicitly
+    provides values for optional fields.
+
+    Returns:
+        Dict[str, Any]: Response data containing the embeddings
+    """
+    try:
+        service = get_authenticated_service(EmbeddingsService)
+        return service.create_embeddings(request)
+    except Exception as e:
+        logger.error(f"Error creating embeddings: {e}")
+        raise handle_telnyx_error(e)

telnyx_mcp_server/tools/messaging.py

@@ -0,0 +1,57 @@
+"""Messaging related MCP tools."""
+
+from typing import Any, Dict
+
+from ..mcp import mcp
+from ..telnyx.services.messaging import MessagingService
+from ..utils.error_handler import handle_telnyx_error
+from ..utils.logger import get_logger
+from ..utils.service import get_authenticated_service
+
+logger = get_logger(__name__)
+
+
+@mcp.tool()
+async def send_message(request: Dict[str, Any]) -> Dict[str, Any]:
+    """Send a message.
+
+    Args:
+        from_: Required. Sending address (phone number, alphanumeric sender ID, or short code).
+        to: Required. Receiving address(es).
+        text: Required. Message text.
+        messaging_profile_id: Optional. Messaging profile ID.
+        subject: Optional. Message subject.
+        media_urls: Optional. List of media URLs.
+        webhook_url: Optional. Webhook URL.
+        webhook_failover_url: Optional. Webhook failover URL.
+        use_profile_webhooks: Optional boolean. Whether to use profile webhooks. Defaults to True.
+        type: Optional. The protocol for sending the message, either "SMS" or "MMS".
+        auto_detect: Optional boolean. Automatically detect if an SMS message is unusually long.
+
+    Returns:
+        Dict[str, Any]: Response data
+    """
+    try:
+        service = get_authenticated_service(MessagingService)
+        return service.send_message(**request)
+    except Exception as e:
+        logger.error(f"Error sending message: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def get_message(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
+    """
+    try:
+        service = get_authenticated_service(MessagingService)
+        return service.get_message(message_id)
+    except Exception as e:
+        logger.error(f"Error retrieving message: {e}")
+        raise handle_telnyx_error(e)

telnyx_mcp_server/tools/messaging_profiles.py

@@ -0,0 +1,123 @@
+"""Messaging profiles related MCP tools."""
+
+from typing import Any, Dict
+
+from ..mcp import mcp
+from ..telnyx.services.messaging_profiles import MessagingProfilesService
+from ..utils.error_handler import handle_telnyx_error
+from ..utils.logger import get_logger
+from ..utils.service import get_authenticated_service
+
+logger = get_logger(__name__)
+
+
+@mcp.tool()
+async def list_messaging_profiles(request: Dict[str, Any]) -> Dict[str, Any]:
+    """List messaging profiles.
+
+    Args:
+        page: Optional integer. Page number. Defaults to 1.
+        page_size: Optional integer. Page size. Defaults to 20.
+        filter_name: Optional. Filter by profile name.
+
+    Returns:
+        Dict[str, Any]: Response data
+    """
+    try:
+        service = get_authenticated_service(MessagingProfilesService)
+        return service.list_messaging_profiles(**request)
+    except Exception as e:
+        logger.error(f"Error listing messaging profiles: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def create_messaging_profile(request: Dict[str, Any]) -> Dict[str, Any]:
+    """Create a messaging profile.
+
+    Args:
+        name: Required. A user friendly name for the messaging profile.
+        whitelisted_destinations: Required. List of destinations to which messages are allowed to be sent (ISO 3166-1 alpha-2 country codes). Use ["*"] to allow all destinations.
+        enabled: Optional boolean. Specifies whether the messaging profile is enabled. Defaults to True.
+        webhook_url: Optional. The URL where webhooks related to this messaging profile will be sent.
+        webhook_failover_url: Optional. The failover URL for webhooks if the primary URL fails.
+        webhook_api_version: Optional. Webhook format version ("1", "2", or "2010-04-01"). Defaults to "2".
+        number_pool_settings: Optional dictionary. Number pool configuration with possible settings:
+            - use_pool: Boolean indicating whether to use number pool.
+            - sticky_sender: Boolean indicating whether to use sticky sender.
+            - pool_weights: Dictionary mapping phone number types to weights.
+        url_shortener_settings: Optional dictionary. URL shortener configuration with possible settings:
+            - enabled: Boolean indicating whether URL shortening is enabled.
+            - domains: List of domains to be shortened.
+        alpha_sender: Optional. The alphanumeric sender ID for destinations requiring it.
+        daily_spend_limit: Optional. Maximum daily spend in USD before midnight UTC.
+        daily_spend_limit_enabled: Optional boolean. Whether to enforce the daily spend limit.
+        mms_fall_back_to_sms: Optional boolean. Enables SMS fallback for MMS messages.
+        mms_transcoding: Optional boolean. Enables automated resizing of MMS media.
+
+    Returns:
+        Dict[str, Any]: Response data
+    """
+    try:
+        service = get_authenticated_service(MessagingProfilesService)
+        return service.create_messaging_profile(**request)
+    except Exception as e:
+        logger.error(f"Error creating messaging profile: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def get_messaging_profile(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
+    """
+    try:
+        service = get_authenticated_service(MessagingProfilesService)
+        return service.get_messaging_profile(profile_id)
+    except Exception as e:
+        logger.error(f"Error retrieving messaging profile: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def update_messaging_profile(
+    profile_id: str, request: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Update a messaging profile.
+
+    Args:
+        profile_id: Required. The ID of the messaging profile to update.
+        name: Optional. A user friendly name for the messaging profile.
+        enabled: Optional boolean. Specifies whether the messaging profile is enabled.
+        webhook_url: Optional. The URL where webhooks related to this messaging profile will be sent.
+        webhook_failover_url: Optional. The failover URL for webhooks if the primary URL fails.
+        webhook_api_version: Optional. Webhook format version ("1", "2", or "2010-04-01").
+        whitelisted_destinations: Optional list. Destinations to which messages are allowed (ISO 3166-1 alpha-2 country codes). Use ["*"] to allow all destinations.
+        v1_secret: Optional. Secret used to authenticate with v1 endpoints.
+        number_pool_settings: Optional dictionary. Number pool configuration with possible settings:
+            - use_pool: Boolean indicating whether to use number pool.
+            - sticky_sender: Boolean indicating whether to use sticky sender.
+            - pool_weights: Dictionary mapping phone number types to weights.
+        url_shortener_settings: Optional dictionary. URL shortener configuration with possible settings:
+            - enabled: Boolean indicating whether URL shortening is enabled.
+            - domains: List of domains to be shortened.
+        alpha_sender: Optional. The alphanumeric sender ID for destinations requiring it.
+        daily_spend_limit: Optional. Maximum daily spend in USD before midnight UTC.
+        daily_spend_limit_enabled: Optional boolean. Whether to enforce the daily spend limit.
+        mms_fall_back_to_sms: Optional boolean. Enables SMS fallback for MMS messages.
+        mms_transcoding: Optional boolean. Enables automated resizing of MMS media.
+
+    Returns:
+        Dict[str, Any]: Response data
+    """
+    try:
+        service = get_authenticated_service(MessagingProfilesService)
+        return service.update_messaging_profile(profile_id, **request)
+    except Exception as e:
+        logger.error(f"Error updating messaging profile: {e}")
+        raise handle_telnyx_error(e)

telnyx_mcp_server/tools/phone_numbers.py

@@ -0,0 +1,161 @@
+"""Phone number related MCP tools."""
+
+from typing import Any, Dict
+
+from pydantic import Field
+
+from ..mcp import mcp
+from ..telnyx.services.numbers import NumbersService
+from ..utils.error_handler import handle_telnyx_error
+from ..utils.logger import get_logger
+from ..utils.service import get_authenticated_service
+
+logger = get_logger(__name__)
+
+
+@mcp.tool()
+async def list_phone_numbers(request: Dict[str, Any]) -> Dict[str, Any]:
+    """List phone numbers.
+
+    Args:
+        page: Optional integer. Page number. Defaults to 1.
+        page_size: Optional integer. Page size. Defaults to 20.
+        filter_tag: Optional. Filter by phone number tag.
+        filter_phone_number: Optional. Filter by phone number.
+        filter_status: Optional. Filter by phone number status.
+        filter_country_iso_alpha2: Optional. Filter by country ISO alpha-2 code.
+
+    Returns:
+        Dict[str, Any]: Response data
+    """
+    try:
+        service = get_authenticated_service(NumbersService)
+        return service.list_phone_numbers(**request)
+    except Exception as e:
+        logger.error(f"Error listing phone numbers: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def get_phone_number(
+    id: str = Field(..., description="Phone number ID as string"),
+) -> Dict[str, Any]:
+    """Get a phone number by ID.
+
+    Args:
+        id: Phone number ID as string
+
+    Returns:
+        Dict[str, Any]: Response data containing Number Object(s) (record_type: "phone_number")
+    """
+    try:
+        service = get_authenticated_service(NumbersService)
+        return service.get_phone_number(id=id)
+    except Exception as e:
+        logger.error(f"Error getting phone number: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def update_phone_number(
+    id: str, request: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Update a phone number.
+
+    Args:
+        id: Required. Phone number ID.
+        connection_id: Optional. Connection ID to associate with the number.
+        tags: Optional. List of tags to associate with the number.
+
+    Returns:
+        Dict[str, Any]: Response data
+    """
+    try:
+        service = get_authenticated_service(NumbersService)
+        return service.update_phone_number(id=id, data=request)
+    except Exception as e:
+        logger.error(f"Error updating phone number: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def list_available_phone_numbers(
+    request: Dict[str, Any],
+) -> Dict[str, Any]:
+    """List available phone numbers.
+
+    Args:
+        page: Optional integer. Page number. Defaults to 1.
+        page_size: Optional integer. Page size. Defaults to 20.
+        filter_phone_number_starts_with: Optional. Filter numbers starting with pattern.
+        filter_phone_number_ends_with: Optional. Filter numbers ending with pattern.
+        filter_phone_number_contains: Optional. Filter numbers containing pattern.
+        filter_locality: Optional. Filter by locality (city).
+        filter_administrative_area: Optional. Filter by administrative area (state).
+        filter_country_code: Optional. Filter by country code.
+        filter_features: Optional. List of features to filter by.
+
+    Returns:
+        Dict[str, Any]: Response data
+    """
+    try:
+        service = get_authenticated_service(NumbersService)
+        filter_params = {
+            key: value
+            for key, value in request.items()
+            if key.startswith("filter_")
+        }
+        base_params = {
+            key: value
+            for key, value in request.items()
+            if not key.startswith("filter_")
+        }
+        return service.list_available_phone_numbers(
+            **base_params, **filter_params
+        )
+    except Exception as e:
+        logger.error(f"Error listing available phone numbers: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def initiate_phone_number_order(
+    request: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Initiate a phone number order.
+
+    Args:
+        phone_number: Required. Phone number to buy.
+        connection_id: Optional. Connection ID to associate with the number.
+
+    Returns:
+        Dict[str, Any]: Response data
+    """
+    try:
+        service = get_authenticated_service(NumbersService)
+        return service.buy_phone_number(**request)
+    except Exception as e:
+        logger.error(f"Error buying phone number: {e}")
+        raise handle_telnyx_error(e)
+
+
+@mcp.tool()
+async def update_phone_number_messaging_settings(
+    id: str, request: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Update the messaging profile and/or messaging product of a phone number.
+
+    Args:
+        id: Required. The phone number ID to update.
+        messaging_profile_id: Optional. Configure the messaging profile this phone number is assigned to. Set to null to keep the current value, set to empty string to unassign, or set to a UUID to assign to that messaging profile.
+        messaging_product: Optional. Configure the messaging product for this number. Set to null to keep the current value, or set to a product ID to change.
+
+    Returns:
+        Dict[str, Any]: Response data
+    """
+    try:
+        service = get_authenticated_service(NumbersService)
+        return service.update_phone_number_messaging_settings(id=id, **request)
+    except Exception as e:
+        logger.error(f"Error updating phone number messaging settings: {e}")
+        raise handle_telnyx_error(e)