Kairos Lang MCP Server

Kairos

決めたら、いつでも。
Write the rule once; list the dates.

English | 日本語版 README（ドキュメントは日本語が正）

The Japanese documentation is canonical; the spec, the descriptor reference, and the stdlib guides are fully mirrored in English under en/ (every page links its counterpart). llms.txt carries the machine-readable overview. Requests and issues in English are welcome — open an issue.

Kairos is a schedule definition language — a small, composable DSL that defines when things should happen. It goes beyond cron-style patterns: schedules like "3 business days before month-end", "the first business day on or after February 1", or dates derived from the lunisolar calendar are all first-class expressions.

premise US { calendar-system: Gregorian; tz: "America/New_York"; wkst: Sun }

@US
federal2026 = [2026-01-01, 2026-01-19, 2026-02-16, 2026-05-25, 2026-06-19, 2026-07-03,
               2026-09-07, 2026-10-12, 2026-11-11, 2026-11-26, 2026-12-25] covering: 2026..2026
bizDay = everyDay \ ((everyDay |> filter(d => weekday(d) == Sat or weekday(d) == Sun)) | federal2026)
monthEnd |> roll(Preceding, on: bizDay) |> shift(-3, unit: bizDay)   # 3 business days before month-end

Try it: Playground · Calendar · What's new in 1.1

cron and iCalendar RRULE can express "N calendar days before month-end", but no existing schedule language lets you write "the Nth business day" inside an expression. The root limitation is not a missing feature — their expressions do not compose: you cannot take the dates one rule derives and feed them into the next rule. Kairos is built around this closure property (every expression is a transformation from a time stream to a time stream), so substitute-holiday derivation, fiscal calendars, the Japanese lunisolar calendar, and the 24 solar terms are all written with the same small operator family.

Highlights

• Business-day arithmetic in the language — roll(Preceding, on: bizDay), shift(-3, unit: bizDay); not a "skip / shift" flag bolted onto an external calendar object.
• Calendars are user-definable — the Gregorian calendar itself is a transparent standard library written in Kairos (stdlib/); fiscal years, ISO weeks, and the Japanese lunisolar calendar (kyūreki) are ordinary definitions, not built-ins.
• Deriving, not enumerating — Japan's substitute holidays and "citizens' holidays" are derived by rule from the statutory holiday table alone; the rokuyō (六曜) cycle is derived from lunar months.
• Deterministic and auditable — a definition denotes a set of instants. Missed fires during downtime are enumerable; evaluation is reproducible.
• Staleness is observable — when calendar data runs out, results carry machine-readable annotations (covering) instead of silently degrading.
• Mistake-proofing as static checks — timezone, granularity, and alignment mismatches, and missing declarations (week start, roll convention, calendar) are errors, not silent misfires.

What an error looks like

Every diagnostic has three parts: operator: what is wrong（how to fix it. where the rule lives）. The text is Japanese (the canonical language); the trailing reference (I3, ADR-38, §3.3) is the spec's own numbering and can be looked up in the English mirror. Three real ones from the reference CLI (unchanged since 1.0.5; checked on 1.1.0):

• roll は規約が必要（I3）——位置引数で Following/Preceding を書くか前文で roll: を宣言 — "roll: a convention is required (I3) — write Following/Preceding as the positional argument, or declare roll: in the premise". Fix: roll(Preceding, on: bizDay), or once in the preamble, @JP roll: Preceding.
• strideBy: 幅は正の量（0 幅は前進しない＝無限ループ。1s・1d のような正の幅を書く。ADR-38 判断 12） — "strideBy: the width must be positive (a zero width never advances = an infinite loop; write a positive width such as 1s or 1d. ADR-38 decision 12)". Fix: strideBy(1d, from: 2026-01-01).
• stride: n は 1 以上の整数（0 は不可。ADR-38 判断 12） — "stride: n is an integer of 1 or more (0 is not allowed. ADR-38 decision 12)". It does not become a silent empty stream. Fix: stride(2, from: 2026-01-05).

The CLI prints the message and exits with code 1; no result is emitted.

Comparison with cron, Quartz, and RRULE

