io.github.qinisolabs/bizdays

bizdays

Verified business-day math for AI agents — holidays + per-country weekends, not guesses.

Verified, trustworthy data tools for AI agents. "Qiniso" means "truth" in Zulu.

Website · npm · MCP endpoint · MCP Registry

LLMs answer "what date is 5 business days after Dec 22nd in the UK?", "how many working days are in this month?", and "is Friday a working day in Saudi Arabia?" confidently and often wrongly — they miscount, forget public holidays, and assume every country's weekend is Saturday/Sunday. bizdays gives an agent the deterministic answer from real public-holiday calendars and per-country weekend rules, showing the weekend rule and the exact holidays it skipped.

Two things break naive business-day math, and bizdays fixes both: weekends aren't Sat/Sun everywhere (Fri/Sat in Saudi Arabia, Egypt & Israel; Fri in Iran; Sun in India; Sat/Sun in the UAE since 2022), and "holiday" must mean a real day off — off-the-shelf data counts observances like Valentine's Day and Christmas Eve, which are not days off.

Counting the working days in a month, a frontier LLM with no tools is wrong 63% of the time, cold — and 23% across business-day questions overall. bizdays: 0%.

Add it to Claude

Settings → Connectors → Add custom connector, and paste — no login, no key:

https://bizdays.qinisolabs.workers.dev/mcp

Stateless, reads no user data, requires no secrets. Prefer to run it locally over stdio? Add { "command": "npx", "args": ["-y", "@qinisolabs/bizdays"] } under mcpServers in your client config.

Use it as a library

Every tool is also a typed function — no MCP required:

npm i @qinisolabs/bizdays

import { addBusinessDays, countBusinessDays, isBusinessDay } from "@qinisolabs/bizdays";

addBusinessDays("2025-12-22", 5, "GB").result;       // "2025-12-31" (skips Christmas + Boxing Day)
countBusinessDays("2025-12-01", "2025-12-31", "US"); // { businessDays: 22, ... }
isBusinessDay("2025-06-13", "SA").isBusinessDay;      // false — Friday is weekend in Saudi Arabia
isBusinessDay("2025-02-14", "US").isBusinessDay;      // true  — Valentine's Day is not a public holiday

Every function returns a rich result: the answer, the weekday, exactly which weekends and named holidays were skipped, the weekend rule and its source, and a confidence flag.

What it does — 6 tools

Public holidays for 206 countries (and subdivisions) come from date-holidays, filtered to type: "public". Weekends come from Unicode CLDR via the runtime Intl API, plus a curated data/weekend-overrides.json correction layer (e.g. Bangladesh Fri/Sat, Nepal Sat-only) — the maintained data is the moat.

What it is not

• Not all-holidays. It counts weekends and public holidays only — not regional or optional observances. Pass company shutdowns or regional days via extraHolidays.
• Not uniformly verified. A Tier-1 set of ~65 countries is verified; others work but are flagged unverified. Where no holiday calendar exists (e.g. Qatar, Kuwait, Oman), the correct weekend still applies and the response says so (holidaysApplied: false).
• Not a live service dependency. The library makes no network calls; dates are YYYY-MM-DD in UTC.

Architecture

A single TypeScript package exposing one MCP server over two transports — stdio (local / npx) and a Cloudflare Worker (the hosted edge endpoint) — both driven by the same core.ts tool definitions, which also power the importable library.

npm install
npm run build
npm test

Privacy

This tool runs locally on your machine and is built not to collect, store, or transmit your data — no analytics, no telemetry, no account. All reference data is bundled — no network calls, and nothing leaves your device. Full policy: https://qinisolabs.github.io/privacy.html.

License

Apache-2.0. Bundled holiday data is from date-holidays (ISC AND CC-BY-3.0); see NOTICE.