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,155 @@
+# 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: 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** (`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: 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 2: 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
+├── run_worker.py           # Worker process (Method 1)
+├── run_basic_workflow.py   # Workflow client (Method 1)
+├── temporal_agent.py       # Single-file approach (Method 2)
+├── main.py                 # MCP-Agent app setup
+├── mcp_agent.config.yaml   # Configuration (MUST set execution_engine: temporal)
+└── mcp_agent.secrets.yaml  # API keys
+```
+
+## When to Use Each Method
+
+- **Separate Files (Method 1)**: Use when you need:
+  - Distributed workers across multiple machines
+  - Independent scaling of workers and clients
+  - Clear separation of concerns
+  - Production deployments
+
+- **Single File (Method 2)**: 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_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

examples/temporal_plugin/graded_report.md

@@ -0,0 +1,36 @@
+## Graded Report: The Battle of Glimmerwood
+
+### Proofreading Feedback:
+1. **Sentence Structure:**
+   - Correction: "Amidst the chaos, a young girl named Elara stood her ground. She rallied the villagers and devised a clever plan."
+   - **Feedback:** Correct use of punctuation for independent clauses.
+
+2. **Clause Clarity:**
+   - Improved Version: "Elara and the villagers cleverly used the forest's natural defenses to lure the marauders into a trap."
+   - **Feedback:** Enhances clarity and strategic emphasis.
+
+3. **Sentence Flow and Punctuation:**
+   - Correction: "As the bandits approached the village square, a herd of Glimmerfoxes emerged and blinded the marauders with their dazzling light. The villagers then seized the opportunity to capture the invaders."
+   - **Feedback:** Breaks run-on for clearer sequence.
+
+Overall, the story is well-written; improvements focus on sentence structure and clarity for better readability.
+
+### Factual Consistency & Logical Coherence:
+1. **Glimmerwood Setting:** Consistent depiction as a mystical forest.
+2. **Conflict and Elara’s Strategy:** Plausible yet could explore villagers' preparation.
+3. **Capture Aftermath:** Lacks detail on what happens to marauders.
+4. **Glimmerstones:** Intriguing but underexplored.
+5. **Character Consistency:** Elara remains consistent in her role.
+
+While internally consistent, expanding underdeveloped areas can enhance depth.
+
+### APA Style Adherence:
+1. **Title/Sections:** Missing APA elements like a title page.
+2. **Formatting:** Ensure compliance with APA font/margins.
+3. **Narrative Flow:** Clear sequence, can benefit from improved transitions.
+
+### Suggestions:
+- Add a title page following APA.
+- Clarify ambiguous plot elements for better coherence.
+
+In conclusion, the story maintains good narrative quality and internal logic, but formatting and APA compliance need attention to meet academic standards.

examples/temporal_plugin/main.py

@@ -0,0 +1,4 @@
+from mcp_agent.app import MCPApp
+
+# Initialize the app to get context
+app = MCPApp(name="mcp_basic_agent")

examples/temporal_plugin/mcp_agent.config.yaml

@@ -0,0 +1,77 @@
+# MCP-Agent Configuration File
+# Config definition: https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/config.py
+$schema: https://raw.githubusercontent.com/lastmile-ai/mcp-agent/refs/heads/main/schema/mcp-agent.config.schema.json
+
+# Execution engine: asyncio or temporal
+# For temporal mode, see: https://github.com/lastmile-ai/mcp-agent/blob/main/examples/temporal/README.md
+execution_engine: temporal
+
+temporal:
+  host: "localhost:7233" # Default Temporal server address
+  namespace: "default" # Default Temporal namespace
+  task_queue: "mcp-agent" # Task queue for workflows and activities
+  max_concurrent_activities: 10 # Maximum number of concurrent activities
+  rpc_metadata:
+    X-Client-Name: "mcp-agent"
+
+logger:
+  transports: [console, file]
+  level: info
+  path: logs/mcp-agent.log
+
+# Configure MCP Servers connections (supports stdio, sse, streamable_http, and websockets)
+mcp:
+  servers:
+    # Filesystem access server
+    filesystem:
+      command: npx
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
+
+    # Web fetch server
+    fetch:
+      command: uvx
+      args: ["mcp-server-fetch"]
+      #env:  # Environment variables passed to the stdio server
+      #  ROOT_PATH: "/workspace"
+
+    # sse_server:
+    #   transport: "sse"
+    #   url: "https://api.example.com/sse"
+    #   headers:
+    #     Authorization: "Bearer ${API_TOKEN}"
+
+    # streamable_http_server:
+    #   transport: streamable_http
+    #   url: "https://api.example.com/mcp"
+    #   headers:
+    #     Authorization: "Bearer ${API_TOKEN}"
+    #     Content-Type: "application/json"
+    #   http_timeout_seconds: 30
+    #   read_timeout_seconds: 120
+    #   terminate_on_close: true
+
+# Optional: Define Agent definitions in config
+agents:
+  definitions:
+    - name: filesystem_helper
+      instruction: "You can read files and summarize their contents."
+      server_names: [filesystem]
+    - name: web_helper
+      instruction: "You can fetch web pages and summarize their content."
+      server_names: [fetch]
+
+# Model provider defaults (API keys go in mcp_agent.secrets.yaml)
+openai:
+  default_model: gpt-4o-mini
+
+anthropic:
+  default_model: claude-sonnet-4-0
+# google:
+#   default_model: "gemini-1.5-pro"
+
+# OpenTelemetry configuration (optional)
+# otel:
+#   enabled: true
+#   exporters: ["file", "otlp"]
+#   otlp_settings:
+#     endpoint: "http://localhost:4318/v1/traces"