edda-framework 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

edda/integrations/mcp/decorators.py

@@ -4,18 +4,17 @@ from __future__ import annotations
 
 import inspect
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
-from edda.workflow import workflow
+from edda.workflow import Workflow, workflow
 
 if TYPE_CHECKING:
     from edda.integrations.mcp.server import EddaMCPServer
-    from edda.workflow import Workflow
 
 
 def create_durable_tool(
     server: EddaMCPServer,
-    func: Callable,
+    func: Callable[..., Any],
     *,
     description: str = "",
 ) -> Workflow:
@@ -38,7 +37,7 @@ def create_durable_tool(
         Workflow instance
     """
     # 1. Create Edda workflow
-    workflow_instance: Workflow = workflow(func, event_handler=False)
+    workflow_instance = cast(Workflow, workflow(func, event_handler=False))
     workflow_name = func.__name__
 
     # Register in server's workflow registry
@@ -56,7 +55,7 @@ def create_durable_tool(
     ]
 
     # Create the tool function
-    async def start_tool(**kwargs: Any) -> dict:
+    async def start_tool(**kwargs: Any) -> dict[str, Any]:
         """
         Start workflow and return instance_id.
 
@@ -94,11 +93,21 @@ def create_durable_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)
-    async def status_tool(instance_id: str) -> dict:
+    @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)
+            instance = await server.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")
@@ -128,11 +137,21 @@ def create_durable_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)
-    async def result_tool(instance_id: str) -> dict:
+    @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)
+            instance = await server.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"]
 

edda/integrations/mcp/server.py

@@ -3,13 +3,16 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import Any
+from typing import TYPE_CHECKING, Any, cast
 
 from edda.app import EddaApp
 from edda.workflow import Workflow
 
+if TYPE_CHECKING:
+    from edda.storage.protocol import StorageProtocol
+
 try:
-    from mcp.server.fastmcp import FastMCP
+    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. "
@@ -45,7 +48,13 @@ class EddaMCPServer:
 
         # Deploy with uvicorn (HTTP transport)
         if __name__ == "__main__":
+            import asyncio
             import uvicorn
+
+            async def startup():
+                await server.initialize()
+
+            asyncio.run(startup())
             uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
 
         # Or deploy with stdio (for MCP clients, e.g., Claude Desktop)
@@ -89,7 +98,7 @@ class EddaMCPServer:
             service_name=name,
             db_url=db_url,
             outbox_enabled=outbox_enabled,
-            broker_url=broker_url,
+            broker_url=broker_url or "",
         )
         self._mcp = FastMCP(name, json_response=True, stateless_http=True)
         self._token_verifier = token_verifier
@@ -97,12 +106,28 @@ class EddaMCPServer:
         # Registry of durable tools (workflow_name -> Workflow instance)
         self._workflows: dict[str, Workflow] = {}
 
+    @property
+    def storage(self) -> StorageProtocol:
+        """
+        Access workflow storage for querying instances and history.
+
+        Returns:
+            StorageProtocol: Storage backend for workflow state
+
+        Example:
+            ```python
+            instance = await server.storage.get_instance(instance_id)
+            history = await server.storage.get_history(instance_id)
+            ```
+        """
+        return self._edda_app.storage
+
     def durable_tool(
         self,
-        func: Callable | None = None,
+        func: Callable[..., Any] | None = None,
         *,
         description: str = "",
-    ) -> Callable:
+    ) -> Callable[..., Any]:
         """
         Decorator to define a durable workflow tool.
 
@@ -128,14 +153,67 @@ class EddaMCPServer:
         """
         from edda.integrations.mcp.decorators import create_durable_tool
 
