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

telnyx_mcp_server/__main__.py

@@ -0,0 +1,23 @@
+"""Main entry point for the Telnyx MCP server."""
+
+import logging
+import os
+import sys
+
+# Set up logging before importing anything else
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger("telnyx-mcp")
+
+# Check for API key
+if not os.getenv("TELNYX_API_KEY"):
+    logger.critical("TELNYX_API_KEY environment variable not set")
+    sys.exit(1)
+
+# Import server only after checking for API key
+from .server import run_server
+
+if __name__ == "__main__":
+    run_server()

telnyx_mcp_server/config.py

@@ -0,0 +1,148 @@
+"""Configuration management for the Telnyx MCP server."""
+
+import os
+import random
+import socket
+from typing import Literal, Optional
+
+from dotenv import load_dotenv
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+# Generate a random port number in the dynamic/private port range
+def get_random_high_port() -> int:
+    """
+    Generate a random port number in the higher end of the dynamic/private port range.
+
+    Returns:
+        int: A random port number between 50000 and 65000
+    """
+    return random.randint(50000, 65000)
+
+
+def is_unix_socket_supported() -> bool:
+    """
+    Check if the system supports Unix domain sockets.
+
+    Returns:
+        bool: True if Unix domain sockets are supported, False otherwise
+    """
+    # On Unix-like systems, we can use os.name to check
+    if os.name != "posix":
+        return False
+
+    # Further check by trying to create a Unix domain socket
+    try:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        # Clean up the socket
+        sock.close()
+        return True
+    except (AttributeError, OSError):
+        return False
+
+
+# Determine API base URL based on environment
+def get_api_base_url() -> str:
+    """
+    Return the Telnyx API base URL.
+
+    Returns:
+        str: The Telnyx API base URL
+            - Value of TELNYX_API_BASE environment variable if set
+            - https://api.telnyx.com/v2 otherwise
+    """
+    telnyx_api_base = os.getenv("TELNYX_API_BASE")
+    if telnyx_api_base:
+        return telnyx_api_base
+    return "https://api.telnyx.com/v2"
+
+
+class Settings(BaseSettings):
+    """Server settings."""
+
+    # Telnyx API settings
+    telnyx_api_key: str = Field(
+        default=os.getenv("TELNYX_API_KEY", ""),
+        description="Telnyx API key for authentication",
+    )
+    telnyx_api_base_url: str = Field(
+        default=get_api_base_url(),
+        description="Base URL for Telnyx API",
+    )
+
+    # Server settings
+    host: str = Field(
+        default="0.0.0.0", description="Host to bind the server to"
+    )
+    port: int = Field(default=8000, description="Port to bind the server to")
+    debug: bool = Field(default=False, description="Enable debug mode")
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = (
+        Field(default="INFO", description="Logging level")
+    )
+
+    # Webhook settings
+    webhook_enabled: bool = Field(
+        default=False, description="Enable webhook receiver"
+    )
+    webhook_port: int = Field(
+        default=get_random_high_port(),
+        description="Port to bind the webhook server to (random high port to avoid conflicts)",
+    )
+    webhook_path: str = Field(
+        default="/webhooks", description="Path for webhook endpoint"
+    )
+    webhook_max_body_size: int = Field(
+        default=1_048_576,  # 1 MB
+        description="Maximum webhook request body size in bytes",
+    )
+    use_unix_socket: bool = Field(
+        default=is_unix_socket_supported(),
+        description="Use Unix domain socket instead of TCP/IP port (Unix-like systems only)",
+    )
+    socket_dir: Optional[str] = Field(
+        default=None,
+        description="Directory for Unix domain socket (default: system temp directory)",
+    )
+
+    # Ngrok settings
+    ngrok_enabled: bool = Field(
+        default=bool(os.getenv("NGROK_AUTHTOKEN", ""))
+        or bool(os.getenv("NGROK_URL", "")),
+        description="Enable ngrok tunnel for webhooks",
+    )
+    ngrok_authtoken: Optional[str] = Field(
+        default=os.getenv("NGROK_AUTHTOKEN", None),
+        description="Ngrok authentication token",
+    )
+
+    ngrok_url: Optional[str] = Field(
+        default=os.getenv("NGROK_URL", None),
+        description="NGROK custom domain - Experimental - TLS errors are possible.",
+    )
+
+    # MCP settings
+    warn_on_duplicate_resources: bool = Field(
+        default=True, description="Warn on duplicate resources"
+    )
+    warn_on_duplicate_tools: bool = Field(
+        default=True, description="Warn on duplicate tools"
+    )
+    warn_on_duplicate_prompts: bool = Field(
+        default=True, description="Warn on duplicate prompts"
+    )
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+        extra="ignore",
+        validate_default=True,
+    )
+
+
+# Create a global settings instance
+settings = Settings()

telnyx_mcp_server/mcp.py

