edda-framework 0.2.0__tar.gz → 0.3.1__tar.gz

{edda_framework-0.2.0 → edda_framework-0.3.1}/PKG-INFO

@@ -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 → edda_framework-0.3.1}/README.md

@@ -27,6 +27,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
@@ -636,6 +637,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.3.1/docs/integrations/mcp.md

@@ -0,0 +1,230 @@
+# MCP (Model Context Protocol) Integration
+
+Edda provides seamless integration with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), allowing AI assistants like Claude to interact with your durable workflows as long-running tools.
+
+## Overview
+
+MCP is a standardized protocol for AI tool integration. Edda's MCP integration automatically converts your durable workflows into MCP-compliant tools that:
+
+- **Start workflows** and return instance IDs immediately
+- **Check workflow status** to monitor progress
+- **Retrieve results** when workflows complete
+
+This enables AI assistants to work with long-running processes that may take minutes, hours, or even days to complete.
+
+## Installation
+
+Install Edda with MCP support:
+
+```bash
+pip install edda-framework[mcp]
+
+# Or using uv
+uv add edda-framework --extra mcp
+```
+
+## Quick Start
+
+### 1. Create an MCP Server
+
+```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 reserve_inventory(ctx: WorkflowContext, items: list[str]):
+    # Your business logic here
+    return {"reserved": True}
+
+@activity
+async def process_payment(ctx: WorkflowContext, amount: float):
+    # Payment processing logic
+    return {"transaction_id": "txn_123"}
+
+@server.durable_tool(description="Process customer order workflow")
+async def process_order(ctx: WorkflowContext, order_id: str, items: list[str]):
+    """
+    Long-running order processing workflow.
+
+    This workflow reserves inventory, processes payment, and ships the order.
+    """
+    # Reserve inventory
+    await reserve_inventory(ctx, items)
+
+    # Process payment
+    await process_payment(ctx, 99.99)
+
+    return {"status": "completed", "order_id": order_id}
+```
+
+### 2. Deploy the Server
+
+```python
+# Deploy with uvicorn (production)
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
+```
+
+```bash
+# Run the server
+uvicorn your_app:server.asgi_app --host 0.0.0.0 --port 8000
+```
+
+### 3. Use from MCP Clients (e.g., Claude Desktop)
+
+Add to your MCP client configuration (e.g., Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "order-service": {
+      "command": "uvicorn",
+      "args": ["your_app:server.asgi_app", "--host", "127.0.0.1", "--port", "8000"],
+      "env": {
+        "DATABASE_URL": "postgresql://user:pass@localhost/orders"
+      }
+    }
+  }
+}
+```
+
+## Auto-Generated Tools
+
+Each `@durable_tool` automatically generates **three MCP tools**:
+
+### 1. Main Tool: Start Workflow
+
+```
+Tool Name: process_order
+Description: Process customer order workflow
+
+Input: {"order_id": "ORD-123", "items": ["item1", "item2"]}
+Output: {
+  "content": [{
+    "type": "text",
+    "text": "Workflow 'process_order' started successfully.\nInstance ID: abc123...\n\nUse 'process_order_status' tool to check progress."
+  }],
+  "isError": false
+}
+```
+
+### 2. Status Tool: Check Progress
+
+```
+Tool Name: process_order_status
+Description: Check status of process_order workflow
+
+Input: {"instance_id": "abc123..."}
+Output: {
+  "content": [{
+    "type": "text",
+    "text": "Workflow Status: running\nCurrent Activity: payment:1\nInstance ID: abc123..."
+  }],
+  "isError": false
+}
+```
+
+### 3. Result Tool: Get Final Result
+
+```
+Tool Name: process_order_result
+Description: Get result of process_order workflow (if completed)
+
+Input: {"instance_id": "abc123..."}
+Output: {
+  "content": [{
+    "type": "text",
+    "text": "Workflow Result:\n{'status': 'completed', 'order_id': 'ORD-123'}"
+  }],
+  "isError": false
+}
+```
+
+## Advanced Configuration
+
+### Authentication
+
+Protect your MCP server with token-based authentication:
+
+```python
+def verify_token(token: str) -> bool:
+    # Your token verification logic
+    return token == "secret-token-123"
+
+server = EddaMCPServer(
+    name="Order Service",
+    db_url="postgresql://user:pass@localhost/orders",
+    token_verifier=verify_token,
+)
+```
+
+Clients must include the token in the Authorization header:
+
+```http
+Authorization: Bearer secret-token-123
+```
+
+### Transactional Outbox Pattern
+
+Enable event-driven architecture with outbox pattern:
+
+```python
+server = EddaMCPServer(
+    name="Order Service",
+    db_url="postgresql://user:pass@localhost/orders",
+    outbox_enabled=True,
+    broker_url="nats://localhost:4222",
+)
+```
+
+## MCP Protocol Compliance
+
+Edda's MCP integration follows the [MCP Tools specification](https://modelcontextprotocol.io/docs/concepts/tools):
+
+- **JSON-RPC 2.0**: All communication uses JSON-RPC 2.0 protocol
+- **Content Arrays**: Responses include `content` array with text/image/resource items
+- **Error Handling**: Errors are reported with `isError: true` flag
+- **Stateless HTTP**: Uses MCP's streamable HTTP transport for production deployments
+
+## Architecture
+
+```
+┌─────────────────┐
+│    MCP Client   │
+└────────┬────────┘
+         │ JSON-RPC 2.0
+         │ (HTTP Transport)
+         ▼
+┌─────────────────┐
+│  EddaMCPServer  │
+│   ┌─────────┐   │
+│   │ FastMCP │   │  ← Official MCP SDK
+│   └─────────┘   │
+│   ┌─────────┐   │
+│   │ EddaApp │   │  ← Durable Execution
+│   └─────────┘   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│    Database     │
+└─────────────────┘
+```
+
+
+## Related Documentation
+
+- [Edda Workflows and Activities](../core-features/workflows-activities.md)
+- [Transactional Outbox Pattern](../core-features/transactional-outbox.md)
+- [MCP Protocol Specification](https://modelcontextprotocol.io/)
+
+## Examples
+
+See the [examples/mcp/](../../examples/mcp/) directory for complete working examples.

edda_framework-0.3.1/edda/integrations/__init__.py

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

edda_framework-0.3.1/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_framework-0.3.1/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