⏰🧠 Temporal-MCP 服务器

Temporal MCP 是一个连接 AI 助手（如 Claude）和 Temporal 工作流的 MCP 服务器。它将复杂的后端编排转换成简单的聊天驱动命令。想象一下，无需编写任何粘合代码就能触发有状态的过程。Temporal-MCP 让这一切成为可能。

为什么选择 Temporal MCP

• 超级充电的 AI — AI 助手获得了可靠且长时间运行的工作流能力
• 对话编排 — 通过自然语言触发、监控和管理工作流
• 企业级准备 — 利用 Temporal 的重试、超时和持久性功能——以纯文本形式暴露

✨ 关键特性

• 🔍 自动发现 — 探索可用的工作流并查看丰富的元数据
• 🏃‍♂️ 无缝执行 — 通过一条聊天消息启动复杂的过程
• 📊 实时监控 — 跟踪进度、检查状态并获取实时更新
• ⚡ 性能优化 — 智能缓存实现即时响应
• 🧠 对 AI 友好的描述 — 目的字段既适合人类也适合机器

🏁 快速开始

预备条件

• Go 1.21+ — 用于构建和运行 MCP 服务器
• Temporal 服务器 — 本地或远程运行（参见 Temporal 文档）

快速安装

1. 运行你的 Temporal 服务器和工作者 在此示例中，我们将使用 Temporal 资金转移演示。

MCP 设置

让 Claude（或其他启用 MCP 的 AI 助手）与你的工作流进行通信只需五个简单步骤：

2. 构建服务器

git clone https://github.com/Mocksi/temporal-mcp.git
cd temporal-mcp
make build

2. 定义你的工作流 在 config.yml 中 示例配置（config.sample.yml）旨在与 Temporal 资金转移演示配合使用：

workflows:
  AccountTransferWorkflow:
    purpose: "在验证和通知的情况下，在账户之间转账。处理所有预期正常工作的场景。"
    input:
      type: "TransferInput"
      fields:
        - from_account: "源账户ID"
        - to_account: "目标账户ID"
        - amount: "要转账的金额"
    output:
      type: "TransferOutput"
      description: "带有收费ID的转账确认"
    taskQueue: "account-transfer-queue"

  AccountTransferWorkflowScenarios:
    purpose: "扩展的账户转账工作流，包括各种场景，如人工审批、可恢复失败和高级可见性功能。"
    input:
      type: "TransferInput"
      fields:
        - from_account: "源账户ID"
        - to_account: "目标账户ID"
        - amount: "要转账的金额"
        - scenario_type: "要执行的场景类型（human_approval, recoverable_failure, advanced_visibility）"
    output:
      type: "TransferOutput"
      description: "带有收费ID的转账确认"
    taskQueue: "account-transfer-queue"

3. 生成 Claude 的配置

cd examples
./generate_claude_config.sh

4. 安装配置

cp examples/claude_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

5. 启动 Claude 使用此配置

与你的工作流对话

现在是神奇的部分！通过 Claude 使用自然语言与你的工作流进行对话：

💬 "Claude，你能从账户ABC123向账户XYZ789转账100美元吗？"

💬 "有哪些可用的转账场景可以测试？"

💬 "执行一个需要人工审批的500美元转账，账户为ABC123和XYZ789"

💬 "转账工作流已经完成了吗？"

💬 "运行一个具有可恢复失败的转账场景来测试错误处理"

幕后，Temporal MCP 将这些自然语言请求转化为正确格式的工作流执行——不再需要复杂的API调用或参数格式化！

核心价值观

1. 清晰第一 — 使用简单直接的语言。避免行话。
2. 利益驱动 — 以“对我有什么好处”为先导。
3. 简洁的力量 — 少即是多——保持句子紧凑而难忘。
4. 个性与声音 — 大胆陈述，短句，一点兴奋感。

准备展示

灯光、摄像、行动——捕捉你第一个由AI驱动的工作流的动态。分享这一刻。激励他人看到Temporal MCP的实际应用。

开发

项目结构

./
├── cmd/            # 可执行程序的入口点
├── internal/       # 内部包代码
│   ├── api/        # MCP API 实现
│   ├── cache/      # 缓存层
│   ├── config/     # 配置管理
│   └── temporal/   # Temporal 客户端集成
├── examples/       # 示例配置和脚本
└── docs/           # 文档

常用命令

命令	描述
make build	在 ./bin 构建二进制文件
make test	运行所有单元测试
make fmt	根据 Go 标准格式化代码
make run	构建并运行服务器
make clean	移除构建产物

🔍 故障排除

常见问题

连接被拒绝

