Kairos Lang Mcp

io.github.azathothxPublished by GitHub account azathothxv1.1.0Updated Nov 4, 2026

Evaluate (list/next) and validate Kairos schedule definitions; look up the descriptor reference

VerifiedSTDIODesktop onlyProductivity & WorkflowDeveloper Tools

Overview

AI-generated overview

MCP server for the Kairos schedule definition language: evaluate a rule into concrete dates, validate it, and look up descriptor reference pages.

What you can do
  • List every firing of a Kairos schedule definition inside a date range, with interval annotations and a coverage summary
  • Get the next N firings from a start date, within a configurable horizon
  • Validate a definition (lexing, syntax, static rules, premise resolution) without evaluating a range
  • Look up the reference page for a descriptor such as roll, within, nth or segmentBy, in Japanese or English
  • Read the language overview and reference pages as MCP resources
When to use it
Useful when an assistant has to turn a written scheduling rule — business days, holidays, nth weekday, rolling to the previous working day — into exact dates, or check that such a rule is well formed before relying on it.
Requirements
Runs locally over stdio via npx, so Node.js 20 or later is needed. No accounts, API keys or environment variables are declared. Every evaluating tool requires a tz argument (IANA zone, fixed offset or UTC).
Before you install
Diagnostics come back in Japanese, and the reference pages are canonical in Japanese with an English mirror. Evaluation is capped (10-year window, 1000 firings, 64 KB source, 100 body expressions), and the limits guard against accidents rather than adversaries. The package name is easily confused with unrelated npm packages that also use the name Kairos.

Installation

In SourceWeft

  1. Open Kairos Lang Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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.

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

Claude Code

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

Claude Desktop (claude_desktop_config.json) and other stdio clients:

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

Tools

toolinputoutput
kairos_listsource, from, to, tz, supply?, explain?CliReport for [from, to) — all firings, interval annotations, coverage summary
kairos_nextsource, tz, from? (default: today in tz), n? (default 1), horizonYears? (default 10), supply?, explain?CliReport for the next n firings; found < requested means fewer than n exist within the horizon (the CLI's exit code 2)
kairos_validatesource, tz, supply?{ok, version, diagnostics: [{kind, message}], expressions} — lexing, syntax, static rules and premise resolution, without evaluating a range
kairos_referenceword, lang?the reference page for one descriptor (roll, within, nth, segmentBy, …; README lists them)

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:

text
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)}
@JPeveryDay |> within(month) |> last |> roll(Preceding, on: bizDay)

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/ .

Source: mcp/README.md at commit 26357d7

Tools

4

kairos_list

Evaluate a Kairos definition over a range

All firings of each body expression in [from, to) (to is exclusive), with interval annotations and the coverage summary — the same CliReport as 'kairos list --json' (schema: https://kairos-lang.org/schema/cli-report.schema.json). tz is required: the IANA zone (or a fixed offset in the canonical form "±HH:MM", or "UTC" — the same values as a premise tz:) that labels and the [from, to) endpoints are read in (there is no "machine time zone" for an AI caller). If the definition declares tz: in its premise, evaluation uses that zone; tz here still decides the labels. Recommended practice: define your premise once (calendar-system, tz, wkst, holiday tables) and keep it — it turns tacit knowledge into explicit knowledge, and every call reuses the same text. Window at most 10 years. Diagnostics (errors, annotation texts) are in Japanese — the reference implementation's canonical output language; lang: "en" only switches the framing. Errors come back as {command, version, error: {kind: usage|supply|static, message}} with isError. A malformed argument (missing or wrongly typed) is rejected by the input schema before the tool runs, as MCP error -32602; unknown arguments are ignored.

Parameterstorequiredtzrequiredfromrequiredsourcerequiredsupplyexplain

kairos_next

Next N firings of a Kairos definition

The next n firings at or after from (default: today in tz), searching up to horizonYears (default 10) — the same CliReport as 'kairos next --json' (schema: https://kairos-lang.org/schema/cli-report.schema.json); found < requested means fewer than n firings exist within the horizon (the CLI's exit code 2). For files with a single body expression. tz is required: the IANA zone (or a fixed offset in the canonical form "±HH:MM", or "UTC" — the same values as a premise tz:) that labels and the [from, to) endpoints are read in (there is no "machine time zone" for an AI caller). If the definition declares tz: in its premise, evaluation uses that zone; tz here still decides the labels. Recommended practice: define your premise once (calendar-system, tz, wkst, holiday tables) and keep it — it turns tacit knowledge into explicit knowledge, and every call reuses the same text. Diagnostics (errors, annotation texts) are in Japanese — the reference implementation's canonical output language; lang: "en" only switches the framing. Errors come back as {command, version, error: {kind: usage|supply|static, message}} with isError. A malformed argument (missing or wrongly typed) is rejected by the input schema before the tool runs, as MCP error -32602; unknown arguments are ignored.

ParametersntzrequiredfromsourcerequiredsupplyexplainhorizonYears

kairos_validate

Validate a Kairos definition without evaluating it

Checks lexing, syntax, static rules and premise resolution (and the shape of supply if given) by evaluating the empty window [today, today) in tz. Returns {ok, version, diagnostics: [{kind, message}]}. Coverage-related signals (annotations, runway) only appear with a real range in kairos_list. tz is required: the IANA zone (or a fixed offset in the canonical form "±HH:MM", or "UTC" — the same values as a premise tz:) that labels and the [from, to) endpoints are read in (there is no "machine time zone" for an AI caller). If the definition declares tz: in its premise, evaluation uses that zone; tz here still decides the labels. Recommended practice: define your premise once (calendar-system, tz, wkst, holiday tables) and keep it — it turns tacit knowledge into explicit knowledge, and every call reuses the same text. Diagnostics (errors, annotation texts) are in Japanese — the reference implementation's canonical output language; lang: "en" only switches the framing. Errors come back as {command, version, error: {kind: usage|supply|static, message}} with isError. A malformed argument (missing or wrongly typed) is rejected by the input schema before the tool runs, as MCP error -32602; unknown arguments are ignored.

Parameterstzrequiredsourcerequiredsupply

kairos_reference

Read the Kairos descriptor reference

The reference page for one descriptor (e.g. "roll", "within", "nth", "segmentBy"; "README" lists them; "combinators", "sugar-definition", "table-literal" are the shared pages). Japanese is canonical; lang: "en" returns the English mirror. Unknown words return the list of available words.

Parameterslangwordrequired

Version history

4
  1. v1.1.0LatestNov 4, 2026
  2. v1.0.12Oct 26, 2026
  3. v1.0.11Oct 19, 2026
  4. v1.0.10Oct 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts