使用说明

临时MCP服务器

Temporal Cloud的模型上下文协议（MCP）服务器，使Claude Code能够与所有地区的Temporal工作流进行交互。

🌍 多区域支持

访问不同的时态云区域：

🇺🇸 美国（us-west-2）
🇪🇺 欧盟（eu-central-1）
🇦🇺 澳大利亚 （ap-southeast-2）
🇮🇳 在……里面 （ap-south-1）

🚀 快速设置

1.配置环境

复制.env.example并设置值

2.添加到克劳德代码

编辑 ~/.claude.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.重新启动克劳德代码

就是这样！服务器会根据您的查询自动连接到任何区域。

🛠️ 可用工具

1.get_workflow_step_结果⭐ （推荐）

使用resultUri获取已处理的步骤结果以下载日志- 用这个代替完整的历史记录！

在以下情况下使用： 您需要步骤摘要、结果URI、持续时间或调试流 退货： 压缩JSON，包含步骤名称、结果URI、成功状态、持续时间

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

答复：

{
  "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.列表_工作流执行

使用时态可见性语法的过滤器查询工作流。

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

示例查询：

"ExecutionStatus='Running'" -所有正在运行的工作流
"ExecutionStatus='Failed' AND StartTime > '2026-02-01T00:00:00Z'" -最近的失败
"WorkflowType='refreshGithubUsersFlow'" -特定工作流类型

3.描述工作流执行

获取工作流状态、时间和元数据。

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

4.终止工作流执行

停止正在运行的工作流。

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

5.列表式工作流执行

列出在某个时间范围内完成的工作流。

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

6.获取工作流执行历史

获取原始时间事件历史记录- 仅在需要完整历史记录时使用！ 警告：可以是80k+个字符。使用 get_workflow_step_results 相反。

💡 使用示例

使用ResultUri获取步骤结果（最常见）

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

调试失败流

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

监控特定流量

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

跨区域健康检查

"Compare total running workflows across all regions"

性能分析

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

🌐 区域处理

所有工具都接受可选 region 参数：

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

无区域： 用途 DEFAULT_REGION 从配置 自然语言： 克劳德了解“欧盟地区”、“澳大利亚”等。

自动映射

服务器自动将区域映射到端点无需手动配置！

🔧 技术细节

什么 `get_workflow_step_results` 是否

从Temporal获取工作流历史记录
活动完成/失败事件的筛选器
解码base64有效载荷→ JSON
提取stepName、resultUri、exposedData
计算步骤持续时间
按步骤名称进行重复数据删除
返回简洁摘要

连接管理

延迟加载连接（仅在需要时连接）
按区域保持单独连接
自动重用连接
首次查询某个地区：约1-2秒
后续查询：快速（缓存连接）

已处理的事件类型

事件类型12： 活动任务已完成
事件类型13： 活动任务失败
事件类型3： 工作流执行失败

🎯 最佳实践

✅ 这样做

使用 get_workflow_step_results 对于大多数查询
在已知的情况下指定区域
与Claude一起使用自然语言
通过resultUri下载日志

❌ 避免这种情况

使用 get_workflow_execution_history 除非需要
手动解析原始历史记录
忘记为已知工作流指定区域

📝 常见模式

模式1：调试失败的流

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

模式2：绩效调查

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

模式3：跨区域监测

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

🔍 故障排除

“找不到工作流”

→ 尝试搜索其他区域或验证工作流ID

“连接错误”

→ 检查配置中的API密钥和帐户ID

“响应太大”

→ Use get_workflow_step_results 而不是完整的历史

“区域不工作”

→ 验证地区代码是以下之一：us、eu、au、in

📚 响应格式

所有回复均包含地区信息：

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

步骤结果还包括：

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

🚦 入门指南

添加API密钥 到 .env
更新Claude代码配置 具有路径和凭据
重新启动Claude代码
测试： "List workflows in US region"
获取步骤结果： "Get step results for workflow X run Y"
使用结果URI 下载日志

🎉 快速示例

简单：

"List running workflows"

地区：

"Show failed workflows in EU from today"

获取步骤结果：

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

跨区域：

"Search all regions for workflow containing 'github'"

演出

"Compare execution times between US and EU regions"