• ✓ 检查 Temporal 服务器是否正在运行
• ✓ 验证 config.yml 中的 hostPort 是否正确

工作流未找到

• ✓ 确保工作流已在 Temporal 注册
• ✓ 检查 config.yml 中的命名空间设置

Claude 无法看到工作流

• ✓ 验证 claude_config.json 是否位于正确位置
• ✓ 配置更改后重启 Claude

⚙️ 配置

Temporal MCP 的核心是其配置文件，该文件将你的 AI 助手连接到你的工作流引擎：

配置架构

你的 config.yml 包含三个关键部分：

1. 🔌 Temporal 连接 — 如何连接到你的 Temporal 服务器
2. 💾 缓存设置 — 工作流结果的性能优化
3. 🔧 工作流定义 — 你的 AI 可以发现和使用的工作流

示例配置

示例配置旨在与 Temporal 资金转移演示配合使用：

# Temporal 服务器连接详情
temporal:
  hostPort: "localhost:7233"       # 你的 Temporal 服务器地址
  namespace: "default"             # Temporal 命名空间
  environment: "local"             # "local" 或 "remote"
  defaultTaskQueue: "account-transfer-queue"  # 工作流的默认任务队列

  # 微调连接行为
  timeout: "5s"                    # 连接超时
  retryOptions:                     # 坚固的重试设置
    initialInterval: "100ms"       # 从快速重试开始
    maximumInterval: "10s"         # 重试之间的最大等待时间
    maximumAttempts: 5              # 不要永远尝试
    backoffCoefficient: 2.0         # 指数退避

# 定义 AI 可发现的工作流
workflows:
  AccountTransferWorkflow:
    purpose: "在验证和通知的情况下，在账户之间转账。处理所有预期正常工作的场景。"
    workflowIDRecipe: "transfer_{{.from_account}}_{{.to_account}}_{{.amount}}"
    input:
      type: "TransferInput"
      fields:
        - from_account: "源账户ID"
        - to_account: "目标账户ID"
        - amount: "要转账的金额"
    output:
      type: "TransferOutput"
      description: "带有收费ID的转账确认"
    taskQueue: "account-transfer-queue"
    activities:
      - name: "validate"
        timeout: "5s"
      - name: "withdraw"
        timeout: "5s"
      - name: "deposit"
        timeout: "5s"
      - name: "sendNotification"
        timeout: "5s"
      - name: "undoWithdraw"
        timeout: "5s"

💡 专业提示： 示例配置已预配置为与 Temporal 资金转移演示配合使用。将其作为你自己的工作流起点。

💎 最佳实践

编写完美的目的字段

purpose 字段是你的 AI 助手理解每个工作流功能的窗口。让它发挥作用！

✅ 应该这样做

• 编写清晰详细的功能描述
• 提及关键参数及其如何定制行为
• 描述预期输出及其格式
• 注意任何限制或约束

❌ 应避免这样做

• 含糊不清的描述（“处理数据”）
• 无解释的技术术语
• 缺少重要参数
• 忽略错误情况或限制

前后对比

之前： "获取关于文件的信息。"

之后： "检索关于文件或目录的详细元数据，包括大小、创建时间、最后修改时间、权限和类型。执行访问验证以确保请求的文件在允许的目录内。返回包含所有属性的格式化JSON或适当的错误信息。"

命名约定

项目	约定	示例
工作流ID	PascalCase	AccountTransferWorkflow
参数名称	snake_case	from_account, to_account
带单位的参数	包括单位	timeout_seconds, amount

安全指南

⚠️ 重要安全注意事项：

• 将凭据移出配置文件
• 使用环境变量存储敏感值
• 考虑对涉及敏感数据的工作流进行访问控制
• 验证和清理所有工作流输入

💡 提示： 为开发和生产环境创建不同的配置

为什么良好的目的字段很重要

1. 增强 AI 理解 — 当 Claude 和其他 AI 工具完全理解每个组件的能力和限制时，它们可以提供更准确和有用的响应
2. 减少错误 — 详细的描述减少了 AI 系统错误使用组件的机会
3. 改进调试 — 清晰的描述有助于识别当工作流的行为不符合预期时的问题
4. 更好的开发者体验 — 新团队成员可以更快地理解你的系统
5. 代码即文档 — 目的字段作为活文档，与代码库保持同步

贡献与协作

我们共同建设这个项目。

• 分享你自己的工作流配置
• 改进描述
• 在问题中分享你的演示（视频或GIF）

让我们一起释放AI和Temporal的力量！

📜 许可

本项目根据MIT许可发布 - 查看LICENSE文件了解详情。 欢迎贡献！