temporal-mcp-server 0.1.0__py3-none-any.whl

temporal_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Temporal MCP Server package."""
+
+__version__ = "0.1.0"

temporal_mcp/__main__.py

@@ -0,0 +1,43 @@
+"""Entry point for Temporal MCP Server.
+
+Supports:
+  - `python -m temporal_mcp`
+  - `temporal-mcp-server` CLI (installed via pip)
+"""
+
+import asyncio
+import os
+import sys
+
+from temporal_mcp.server import TemporalMCPServer
+
+
+def main():
+    """Main entry point for the MCP server."""
+    temporal_host = os.environ.get("TEMPORAL_HOST", "localhost:7233")
+    namespace = os.environ.get("TEMPORAL_NAMESPACE", "default")
+
+    # Parse TLS setting: None (auto-detect), True (force enable), False (force disable)
+    tls_env = os.environ.get("TEMPORAL_TLS_ENABLED", "").lower()
+    if tls_env == "true":
+        tls_enabled = True
+    elif tls_env == "false":
+        tls_enabled = False
+    else:
+        tls_enabled = None  # Auto-detect
+
+    print(
+        f"Starting MCP server with TEMPORAL_HOST={temporal_host}, TLS={tls_enabled}",
+        file=sys.stderr,
+    )
+
+    server = TemporalMCPServer(
+        temporal_host=temporal_host,
+        namespace=namespace,
+        tls_enabled=tls_enabled,
+    )
+    asyncio.run(server.run())
+
+
+if __name__ == "__main__":
+    main()

temporal_mcp/client.py

@@ -0,0 +1,125 @@
+"""Temporal client management and connection handling."""
+
+import sys
+from typing import Optional
+
+from temporalio.client import Client, TLSConfig
+
+
+class TemporalClientManager:
+    """Manages connection to Temporal server."""
+    
+    def __init__(
+        self,
+        temporal_host: str = "localhost:7233",
+        namespace: str = "default",
+        tls_enabled: Optional[bool] = None
+    ):
+        """Initialize the Temporal client manager.
+        
+        Args:
+            temporal_host: The Temporal server host and port
+            namespace: The Temporal namespace to use
+            tls_enabled: Whether to use TLS for connection (None = auto-detect, True = force enable, False = force disable)
+        """
+        self.temporal_host = temporal_host
+        self.namespace = namespace
+        self.tls_enabled = tls_enabled
+        self.client: Optional[Client] = None
+    
+    async def connect(self) -> Client:
+        """Connect to Temporal server.
+        
+        Returns:
+            Connected Temporal client
+            
+        Raises:
+            Exception: If connection fails
+        """
+        if not self.client:
+            tls_config = self._determine_tls_config()
+            
+            self._log_connection_info(tls_config)
+            
+            try:
+                self.client = await Client.connect(
+                    self.temporal_host,
+                    namespace=self.namespace,
+                    tls=tls_config,
+                )
+                print(f"Successfully connected to Temporal at {self.temporal_host}", file=sys.stderr)
+            except Exception as e:
+                print(f"Failed to connect to Temporal at {self.temporal_host}: {type(e).__name__}: {e}", file=sys.stderr)
+                import traceback
+                traceback.print_exc(file=sys.stderr)
+                raise
+        
+        return self.client
+    
+    async def disconnect(self):
+        """Disconnect from Temporal server."""
+        if self.client:
+            try:
+                await self.client.close()
+            except Exception as e:
+                print(f"Error closing Temporal client: {e}", file=sys.stderr)
+            finally:
+                self.client = None
+    
+    def ensure_connected(self) -> Client:
+        """Ensure client is connected.
+        
+        Returns:
+            The connected client
+            
+        Raises:
+            RuntimeError: If not connected
+        """
+        if not self.client:
+            raise RuntimeError("Not connected to Temporal server. Connection may have failed or been lost.")
+        return self.client
+    
+    def _determine_tls_config(self) -> Optional[TLSConfig]:
+        """Determine TLS configuration based on settings and hostname.
+        
+        Returns:
+            TLS configuration or None
+        """
+        # Priority: explicit tls_enabled setting > auto-detect from hostname
+        if self.tls_enabled is True:
+            return TLSConfig()
+        elif self.tls_enabled is False:
+            return None
+        elif self._is_remote_host():
+            # Auto-detect: enable TLS for remote connections
+            return TLSConfig()
+        else:
+            # Auto-detect: disable TLS for local connections
+            return None
+    
+    def _is_remote_host(self) -> bool:
+        """Check if the host is a remote (non-local) host.
+        
+        Returns:
+            True if host is remote, False if local
+        """
+        local_hosts = ["localhost", "127.0.0.1", "host.docker.internal"]
+        return not any(local_host in self.temporal_host for local_host in local_hosts)
+    
+    def _log_connection_info(self, tls_config: Optional[TLSConfig]):
+        """Log connection information for debugging.
+        
+        Args:
+            tls_config: The TLS configuration being used
+        """
+        if self.tls_enabled is True:
+            print(f"Connecting to {self.temporal_host} with TLS enabled (explicit)", file=sys.stderr)
+        elif self.tls_enabled is False:
+            print(f"Connecting to {self.temporal_host} without TLS (explicit)", file=sys.stderr)
+        elif tls_config is not None:
+            print(f"Connecting to {self.temporal_host} with TLS enabled (auto-detected for remote host)", file=sys.stderr)
+        else:
+            print(f"Connecting to {self.temporal_host} without TLS (auto-detected for local host)", file=sys.stderr)
+        
+        print(f"Namespace: {self.namespace}", file=sys.stderr)
+        print(f"TLS Enabled: {tls_config is not None}", file=sys.stderr)

temporal_mcp/handlers/__init__.py

@@ -0,0 +1 @@
+"""Handler modules for Temporal operations."""

temporal_mcp/handlers/batch_handlers.py

@@ -0,0 +1,250 @@
+"""Handlers for batch workflow operations."""
+
+import json
+import sys
+from typing import Any
+
+from mcp.types import TextContent
+from temporalio.client import Client
+
+
+async def batch_signal(client: Client, args: dict) -> list[TextContent]:
+    """Send signal to multiple workflows.
+    
+    Args:
+        client: Connected Temporal client
+        args: Arguments containing query, signal_name, optional args, and optional limit
+        
+    Returns:
+        Batch operation results with success and error counts
+    """
+    query = args["query"]
+    signal_name = args["signal_name"]
+    signal_args = args.get("args")
+    limit = args.get("limit", 100)
+
+    workflows_signaled = []
+    errors = []
+    
+    async for workflow in client.list_workflows(query):
+        if len(workflows_signaled) + len(errors) >= limit:
+            break
+        
+        try:
+            handle = client.get_workflow_handle(workflow.id)
+            await handle.signal(signal_name, signal_args)
+            workflows_signaled.append(workflow.id)
+        except Exception as e:
+            error_detail = {
+                "workflow_id": workflow.id,
+                "error": str(e),
+                "error_type": type(e).__name__
+            }
+            errors.append(error_detail)
+            print(f"Error signaling workflow {workflow.id}: {e}", file=sys.stderr)
+    
+    result = {
+        "signal_name": signal_name,
+        "workflows_signaled": workflows_signaled,
+        "success_count": len(workflows_signaled),
+        "error_count": len(errors)
+    }
+    
+    if errors:
+        result["errors"] = errors
+    
+    return [TextContent(type="text", text=json.dumps(result, indent=2))]
+
+
+async def batch_cancel(client: Client, args: dict) -> list[TextContent]:
+    """Cancel multiple workflows with concurrent processing.
+    
+    Args:
+        client: Connected Temporal client
+        args: Arguments containing query and optional limit, concurrency
+        
+    Returns:
+        Batch operation results with success and error counts
+    """
+    import asyncio
+    
+    query = args["query"]
+    limit = args.get("limit", 100)
+    concurrency = args.get("concurrency", 50)  # Process 50 workflows concurrently
+    
+    print(f"Starting batch cancel with limit={limit}, concurrency={concurrency}", file=sys.stderr)
+
+    workflows_cancelled = []
+    errors = []
+    
+    async def cancel_workflow(workflow_id: str) -> tuple[str, Exception | None]:
+        """Cancel a single workflow and return result."""
+        try:
+            handle = client.get_workflow_handle(workflow_id)
+            await handle.cancel()
+            return workflow_id, None
+        except Exception as e:
+            return workflow_id, e
+    
+    # Collect workflows to cancel
+    workflows_to_cancel = []
+    async for workflow in client.list_workflows(query):
+        workflows_to_cancel.append(workflow.id)
+        if len(workflows_to_cancel) >= limit:
+            break
+    
+    total = len(workflows_to_cancel)
+    print(f"Found {total} workflows to cancel. Starting cancellation...", file=sys.stderr)
+    
+    # Process in batches for concurrency
+    for i in range(0, len(workflows_to_cancel), concurrency):
+        batch = workflows_to_cancel[i:i + concurrency]
+        batch_num = i // concurrency + 1
+        total_batches = (len(workflows_to_cancel) + concurrency - 1) // concurrency
+        
+        print(f"Processing batch {batch_num}/{total_batches} ({len(batch)} workflows)...", file=sys.stderr)
+        
+        # Cancel workflows concurrently in this batch
+        results = await asyncio.gather(
+            *[cancel_workflow(wf_id) for wf_id in batch],
+            return_exceptions=False
+        )
+        
+        # Process results
+        for workflow_id, error in results:
+            if error is None:
+                workflows_cancelled.append(workflow_id)
+            else:
+                error_detail = {
+                    "workflow_id": workflow_id,
+                    "error": str(error),
+                    "error_type": type(error).__name__
+                }
+                errors.append(error_detail)
+                print(f"Error cancelling workflow {workflow_id}: {error}", file=sys.stderr)
+        
+        print(f"Batch {batch_num}/{total_batches} complete. Total cancelled: {len(workflows_cancelled)}, errors: {len(errors)}", file=sys.stderr)
+    
+    print(f"Batch cancel complete! Cancelled: {len(workflows_cancelled)}, Errors: {len(errors)}", file=sys.stderr)
+    
+    # Return only summary to avoid context overflow - do NOT include full list of IDs
+    result = {
+        "success_count": len(workflows_cancelled),
+        "error_count": len(errors),
+        "total_processed": len(workflows_cancelled) + len(errors),
+        "message": f"Successfully cancelled {len(workflows_cancelled)} workflows."
+    }
+    
+    # Include first and last few IDs as samples only
+    if len(workflows_cancelled) > 0:
+        if len(workflows_cancelled) <= 10:
+            result["cancelled_workflows"] = workflows_cancelled
+        else:
+            result["sample_first"] = workflows_cancelled[:5]
+            result["sample_last"] = workflows_cancelled[-5:]
+            result["note"] = f"Showing first 5 and last 5 of {len(workflows_cancelled)} cancelled workflows to avoid context overflow"
+    
+    if errors:
+        result["sample_errors"] = errors[:5]  # Only show first 5 errors
+        if len(errors) > 5:
+            result["errors_note"] = f"Showing first 5 of {len(errors)} errors"
+    
+    return [TextContent(type="text", text=json.dumps(result, indent=2))]
+
+
+async def batch_terminate(client: Client, args: dict) -> list[TextContent]:
+    """Terminate multiple workflows with concurrent processing.
+    
+    Args:
+        client: Connected Temporal client
+        args: Arguments containing query, optional reason, limit, and concurrency
+        
+    Returns:
+        Batch operation results with success and error counts
+    """
+    import asyncio
+    
+    query = args["query"]
+    reason = args.get("reason", "Batch termination via MCP")
+    limit = args.get("limit", 100)
+    concurrency = args.get("concurrency", 50)  # Process 50 workflows concurrently
+    
+    print(f"Starting batch terminate with limit={limit}, concurrency={concurrency}", file=sys.stderr)
+
+    workflows_terminated = []
+    errors = []
+    
+    async def terminate_workflow(workflow_id: str) -> tuple[str, Exception | None]:
+        """Terminate a single workflow and return result."""
+        try:
+            handle = client.get_workflow_handle(workflow_id)
+            await handle.terminate(reason)
+            return workflow_id, None
+        except Exception as e:
+            return workflow_id, e
+    
+    # Collect workflows to terminate
+    workflows_to_terminate = []
+    async for workflow in client.list_workflows(query):
+        workflows_to_terminate.append(workflow.id)
+        if len(workflows_to_terminate) >= limit:
+            break
+    
+    total = len(workflows_to_terminate)
+    print(f"Found {total} workflows to terminate. Starting termination...", file=sys.stderr)
+    
+    # Process in batches for concurrency
+    for i in range(0, len(workflows_to_terminate), concurrency):
+        batch = workflows_to_terminate[i:i + concurrency]
+        batch_num = i // concurrency + 1
+        total_batches = (len(workflows_to_terminate) + concurrency - 1) // concurrency
+        
+        print(f"Processing batch {batch_num}/{total_batches} ({len(batch)} workflows)...", file=sys.stderr)
+        
+        # Terminate workflows concurrently in this batch
+        results = await asyncio.gather(
+            *[terminate_workflow(wf_id) for wf_id in batch],
+            return_exceptions=False
+        )
+        
+        # Process results
+        for workflow_id, error in results:
+            if error is None:
+                workflows_terminated.append(workflow_id)
+            else:
+                error_detail = {
+                    "workflow_id": workflow_id,
+                    "error": str(error),
+                    "error_type": type(error).__name__
+                }
+                errors.append(error_detail)
+                print(f"Error terminating workflow {workflow_id}: {error}", file=sys.stderr)
+        
+        print(f"Batch {batch_num}/{total_batches} complete. Total terminated: {len(workflows_terminated)}, errors: {len(errors)}", file=sys.stderr)
+    
+    print(f"Batch terminate complete! Terminated: {len(workflows_terminated)}, Errors: {len(errors)}", file=sys.stderr)
+    
+    # Return only summary to avoid context overflow - do NOT include full list of IDs
+    result = {
+        "reason": reason,
+        "success_count": len(workflows_terminated),
+        "error_count": len(errors),
+        "total_processed": len(workflows_terminated) + len(errors),
+        "message": f"Successfully terminated {len(workflows_terminated)} workflows."
+    }
+    
+    # Include first and last few IDs as samples only
+    if len(workflows_terminated) > 0:
+        if len(workflows_terminated) <= 10:
+            result["terminated_workflows"] = workflows_terminated
+        else:
+            result["sample_first"] = workflows_terminated[:5]
+            result["sample_last"] = workflows_terminated[-5:]
+            result["note"] = f"Showing first 5 and last 5 of {len(workflows_terminated)} terminated workflows to avoid context overflow"
+    
+    if errors:
+        result["sample_errors"] = errors[:5]  # Only show first 5 errors
+        if len(errors) > 5:
+            result["errors_note"] = f"Showing first 5 of {len(errors)} errors"
+    
+    return [TextContent(type="text", text=json.dumps(result, indent=2))]

temporal_mcp/handlers/query_handlers.py

@@ -0,0 +1,88 @@
+"""Handlers for workflow query and signal operations."""
+
+import json
+from typing import Any
+
+from mcp.types import TextContent
+from temporalio.client import Client
+
+
+async def query_workflow(client: Client, args: dict) -> list[TextContent]:
+    """Query a workflow execution.
+    
+    Args:
+        client: Connected Temporal client
+        args: Arguments containing workflow_id, query_name, and optional args
+        
+    Returns:
+        Query result
+    """
+    workflow_id = args["workflow_id"]
+    query_name = args["query_name"]
+    query_args = args.get("args")
+
+    handle = client.get_workflow_handle(workflow_id)
+    result = await handle.query(query_name, query_args)
+    
+    return [TextContent(
+        type="text",
+        text=json.dumps({"query_result": result}, indent=2, default=str)
+    )]
+
+
+async def signal_workflow(client: Client, args: dict) -> list[TextContent]:
+    """Send a signal to a workflow.
+    
+    Args:
+        client: Connected Temporal client
+        args: Arguments containing workflow_id, signal_name, and optional args
+        
+    Returns:
+        Success response
+    """
+    workflow_id = args["workflow_id"]
+    signal_name = args["signal_name"]
+    signal_args = args.get("args")
+
+    handle = client.get_workflow_handle(workflow_id)
+    await handle.signal(signal_name, signal_args)
+    
+    return [TextContent(
+        type="text",
+        text=json.dumps({
+            "status": "signal_sent",
+            "workflow_id": workflow_id,
+            "signal_name": signal_name
+        }, indent=2)
+    )]
+
+
+async def continue_as_new(client: Client, args: dict) -> list[TextContent]:
+    """Signal a workflow to continue as new.
+    
+    Note: This sends a signal to the workflow. The workflow itself must be
+    designed to call workflow.continue_as_new() when it receives this signal.
+    
+    Args:
+        client: Connected Temporal client
+        args: Arguments containing workflow_id, signal_name, and optional signal_args
+        
+    Returns:
+        Success response
+    """
+    workflow_id = args["workflow_id"]
+    signal_name = args["signal_name"]
+    signal_args = args.get("signal_args", {})
+    
+    handle = client.get_workflow_handle(workflow_id)
+    await handle.signal(signal_name, signal_args)
+    
+    return [TextContent(
+        type="text",
+        text=json.dumps({
+            "status": "signal_sent",
+            "workflow_id": workflow_id,
+            "signal_name": signal_name,
+            "note": "Workflow must implement continue-as-new logic in signal handler"
+        }, indent=2)
+    )]