edda-framework 0.2.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

edda/integrations/__init__.py

@@ -0,0 +1 @@
+"""Edda integrations package."""

edda/integrations/mcp/__init__.py

@@ -0,0 +1,40 @@
+"""
+Edda MCP (Model Context Protocol) Integration.
+
+Provides MCP server functionality for Edda durable workflows,
+enabling long-running workflow tools via the MCP protocol.
+
+Example:
+    ```python
+    from edda.integrations.mcp import EddaMCPServer
+    from edda import WorkflowContext, activity
+
+    server = EddaMCPServer(
+        name="Order Service",
+        db_url="postgresql://user:pass@localhost/orders",
+    )
+
+    @activity
+    async def reserve_inventory(ctx, items):
+        return {"reserved": True}
+
+    @server.durable_tool(description="Process order workflow")
+    async def process_order(ctx: WorkflowContext, order_id: str):
+        await reserve_inventory(ctx, [order_id], activity_id="reserve:1")
+        return {"status": "completed"}
+
+    # Deploy with uvicorn
+    if __name__ == "__main__":
+        import uvicorn
+        uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
+    ```
+
+The server automatically generates three MCP tools for each @durable_tool:
+- `tool_name`: Start the workflow, returns instance_id
+- `tool_name_status`: Check workflow status
+- `tool_name_result`: Get workflow result (if completed)
+"""
+
+from edda.integrations.mcp.server import EddaMCPServer
+
+__all__ = ["EddaMCPServer"]

edda/integrations/mcp/decorators.py