-        def decorator(f: Callable) -> Workflow:
+        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:
+    def prompt(
+        self,
+        func: Callable[..., Any] | None = None,
+        *,
+        description: str = "",
+    ) -> Callable[..., Any]:
+        """
+                Decorator to define a prompt template.
+
+                Prompts can access workflow state to generate dynamic, context-aware
+                prompts for AI clients (Claude Desktop, etc.).
+
+                Args:
+                    func: Prompt function (async or sync)
+                    description: Prompt description for MCP clients
+
+                Returns:
+                    Decorated function
+
+                Example:
+                    ```python
+                    from fastmcp.prompts.prompt import PromptMessage, TextContent
+
+                    @server.prompt(description="Analyze workflow results")
+                    async def analyze_workflow(instance_id: str) -> PromptMessage:
+                        '''Generate a prompt to analyze a specific workflow execution.'''
+                        instance = await server.storage.get_instance(instance_id)
+                        history = await server.storage.get_history(instance_id)
+
+                        text = f'''Analyze this workflow:
+
+        Instance ID: {instance_id}
+        Status: {instance['status']}
+        Activities: {len(history)}
+
+        Please identify any issues or optimization opportunities.'''
+
+                        return PromptMessage(
+                            role="user",
+                            content=TextContent(type="text", text=text)
+                        )
+                    ```
+        """
+
+        def decorator(f: Callable[..., Any]) -> Callable[..., Any]:
+            # Use FastMCP's native prompt decorator
+            prompt_desc = description or f.__doc__ or f"Prompt: {f.__name__}"
+            return cast(Callable[..., Any], self._mcp.prompt(description=prompt_desc)(f))
+
+        if func is None:
+            return decorator
+        return decorator(func)
+
+    def asgi_app(self) -> Callable[..., Any]:
         """
         Create ASGI application with MCP + CloudEvents support.
 
@@ -150,8 +228,8 @@ class EddaMCPServer:
         Returns:
             ASGI callable (Starlette app)
         """
-        from starlette.requests import Request
-        from starlette.responses import Response
+        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()
@@ -169,9 +247,9 @@ class EddaMCPServer:
             scope["path"] = f"/cancel/{instance_id}"
 
             # Capture response
-            response_data = {"status": 200, "headers": [], "body": b""}
+            response_data: dict[str, Any] = {"status": 200, "headers": [], "body": b""}
 
-            async def send(message: dict) -> None:
+            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", [])
@@ -185,7 +263,7 @@ class EddaMCPServer:
             return Response(
                 content=response_data["body"],
                 status_code=response_data["status"],
-                headers=dict(response_data["headers"]),
+                headers=cast(dict[str, str], dict(response_data["headers"])),
             )
 
         # Add cancel route
@@ -193,14 +271,18 @@ class EddaMCPServer:
 
         # Add authentication middleware if token_verifier provided (AFTER adding routes)
         if self._token_verifier is not None:
-            from starlette.middleware.base import BaseHTTPMiddleware
+            from starlette.middleware.base import (  # type: ignore[import-not-found]
+                BaseHTTPMiddleware,
+            )
 
-            class AuthMiddleware(BaseHTTPMiddleware):
-                def __init__(self, app: Any, token_verifier: Callable):
+            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):
+                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:]
@@ -211,17 +293,15 @@ class EddaMCPServer:
             # Wrap app with auth middleware
             app = AuthMiddleware(app, self._token_verifier)
 
-        return app
+        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.
+        This method must be called before running the server in either stdio or HTTP mode.
 
-        Example:
+        Example (stdio mode):
             ```python
             async def main():
                 await server.initialize()
@@ -231,9 +311,85 @@ class EddaMCPServer:
                 import asyncio
                 asyncio.run(main())
             ```
