Agents and MCP

Agents-and-MCP

This page describes how software agents are meant to use fiscalclock: only explain and the structured errors exist in 0.1.0, and everything else here is planned for 0.4.

Last reviewed: 1 Nov 2026

The design comes from the research proposal's section on agents. The Roadmap schedules it as Phase 4: v0.4, closed by Gate E.

What exists in 0.1.0

Feature	Status	Where
explain	Built. Returns {"date","calendar_id","steps":[{"level","rule","result"}]} for a date. The rule and result strings are English for people to read; their wording is not part of the API and may change in any release.	spec/api-v1.md
Structured errors	Built. Every error has a stable code, a JSON path, a message, a hint where one helps, and details (for example the candidates of AMBIGUOUS_LABEL).	Error catalogue, ADR-0010
calendar_id	Built. A content hash of the canonical form, so an agent can refer to a calendar across calls and check that two definitions are the same.	ADR-0008
No hidden clock	Built. Every "current" question takes the date as an argument, so repeated runs agree.	ADR-0017

The planned agent contract (0.4)

The proposal names four things an agent needs: a contract it can read, a way to get the right calendar, answers it can check, and errors it can correct itself from. The last is built; the rest is planned.

A machine-readable contract

• JSON Schema for every definition and output, generated from the Rust types and published at a versioned URL (ADR-0009, implementation planned for 0.2, publication for 0.4). Definitions can carry $schema, which the engine already ignores.
• The same names everywhere: an operation means the same thing in Rust, Python, JavaScript, the CLI and the MCP tools.
• llms.txt and Markdown copies of the documentation.

A way to get the right calendar

• infer will take known dates (year ends, quarter ends, example labels) and return every definition that reproduces them, ranked, with the first date where each pair of candidates diverges. Year ends alone fix the anchor but not the subdivision, extra-week placement or naming, so several matches are expected with few inputs (see Risks). The proposal cites ThreeTen-Extra's count of about 8,064 configurations to argue the rule space is small enough to enumerate. The source states "approximately 7 x 2 x 12 x 4 x 12/13 x 2 = 8064", but that product evaluates to 16,128 or 17,472, so the figure is disputed (recorded on the Evidence page).
• A definition registry kept outside the API: a separate, versioned repository of community definitions for real companies and governments. Each entry quotes the filing sentence it encodes and is tested against that filer's reported period ends. The core stays free of presets (ADR-0004). ADR-0027 (Accepted, 1 Nov 2026) puts the registry in a separate repository under the Karthik-beta account, reviewed by CI against each filing's reported dates plus one human approval.
• Filing dates, not EDGAR frames: each filing's own period start and end dates are the input, because SEC frames align facts to calendar periods and can mix different reporting periods.

Answers it can check

• describe will turn a definition into one plain-English paragraph that an agent can show the user to confirm it understood the calendar. The proposal's example: "The fiscal year ends on the Saturday nearest 31 January; the 53rd week is added to period 12; years are named by the calendar year in which they start."
• explain exists today (see above).

The MCP server and CLI (planned for 0.4)

The server will ship inside the npm and PyPI packages, so it runs with npx or uvx and needs no separate install (ADR-0013). Every tool will be read-only and pure, so clients can auto-approve them. Results will carry structured content that matches each tool's output schema, plus the same JSON as text. The CLI will expose the same commands for scripts.

The latest MCP specification revision is 2026-07-28 as of 31 Oct 2026 (specification). The proposal targets that revision; Gate E requires the server to pass the conformance checks of the revision that is current when 0.4 is released, which may be a later one.

Tool	Input	Output
validate_calendar	Definition	ok and calendar_id, or structured errors
describe_calendar	Definition, optional year range	Plain-English summary and year boundaries
infer_calendar	Known year ends, quarter ends or example labels	Ranked candidate definitions and where they diverge
locate_dates	Definition, one or many dates	Every level for each date
get_period	Definition, a label or (level, year, index), optional scheme	The period, its label in each scheme, its flags
list_periods	Definition, date range, level	Periods overlapping the range
split_range	Definition, range, level, basis, optional amount	Days, exact shares and allocated amounts
comparable_period	Definition, period, target year, mode	Comparable period, its bounds and excluded dates
map_period	Two definitions and a period in the first	Overlapping periods in the second, with overlap days

The proposal folds label parsing and formatting into get_period to keep the list to nine tools. split_range depends on proration (0.2), and comparable_period and map_period depend on 0.3 features (see Semantics).

Gate E

From the Roadmap (status Proposed):

1. The MCP server passes the conformance checks of the MCP specification revision current at release, and every tool's output validates against its output schema.
2. infer ranks the correct definition first for every registry entry, given that entry's reported period end dates.
3. Every conformance vector's definition validates against the published JSON Schema.
4. All earlier gate checks still pass.