# Temporal MCP Server

A Model Context Protocol (MCP) server for Temporal Cloud that enables Claude Code to interact with your Temporal workflows across all regions.

## 🌍 Multi-Region Support

Access different Temporal Cloud regions:

- 🇺🇸 **US** (us-west-2)
- 🇪🇺 **EU** (eu-central-1)
- 🇦🇺 **AU** (ap-southeast-2)
- 🇮🇳 **IN** (ap-south-1)

## 🚀 Quick Setup

### 1. Configure Environment

Copy .env.example and setup the values

### 2. Add to Claude Code

Edit `~/.claude.json`:

```json
{
  "mcpServers": {
    "temporal": {
      "command": "node",
      "args": ["/absolute/path/to/your/temporal-mcp/build/index.js"],
      "env": {
        "TEMPORAL_API_KEY": "your-actual-api-key",
        "TEMPORAL_ACCOUNT_ID": "<cloud_account_id>",
        "DEFAULT_REGION": "us"
      }
    }
  }
}
```

### 3. Restart Claude Code

That's it! The server auto-connects to any region based on your queries.

## 🛠️ Available Tools

### 1. get_workflow_step_results ⭐ (Recommended)

Get processed step results with resultUri for downloading logs - **use this instead of full history!**

**Use when:** You want step summaries, resultUri, durations, or to debug flows
**Returns:** Compact JSON with step names, resultUri, success status, durations

```
"Get step results for workflow 'refresh-monitors-456' run 'abc-123' in EU region"
```

**Response:**

```json
{
  "success": true,
  "totalSteps": 3,
  "steps": [
    {
      "stepName": "fetchData",
      "isSuccess": true,
      "resultUri": "flowData/99/99999/flow-id/run-id/step-fetchData/1234567890.json",
      "durationSeconds": "2.45",
      "exposedData": { "count": 150 }
    }
  ]
}
```

### 2. list_workflow_executions

Query workflows with filters using Temporal visibility syntax.

```json
{
  "query": "WorkflowType='refreshSlackUsersFlow' AND ExecutionStatus='Running'",
  "pageSize": 20,
  "region": "eu"
}
```

**Example queries:**

- `"ExecutionStatus='Running'"` - All running workflows
- `"ExecutionStatus='Failed' AND StartTime > '2026-02-01T00:00:00Z'"` - Recent failures
- `"WorkflowType='refreshGithubUsersFlow'"` - Specific workflow type

### 3. describe_workflow_execution

Get workflow status, timing, and metadata.

```json
{
  "workflowId": "my-workflow-123",
  "region": "us"
}
```

### 4. terminate_workflow_execution

Stop a running workflow.

```json
{
  "workflowId": "stuck-workflow",
  "reason": "Manual termination - investigating data source issue",
  "region": "au"
}
```

### 5. list_closed_workflow_executions

List workflows that completed in a time range.

```json
{
  "startTime": "2026-02-01T00:00:00Z",
  "endTime": "2026-02-05T23:59:59Z",
  "region": "in"
}
```

### 6. get_workflow_execution_history

Get raw Temporal event history - **only use if you need full history!**
Warning: Can be 80k+ characters. Use `get_workflow_step_results` instead.

## 💡 Usage Examples

### Get Step Results with ResultUri (Most Common)

```
"Use temporal MCP and get step results for workflow 'intune.refreshIntuneEntitiesFlow.orgPk_756d...' run 'abc-123' and show me the resultUri for each step"
```

### Debug Failed Flow

```
"Show me failed workflows in EU region from last 24 hours, then get step results for the most recent failure"
```

### Monitor Specific Flow

```
"Is the GitHub user sync running for org 12345 in US region?"
```

### Cross-Region Health Check

```
"Compare total running workflows across all regions"
```

### Performance Analysis

```
"Get step results for the last 5 runs of 'refreshSlackUsersFlow' in US region and show me average step durations"
```

## 🌐 Region Handling

All tools accept an optional `region` parameter:

```json
{ "region": "us" }  // United States (default)
{ "region": "eu" }  // Europe
{ "region": "au" }  // Australia
{ "region": "in" }  // India
```

**Without region:** Uses `DEFAULT_REGION` from config
**Natural language:** Claude understands "EU region", "Australia", etc.

### Automatic Mapping

The server automatically maps regions to endpoints
No manual configuration needed!

## 🔧 Technical Details

### What `get_workflow_step_results` Does

1. Fetches workflow history from Temporal
2. Filters for activity completed/failed events
3. Decodes base64 payloads → JSON
4. Extracts stepName, resultUri, exposedData
5. Calculates step durations
6. Deduplicates by step name
7. Returns compact summary

### Connection Management

- Lazy-loads connections (only connects when needed)
- Maintains separate connection per region
- Reuses connections automatically
- First query to a region: ~1-2 seconds
- Subsequent queries: Fast (cached connection)

### Event Types Processed

- **Event Type 12:** Activity Task Completed
- **Event Type 13:** Activity Task Failed
- **Event Type 3:** Workflow Execution Failed

## 🎯 Best Practices

### ✅ Do This

- Use `get_workflow_step_results` for most queries
- Specify region when known
- Use natural language with Claude
- Download logs via resultUri

### ❌ Avoid This

- Using `get_workflow_execution_history` unless needed
- Parsing raw history manually
- Forgetting to specify region for known workflows

## 📝 Common Patterns

### Pattern 1: Debugging Failed Flows

```
1. "List failed flows from last hour in US region"
2. "Get step results for workflow XYZ run ABC"
3. Use resultUri to download logs
4. Analyze error from step data
```

### Pattern 2: Performance Investigation

```
1. "Get step results for last 5 successful runs"
2. "Compare step durations"
3. "Identify slowest steps"
```

### Pattern 3: Cross-Region Monitoring

```
1. "Query all regions for specific workflow type"
2. "Aggregate results by region"
3. "Identify regional differences"
```

## 🔍 Troubleshooting

### "Can't find workflow"

→ Try searching other regions or verify workflow ID

### "Connection error"

→ Check API key and account ID in config

### "Response too large"

→ Use `get_workflow_step_results` instead of full history

### "Region not working"

→ Verify region code is one of: us, eu, au, in

## 📚 Response Format

All responses include region information:

```json
{
  "success": true,
  "region": "eu",
  "namespace": "your_temporal_host.<cloud_account_id>",
  "data": { ... }
}
```

Step results also include:

```json
{
  "totalSteps": 3,
  "steps": [
    {
      "stepName": "...",
      "isSuccess": true,
      "resultUri": "...",
      "durationSeconds": "2.45",
      "exposedData": { ... }
    }
  ]
}
```

## 🚦 Getting Started

1. **Add your API key** to `.env`
2. **Update Claude Code config** with paths and credentials
3. **Restart Claude Code**
4. **Test:** `"List workflows in US region"`
5. **Get step results:** `"Get step results for workflow X run Y"`
6. **Use resultUri** to download logs

## 🎉 Quick Examples

**Simple:**

```
"List running workflows"
```

**With region:**

```
"Show failed workflows in EU from today"
```

**Get step results:**

```
"Get step results for workflow X run Y and show me resultUri"
```

**Cross-region:**

```
"Search all regions for workflow containing 'github'"
```

**Performance:**

```
"Compare execution times between US and EU regions"
```

---

**Ready to use!** Just add your API key and start debugging workflows with Claude! 🚀