JMoak-chrono-mcp

chrono-mcp

面向大规模时间计算的 MCP 服务。 单次工具调用即可批量处理多达 100,000 个时间戳，支持业界时间互操作标准（RFC 9557 IXDTF、RFC 5545 RRULE、ISO 8601 重复间隔），并在每次响应中为 Agent 提供对时间流逝的被动感知。由 Luxon 提供支持，从设计上确保符合夏令时规则，且每项限制都有基准测试数据支撑。

快速开始

npx @jmoak/chrono-mcp

作为本地 HTTP 服务运行

npm install
npm run build
npm run start:http
# Server listens on http://localhost:8000/mcp (health check at /health)

MCP 客户端配置

配置 MCP 客户端，通过 npx 启动 chrono-mcp。下面是针对不同客户端的示例。

Claude Code

问问 Claude！以下是配置：

{
  "mcpServers": {
    "chrono-mcp": {
      "command": "npx",
      "args": ["-y", "@jmoak/chrono-mcp@latest"]
    }
  }
}

Cursor

参考：Cursor MCP 文档

{
  "mcpServers": {
    "chrono-mcp": {
      "command": "npx",
      "args": ["-y", "@jmoak/chrono-mcp@latest"]
    },
    "chrono-mcp-http": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

为什么选择 chrono-mcp

大模型在处理时间方面出了名地不可靠：它们会数错星期几，无法追踪轮次之间经过的时间，而且一遇到夏令时计算就会出错。chrono-mcp 解决了这三个问题，而且能大规模处理，并支持业界已广泛使用的格式。

• 专为批量处理而设计 - 每项操作每个请求最多可进行 10,000 次计算；stats 返回纯聚合结果，最多可处理 100,000 个时间戳。每项上限都有基准测试验证，你可以自行运行（npm run bench）——达到上限时，逐项操作可在 100ms 内完成，处理 100k 个项目的 stats 约需 460ms
• RFC 9557（IXDTF）互操作 - 所有日期时间输入均支持带方括号的 IANA 时区注解（2026-08-09T15:00:00-04:00[America/New_York]），并执行与 Temporal 兼容的偏移量一致性验证；还提供 ixdtf 输出格式——这是 JS Temporal API 的序列化标准
• 重复规则展开 - expand 可将 RFC 5545 RRULE（Google Calendar、Outlook 和 Apple Calendar 使用的格式）和 ISO 8601 重复间隔展开为具体的发生时间——符合夏令时规则、限定在指定时间范围内，并明确报告截断情况
• 时间上下文信封 - 每个工具响应都会附带一行精简信息，其中包含当前时间、星期几、距 Agent 上次调用经过的时间、会话时长以及 tzdb 版本——让每次交互都能被动感知时间
• 批量错误隔离 - 单个错误时间戳不会导致包含 10,000 个项目的批次失败：无效条目会被跳过并报告（invalid_count + 示例），绝不会悄然丢弃
• 令牌优化输出 - 动态调整响应结构，在最大化信息密度的同时尽量减少令牌用量
• 全球时区支持 - 支持所有 IANA 时区标识符，以及 ISO、RFC2822、SQL 和本地化格式
• 类型安全 - 对每个参数进行 Zod 验证，提供符合 MCP 规范的错误，全面采用严格的 TypeScript

文档

• API 参考 - 所有工具、参数和示例的完整文档
• 架构 - 系统架构和设计原则
• 示例 - 实用用法示例和模式

可用工具

获取时间

获取当前时间或通过灵活的格式转换不同时区的时间。

参数：

• datetime（字符串，可选）：ISO 日期时间字符串。默认为当前时间
• timezones（数组，可选）：用于转换的时区名称列表
• formats（数组，可选）：输出格式（iso、rfc2822、sql、local、localeString、short、medium、long、full）
• locale（字符串，可选）：格式化所用的区域设置（例如 en-US、fr-FR、ja-JP）
• includeOffsets（布尔值，可选）：在输出中包含 UTC 偏移量

示例：

输入

{
  "datetime": "2024-01-01T12:00:00Z",
  "timezones": ["America/New_York", "Asia/Tokyo"],
  "includeOffsets": true
}

输出

{
  "baseTime": "2024-01-01T12:00:00.000Z",
  "America/New_York": "2024-01-01T07:00:00.000-05:00",
  "Asia/Tokyo": "2024-01-01T21:00:00.000+09:00"
}

时间计算器

以任意规模执行时间运算——从单次转换到包含 10 万项的批量分析。

操作：

• add - 将时长加到日期时间上
• subtract - 从日期时间中减去时长
• diff - 以不同单位计算简单差值
• duration_between - 详细拆分两个时间点之间的时长
• stats - 对时间序列和时长进行统计分析（每次调用最多 100,000 个时间戳）
• sort - 按时间顺序排列时间戳
• expand - 将 RFC 5545 RRULE 或 ISO 8601 重复间隔展开为多个发生时间

每种操作都支持数组和单个值；interaction_mode 用于控制基准数组与比较数组的组合方式（pairwise、cross_product、single_to_many，等等）。批次中的无效条目会被跳过并报告——绝不会静默丢弃，也不会导致操作失败。

展开示例：

输入

{
  "operation": "expand",
  "recurrence": "FREQ=WEEKLY;BYDAY=TU;COUNT=4",
  "base_time": "2026-02-24T09:00:00[America/New_York]",
  "occurrence_format": "ixdtf"
}

输出（结果摘录——注意跨越 DST 转换时保留的墙上时间）

{
  "rule_type": "rrule",
  "count": 4,
  "truncated": false,
  "occurrences": [
    "2026-02-24T09:00:00.000-05:00[America/New_York]",
    "2026-03-03T09:00:00.000-05:00[America/New_York]",
    "2026-03-10T09:00:00.000-04:00[America/New_York]",
    "2026-03-17T09:00:00.000-04:00[America/New_York]"
  ]
}

还支持 ISO 8601 重复间隔（R5/2026-03-01T14:00:00Z/P1D）、window_start/window_end 边界，以及 max_occurrences 上限（默认值为 100，最大值为 10,000），并会明确报告 truncated 状态。

批量统计示例——传入完整的事件日志；无论包含多少时间戳，响应都很精简（最多 100,000 个）：

{
  "operation": "stats",
  "base_time": ["2026-01-01T00:00:00Z", "...99,998 more...", "2026-01-02T03:46:39Z"]
}

输出（仅聚合结果——摘自一次包含 100,000 个时间戳、耗时约 500 毫秒的实际调用）

{
  "input_analysis": { "base_time_count": 100000 },
  "timestamp_analysis": {
    "earliest": "2026-01-01T00:00:00.000Z",
    "latest": "2026-01-02T03:46:39.000Z",
    "total_span_human": "1 day, 3 hours, 46 minutes, 39 seconds",
    "std_deviation_ms": 28867513
  },
  "interval_analysis": {
    "interval_count": 99999,
    "mean_interval_human": "1 second"
  }
}

参数：

• operation（必需）：计算类型
• interaction_mode（可选）：auto_detect | single_to_many | many_to_single | pairwise | cross_product | aggregate。默认为 auto_detect。
• base_time（可选）：基准 ISO 日期时间。可以是字符串或数组。默认为当前时间。
• compare_time（可选）：用于 diff/duration_between 的比较 ISO 日期时间。可以是字符串或数组。
• timezone（可选）：base_time 的时区
• compare_time_timezone（可选）：compare_time 的时区
• years、months、days、hours、minutes、seconds（可选）：时长值

示例：

输入

{
  "operation": "add",
  "base_time": "2024-12-25T10:00:00Z",
  "days": 5,
  "hours": 3
}

输出

{
  "operation": "add",
  "interaction_mode": "single_to_single",
  "input": {
    "base_time": "2024-12-25T10:00:00.000Z",
    "duration": { "days": 5, "hours": 3 }
  },
  "result": "2024-12-30T13:00:00.000Z",
  "result_timezone": "UTC"
}

时间上下文封套

每个工具响应都包含第二个内容块——一行约 20 个 Token 的文本，为调用方 Agent 提供被动的时间感知：

⏱ now 2026-08-09T15:02:11.123-04:00 (Sun) · first call this session
⏱ now 2026-08-09T15:49:03.456-04:00 (Sun) · +46m52s since last call · session 47m1s · call #2

LLM 本身无法感知轮次之间经过了多长时间；封套会在每次与服务交互时显示时间流逝情况，其中也包括星期几——模型经常会算错。要禁用此功能，请在服务环境中将 CHRONO_ENVELOPE=off。

git clone https://github.com/yourusername/chrono-mcp.git
cd chrono-mcp
npm install

npm run build

npm test
npm run test:ui
npm run test:mcp
npm run inspector

npm run bench

支持的时区

支持所有 IANA 时区标识符，包括：

• 美洲：America/New_York、America/Los_Angeles、America/Toronto 等。
• 欧洲：Europe/London、Europe/Paris、Europe/Berlin 等。
• 亚洲：Asia/Tokyo、Asia/Shanghai、Asia/Dubai 等。
• 澳大利亚：Australia/Sydney、Australia/Melbourne 等。
• 以及 400 多个其他时区……

致谢

本项目由 Luxon 提供支持。Luxon 是一款出色的 DateTime 库，可提供可靠的时区处理和日期运算。我们感谢 Luxon 团队打造了如此可靠的时间操作基础。

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

发布版本

详细变更请参阅 GitHub Releases。