business-days-mcp

# business-days-mcp

An MCP server for the date arithmetic that support, billing and operations
teams actually do: **is this a working day, when is this SLA due, what is the
next working day after a bank holiday** — plus cron and recurrence-rule
parsing for the recurring side of the same job.

It runs offline. No network calls, no stored data, no model calls — every
answer is computed from bundled public-holiday rules.

## What it does

**Business days and SLAs** — holiday-aware for ~150 countries and their
subdivisions (England and Scotland differ; so do US states), via the
[`holidays`](https://pypi.org/project/holidays/) package.

| Tool | Answers |
| --- | --- |
| `is_business_day` | Is this a working day? If not, is it a weekend or a named holiday? |
| `next_business_day` / `previous_business_day` | The next/last working day around a date |
| `add_business_days` | Move ±N working days from a date |
| `business_days_between` | How many working days between two dates (half-open) |
| `first_business_day_of_month` / `last_business_day_of_month` | Month boundaries |
| `sla_due_time` | When does an N-business-hour SLA fall due, counting only open hours? |

**Cron and recurrence — parsing only.** Nothing is scheduled, stored, or
executed; there are no timers and no job store. If you want something *run* on
a schedule, this is deliberately not that tool.

| Tool | Answers |
| --- | --- |
| `validate_cron_expression` / `explain_cron_expression` | Is this cron valid, and what does it mean in English? |
| `next_cron_occurrences` | When would it next fire? |
| `validate_recurrence_rule` / `explain_recurrence_rule` | Same, for an RFC 5545 RRULE |
| `next_recurrence_occurrences` | Expand an RRULE to its next occurrences |

## Install and run

No install step needed — `uvx` fetches and runs it:

```sh
uvx --from git+https://github.com/Vessark/business-days-mcp business-days-mcp
```

From a clone:

```sh
git clone https://github.com/Vessark/business-days-mcp
cd business-days-mcp
uv sync && uv run business-days-mcp
uv run pytest                         # the tests are the documentation
```

## Client configuration

Add to your MCP client's config (Claude Desktop, or anything that speaks MCP):

```json
{
  "mcpServers": {
    "business-days": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Vessark/business-days-mcp",
        "business-days-mcp"
      ]
    }
  }
}
```

### Hosted

If you'd rather not run it, the same tools are available as a managed HTTP
endpoint at `https://vessark.com/mcp` — no credentials needed for these:

```json
{
  "mcpServers": {
    "vessark": {
      "url": "https://vessark.com/mcp"
    }
  }
}
```

## Examples

```jsonc
// is_business_day — 2026-12-28, UK
{"date": "2026-12-28", "country": "GB"}
→ {"is_business_day": false, "reason": "holiday: Boxing Day (substitute day)"}

// sla_due_time — 8 business hours from Monday 16:00
{"start": "2026-07-27T16:00", "business_hours": 8}
→ {"due": "2026-07-28T16:00:00", "started_within_business_hours": true}

// explain_cron_expression
{"expression": "30 9 * * MON-FRI"}
→ {"explanation": "At 09:30, on Monday through Friday."}
```

## Design notes

Every tool is a pure function of its arguments, which is why the test suite is
mostly tables. Invalid input is an ordinary typed result, never an exception —
a model that gets an argument wrong gets a readable reason and can correct
itself. Every loop that a caller can influence is bounded, so no request can
buy an expensive computation. Error messages never echo what you sent, so the
server can't be used to relay text into someone else's agent.

Known limits, stated rather than hidden: a working week is Monday–Friday, so
countries with Sunday–Thursday weeks are wrong under this assumption; holiday
data covers only the years the underlying dataset knows about, and a date
outside that range is refused rather than silently answered as an ordinary
working day.

## Releasing

Bump the version in both `pyproject.toml` and `server.json`, then push a
matching tag:

```sh
git tag v0.2.0 && git push origin v0.2.0
```

That runs the test suite, checks the tag agrees with both version fields, and
republishes to the MCP registry. Authentication is GitHub OIDC, so no token is
stored anywhere.

## About

Built and maintained by [Vessark](https://vessark.com). The tools in this
repository are the free tier and are open source under the MIT licence.
Vessark's workspace tools — the ones that operate on a connected workspace —
are the commercial product and are not open source.

Issues and pull requests welcome.