kairos-lang-mcp
決めたら、いつでも。
Write the rule once; list the dates.
An MCP server for Kairos, the schedule definition language
(https://kairos-lang.org). It lets an AI client evaluate a schedule definition deterministically —
every firing in a range, or the next N — validate a definition, and read the descriptor reference.
The server is a thin wrapper over the reference implementation's CLI: the tools return exactly what
kairos list --json / kairos next --json print (the CliReport, schema at
https://kairos-lang.org/schema/cli-report.schema.json). Points are epoch milliseconds and are the
identity; dates are one-to-one civil labels. Out-of-coverage intervals come back as annotations,
never as silently dropped points.
日本語: README.ja.md
Install
Listed in the official MCP Registry as io.github.azathothx/kairos-lang-mcp (https://registry.modelcontextprotocol.io — clients that read the registry can install it by that name).
Node.js 20 or later. The server speaks MCP over stdio.
Claude Code
Claude Desktop (claude_desktop_config.json) and other stdio clients:
Tools
Resources: kairos://llms.txt (the language overview for AI readers) and
kairos://reference/{ja|en}/{word} (the same pages as kairos_reference).
tz is required
The CLI defaults to the machine's time zone; an AI caller has no machine, so every evaluating tool
takes tz (an IANA name such as Asia/Tokyo; the same values as a premise tz:, so the canonical fixed offset +09:00 and UTC are accepted too). It decides how labels and the [from, to) endpoints
are read. If the definition's premise declares tz:, evaluation uses that zone — tz still labels
the output.
Recommended practice: define your premise once and keep it. A premise names the calendar system,
the zone, the week start and the holiday tables:
Keeping that text next to your schedules turns tacit knowledge ("our business days") into explicit
knowledge that every call reuses — and the covering: clause makes the table's expiry visible in the
output (runwayDays) instead of letting it rot silently.
Supply
supply resolves external(kind: dates | instants) bindings with a static bundle, exactly like the
CLI's --supply: { "binding" | "Premise.binding": { "dates": ["YYYY-MM-DD", …] | "instants": [ms, …], "covering": "2026-01-01..2026-12-31", "asof": "2026-10-01" } } — schema at
https://kairos-lang.org/schema/supply.schema.json.
Errors
Errors are returned as data, not as protocol errors, so the model can read and fix them.
kairos_list / kairos_next: {command, version, error: {kind: "usage" | "supply" | "static", message}}
with isError: true. kairos_validate: {ok: false, version, diagnostics: [{kind, message}]} (a finding, not
an error — no isError). kairos_reference: {error: {kind: "usage", message}, words} with isError: true
for an unknown descriptor. usage is the shape of the call (bad zone, non-existent date, window over 10 years, source over 64 KB,
more than 100 body expressions), supply a violation of the supply contract, static anything the language reports about the definition
(lexing, syntax, static rules, evaluation). Diagnostics are in Japanese — the reference implementation's
canonical output language; the report itself is language-neutral JSON (the same as the CLI's --json).
The spec in English (https://kairos-lang.org/en/spec/) defines what each diagnostic means.
A malformed argument (missing, wrongly typed, from not YYYY-MM-DD) is rejected by the input schema before the tool runs and
comes back as the MCP protocol error -32602. Unknown arguments are ignored.
Limits
Evaluation window at most 10 years; n at most 1000; horizonYears at most 10; source at most
64 KB; at most 100 body expressions per source. These guard against accidents, not against adversaries.
Name
This package is kairos-lang-mcp — the MCP server for the schedule definition language at https://kairos-lang.org.
It is unrelated to other npm packages that carry the name Kairos (such as kairos-mcp or kairos-mcp-server), which
serve other projects that happen to share the word.
Versioning
The server's version tracks kairos-lang (same number, same contract); it depends on
kairos-lang for evaluation and on @modelcontextprotocol/sdk for the protocol.
License
Apache-2.0. The bundled reference pages and llms.txt are copies from the same repository as of this package's release; the latest are at https://kairos-lang.org/llms.txt and https://kairos-lang.org/en/reference/ .
