API & MCP

Everything a person can do on Bridge-Day Leave Optimizer, a program or AI agent can do with the same inputs and get the identical result.

HTTP API

POST https://hearthleaveoptimizer.usefulweb.app/api/v1/calculate – run Bridge-Day Leave Optimizer
GET https://hearthleaveoptimizer.usefulweb.app/api/v1/tool – inputs, output schema, examples
OpenAPI 3.1: /openapi.json · /openapi.yaml
Errors: application/problem+json; 422 includes per-field errors.

Bridge-Day Leave Optimizer

Takes your number of leave days, the public holidays of your country and region and your weekend, and finds the leave days that give the most days off in breaks — computed exactly, not by trial and error — plus a list of the best bridge days around each holiday.

Inputs of Bridge-Day Leave Optimizer
Field	Type	Default	Description
`country`	select (DE, AT, CH, US, GB, FR, NL, BE, ES, IT, PL, SE, DK, IE, CA, AU)	"DE"	Country
`subdivision`	text	—	State or region (optional). ISO 3166-2 code such as DE-BY (Bavaria) or CH-ZH. Without it only nationwide holidays count.
`from` (required)	date	"2027-01-01"	Period from
`to` (required)	date	"2027-12-31"	Period to
`leaveDays`	integer	10	Leave days to plan
`minBreak`	integer	4	Shortest break worth taking (days off in a row)
`maxBreaks`	integer	0	Most separate breaks (0 = any number)
`weekendDays`	multiselect (sun, mon, tue, wed, thu, fri, sat)	["sat","sun"]	Weekend days
`closures`	list	—	Extra days off without leave (optional). One YYYY-MM-DD per line, for example company closing days.

Example request

Bavaria 2027, 10 leave days

curl -X POST https://hearthleaveoptimizer.usefulweb.app/api/v1/calculate -H 'content-type: application/json' -d '{"country":"DE","subdivision":"DE-BY","from":"2027-01-01","to":"2027-12-31","leaveDays":10,"minBreak":4}'

Every result contains

inputs (normalised, defaults applied), summary, result (validated against the published schema), units, assumptions, sources, warnings, computedAt and links.

MCP (Model Context Protocol)

Streamable HTTP endpoint: https://hearthleaveoptimizer.usefulweb.app/mcp – protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake).
Tools: hearth_leave_optimizer
Local stdio connector: node src/mcp-stdio.ts --tool=hearth-leave-optimizer

{
  "mcpServers": {
    "hearth-leave-optimizer": { "type": "http", "url": "https://hearthleaveoptimizer.usefulweb.app/mcp" }
  }
}