@@ -0,0 +1,188 @@
+"""Decorators for MCP durable tools."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, cast
+
+from edda.workflow import workflow
+
+if TYPE_CHECKING:
+    from edda.integrations.mcp.server import EddaMCPServer
+    from edda.workflow import Workflow
+
+
+def create_durable_tool(
+    server: EddaMCPServer,
+    func: Callable[..., Any],
+    *,
+    description: str = "",
+) -> Workflow:
+    """
+    Create a durable workflow tool with auto-generated status/result tools.
+
+    This function:
+    1. Wraps the function as an Edda @workflow
+    2. Registers three MCP tools:
+       - {name}: Start workflow, return instance_id
+       - {name}_status: Check workflow status
+       - {name}_result: Get workflow result
+
+    Args:
+        server: EddaMCPServer instance
+        func: Async workflow function
+        description: Tool description
+
+    Returns:
+        Workflow instance
+    """
+    # 1. Create Edda workflow
+    workflow_instance = cast(Workflow, workflow(func, event_handler=False))
+    workflow_name = func.__name__
+
+    # Register in server's workflow registry
+    server._workflows[workflow_name] = workflow_instance
+
+    # 2. Generate main tool (start workflow)
+    tool_description = description or func.__doc__ or f"Start {workflow_name} workflow"
+
+    # Extract parameters from workflow function (excluding ctx)
+    sig = inspect.signature(func)
+    params = [
+        param
+        for name, param in sig.parameters.items()
+        if name != "ctx"  # Exclude WorkflowContext parameter
+    ]
+
+    # Create the tool function
+    async def start_tool(**kwargs: Any) -> dict[str, Any]:
+        """
+        Start workflow and return instance_id.
+
+        This is the main entry point for the durable tool.
+        """
+        # Remove 'ctx' if provided by client (workflow will inject it)
+        kwargs.pop("ctx", None)
+
+        # Start Edda workflow
+        instance_id = await workflow_instance.start(**kwargs)
+
+        # Return MCP-compliant response
+        return {
+            "content": [
+                {
+                    "type": "text",
+                    "text": (
+                        f"Workflow '{workflow_name}' started successfully.\n"
+                        f"Instance ID: {instance_id}\n\n"
+                        f"Use '{workflow_name}_status' tool with instance_id='{instance_id}' to check progress.\n"
+                        f"Use '{workflow_name}_result' tool to get the final result once completed."
+                    ),
+                }
+            ],
+            "isError": False,
+        }
+
+    # Override the function's signature for introspection (FastMCP uses this for schema generation)
+    start_tool.__signature__ = inspect.Signature(parameters=params)  # type: ignore[attr-defined]
+
+    # Register with FastMCP (call as function, not decorator syntax)
+    server._mcp.tool(name=workflow_name, description=tool_description)(start_tool)
+
+    # 3. Generate status tool
+    status_tool_name = f"{workflow_name}_status"
+    status_tool_description = f"Check status of {workflow_name} workflow"
+
+    @server._mcp.tool(name=status_tool_name, description=status_tool_description)  # type: ignore[misc]
+    async def status_tool(instance_id: str) -> dict[str, Any]:
+        """Check workflow status."""
+        try:
+            instance = await server._edda_app.storage.get_instance(instance_id)
+            if instance is None:
+                return {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": f"Workflow instance not found: {instance_id}",
+                        }
+                    ],
+                    "isError": True,
+                }
+
+            status = instance["status"]
+            current_activity_id = instance.get("current_activity_id", "N/A")
+
+            status_text = (
+                f"Workflow Status: {status}\n"
+                f"Current Activity: {current_activity_id}\n"
+                f"Instance ID: {instance_id}"
+            )
+
+            return {
+                "content": [{"type": "text", "text": status_text}],
+                "isError": False,
+            }
+        except Exception as e:
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Error checking status: {str(e)}",
+                    }
+                ],
+                "isError": True,
+            }
+
+    # 4. Generate result tool
+    result_tool_name = f"{workflow_name}_result"
+    result_tool_description = f"Get result of {workflow_name} workflow (if completed)"
+
+    @server._mcp.tool(name=result_tool_name, description=result_tool_description)  # type: ignore[misc]
+    async def result_tool(instance_id: str) -> dict[str, Any]:
+        """Get workflow result (if completed)."""
+        try:
+            instance = await server._edda_app.storage.get_instance(instance_id)
+            if instance is None:
+                return {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": f"Workflow instance not found: {instance_id}",
+                        }
+                    ],
+                    "isError": True,
+                }
+
+            status = instance["status"]
+
+            if status != "completed":
+                return {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": f"Workflow not completed yet. Current status: {status}",
+                        }
+                    ],
+                    "isError": True,
+                }
+
+            output_data = instance.get("output_data")
+            result_text = f"Workflow Result:\n{output_data}"
+
+            return {
+                "content": [{"type": "text", "text": result_text}],
+                "isError": False,
+            }
+        except Exception as e:
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Error getting result: {str(e)}",
+                    }
+                ],
+                "isError": True,
+            }
+
+    return workflow_instance

edda/integrations/mcp/server.py

@@ -0,0 +1,261 @@
+"""MCP Server implementation for Edda workflows."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, cast
+
+from edda.app import EddaApp
+from edda.workflow import Workflow
+
+try:
+    from mcp.server.fastmcp import FastMCP  # type: ignore[import-not-found]
+except ImportError as e:
+    raise ImportError(
+        "MCP Python SDK is required for MCP integration. "
+        "Install it with: pip install edda-framework[mcp]"
+    ) from e
+
+
+class EddaMCPServer:
+    """
+    MCP (Model Context Protocol) server for Edda durable workflows.
+
+    Integrates EddaApp (CloudEvents + Workflows) with FastMCP to provide
+    long-running workflow tools via the MCP protocol.
+
+    Example:
+        ```python
+        from edda.integrations.mcp import EddaMCPServer
+        from edda import WorkflowContext, activity
+
+        server = EddaMCPServer(
+            name="Order Service",
+            db_url="postgresql://user:pass@localhost/orders",
+        )
+
+        @activity
+        async def reserve_inventory(ctx, items):
+            return {"reserved": True}
+
+        @server.durable_tool(description="Process order workflow")
+        async def process_order(ctx: WorkflowContext, order_id: str):
+            await reserve_inventory(ctx, [order_id], activity_id="reserve:1")
+            return {"status": "completed"}
+
+        # Deploy with uvicorn (HTTP transport)
+        if __name__ == "__main__":
+            import uvicorn
+            uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
+
+        # Or deploy with stdio (for MCP clients, e.g., Claude Desktop)
+        if __name__ == "__main__":
+            import asyncio
+
+            async def main():
+                await server.initialize()
+                await server.run_stdio()
+
+            asyncio.run(main())
+        ```
+
+    The server automatically generates three MCP tools for each @durable_tool:
+    - `tool_name`: Start the workflow, returns instance_id
+    - `tool_name_status`: Check workflow status
+    - `tool_name_result`: Get workflow result (if completed)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        db_url: str,
+        *,
+        outbox_enabled: bool = False,
+        broker_url: str | None = None,
+        token_verifier: Callable[[str], bool] | None = None,
+    ):
+        """
+        Initialize MCP server.
+
+        Args:
+            name: Service name (shown in MCP client)
+            db_url: Database URL for workflow storage
+            outbox_enabled: Enable transactional outbox pattern
+            broker_url: Message broker URL (if outbox enabled)
+            token_verifier: Optional function to verify authentication tokens
+        """
+        self._name = name
+        self._edda_app = EddaApp(
+            service_name=name,
+            db_url=db_url,
+            outbox_enabled=outbox_enabled,
+            broker_url=broker_url or "",
+        )
+        self._mcp = FastMCP(name, json_response=True, stateless_http=True)
+        self._token_verifier = token_verifier
+
+        # Registry of durable tools (workflow_name -> Workflow instance)
+        self._workflows: dict[str, Workflow] = {}
+
+    def durable_tool(
+        self,
+        func: Callable[..., Any] | None = None,
+        *,
+        description: str = "",
+    ) -> Callable[..., Any]:
+        """
+        Decorator to define a durable workflow tool.
+
+        Automatically generates three MCP tools:
+        1. Main tool: Starts the workflow, returns instance_id
+        2. Status tool: Checks workflow status
+        3. Result tool: Gets workflow result (if completed)
+
+        Args:
+            func: Workflow function (async)
+            description: Tool description for MCP clients
+
+        Returns:
+            Decorated workflow instance
+
+        Example:
+            ```python
+            @server.durable_tool(description="Long-running order processing")
+            async def process_order(ctx, order_id: str):
+                # Workflow logic
+                return {"status": "completed"}
+            ```
+        """
+        from edda.integrations.mcp.decorators import create_durable_tool
+
+        def decorator(f: Callable[..., Any]) -> Workflow:
+            return create_durable_tool(self, f, description=description)
+
+        if func is None:
+            return decorator
+        return decorator(func)
+
+    def asgi_app(self) -> Callable[..., Any]:
+        """
+        Create ASGI application with MCP + CloudEvents support.
+
+        This method uses the Issue #1367 workaround: instead of using Mount,
+        we get the MCP's Starlette app directly and add Edda endpoints to it.
+
+        Routing:
+        - POST /    -> FastMCP (MCP tools via streamable HTTP)
+        - POST /cancel/{instance_id} -> Workflow cancellation
+        - Other POST -> CloudEvents
+
+        Returns:
+            ASGI callable (Starlette app)
+        """
+        from starlette.requests import Request  # type: ignore[import-not-found]
+        from starlette.responses import Response  # type: ignore[import-not-found]
+
+        # Get MCP's Starlette app (Issue #1367 workaround: use directly)
+        app = self._mcp.streamable_http_app()
+
+        # Add Edda endpoints to Starlette router BEFORE wrapping with middleware
+        # Note: MCP's streamable HTTP is already mounted at "/" by default
+        # We add additional routes for Edda's CloudEvents and cancellation
+
+        async def edda_cancel_handler(request: Request) -> Response:
+            """Handle workflow cancellation."""
+            instance_id = request.path_params["instance_id"]
+
+            # Create ASGI scope for EddaApp
+            scope = dict(request.scope)
+            scope["path"] = f"/cancel/{instance_id}"
+
+            # Capture response
+            response_data: dict[str, Any] = {"status": 200, "headers": [], "body": b""}
+
+            async def send(message: dict[str, Any]) -> None:
+                if message["type"] == "http.response.start":
+                    response_data["status"] = message["status"]
+                    response_data["headers"] = message.get("headers", [])
+                elif message["type"] == "http.response.body":
+                    response_data["body"] += message.get("body", b"")
+
+            # Forward to EddaApp
+            await self._edda_app(scope, request.receive, send)
+
+            # Return response
+            return Response(
+                content=response_data["body"],
+                status_code=response_data["status"],
+                headers=cast(dict[str, str], dict(response_data["headers"])),
+            )
+
+        # Add cancel route
+        app.router.add_route("/cancel/{instance_id}", edda_cancel_handler, methods=["POST"])
+
+        # Add authentication middleware if token_verifier provided (AFTER adding routes)
+        if self._token_verifier is not None:
+            from starlette.middleware.base import (  # type: ignore[import-not-found]
+                BaseHTTPMiddleware,
+            )
+
+            class AuthMiddleware(BaseHTTPMiddleware):  # type: ignore[misc]
+                def __init__(self, app: Any, token_verifier: Callable[[str], bool]):
+                    super().__init__(app)
+                    self.token_verifier = token_verifier
+
+                async def dispatch(
+                    self, request: Request, call_next: Callable[..., Any]
+                ) -> Response:
+                    auth_header = request.headers.get("authorization", "")
+                    if auth_header.startswith("Bearer "):
+                        token = auth_header[7:]
+                        if not self.token_verifier(token):
+                            return Response("Unauthorized", status_code=401)
+                    return await call_next(request)
+
+            # Wrap app with auth middleware
+            app = AuthMiddleware(app, self._token_verifier)
+
+        return cast(Callable[..., Any], app)
+
+    async def initialize(self) -> None:
+        """
+        Initialize the EddaApp (setup replay engine, storage, etc.).
+
+        This method must be called before running the server in stdio mode.
+        For HTTP mode (asgi_app()), initialization happens automatically
+        when the ASGI app is deployed.
+
+        Example:
+            ```python
+            async def main():
+                await server.initialize()
+                await server.run_stdio()
+
+            if __name__ == "__main__":
+                import asyncio
+                asyncio.run(main())
+            ```
+        """
+        await self._edda_app.initialize()
+
+    async def run_stdio(self) -> None:
+        """
+        Run MCP server with stdio transport (for MCP clients, e.g., Claude Desktop).
+
+        This method uses stdin/stdout for JSON-RPC communication.
+        stderr can be used for diagnostic messages.
+
+        The server will block until terminated (Ctrl+C or SIGTERM).
+
+        Example:
+            ```python
+            async def main():
+                await server.initialize()
+                await server.run_stdio()
+
+            if __name__ == "__main__":
+                import asyncio
+                asyncio.run(main())
+            ```
+        """
+        await self._mcp.run_stdio_async()

{edda_framework-0.2.0.dist-info → edda_framework-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.2.0
+Version: 0.3.1
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -38,6 +38,8 @@ Requires-Dist: ruff>=0.14.2; extra == 'dev'
 Requires-Dist: testcontainers[mysql]>=4.0.0; extra == 'dev'
 Requires-Dist: testcontainers[postgres]>=4.0.0; extra == 'dev'
 Requires-Dist: tsuno>=0.1.3; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.22.0; extra == 'mcp'
 Provides-Extra: mysql
 Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
 Provides-Extra: postgresql
@@ -77,6 +79,7 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📦 **Transactional Outbox**: Reliable event publishing with guaranteed delivery
 - ☁️ **CloudEvents Support**: Native support for CloudEvents protocol
 - ⏱️ **Event & Timer Waiting**: Free up worker resources while waiting for events or timers, resume on any available worker
+- 🤖 **MCP Integration**: Expose durable workflows as AI tools via Model Context Protocol
 - 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
 ## Use Cases
@@ -686,6 +689,49 @@ async def payment_workflow(ctx: WorkflowContext, order_id: str) -> dict:
 
 **Performance note**: ASGI servers (uvicorn, hypercorn) are recommended for better performance with Edda's async architecture. WSGI support is provided for compatibility with existing infrastructure and users who prefer synchronous programming.
 
+## MCP Integration
+
+Edda integrates with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), allowing AI assistants like Claude to interact with your durable workflows as long-running tools.
+
+### Quick Example
+
+```python
+from edda.integrations.mcp import EddaMCPServer
+from edda import WorkflowContext, activity
+
+# Create MCP server
+server = EddaMCPServer(
+    name="Order Service",
+    db_url="postgresql://user:pass@localhost/orders",
+)
+
+@activity
+async def process_payment(ctx: WorkflowContext, amount: float):
+    return {"status": "paid", "amount": amount}
+
+@server.durable_tool(description="Process customer order")
+async def process_order(ctx: WorkflowContext, order_id: str):
+    await process_payment(ctx, 99.99)
+    return {"status": "completed", "order_id": order_id}
+
+# Deploy with uvicorn
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
+```
+
+### Auto-Generated Tools
+
+Each `@durable_tool` automatically generates **three MCP tools**:
+
+1. **Main tool** (`process_order`): Starts the workflow, returns instance ID
+2. **Status tool** (`process_order_status`): Checks workflow progress
+3. **Result tool** (`process_order_result`): Gets final result when completed
+
+This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
+
+**For detailed documentation**, see [MCP Integration Guide](docs/integrations/mcp.md).
+
 ## Observability Hooks
 
 Extend Edda with custom observability without coupling to specific tools:

{edda_framework-0.2.0.dist-info → edda_framework-0.3.1.dist-info}/RECORD

@@ -12,6 +12,10 @@ edda/replay.py,sha256=5RIRd0q2ZrH9iiiy35eOUii2cipYg9dlua56OAXvIk4,32499
 edda/retry.py,sha256=t4_E1skrhotA1XWHTLbKi-DOgCMasOUnhI9OT-O_eCE,6843
 edda/workflow.py,sha256=daSppYAzgXkjY_9-HS93Zi7_tPR6srmchxY5YfwgU-4,7239
 edda/wsgi.py,sha256=1pGE5fhHpcsYnDR8S3NEFKWUs5P0JK4roTAzX9BsIj0,2391
+edda/integrations/__init__.py,sha256=F_CaTvlDEbldfOpPKq_U9ve1E573tS6XzqXnOtyHcXI,33
+edda/integrations/mcp/__init__.py,sha256=YK-8m0DIdP-RSqewlIX7xnWU7TD3NioCiW2_aZSgnn8,1232
+edda/integrations/mcp/decorators.py,sha256=MIHDrcP_OelxOXISkX6a561Gl3DcVNT9yRakd4O4COo,6333
+edda/integrations/mcp/server.py,sha256=sSemdl7uR133YgZn34uUWzjJUqnPi13HauzXOrf8Kq8,9175
 edda/outbox/__init__.py,sha256=azXG1rtheJEjOyoWmMsBeR2jp8Bz02R3wDEd5tQnaWA,424
 edda/outbox/relayer.py,sha256=2tnN1aOQ8pKWfwEGIlYwYLLwyOKXBjZ4XZsIr1HjgK4,9454
 edda/outbox/transactional.py,sha256=LFfUjunqRlGibaINi-efGXFFivWGO7v3mhqrqyGW6Nw,3808
@@ -29,8 +33,8 @@ edda/viewer_ui/data_service.py,sha256=mXV6bL6REa_UKsk8xMGBIFbsbLpIxe91lX3wgn-FOj
 edda/visualizer/__init__.py,sha256=DOpDstNhR0VcXAs_eMKxaL30p_0u4PKZ4o2ndnYhiRo,343
 edda/visualizer/ast_analyzer.py,sha256=plmx7C9X_X35xLY80jxOL3ljg3afXxBePRZubqUIkxY,13663
 edda/visualizer/mermaid_generator.py,sha256=XWa2egoOTNDfJEjPcwoxwQmblUqXf7YInWFjFRI1QGo,12457
-edda_framework-0.2.0.dist-info/METADATA,sha256=9qiWE872ENCjRcSC4ezcz5y1v1g5TfpLRgIiQUJXgHc,27823
-edda_framework-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-edda_framework-0.2.0.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
-edda_framework-0.2.0.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
-edda_framework-0.2.0.dist-info/RECORD,,
+edda_framework-0.3.1.dist-info/METADATA,sha256=uOiXJuq8Xy4fgfyblF3FwbJpo-cJrXVWgHhoIjdIi9s,29421
+edda_framework-0.3.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+edda_framework-0.3.1.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
+edda_framework-0.3.1.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
+edda_framework-0.3.1.dist-info/RECORD,,