Temporal Cortex MCP

Temporal Cortex MCP

v0.9.1 · 2026 年 3 月 · 更新日志 · 网站： temporal-cortex.com

为任何 AI Agent 赋予自主安排日程的能力。Temporal Cortex 是开放的日程安排基础设施，让任何 AI Agent 都能可靠地安排日程——无论对方是否拥有 AI Agent、使用 Google Calendar 还是 Outlook，也无论对方即时回复还是几天后才回复。5 层中的 18 个工具可处理联系人解析、时间推理、跨服务商可用时间查询和原子化预订。可通过 MCP、A2A、REST 和浏览器访问。由 Truth Engine 提供支持。安装：npx @temporal-cortex/cortex-mcp。

两种使用 Temporal Cortex 的方式

面向个人用户

连接你的日历。你的 AI Agent 会处理其余工作——检查可用时间、解析时区并预订会议，避免重复预订。适用于 Claude Desktop、Cursor、OpenClaw、Manus 以及任何兼容 MCP 的 AI 客户端。

npx @temporal-cortex/cortex-mcp setup

设置向导将交互式引导你完成服务商身份验证、时区配置和 MCP 客户端设置。不到一分钟即可开始安排日程。

或者使用托管 Platform——无需 Node.js。前往 app.temporal-cortex.com 注册，通过 OAuth 连接日历，然后添加一项包含 API 密钥的 MCP 配置即可。

面向开发者

为你的 AI Agent 或产品添加日程安排功能。5 层中的 18 个工具、4 种协议（MCP、A2A、REST、Browser）、基于两阶段提交的原子化预订，以及由 Truth Engine 提供支持的确定性时间计算。

• 本地 MCP 服务： npx @temporal-cortex/cortex-mcp — 完整工具套件，无需基础设施
• Platform REST API： app.temporal-cortex.com — 托管服务、API 密钥、用量仪表板、开放日程网络
• 框架集成： LangGraph、CrewAI、OpenAI Agents SDK
• REST API 参考： temporal-cortex.com/docs/rest-api

---

为什么 AI Agent 会在日历任务上出错？

即使是最新的大模型——GPT-5、Claude、Gemini——在时间推理任务上的得分也不到 50%（OOLONG 基准测试）。较早的模型在日程安排上的得分低至 29%，在时长计算上的得分低至 13%（Test of Time，ICLR 2025）。问它“安排在下周二下午 2 点”，它却选错了星期二。问它“我下午 3 点有空吗？”，它却查错了时区。然后，它还会在你的日历上重复安排。

大多数面向 AI Agent 的日历工具只是薄薄一层 CRUD 封装，会将这些错误直接传给单一日历服务提供商——缺乏时间感知、冲突检测和安全保障。

Temporal Cortex 有何不同？

• 时间感知——Agent 会调用 get_temporal_context 来了解实际时间和时区。resolve_datetime 会将 "next Tuesday at 2pm" 转换为精确的 RFC 3339 时间戳。不再产生幻觉。
• 原子预订——锁定时间段，确认不存在冲突，然后再写入。两个 Agent 都要预订下午 2 点的时段？只有一个能成功。另一个会收到明确的错误提示。不会重复预订。
• 计算可用时间——将多个日历中的空闲/忙碌数据合并为统一视图。AI 看到的是实际可用时间，而不是可能被误读的原始事件数据。
• 确定性 RRULE 展开——可处理夏令时切换、BYSETPOS=-1（每月最后一个工作日）、带时区的 EXDATE、闰年重复事件，以及带 BYDAY 的 INTERVAL>1。由 Truth Engine 驱动，而非依赖大模型推理。
• 高效的令牌输出——与标准 JSON 相比，TOON 格式可将日历数据的令牌数压缩约 40%，从而降低成本并减少上下文窗口占用。TOON 是所有数据工具（list_calendars、list_events、find_free_slots、expand_rrule、get_availability）的默认输出格式。也可以通过显式设置 format: "json" 使用 JSON。

运行 Temporal Cortex 需要什么？

