kairos-lang-mcp

kairos-lang-mcp

一旦定义，随时可用。
_{Write the rule once; list the dates.}

一个用于 Kairos（一种日程定义语言）的 MCP 服务 (https://kairos-lang.org)。它让 AI 客户端能够确定性地计算日程定义——列出某个范围内的所有触发时间，或接下来的 N 个；验证定义；并读取描述符参考。

该服务是对参考实现 CLI 的轻量封装：工具返回的内容与 kairos list --json / kairos next --json 的输出完全相同（即 CliReport，架构见 https://kairos-lang.org/schema/cli-report.schema.json）。时间点以 epoch 毫秒表示，并作为唯一标识；dates 是一一对应的民用日期标签。超出覆盖范围的区间会作为注释返回，绝不会静默丢弃时间点。

日本語：README.ja.md

安装

已在官方 MCP Registry 中列出，名称为 io.github.azathothx/kairos-lang-mcp（https://registry.modelcontextprotocol.io — 能读取 Registry 的客户端可以通过该名称安装）。

需要 Node.js 20 或更高版本。该服务通过 stdio 使用 MCP。

npx -y kairos-lang-mcp          # start on stdio (what an MCP client runs for you)
npx -y kairos-lang-mcp --version

Claude Code

claude mcp add kairos-lang -- npx -y kairos-lang-mcp

Claude Desktop（claude_desktop_config.json）及其他 stdio 客户端：

{
  "mcpServers": {
    "kairos-lang": { "command": "npx", "args": ["-y", "kairos-lang-mcp"] }
  }
}

工具

工具	输入	输出
kairos_list	source、from、to、tz、supply?、explain?	[from, to) 的 CliReport — 所有触发时间、区间注释、覆盖范围摘要
kairos_next	source、tz、from?（默认值：tz 中的今天）、n?（默认值 1）、horizonYears?（默认值 10）、supply?、explain?	接下来 n 次触发的 CliReport；found < requested 表示在时间范围内找到的数量少于 n（CLI 的退出代码为 2）
kairos_validate	source、tz、supply?	{ok, version, diagnostics: [{kind, message}], expressions} — 进行词法分析、语法分析、静态规则检查和前提解析，不计算日期范围
kairos_reference	word、lang?	单个描述符的参考页面（roll、within、nth、segmentBy 等；README 中列有完整列表）

资源：kairos://llms.txt（面向 AI 读者的语言概览）和 kairos://reference/{ja|en}/{word}（与 kairos_reference 相同的页面）。

必须提供 tz

CLI 默认使用机器的时区；AI 调用方没有机器，因此每个执行计算的工具都需要 tz（例如 Asia/Tokyo 这样的 IANA 名称）。它决定如何解读日期标签和 [from, to) 端点。如果定义的前提声明了 tz:，计算时会使用该时区；tz 仍用于标注输出。

推荐做法：定义一次前提并保持不变。 前提用于指定日历系统、时区、一周的起始日和节假日表：

premise JP {
  calendar-system: Gregorian; tz: "Asia/Tokyo"; wkst: Mon
  national = [2026-01-01, 2026-01-12, 2026-02-11, 2026-02-23, 2026-03-20, 2026-04-29, 2026-05-03..2026-05-06,
              2026-07-20, 2026-08-11, 2026-09-21..2026-09-23, 2026-10-12, 2026-11-03, 2026-11-23] covering: 2026..2026
  satSun = everyDay |> filter(d => weekday(d) == Sat or weekday(d) == Sun)
  bizDay = everyDay \ (satSun | national)
}

@JP
everyDay |> within(month) |> last |> roll(Preceding, on: bizDay)

将这段文本与日程定义放在一起，便可把“我们的工作日”这类隐性知识转化为每次调用都能复用的显性知识；而 covering: 子句会在输出的 runwayDays 中标明表格的有效期，避免其在无声无息中失效。

Supply

supply 用静态数据包解析 external(kind: dates | instants) 绑定，与 CLI 的 --supply 完全相同：{ "binding" | "Premise.binding": { "dates": ["YYYY-MM-DD", …] | "instants": [ms, …], "covering": "2026-01-01..2026-12-31", "asof": "2026-10-01" } } — 架构见 https://kairos-lang.org/schema/supply.schema.json。

错误

错误会作为数据返回，而不是协议错误，因此模型可以读取并修复。 kairos_list / kairos_next：{command, version, error: {kind: "usage" | "supply" | "static", message}} 并带有 isError: true。kairos_validate：{ok: false, version, diagnostics: [{kind, message}]}（这是发现项，而不是错误——不带 isError）。对于未知描述符，kairos_reference：{error: {kind: "usage", message}, words}，并带有 isError: true。usage 指调用形式有误（区域无效、时间窗口超过 10 年、来源超过 64 KB），supply 指违反供应约定，static 指语言对定义报告的任何问题（词法、语法、静态规则、求值）。诊断信息为日语——这是参考实现的规范输出语言；报告本身是与语言无关的 JSON（与 CLI 的 --json 相同）。英文规范（https://kairos-lang.org/en/spec/）定义了每条诊断的含义。

限制

求值窗口最多 10 年；n 最多为 1000；horizonYears 最多为 10；source 最多为 64 KB。这些限制旨在防止意外，而非防范攻击者。

名称

此软件包名为 kairos-lang-mcp，是用于 https://kairos-lang.org 上的日程定义语言的 MCP 服务。它与其他使用 Kairos 名称的 npm 软件包（例如 kairos-mcp 或 kairos-mcp-server）无关；那些软件包服务于其他恰好共享该名称的项目。

版本管理

服务的版本与 kairos-lang 保持一致（版本号相同，约定相同）；它依赖 kairos-lang 进行求值，依赖 @modelcontextprotocol/sdk 实现协议。

许可证

Apache-2.0。随附的参考页面和 llms.txt 是本软件包发布时从同一仓库复制的；最新版本见 https://kairos-lang.org/llms.txt 和 https://kairos-lang.org/en/reference/。