Temporal plugin implementation

examples/temporal_plugin/.gitignore

@@ -0,0 +1,93 @@
+# MCP-Agent
+mcp_agent.secrets.yaml
+*.secrets.yaml
+.mcp-agent/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual Environment
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+*.code-workspace
+
+# Vim
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+*~
+
+# Logs
+logs/
+*.log
+*.jsonl
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Local environment variables
+.env.local
+.env.*.local

examples/temporal_plugin/README.md

@@ -0,0 +1,206 @@
+# MCP-Agent with Temporal Plugin
+
+This example demonstrates multiple ways to use the Temporal plugin with MCP-Agent for workflow orchestration.
+
+## Prerequisites
+
+1. **Temporal Server**: Ensure you have a Temporal server running locally:
+   ```bash
+   temporal server start-dev
+   ```
+   This starts a development server at `localhost:7233`
+
+2. **API Keys**: Add your API keys to `mcp_agent.secrets.yaml`:
+   ```yaml
+   OPENAI_API_KEY: "your-key-here"
+   ANTHROPIC_API_KEY: "your-key-here"  # optional
+   ```
+
+3. **Configuration**: Set the execution engine to `temporal` in `mcp_agent.config.yaml`:
+   ```yaml
+   execution_engine: temporal
+
+   temporal:
+     host: "localhost:7233"
+     namespace: "default"
+     task_queue: "mcp-agent"
+   ```
+
+## Usage Methods
+
+### Method 1: MCP Server with Temporal Workflows
+
+This approach exposes Temporal workflows as MCP tools that can be called by Claude Desktop or other MCP clients.
+
+**Step 1: Define your workflow** (`basic_workflow.py`):
+```python
+from temporalio import workflow
+from mcp_agent.agents.agent import Agent
+from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
+
+@workflow.defn
+class BasicWorkflow:
+    @workflow.run
+    async def run(self, prompt: str) -> str:
+        simple_agent = Agent(
+            name="finder",
+            instruction="You are a helpful agent",
+            server_names=["fetch"],
+        )
+
+        async with simple_agent:
+            llm = await simple_agent.attach_llm(OpenAIAugmentedLLM)
+            result = await llm.generate_str(prompt)
+            return result
+```
+
+**Step 2: Start the MCP server** (`basic_agent_server.py`):
+```bash
+uv run basic_agent_server.py
+```
+This starts an MCP server that exposes your Temporal workflows as tools.
+
+**Step 3: Run the Temporal worker** (in another terminal):
+```bash
+uv run run_worker.py
+```
+This starts a Temporal worker that can execute the workflows.
+
+**Step 4: Test with MCP Inspector**:
+```bash
+npx @modelcontextprotocol/inspector sse://localhost:3001
+```
+
+In the inspector, you can:
+- Call `workflows-list` to see available workflows
+- Call `workflows-BasicWorkflow-run` with a prompt parameter to execute the workflow
+- Monitor workflow execution in the Temporal UI at http://localhost:8233
+
+### Method 2: Separate Worker and Workflow Files
+
+This approach separates the worker and workflow execution into different processes, useful for distributed systems.
+
+**Step 1: Define your workflow** (already shown above)
+
+**Step 2: Run the worker** (`run_worker.py`):
+```bash
+uv run run_worker.py
+```
+
+**Step 3: Execute the workflow** (in another terminal):
+```bash
+uv run run_basic_workflow.py
+```
+
+### Method 3: Single File Execution (temporal_agent.py)
+
+This approach combines worker and workflow execution in a single file, ideal for simpler deployments or testing.
+
+```bash
+uv run temporal_agent.py
+```
+
+This file:
+- Defines the workflow
+- Starts the worker
+- Executes the workflow
+- All within the same process using `async with Worker(...)`
+
+**Key difference**: The single-file approach runs both the worker and client in the same process:
+```python
+async with Worker(
+    client,
+    task_queue=running_app.config.temporal.task_queue,
+    workflows=[BasicWorkflow],
+):
+    # Execute workflow while worker is running
+    output = await client.execute_workflow(...)
+```
+
+## Important Configuration Notes
+
+### Execution Engine Setting
+
+The `execution_engine` in `mcp_agent.config.yaml` **MUST** be set to `temporal` for the Temporal plugin to work:
+
+```yaml
+execution_engine: temporal  # Required for Temporal plugin
+```
+
+Without this setting, MCP-Agent will use the default `asyncio` engine and Temporal features won't be available.
+
+### Temporal Configuration
+
+Configure Temporal settings in `mcp_agent.config.yaml`:
+
+```yaml
+temporal:
+  host: "localhost:7233"           # Temporal server address
+  namespace: "default"              # Temporal namespace
+  task_queue: "mcp-agent"          # Task queue name
+  max_concurrent_activities: 10    # Concurrency limit
+  rpc_metadata:
+    X-Client-Name: "mcp-agent"     # Client identification
+```
+
+## File Structure
+
+```
+temporal_plugin/
+├── basic_workflow.py        # Workflow definition
+├── basic_agent_server.py    # MCP server that exposes workflows as tools
+├── run_worker.py           # Worker process
+├── run_basic_workflow.py   # Workflow client (direct execution)
+├── temporal_agent.py       # Single-file approach
+├── main.py                 # MCP-Agent app setup
+├── mcp_agent.config.yaml   # Configuration (MUST set execution_engine: temporal)
+└── mcp_agent.secrets.yaml  # API keys
+```
+
+## Registering Pure Temporal Workflows
+
+The new `register_temporal_workflows()` method allows you to register pure Temporal workflows (decorated with `@workflow.defn`) with the MCP-Agent framework:
+
+```python
+# In basic_agent_server.py
+from main import app
+from basic_workflow import BasicWorkflow
+
+# Register pure Temporal workflows
+app.register_temporal_workflows([BasicWorkflow])
+```
+
+This automatically:
+- Adds MCP-Agent compatibility to your pure Temporal workflows
+- Exposes them as MCP tools
+- Handles deduplication if workflows are registered in multiple places
+
+## When to Use Each Method
+
+- **MCP Server (Method 1)**: Use when you need:
+  - Integration with Claude Desktop or other MCP clients
+  - Exposing workflows as callable tools
+
+- **Separate Files (Method 2)**: Use when you need:
+  - Distributed workers across multiple machines
+  - Independent scaling of workers and clients
+  - Clear separation of concerns
+  - Production deployments with direct workflow execution
+
+- **Single File (Method 3)**: Use when you need:
+  - Quick prototyping and testing
+  - Simple deployments
+  - All-in-one execution for demos
+  - Development and debugging
+
+## Troubleshooting
+
+1. **Temporal not working**: Ensure `execution_engine: temporal` in config
+2. **Connection refused**: Start Temporal server with `temporal server start-dev`
+3. **Task queue mismatch**: Verify task queue names match between worker and client
+
+## Further Resources
+
+- [Temporal Documentation](https://docs.temporal.io/)
+- [MCP-Agent Documentation](https://docs.mcp-agent.com/)
+- [MCP-Agent GitHub](https://github.com/lastmile-ai/mcp-agent)

examples/temporal_plugin/basic_agent_server.py

@@ -0,0 +1,28 @@
+import logging
+import asyncio
+from main import app
+from mcp_agent.server.app_server import create_mcp_server_for_app
+from basic_workflow import BasicWorkflow
+
+# Initialize logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+app.register_temporal_workflows([BasicWorkflow])
+
+
+async def main():
+    async with app.run() as agent_app:
+        logger.info(f"Creating MCP server for {agent_app.name}")
+
+        logger.info("Registered workflows:")
+        for workflow_id in agent_app.workflows:
+            logger.info(f"  - {workflow_id}")
+
+        mcp_server = create_mcp_server_for_app(agent_app)
+
+        await mcp_server.run_sse_async()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/temporal_plugin/basic_workflow.py

@@ -0,0 +1,19 @@
+from temporalio import workflow
+from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
+from mcp_agent.agents.agent import Agent
+
+
+@workflow.defn
+class BasicWorkflow:
+    @workflow.run
+    async def run(self, prompt: str) -> str:
+        simple_agent = Agent(
+            name="finder",
+            instruction="You are a helpful agent",
+            server_names=["fetch"],
+        )
+
+        async with simple_agent:
+            llm = await simple_agent.attach_llm(OpenAIAugmentedLLM)
+            result = await llm.generate_str(prompt)
+            return result