✓ = expressible in the language/definition · △ = partial (hacks, add-ons, implementation-specific) · ✗ = not expressible. "BDC products" = business schedulers with a business-day-calendar object plus shift flags. Full version with section pointers: spec §1.2.

What Kairos deliberately does not do: firing, retries, and execution management (the host runtime's job — the language stops at defining the set of instants); feedback on execution state ("every 5 hours since the last completion" as one infinite stream — instead, computing the next fire from an injected instant is in scope and pure, see spec §7.7); guaranteeing the authenticity of calendar data (provenance source: / asof: carries the evidence; the judgment is external); branching on runtime conditions. (Count-based termination — RRULE COUNT — was on this list until ADR-49: it is now covered by take(n, from:).)

Runtime integration — how a scheduler consumes Kairos

Kairos deliberately stops at defining the set of instants. Your scheduler (the "firing layer") owns timers, retries, and state, and the division of labor is one simple loop — evaluate over a rolling horizon, register timers, repeat:

sequenceDiagram
    participant R as Runtime (firing layer / out of scope)
    participant K as Kairos (pure evaluation)
    loop Rolling horizon
        R->>K: evaluate definition over [from, to)
        K-->>R: list of instants (+ coverage annotations)
        R->>R: register timers → fire … (re-evaluate as "to" nears)
    end
    Note over R,K: every evaluation is a pure function<br/>overlapping ranges always agree (deterministic, auditable)

• Determinism — the same definition, range, and data always yield the same instants; advancing the horizon never changes the overlap. Restarts, replays, and audits are safe.
• Missed fires — evaluate over the downtime window [down, up) and you get exactly the instants that should have fired, as a plain list.
• Operational signal — instants beyond the calendar data's coverage carry machine-readable annotations ("your holiday data needs updating"), instead of silently degrading.

Feedback schedules ("every 5 hours since the last completion") are not a single infinite stream — that would feed outputs back into the expression. Instead the runtime injects the last completion time as data (exactly like a holiday table), and Kairos computes the next fire as a pure function of it:

@US
lastCompleted = [2026-07-09T14:23] covering: ..     # injected by the runtime (with source:/asof:)
lastCompleted |> snapTo(day) |> roll(Following, on: bizDay) |> shift(+3, unit: bizDay)
#=> 2026-07-14   ("3 business days after the last completion")

Full explanation with sequence diagrams and runnable doctests: spec §7.7–7.8; the full worked study is design/40-examples/07 (Japanese). The conformance profile for firing layers — what a Kairos-compatible runtime must satisfy (re-evaluation, at-least-once with idempotency keys, wiring of operational signals) — is spec appendix A (日本語). The matching contract for whoever publishes the tables that external resolves (the static bundle, covering as a completeness claim, asof as a version id, fixed URLs, four acceptance tests that run with the reference CLI alone) — is spec appendix B (日本語).

The language and its implementations

Kairos is a specification (spec/). kairos-lang on npm is its reference implementation — one implementation of the language, not the language. Conformance is defined in appendix A (A.1: the same verdicts, the same instants, the same diagnostic wording, and the doctests of reference/ as the oracle); an independent evaluator that follows the specification runs in production on the supply side (A.7). The parameters the language leaves to each implementation — the evaluation-range floor, the materialisation horizon, the time resolution, the tz database, the point cap — are listed in impl/README.md and are not language constraints (spec §1.4).

Quick start (reference implementation)

Try it in your browser first: the Playground runs the reference implementation as-is — no install, nothing leaves your browser.

Install from npm (Node.js 20+; zero runtime dependencies):

npm i -g kairos-lang                             # or without installing: npx kairos-lang --version
kairos list impl/examples/payday.kairos --from 2026-01-01 --to 2027-01-01
kairos next -n 3 --json impl/examples/payday.kairos   # next 3 firings from today, machine-readable

Windows without Node.js: download kairos-<version>-win-x64.zip (a single kairos.exe, SHA256 listed) from the Releases page and run it as is. Steps: Kairos for Windows administrators.

Reading the output (the design never stays silent, so this is what you see first):

• # ⚠ 範囲外 … (out of coverage) marks an interval computed outside the holiday table; points there have no backing from the table.
• 残走路 N 日 (runway) is how many days the table still covers; negative means the table has run out — extend it (and its covering:).
• 警告: window-clip says a point moved past the edge of the evaluation range and is not in the output — widen the range.
• Dates print in the CLI's time zone (--tz; default = the machine's). If it differs from the premise's tz:, day-level points show a time of day — match the premise's tz: (--tz Asia/Tokyo for payday.kairos, whose premise is Asia/Tokyo).