+
+        Example (HTTP mode):
+            ```python
+            import asyncio
+            import uvicorn
+
+            async def startup():
+                await server.initialize()
+
+            asyncio.run(startup())
+            uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
+            ```
         """
         await self._edda_app.initialize()
 
+    async def shutdown(self) -> None:
+        """
+        Shutdown the server and cleanup resources.
+
+        Stops background tasks (auto-resume, timer checks, event timeouts),
+        closes storage connections, and performs graceful shutdown.
+
+        This method should be called when the server is shutting down.
+
+        Example (stdio mode):
+            ```python
+            import signal
+            import asyncio
+
+            async def main():
+                server = EddaMCPServer(...)
+                await server.initialize()
+
+                # Setup signal handlers for graceful shutdown
+                loop = asyncio.get_running_loop()
+                shutdown_event = asyncio.Event()
+
+                def signal_handler():
+                    shutdown_event.set()
+
+                for sig in (signal.SIGTERM, signal.SIGINT):
+                    loop.add_signal_handler(sig, signal_handler)
+
+                # Run server
+                try:
+                    await server.run_stdio()
+                finally:
+                    await server.shutdown()
+
+            if __name__ == "__main__":
+                asyncio.run(main())
+            ```
+
+        Example (HTTP mode with uvicorn):
+            ```python
+            import asyncio
+            import uvicorn
+
+            async def startup():
+                await server.initialize()
+
+            async def shutdown_handler():
+                await server.shutdown()
+
+            # Use uvicorn lifecycle events
+            config = uvicorn.Config(
+                server.asgi_app(),
+                host="0.0.0.0",
+                port=8000,
+            )
+            server_instance = uvicorn.Server(config)
+
+            # Uvicorn handles SIGTERM/SIGINT automatically
+            await server_instance.serve()
+            await shutdown_handler()
+            ```
+        """
+        await self._edda_app.shutdown()
+
     async def run_stdio(self) -> None:
         """
         Run MCP server with stdio transport (for MCP clients, e.g., Claude Desktop).

{edda_framework-0.3.0.dist-info → edda_framework-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.3.0
+Version: 0.4.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -730,6 +730,32 @@ Each `@durable_tool` automatically generates **three MCP tools**:
 
 This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
 
+### MCP Prompts
+
+Define reusable prompt templates that can access workflow state:
+
+```python
+from mcp.server.fastmcp.prompts.base import UserMessage
+from mcp.types import TextContent
+
+@server.prompt(description="Analyze a workflow execution")
+async def analyze_workflow(instance_id: str) -> UserMessage:
+    """Generate analysis prompt for a specific workflow."""
+    instance = await server.storage.get_instance(instance_id)
+    history = await server.storage.get_history(instance_id)
+
+    text = f"""Analyze this workflow:
+**Status**: {instance['status']}
+**Activities**: {len(history)}
+**Result**: {instance.get('output_data')}
+
+Please provide insights and optimization suggestions."""
+
+    return UserMessage(content=TextContent(type="text", text=text))
+```
+
+AI clients can use these prompts to generate context-aware analysis of your workflows.
+
 **For detailed documentation**, see [MCP Integration Guide](docs/integrations/mcp.md).
 
 ## Observability Hooks

{edda_framework-0.3.0.dist-info → edda_framework-0.4.0.dist-info}/RECORD

@@ -14,8 +14,8 @@ 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=HYZi6Ic_w-ffqMzO0cmuio88OSm1FVQ5jzjePcW48QM,5541
-edda/integrations/mcp/server.py,sha256=N-QTebRKd05LB9r2Cwywm4xU9wsbO_UAdYofoEhArms,8785
+edda/integrations/mcp/decorators.py,sha256=UTBb-Un2JK938pDZmANOvfsdKOMI2AF9yGtfSuy8VrE,6284
+edda/integrations/mcp/server.py,sha256=pzCG46Zko9hHmQ3REbo1w3A23SjrGFLiZupwSkIPhOA,13942
 edda/outbox/__init__.py,sha256=azXG1rtheJEjOyoWmMsBeR2jp8Bz02R3wDEd5tQnaWA,424
 edda/outbox/relayer.py,sha256=2tnN1aOQ8pKWfwEGIlYwYLLwyOKXBjZ4XZsIr1HjgK4,9454
 edda/outbox/transactional.py,sha256=LFfUjunqRlGibaINi-efGXFFivWGO7v3mhqrqyGW6Nw,3808
@@ -33,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.3.0.dist-info/METADATA,sha256=fVS73kMWDrVBU3BYcRKFNMGlFhMB12dvaZbOoz2T_LI,29421
-edda_framework-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-edda_framework-0.3.0.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
-edda_framework-0.3.0.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
-edda_framework-0.3.0.dist-info/RECORD,,
+edda_framework-0.4.0.dist-info/METADATA,sha256=YEsevYgVMtBEBJlAhQL1lALOOiNrejsC9Z6QpyZsFRg,30272
+edda_framework-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+edda_framework-0.4.0.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
+edda_framework-0.4.0.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
+edda_framework-0.4.0.dist-info/RECORD,,