• Node.js 18+（供 npx 下载并运行二进制文件）或 Docker
• 至少一个日历服务提供商：
  • Google Calendar——需要 Google OAuth 凭据
  • Microsoft Outlook——需要 Azure AD 应用注册（MICROSOFT_CLIENT_ID）
  • CalDAV（iCloud、Fastmail 等）——需要应用专用密码

如何安装 Temporal Cortex？

最快的入门方式：

npx @temporal-cortex/cortex-mcp setup

cortex-mcp setup 向导会引导你交互式地完成服务提供商身份验证、时区配置和 MCP 客户端设置。详细步骤请参阅首次运行指南。

也可以通过 3 个步骤手动设置：

1. 安装先决条件——Node.js 18+（或 Docker）以及至少一个日历服务提供商（Google Calendar、Microsoft Outlook 或 CalDAV）。
2. 将 MCP 配置添加到 AI 客户端的配置文件中（请参阅下方针对各客户端的示例）。
3. 运行身份验证流程——npx @temporal-cortex/cortex-mcp auth google（或 outlook / caldav）。此流程会完成身份验证，并配置时区、每周起始日和遥测偏好设置。

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["-y", "@temporal-cortex/cortex-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}

Cursor

添加到 Cursor 的 MCP 设置（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["-y", "@temporal-cortex/cortex-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}

Windsurf

添加到 Windsurf 的 MCP 配置（~/.codeium/windsurf/mcp_config.json）：

{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["-y", "@temporal-cortex/cortex-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}

Docker

docker run --rm -i \
  -e GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com" \
  -e GOOGLE_CLIENT_SECRET="your-client-secret" \
  -e TIMEZONE="America/New_York" \
  -v ~/.config/temporal-cortex:/root/.config/temporal-cortex \
  cortex-mcp

请先构建镜像：docker build -t cortex-mcp .（或直接从仓库构建：docker build -t cortex-mcp https://github.com/temporal-cortex/mcp.git）。

需要提供商凭据方面的帮助？ 请参阅设置指南：Google Calendar、Microsoft Outlook、CalDAV (iCloud/Fastmail)。如需查看所有环境变量和配置选项的完整参考，请参阅配置指南。

如何验证安装？

每个 GitHub Release 都会发布 SHA256 校验和，并将其嵌入 npm 包中的 checksums.json，以便自动进行安装后验证。安装后脚本会下载特定平台的二进制文件，并将其 SHA256 哈希值与 checksums.json 中的预期校验和进行比对。如果不匹配，安装将报错失败——不会安装二进制文件，错误消息中会同时显示预期和实际哈希值。

手动验证：

# Download the published checksums
curl -sL https://github.com/temporal-cortex/mcp/releases/download/mcp-v0.9.1/SHA256SUMS.txt

# Compare against your installed binary
sha256sum "$(dirname "$(which cortex-mcp)")/../cortex-mcp" 2>/dev/null || \
  shasum -a 256 "$(npm root -g)/@temporal-cortex/cortex-mcp/bin/cortex-mcp" 2>/dev/null

**构建来源：**二进制文件由 GitHub Actions 从 Rust 源代码交叉编译，支持 5 个平台（darwin-arm64、darwin-x64、linux-x64、linux-arm64、win32-x64）。计算层在 temporal-cortex/core 上开源。

**Docker 隔离：**如需最大程度的隔离，请在容器中运行 MCP 服务：

docker build -t cortex-mcp https://github.com/temporal-cortex/mcp.git
docker run --rm -i -v ~/.config/temporal-cortex:/root/.config/temporal-cortex cortex-mcp

主机上无需安装 Node.js，除已挂载的配置目录外，不会直接访问文件系统。

如何通过日历提供商进行身份验证？

最简单的方式是运行 npx @temporal-cortex/cortex-mcp setup，它会通过引导流程一次性处理身份验证、配置和 MCP 客户端设置。如需单独对某个提供商进行身份验证，请运行以下命令：

# Google Calendar (default)
npx @temporal-cortex/cortex-mcp auth google

# Microsoft Outlook
npx @temporal-cortex/cortex-mcp auth outlook

# CalDAV (iCloud, Fastmail, or custom server)
npx @temporal-cortex/cortex-mcp auth caldav

# Docker (interactive auth — needs terminal + browser)
docker run --rm -it \
  -e GOOGLE_CLIENT_ID="your-id" -e GOOGLE_CLIENT_SECRET="your-secret" \
  -p 8085:8085 \
  -v ~/.config/temporal-cortex:/root/.config/temporal-cortex \
  cortex-mcp auth google

每个身份验证流程都会将凭据保存到 ~/.config/temporal-cortex/credentials.json，并将提供商注册到 ~/.config/temporal-cortex/config.json。你可以连接多个提供商——服务启动时会发现所有已配置的提供商，并将它们的日历合并为统一视图。

在身份验证过程中，服务会引导你完成交互式设置：

• 时区 — 自动检测系统时区，并打开包含全部 597 个 IANA 时区的模糊搜索选择器（输入文字进行筛选，使用方向键导航）
• 每周起始日 — 使用方向键在星期一（ISO 标准）和星期日之间选择
• 遥测 — 可选的匿名使用数据（默认关闭）

所有偏好设置都会保存到 ~/.config/temporal-cortex/config.json，并供所有 temporal 工具使用。你可以通过 TIMEZONE 和 WEEK_START 环境变量按会话覆盖这些设置。

完成身份验证后，可以向 AI 助手询问 “现在几点？” 来验证是否正常工作——Agent 应调用 get_temporal_context 并返回你当前的本地时间。

如需使用引导式工作流，请安装 Temporal Cortex Agent Skills，让 AI Agent 学会 orient-resolve-query-book 模式。

Temporal Cortex Platform

你可以使用托管式 Temporal Cortex Platform，而不必通过 npx 在本地运行 MCP 服务。无需安装 Node.js，也无需本地 OAuth 凭据。

开始使用：

1. 在 app.temporal-cortex.com 注册。
2. 在控制面板中通过 OAuth 连接 Google Calendar 或 Microsoft Outlook 帐户。
3. 在控制面板中生成 API 密钥。
4. 将 MCP 配置添加到 AI 客户端（参见以下示例）。

Claude Desktop（Platform）

将以下内容添加到 Claude Desktop 配置文件中：

{
  "mcpServers": {
    "temporal-cortex": {
      "url": "https://mcp.temporal-cortex.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor（平台）

使用相同格式将其添加到 Cursor 的 MCP 设置（~/.cursor/mcp.json）中：

{
  "mcpServers": {
    "temporal-cortex": {
      "url": "https://mcp.temporal-cortex.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

平台能力（超出本地模式）：

• 无需管理 OAuth 凭据——日历连接通过标准 OAuth 流程在控制面板中处理。
• 无需 Node.js——客户端通过 HTTP 直接连接云端端点。
• 用量控制面板——通过 app.temporal-cortex.com 监控工具调用、已连接的日历和账单。
• 托管日历连接——令牌刷新、重新授权和服务提供商运行状况均在服务端处理。
• 多 Agent 协调——分布式锁可防止多个 Agent 同时安排日程时重复预订。
• 用量计量——在控制面板中按 Agent 和团队跟踪工具调用。
• 内容防火墙——自动检测提示词注入并剥除零宽度 Unicode 字符。
• 基于调用方的策略——为每个 Agent 强制执行预订规则（最长时长、允许时段、预订限制）。

全部 15 个核心工具和 5 个层级的工作方式完全相同。平台在此基础上增加了安全、协调和可见性基础设施，并额外提供 3 个开放日程工具（见下文）。

开放日程 + Temporal Links

平台用户可以启用开放日程，让 AI Agent 和人类无需 API 密钥即可公开查询其可用时间。

1. 在控制面板中进入设置 > 日程安排。
2. 设置一个 slug（例如 billy）并启用开放日程。
3. 分享你的 Temporal Link：book.temporal-cortex.com/billy

调用方可使用的功能：

• Agent Card（A2A 发现）：GET /public/{slug}/.well-known/agent-card.json
• 可用时间（REST）：GET /public/{slug}/availability?date=2026-03-15
• 预订（REST）：POST /public/{slug}/book
• A2A JSON-RPC：使用 query_availability 或 book_slot 方法调用 POST /public/{slug}/a2a
• 身份解析：GET /[email protected] 可解析并返回用户的 Agent Card

**人工备用方案：**同一个 Temporal Link 也可在浏览器中使用——人类会看到一个包含日期／时间选择器和表单的预订页面。

**传播循环：**每个 Agent Card 都会向调用方 Agent 的框架展示 Temporal Cortex。每笔预订的事件描述中都会包含“Powered by Temporal Cortex”。

Temporal Cortex 提供哪些工具？

Temporal Cortex 最多提供 18 个按 5 个层级组织的模型上下文协议工具。15 个核心工具始终可用；平台模式下还可使用 3 个额外的开放日程工具。

层级 0 — 发现

工具	描述
resolve_identity	将身份（电子邮件、slug 或 URL）解析为 Temporal Cortex 用户的 Agent Card——返回 slug、显示名称和开放日程状态。仅限平台模式。
search_contacts	按姓名搜索用户的通讯录（Google People API、Microsoft Graph）。返回匹配联系人的电子邮件、电话号码、组织和职位。需主动启用，并要求拥有联系人权限。
resolve_contact	根据已确认联系人的电子邮件，确定最佳日程安排方式：开放日程（即时预订）、电子邮件或电话。平台 API 可用时会与 resolve_identity 串联调用。

第 1 层 — 时间上下文

工具	描述
get_temporal_context	返回配置区域的当前时间、时区、UTC 偏移量、夏令时状态、夏令时预测（下一次切换日期和方向）以及星期几。在任何日历会话中都应首先调用此工具。
resolve_datetime	将“下周二下午 2 点”或“明天早上”等自然语言表达解析为精确的 RFC 3339 时间戳。
convert_timezone	将任意 RFC 3339 日期时间从一个 IANA 时区转换为另一个时区，并报告目标时区的夏令时状态。
compute_duration	计算两个时间戳之间的时长，并返回天、小时、分钟和易读字符串。
adjust_timestamp	按类似“+1d2h30m”的复合时长调整时间戳；按天调整时会考虑夏令时，并保留当地时钟时间。

第 2 层 — 日历操作

工具	描述
list_calendars	列出所有已连接服务提供商的日历，包含带服务提供商前缀的 ID、名称、颜色和访问角色。默认使用 TOON 输出（令牌数约减少 40%）。
list_events	列出指定时间范围内的日历事件，支持带服务提供商前缀的 ID。默认使用 TOON 输出（令牌数约减少 40%）；使用 format: "json" 可输出 JSON。
find_free_slots	通过计算事件之间的间隔查找日历中的可用时段，并支持设置最短时段时长。默认使用 TOON 输出。
expand_rrule	将 RFC 5545 重复规则展开为具体的日期时间实例，并以确定性方式处理夏令时切换、BYSETPOS、闰年和 EXDATE 排除项。默认使用 TOON 输出。
check_availability	检查指定时段是否可用，同时查看日历事件和有效的预订锁。

第 3 层 — 可用性

工具	描述
get_availability	合并多个日历的空闲/忙碌数据，生成统一视图，并支持配置隐私级别（Opaque 或 Full）。默认使用 TOON 输出。
query_public_availability	按 slug 查询其他用户的公开可用性 — 返回指定日期和时长的可用时段。无需 API 密钥。仅限 Platform Mode。

第 4 层 — 预订

工具	描述
book_slot	使用两阶段提交预订日历时段：获取时间范围锁、验证不存在冲突、写入事件，然后释放锁。
request_booking	按 slug 请求在其他用户的公开日历上预订 — 代表对方创建日历事件，并包含参与者和标题信息。仅限 Platform Mode。
compose_proposal	为电子邮件、Slack 或 SMS 撰写日程安排提议消息，并按收件人的时区格式化建议时段。可选包含 Temporal Link 自助预订 URL。不会发送消息 — 返回格式化文本，供 Agent 通过其渠道 MCP 发送。

完整的输入/输出架构和用法示例，请参阅 docs/tools.md。

Temporal Cortex 如何处理重复规则？

大多数 AI 模型和日历工具都会在重复规则的边缘情况下悄无声息地失败。运行挑战即可了解差异：

npx @temporal-cortex/cortex-mcp rrule-challenge

大模型始终无法正确处理的 5 种情况

1. 夏令时期间的“每月第三个星期二”（2026 年 3 月，America/New_York）

第三个星期二是 3 月 17 日。3 月 8 日进入夏令时，UTC 偏移从 -05:00 变为 -04:00。大模型常会给出错误的 UTC 时间，或直接漏掉该月。

2. “每月最后一个星期五”（BYSETPOS=-1）

RRULE:FREQ=MONTHLY;BYDAY=FR;BYSETPOS=-1 — 大模型经常返回第一个星期五而不是最后一个，或无法正确处理当月有 4 个还是 5 个星期五的情况。

3. “除节假日外的每个工作日”（带时区的 EXDATE）

带有明确时区偏移的 EXDATE 值，必须与生成的实例精确匹配。大模型常会完全忽略 EXDATE，或将其应用到错误的日期。

4. “每两周的星期一、星期三和星期五”（INTERVAL=2 + BYDAY）

RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE,FR — INTERVAL=2 适用于周，而不是单独的日期。大模型经常生成每周一次的事件，而不是每隔一周一次。

5. “每年 2 月 29 日”（闰年重复规则）

RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=29 — 只应在闰年生成实例（2028、2032……）。大模型常会在非闰年生成 2 月 28 日或 3 月 1 日的实例。

Truth Engine 根据 RFC 5545 规范，以确定性的方式处理所有这些情况。无需推断，也不会产生幻觉。

MCP 服务架构如何运作？

MCP 服务是一个通过 npm 和 Docker 分发的 Rust 单一二进制文件。它在你的机器上本地运行，并通过 stdio（标准输入/输出）或可流式传输的 HTTP 与 MCP 客户端通信。

请求流程分为 4 个阶段：

1. 接收 — 服务通过 stdio（默认）或可流式传输的 HTTP（设置 HTTP_PORT 时）接收来自 MCP 客户端的 JSON-RPC 消息。
2. 解析 — Truth Engine 将人类可读的日期时间表达式转换为精确的 UTC 时间戳，并以确定性的方式处理时区转换和夏令时切换。
3. 计算 — 对于可用性查询，引擎会合并所有已连接日历提供商的空闲/忙碌数据。对于 RRULE 展开，则会按照 RFC 5545 规则生成具体实例。
4. 执行 — 对于预订操作，两阶段提交会获取锁、验证时段是否空闲、写入事件并释放锁。任何步骤失败都会触发回滚。

TOON（Token-Oriented Object Notation）会压缩日历数据，便于大模型使用 — 与 JSON 相比可减少约 40% 的 token，且往返转换完全保真。TOON 是所有数据工具的默认输出格式；需要结构化 JSON 时，请使用 format: "json"。

Stdio 与 HTTP 传输

传输模式会自动检测 — 设置 HTTP_PORT 即可从 stdio 切换到 HTTP。

• Stdio（默认）：适用于本地客户端（Claude Desktop、VS Code、Cursor）的标准 MCP 传输方式。服务通过 stdin/stdout 读取和写入 JSON-RPC 消息。
• HTTP（设置 HTTP_PORT 时）：符合 MCP 2025-11-25 规范的可流式传输 HTTP 方式。服务会在 http://{HTTP_HOST}:{HTTP_PORT}/mcp 上监听，并提供 SSE 流式传输、会话管理（Mcp-Session-Id 标头）和 Origin 验证。带有无效 Origin 标头的请求会被拒绝，并返回 HTTP 403。

# HTTP mode example
HTTP_PORT=8009 npx @temporal-cortex/cortex-mcp

本地模式与平台模式

模式会自动检测 — 无需配置标志。

• 本地模式（默认）：无需基础设施。使用内存锁定和本地文件凭据存储。支持多个日历提供商（Google、Outlook、CalDAV），并可合并多个日历的可用性。面向个人开发者设计。
• 平台模式（托管服务，位于 mcp.temporal-cortex.com）：提供托管式多租户服务，支持由 Postgres 提供后端的凭据、Bearer 令牌身份验证、护栏（速率限制 + 预订上限）、用量计量，以及用于保障多 Agent 安全的分布式锁定。面向团队和生产环境部署设计。

如何配置 Temporal Cortex？

变量	必需	默认值	说明
GOOGLE_CLIENT_ID	使用 Google 时必需	—	来自 Cloud Console 的 Google OAuth 客户端 ID
GOOGLE_CLIENT_SECRET	使用 Google 时必需	—	Google OAuth 客户端密钥
GOOGLE_OAUTH_CREDENTIALS	否	—	Google OAuth JSON 凭据文件的路径（可替代 CLIENT_ID + CLIENT_SECRET）
MICROSOFT_CLIENT_ID	使用 Outlook 时必需	—	用于访问 Outlook 日历的 Azure AD 应用程序（客户端）ID
MICROSOFT_CLIENT_SECRET	使用 Outlook 时必需	—	用于访问 Outlook 日历的 Azure AD 客户端密钥
TIMEZONE	否	自动检测	IANA 时区覆盖值（例如 America/New_York）。覆盖存储的配置和操作系统检测结果。
WEEK_START	否	monday	一周的起始日：monday（ISO 8601）或 sunday。影响“本周开始”“下周”等表达。
REDIS_URLS	否	—	用于 Platform Mode 内分布式锁的逗号分隔 Redis URL。可选 — 若未设置，则回退到内存锁。
TENANT_ID	否	自动生成	用于租户隔离的 UUID
LOCK_TTL_SECS	否	30	锁的生存时间（秒）
OAUTH_REDIRECT_PORT	否	8085	本地 OAuth 回调服务的端口
HTTP_PORT	否	—	HTTP 传输的端口。设置后，将启用可流式 HTTP 模式而非 stdio。
HTTP_HOST	否	127.0.0.1	HTTP 传输的绑定地址。仅在反向代理后使用 0.0.0.0。
ALLOWED_ORIGINS	否	—	HTTP 模式允许的逗号分隔 Origin 标头（例如 http://localhost:3000）。若未设置，则拒绝所有跨源请求。

必须至少配置一个日历提供方。请参阅提供方设置指南：Google Calendar、Microsoft Outlook、CalDAV (iCloud/Fastmail)。完整的配置参考请参阅配置指南。

如何排查常见问题？

问题	解决方案
“未找到凭据”	运行 npx @temporal-cortex/cortex-mcp auth google（或 outlook / caldav）进行身份验证
OAuth 错误 /“访问被阻止”	检查 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET（Outlook 则检查 MICROSOFT_CLIENT_ID 和 MICROSOFT_CLIENT_SECRET）是否正确。确保已配置 OAuth 同意屏幕。
端口 8085 已被占用	将 OAUTH_REDIRECT_PORT 设为其他端口（例如 8086）
MCP 客户端中未显示服务	确保已安装 Node.js 18+（node --version）。检查 MCP 客户端的日志是否有错误。
启动时未发现提供方	确认提供方已在 ~/.config/temporal-cortex/config.json 中注册（如有需要，再次运行 auth）

请参阅各提供方的故障排查说明：Google Calendar、Microsoft Outlook、CalDAV。

常见问题

Temporal Cortex 能否在没有互联网连接的情况下运行？

第 1 层工具（时间上下文、日期时间解析、时区转换、时长计算、时间戳调整）仅执行计算，无需网络连接。日历工具（第 2–4 层）需要网络连接，以访问 Google Calendar、Microsoft Outlook 或 CalDAV API。MCP 服务本身在你的计算机上本地运行。

支持哪些 AI 客户端？

任何兼容 Model Context Protocol 的客户端都可以使用。我们提供了针对 Claude Desktop、Claude Code、搭配 GitHub Copilot 的 VS Code、Cursor 和 Windsurf 的测试配置。该服务默认使用 stdio 传输，也支持可流式 HTTP 传输，以便进行自定义集成。

如何将 Temporal Cortex 与 CrewAI 搭配使用？

Temporal Cortex 可通过原生 MCPServerAdapter 与 CrewAI 搭配使用，无需包装器。完整的多 Agent 调度团队示例，请参阅 CrewAI 集成指南和示例代码。

快速入门（DSL — 最简单的方式）：

from crewai import Agent
from crewai.mcp import MCPServerStdio

scheduler = Agent(
    role="Calendar Scheduling Assistant",
    goal="Schedule meetings using deterministic calendar tools",
    backstory="You always call get_temporal_context first to orient in time.",
    mcps=[
        MCPServerStdio(
            command="npx",
            args=["-y", "@temporal-cortex/cortex-mcp"],
            env={"TIMEZONE": "America/New_York"},
        ),
    ],
)

平台模式（SSE — 无需本地服务）：

from crewai.mcp import MCPServerSSE

scheduler = Agent(
    ...,
    mcps=[
        MCPServerSSE(
            url="https://mcp.temporal-cortex.com/mcp",
            headers={"Authorization": "Bearer YOUR_API_KEY"},
        ),
    ],
)

如何将 Temporal Cortex 与 LangGraph 搭配使用？

Temporal Cortex 可通过 langchain-mcp-adapters 与 LangGraph 搭配使用——该适配器会自动发现所有 MCP 工具，并将它们转换为兼容 LangChain 的 StructuredTool 对象。ReAct Agent、多 Agent StateGraph 和人工参与示例，请参阅 LangGraph 集成指南和示例代码。

快速入门（ReAct Agent）：

from langchain_anthropic import ChatAnthropic
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

model = ChatAnthropic(model="claude-sonnet-4-6")

async with MultiServerMCPClient(
    {
        "temporal-cortex": {
            "command": "npx",
            "args": ["-y", "@temporal-cortex/cortex-mcp"],
            "env": {"TIMEZONE": "America/New_York"},
            "transport": "stdio",
        }
    }
) as client:
    tools = client.get_tools()
    agent = create_react_agent(model, tools)

平台模式（HTTP — 无需本地服务）：

async with MultiServerMCPClient(
    {
        "temporal-cortex": {
            "url": "https://mcp.temporal-cortex.com/mcp",
            "headers": {"Authorization": "Bearer YOUR_API_KEY"},
            "transport": "streamable_http",
        }
    }
) as client:
    tools = client.get_tools()
    agent = create_react_agent(model, tools)

如何将 Temporal Cortex 与 OpenAI Agents SDK 搭配使用？

Temporal Cortex 可通过 HostedMCPTool 与 OpenAI Agents SDK 搭配使用——MCP 连接由 OpenAI 在服务器端处理，无需本地服务。有关单 Agent、多 Agent 和审批工作流示例，请参阅 OpenAI Agents SDK 集成指南和示例代码。

快速入门：

from agents import Agent, HostedMCPTool

agent = Agent(
    name="Calendar Scheduler",
    instructions="You schedule meetings using Temporal Cortex calendar tools.",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "temporal-cortex",
                "server_url": "https://mcp.temporal-cortex.com/mcp",
                "headers": {"Authorization": "Bearer YOUR_API_KEY"},
                "require_approval": "never",
            }
        ),
    ],
)

我可以同时连接多个日历提供商吗？

可以。分别为每个提供商（Google、Outlook、CalDAV）运行授权流程。服务会在启动时发现所有已配置的提供商，并将它们的日历合并为统一的可用时间视图。使用带提供商前缀的 ID（例如 google/primary 或 outlook/work）可指定特定日历。

两阶段提交如何防止重复预订？

调用 book_slot 时，服务会获取一个时间范围锁，确认不存在冲突事件或有效锁，然后将事件写入日历 API，最后释放锁。如果任何步骤失败，操作都会回滚。两个 Agent 同时预订同一时间段时，恰好只有一个会成功，另一个会收到明确的错误信息。

什么是 TOON？它为什么能降低成本？

与 JSON 相比，TOON（面向令牌的对象表示法）可将日历负载压缩约 40%，减少令牌数（在 Google Calendar 事件架构基准测试中减少 38%），同时保持完全的往返保真度。令牌越少，API 成本越低，LLM 上下文窗口可容纳的内容也越多。TOON 现在是所有数据工具（list_calendars、list_events、find_free_slots、expand_rrule、get_availability）的默认输出格式。使用 format: "json" 可获取 JSON 输出。

Temporal Cortex 如何处理夏令时？

所有时间工具都能识别夏令时。在春季拨快时钟的切换点之后，使用 "+1d" 调用 adjust_timestamp 会保留墙上时钟时间（上午 1:00 EST 变为上午 1:00 EDT）。RRULE 展开会确保循环事件在夏令时切换期间仍保持当地时间。get_temporal_context 会报告当前是否处于夏令时，并预测下一次夏令时切换，包括切换日期、方向（春季拨快或秋季拨回）以及距切换的天数。

本地模式与平台模式有什么区别？

本地模式（默认）在你的计算机上运行，使用内存锁和本地文件凭据存储，无需任何基础设施——全部 15 个核心工具均可零配置使用（联系人工具需要选择启用联系人权限）。平台模式（位于 mcp.temporal-cortex.com）增加了托管式 OAuth 生命周期管理、多 Agent 协调与分布式锁、用量计量、基于调用方的策略、内容防火墙、仪表板 UI，以及 3 个额外的开放调度工具（resolve_identity、query_public_availability、request_booking）。两种模式都提供相同的 15 个核心工具和 5 个层级——平台模式为团队增加安全性、协调能力、可见性，工具总数最多可达 18 个。

LLM 的时间推理能力有多差？

即使是最新的前沿模型——GPT-5、Claude Sonnet 4、Gemini 2.5 Pro——在时间推理任务上的得分也不到 50%（OOLONG 基准测试，arXiv:2511.02817）。早期模型在日程安排上的得分低至 29%，在时长计算上的得分低至 13%（Test of Time，ICLR 2025，arXiv:2406.09170）。时间问题一直是 LLM 最具挑战性的类别。Temporal Cortex 在所有日历计算中都以确定性计算取代 LLM 推理。

有托管云服务选项吗？

有。Temporal Cortex Platform 可通过 app.temporal-cortex.com 使用。免费注册——个人用户在 Starter 套餐中每月可预订 20 次，开发者每月可预订 100 次。付费套餐（Individual Pro、Developer Growth/Scale）提供更高限额和优先支持。所有套餐均可使用全部日程安排功能，包括免费套餐。

Temporal Cortex 会收集遥测数据吗？

设置期间会出现交互式提示，询问你是否愿意分享匿名使用数据（默认：关闭）。

收集的数据： 工具名称、成功/错误次数、平台、版本。绝不会收集： 日历数据、日历事件或个人信息。

非交互式会话（MCP stdio）会自动选择退出。你可以随时更改选择：

export TEMPORAL_CORTEX_TELEMETRY=off

如何教我的 AI Agent 掌握日程安排工作流？

Temporal Cortex Agent Skills 会教 AI Agent 使用这些工具的正确工作流——从时间定位到无冲突预订。安装它们，为你的 Agent 提供日历操作的流程知识：

# Claude Code
npx skills add temporal-cortex/skills

该技能遵循 Agent Skills 规范，适用于 Claude Code、OpenAI Codex、Google Gemini、GitHub Copilot、Cursor 以及其他 20 多个平台。

Temporal Cortex 背后的计算层是什么？

计算层已开源：

• temporal-cortex-core — Truth Engine（时间解析、RRULE 展开、可用时间合并、时区转换）+ TOON（令牌压缩）
• 可通过 crates.io、npm 和 PyPI 获取
• 510+ 个 Rust 测试、42 个 JS 测试、30 个 Python 测试，约 9,000 个基于属性的测试

贡献

欢迎提交错误报告和功能请求。请参阅 CONTRIBUTING.md。

许可证

MIT