(impl/examples/ lives in this repository; the npm package ships the CLI and the stdlib. The block below runs the TypeScript source directly, for development.)

Runs TypeScript directly with Node.js 24+; zero runtime dependencies.

cd impl
npm install          # devDependencies only (typescript / vitest)
npm test             # spec examples, real-ephemeris cross-checks, doctests

node src/cli.ts list examples/payday.kairos      --from 2026-01-01 --to 2027-01-01
node src/cli.ts list examples/jp-holidays.kairos --from 2026-01-01 --to 2027-01-01
node src/cli.ts list examples/rokuyo.kairos      --from 2026-01-01 --to 2027-01-01
node src/cli.ts next -n 3 examples/payday.kairos   # next 3 firings from today (--json for machines)

--lang en switches the human-readable framing (headings, coverage summary, usage) to English; evaluator messages stay in Japanese — the implementation's canonical output — and --json is language-neutral.

jp-holidays.kairos derives Japan's substitute holidays and citizens' holidays from the statutory holiday table alone. rokuyo.kairos derives the rokuyō cycle (大安 and friends) from the lunisolar calendar, cut by the National Astronomical Observatory of Japan's new-moon data.

Limits (what it does not do)

• Calendar model: the proleptic Gregorian calendar as an idealisation (the leap-year rule is applied to every year; the 1582 reform is not modelled). Other calendars are built on top of it in the premise layer (spec §3.6).
• No leap seconds: the base axis (chronos) is uniform; 23:59:60 is a lexical error (spec §5, ADR-33). This is a language decision made for determinism, not an implementation limit.
• No sub-millisecond resolution, no real-time control (high-frequency trading, scientific instrumentation): the axis is continuous and the resolution is implementation-defined (1 ms in the reference implementation; a finer literal is a lexical error, never a silent rounding). Placing the instants precisely in real time is the host runtime's job (spec §7.8).
• Years have four digits (0000–9999); 10000-01-01 is a lexical error.
• DST: civil widths (1d) keep wall-clock time, so a civil day may be 23–25 hours; a time literal that falls into a DST gap or overlap is an error, not a guess (spec §3.6, §5; ADR-33, ADR-51). A civil width is a whole number of days (1.5d is an error; write 36h).
• Reference implementation only, not the language: the evaluation range starts at 1970-01-01 (an earlier --from is an explicit error); points are materialised up to to + 400 days and a horizon-clip warning marks that edge; a point that a stage moves out of [from, to) is not in the output and gets a window-clip warning; there is no cap on the number of points — memory grows with the output, and the caller chooses the range (a service front end should bound the range; the language does not); the time resolution is 1 ms (a finer width or seconds fraction is a lexical error, not a silent rounding).
• Out of scope: firing, retries, logging and job execution belong to the host (spec §7.8); Modified roll conventions and the general composition of everyInstant are unimplemented (impl/README).

Status and documentation

Version 1.1 (2026-11-04, 1.1.0): 1.0 is frozen; 2 additive extensions (labelOrdinal, since/before); 1.0 addenda through no. 29 (1.0.12) reflected. Semantics, the operator family, grammar (EBNF), and lexis are frozen; naming is final for every 1.0 word (the last placeholder shiftBoundary was settled as rephase on 2026-07-26), and 1.1 adds labelOrdinal, since and before (record, Japanese). Expressiveness is validated against 20 well-known schedule families and by a reference implementation (981 tests), including cross-checks against the official ephemeris of the National Astronomical Observatory of Japan.

Study materials for the Kairos language exam — graded textbooks (reading, writing, operational semantics) and sample questions, every example executed against the reference implementation — live at exam.kairos-lang.org (Japanese).

License

Apache-2.0 (attribution in NOTICE). Contributions are accepted under Apache-2.0 §5 with a DCO sign-off (Signed-off-by: line). The "Kairos" name and logo (assets/logo/) are excluded from the license (Apache-2.0 §6).