kairos-lang-mcp

kairos-lang-mcp

Kairos（スケジュール定義言語、https://kairos-lang.org）の[MCP](https://modelcontextprotocol.io/)サーバーです。AI クライアントからスケジュール定義を決定論的に評価できます。範囲内のすべての発火、または次の N 件の発火を取得したり、定義を検証したり、記述子のリファレンスを参照したりできます。

このサーバーは、参照実装の CLI を薄くラップしています。ツールは kairos list --json／kairos next --json の出力（CliReport、スキーマは https://kairos-lang.org/schema/cli-report.schema.json）をそのまま返します。ポイントはエポックミリ秒で表され、これが識別子となります。`dates` は一対一で対応する市民暦ラベルです。カバレッジ外の区間は注釈として返され、ポイントが黙って除外されることはありません。

日本語: README.ja.md

インストール

公式 MCP Registry に io.github.azathothx/kairos-lang-mcp として登録されています（https://registry.modelcontextprotocol.io — レジストリに対応したクライアントは、この名前でインストールできます）。

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?	1 つの記述子のリファレンスページ（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-mcp や kairos-mcp-server など、Kairos という名前を持つほかの npm パッケージとは無関係です。これらは、 たまたま同じ名前を共有する別のプロジェクトにサービスを提供しています。

バージョン管理

サーバーのバージョンは kairos-lang に合わせています（番号も契約も同じです）。評価には kairos-lang を、プロトコルには @modelcontextprotocol/sdk を使用します。

ライセンス

Apache-2.0。同梱のリファレンスページと llms.txt は、同じリポジトリから複製したものです。