@@ -0,0 +1,148 @@
+"""Simple MCP server using FastMCP framework with STDIO transport."""
+
+import os
+from typing import (  # Added Sequence
+    Any,
+    Dict,
+    List,
+    Optional,
+    Sequence,
+)
+
+from dotenv import load_dotenv
+from fastmcp import FastMCP
+
+# MCPTool is defined in mcp.types, but often exposed via fastmcp or mcp.server
+# For clarity, let's try importing directly if fastmcp doesn't re-export it well.
+try:
+    from fastmcp import MCPTool
+except ImportError:
+    from mcp.types import (
+        Tool as MCPTool,  # Fallback if not in fastmcp directly
+    )
+
+from mcp.types import EmbeddedResource, ImageContent, TextContent
+
+from .telnyx.client import TelnyxClient  # Assuming this path is correct
+from .utils.logger import get_logger  # Assuming this path is correct
+
+logger = get_logger(__name__)
+
+# Load environment variables
+load_dotenv()
+
+# Get API key from environment
+api_key = os.getenv("TELNYX_API_KEY", "")
+if not api_key:
+    logger.error("TELNYX_API_KEY environment variable must be set")
+    raise ValueError("TELNYX_API_KEY environment variable must be set")
+
+
+class FilterableFastMCP(FastMCP):
+    """Extended FastMCP class that supports tool filtering."""
+
+    def __init__(self, *args, **kwargs):
+        # Call super().__init__() first. This will run FastMCP's _setup_handlers,
+        # which will register self.list_tools and self.call_tool (from this FilterableFastMCP class)
+        super().__init__(*args, **kwargs)
+
+        self._enabled_tools: Optional[List[str]] = None
+        self._excluded_tools: List[str] = []
+        # Note: The original _original_list_tools_handler and _filtered_list_tools etc. are removed
+        # as the filtering is now done by overriding list_tools and call_tool directly.
+
+    def set_enabled_tools(self, tool_names: List[str]) -> None:
+        """
+        Set specific tools to enable. All other tools will be disabled.
+
+        Args:
+            tool_names: List of tool names to enable
+        """
+        self._enabled_tools = tool_names
+        logger.info(
+            f"Tool filtering enabled. Available tools: {', '.join(tool_names)}"
+        )
+
+    def set_excluded_tools(self, tool_names: List[str]) -> None:
+        """
+        Set specific tools to exclude. All other tools will remain enabled.
+
+        Args:
+            tool_names: List of tool names to exclude
+        """
+        self._excluded_tools = tool_names
+        logger.info(
+            f"Tool exclusion enabled. Excluded tools: {', '.join(tool_names)}"
+        )
+
+    async def list_tools(
+        self,
+    ) -> list[MCPTool]:  # Matches signature from FastMCP
+        """Filter the list of tools based on enabled/excluded settings."""
+        all_mcp_tools = (
+            await super().list_tools()
+        )  # Get all tools as defined by FastMCP
+
+        # If no filtering is configured, return all tools
+        if self._enabled_tools is None and not self._excluded_tools:
+            return all_mcp_tools
+
+        filtered_mcp_tools = []
+        for tool_spec in all_mcp_tools:
+            # MCPTool has a 'name' attribute according to MCP spec and fastmcp usage
+            tool_name = tool_spec.name
+
+            # Check if tool should be included
+            if (
+                self._enabled_tools is not None
+                and tool_name not in self._enabled_tools
+            ):
+                logger.debug(
+                    f"Filtering out tool: {tool_name} (not in enabled list)"
+                )
+                continue
+
+            # Check if tool should be excluded
+            if tool_name in self._excluded_tools:
+                logger.debug(
+                    f"Filtering out tool: {tool_name} (in excluded list)"
+                )
+                continue
+
+            filtered_mcp_tools.append(tool_spec)
+
+        # This logging can be verbose if many tools, consider conditional logging or removing
+        # logger.info(f"Filtered tools from {len(all_mcp_tools)} to {len(filtered_mcp_tools)}")
+        return filtered_mcp_tools
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: Dict[str, Any],  # 'name' instead of 'key' to match FastMCP
+    ) -> Sequence[
+        TextContent | ImageContent | EmbeddedResource
+    ]:  # Matches signature
+        """Filter tool calls based on enabled/excluded settings."""
+        # Check if tool is allowed
+        if self._enabled_tools is not None and name not in self._enabled_tools:
+            logger.warning(f"Attempted to call disabled tool: '{name}'")
+            # Consider raising a specific MCP error type if available/appropriate
+            raise ValueError(f"Tool '{name}' is not enabled")
+
+        if name in self._excluded_tools:
+            logger.warning(f"Attempted to call excluded tool: '{name}'")
+            raise ValueError(f"Tool '{name}' is excluded")
+
+        try:
+            # Call the original FastMCP behavior to execute the tool
+            return await super().call_tool(name, arguments)
+        except Exception as e:
+            logger.error(f"Error calling tool '{name}': {str(e)}")
+            raise
+
+
+# Create a single shared MCP instance with filtering support
+mcp = FilterableFastMCP("Telnyx MCP")
+
+# Initialize Telnyx client with API key from environment
+telnyx_client = TelnyxClient(api_key=api_key)