holiplan 0.1.0__tar.gz

holiplan-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,99 @@
+name: publish
+
+# Run it by hand for a dry run: build, upload to TestPyPI and check the package
+# installs and starts. Push a tag like v0.1.0 to do the same and then publish
+# to PyPI. Uploads use trusted publishing (OIDC), so there are no tokens.
+on:
+  workflow_dispatch:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Read the version
+        id: version
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+      - name: Check the tag matches the version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          if [ "${GITHUB_REF_NAME}" != "v${{ steps.version.outputs.version }}" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match pyproject version ${{ steps.version.outputs.version }}"
+            exit 1
+          fi
+      - name: Build
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          # A dry run and the tagged release upload the same version.
+          skip-existing: true
+
+  check-testpypi:
+    needs: [build, testpypi]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install from TestPyPI and start the server
+        run: |
+          # Dependencies come from PyPI; only holiplan comes from TestPyPI.
+          for attempt in 1 2 3 4 5 6; do
+            pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ \
+              "holiplan==${{ needs.build.outputs.version }}" && break
+            echo "Not on the index yet; retrying"; sleep 20
+          done
+          python - <<'EOF'
+          import asyncio
+          from holiplan import server
+          tools = asyncio.run(server.mcp.list_tools())
+          schema = server.profile_schema()
+          assert len(tools) == 9, [t.name for t in tools]
+          print(f"Installed holiplan serves {len(tools)} tools; profile schema {len(schema)} chars")
+          EOF
+
+  pypi:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: check-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

holiplan-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,29 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      # Offline: OpenHolidays is stubbed or replayed from tests/fixtures throughout.
+      - name: Test
+        run: python -m unittest discover -s tests -v

holiplan-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+my-ledger.json

holiplan-0.1.0/CLAUDE.md

@@ -0,0 +1,150 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`holiplan` is a stateless MCP server that helps an assistant plan a family's year around school
+holidays and a limited leave allowance. The server does the arithmetic (leave cost, budget,
+carryover expiry, bridge days, overlaps, deadlines, .ics export); the assistant does the judgement
+(destinations). Holiday data comes from the OpenHolidays API (CC BY 4.0, no key). Attribution is
+required wherever that data is shown, which is why tool results carry a `source` field.
+
+This is Release 1 of a two-release product (MCP server, then a web app on the same engine). The
+ledger schema is the contract between them.
+
+## Commands
+
+A venv already exists at `.venv` (Windows layout: `.venv/Scripts/python`).
+
+```bash
+pip install -e ".[dev]"                                   # install with pytest
+python -m unittest discover -s tests                      # full suite, offline
+python -m unittest tests.test_engine.EffectiveWindowTests # one class
+python -m unittest tests.test_engine.BudgetTests.<test_name>  # one test
+python -m holiplan.server                                 # run the server over stdio (or the `holiplan` script)
+```
+
+Tests prepend `src/` to `sys.path`, so the engine tests run without installing the package. Tests
+that import the server need `mcp` installed and skip themselves otherwise; schema validation tests
+need `jsonschema` (a dependency of `mcp`). `pytest` also works. There is no linter or formatter
+configured.
+
+## Architecture
+
+Two layers with a hard boundary:
+
+- **`src/holiplan/engine/`**: pure, offline, deterministic. `models.py` (dependency-free dataclasses,
+  `migrate`, and a `_build` helper every `from_dict` goes through); `leave.py` (`leave_cost`,
+  `year_budget`); `checks.py` (`validate_ledger`, `deadlines`, `effective_window`,
+  `describe_window`); `bridges.py` (`bridge_days`); `summary.py` (`summarise`); `ics.py` (RFC 5545
+  export). Public holidays are always **passed in**: a `set[str]` of full-day ISO dates, plus an
+  optional `half_holidays` set. The engine never does I/O.
+- **`src/holiplan/holidays.py`**: the OpenHolidays client, with an in-process one-week cache. On a
+  failed fetch it serves the expired cache entry if there is one, otherwise raises
+  `HolidayDataUnavailable` with a message an assistant can relay; a 4xx becomes a `ValueError`
+  about the input. It also owns the data-shaped logic: `resolve_region`, `is_local`, `covers`,
+  `locate`, `is_half_day`, and `holiday_dates` (which filters by all of them).
+- **`src/holiplan/server.py`**: the MCP surface. Each tool resolves its region, fetches what it
+  needs, parses the ledger into models, calls the engine and returns plain dicts. Shared helpers:
+  `_holiday_set` returns `(full, half)` holiday sets filtered by the profile's local-holiday
+  settings; `_padded` widens a year range by a month either side, because windows stretch over
+  holidays just past them (Christmas into January); `_school_windows` merges the per-school-type
+  repeats the data contains; `_described_windows` adds effective dates and sizes; `_validate`
+  backs `check_ledger` and `upsert_trip`, and falls back to date-only checks without a profile.
+
+The server is built on **MCP SDK v2** (`mcp>=2,<3`): `from mcp.server.mcpserver import MCPServer`.
+Do not use the v1 `FastMCP` import. Tools are registered with `@_tool`, not `@mcp.tool()`: SDK v2
+shows the model an exception's text only for `ToolError`, and reports anything else as a bare
+"Error executing tool X". `_tool` re-raises `ValueError` and `HolidayDataUnavailable` as
+`ToolError`, so **errors meant for the user must be one of those two**; any other exception is
+treated as a crash and its message stays on the server. Tool functions stay plain callables, so
+tests call them directly (and see `ToolError`).
+
+### The ledger contract
+
+The ledger is a JSON document owned by the user. The server stores nothing: every tool takes the
+ledger as input, and mutating tools (`upsert_trip`) return a new ledger for the assistant to hand
+back. The server instructions and every prompt tell the assistant to pass the ledger everywhere
+(including the optional `ledger` of `calculate_leave_cost` and `find_bridge_days`) and hand back
+the whole ledger after changes.
+
+The shape is defined twice: `engine/models.py` and `src/holiplan/schemas/ledger.schema.json`
+(profile and trip in `$defs`, also served on their own as `holiplan://schema/profile` and
+`/trip`). `tests/test_contract.py` fails if their fields or choices drift apart, and validates
+round-tripped, starter and example ledgers against the schema. `to_dict` writes `null` for unset
+optional fields, so the schema's optional fields are nullable. Both refuse unknown fields.
+
+**Changing the ledger shape:** a new optional field with a default needs no migration. Anything
+that would make an older ledger read differently needs `SCHEMA_VERSION` bumped and a
+`MIGRATIONS[old_version]` entry in `models.py`; `Ledger.from_dict` runs `migrate` first.
+`examples/ledger.example.json` is the sample; `my-ledger.json` is gitignored.
+
+### OpenHolidays quirks the code relies on
+
+- **Region codes** are OpenHolidays' own where they differ from ISO 3166-2 (Vienna `AT-WI`, not
+  `AT-9`), and an unknown code silently returns only nationwide data. `resolve_region` accepts
+  either form and raises on unknown ones. It reads `/Subdivisions`, so server tests patch
+  `holiplan.holidays.subdivisions` (see `StubbedHolidays` in `tests/test_server.py`).
+- **`nationwide` is not "applies to the whole region"**: Epiphany is `nationwide: false` yet covers
+  all of DE-BY. `is_local` checks whether the `subdivisions` include the region or a parent.
+- **`temporalScope: "HalfDay"`** marks half-day holidays (Zürich's Sechseläuten). They are kept out
+  of the full-day set and cost at most half a day of leave; they don't stretch windows.
+- **School holidays repeat per school-type group** where types differ (Zürich: `CH-ZH-VS` primary,
+  `-MS`, `-BS`). Identical repeats are merged and their `groups` listed; no groups means every
+  school. There is no per-child school type in the profile yet.
+- **Single-day school closures** exist as short school-holiday entries (All Souls' Day in Austria).
+  `describe_window` marks anything with `CLOSURE_MAX_SCHOOL_DAYS` (2) or fewer school days as a
+  closure; `get_holiday_windows` lists those separately. Checks treat closures like any window.
+
+### Domain rules that span files
+
+- **Intent decides leave.** `Trip.consumes_leave` is true for intents `trip`/`obligation`, false for
+  `home`/`camp`, and `takes_leave` overrides it. Budgeting skips non-consuming and `cancelled` trips.
+  A `home` week never gets an "unbooked" deadline.
+- **Leave cost**: weekends (per `DayPattern.workdays`, so part-time patterns work) and public
+  holidays on workdays are free. Personal `half_days` (`"MM-DD"`) and half-day public holidays
+  cost 0.5.
+- **Local holidays**: profile `local_holidays` defaults to `auto`: `_home_locality` resolves `home`
+  against the subdivision tree (`locate`, names in any language, strictly below the region) and
+  keeps only local holidays that `covers` that town. A home the tree doesn't know (Munich) keeps
+  none; no home or bare coordinates keeps all. `include`/`exclude` override, and
+  `ignore_holidays` (`"MM-DD"`, for region-wide entries like Assumption Day that are really local)
+  applies on top.
+- **Budgets are per calendar year.** `year_budget` clips each trip to the year, so a trip over New
+  Year costs each year only its own days. A trip that takes leave in a year with no `LeaveAccount`
+  gets a `no_leave_account` warning.
+- **Carryover** is spent first, but only by trips ending on or before `carryover_expires`. Anything
+  left becomes `carryover_at_risk`. `validate_ledger` turns budget warnings into issues by string
+  prefix (`"Over budget"` means error `over_budget`, anything else is warning `carryover_at_risk`),
+  so changing warning text in `year_budget` changes issue classification.
+- **`effective_window`** stretches an official school window outwards over adjacent weekends and
+  public holidays (Whit Monday before Bavaria's Pentecost window), capped at `_MAX_STRETCH` days.
+  It drives the `outside_school_window` warning, which applies only to intent `trip`.
+- **Bridge days** are gaps of workdays between free runs; an option is one gap or several
+  neighbouring ones within `max_leave`, and must contain a public holiday on a workday. Options
+  overlap by design, ranked by days off per leave day.
+- **Privacy**: children are identified by `alias`, birth year and interests only, never names.
+- The server never books anything. Bookings (`todo`/`booked`, `book_by`, `cancel_by`) only drive
+  `list_deadlines` and the VTODOs in the .ics export. VTODO UIDs are hashes of the deadline's
+  content, so re-importing a calendar updates entries rather than duplicating them. Lines are folded
+  at 75 UTF-8 octets.
+
+### Tests
+
+Expected figures in the golden tests are worked out by hand from the calendar, with the reasoning
+in a comment. A failure means arithmetic a family relies on has broken, so fix the code, not the
+expectation, unless the calendar reasoning itself was wrong.
+
+- `test_engine.py`: the engine over real Bavaria 2027 public holidays and a realistic ledger.
+- `test_holidays.py`: region resolution, local and half-day filtering, and the HTTP layer via
+  httpx's `MockTransport` (caching, outages, stale cache).
+- `test_server.py`: the tools, with the three OpenHolidays calls patched (`StubbedHolidays`).
+- `test_golden_dach.py`: Vienna and Zürich plans against real OpenHolidays responses recorded in
+  `tests/fixtures/` and replayed offline. If you re-record them, re-check every expectation.
+- `test_models.py`: migrations and parse errors. `test_contract.py`: schema versus models,
+  resources, prompts and the tool list.
+- `test_protocol.py`: the server as a subprocess over real MCP stdio (handshake, a scenario across
+  every tool, errors, resources, prompts), launched through `tests/fixture_server.py`, which swaps
+  OpenHolidays for a recorded fixture. About 25 seconds; it's the only slow file. Run the rest
+  with `python -m unittest tests.test_engine tests.test_server ...` when iterating.

holiplan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adekola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

holiplan-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: holiplan
+Version: 0.1.0
+Summary: MCP server for planning a family's year around school holidays and a limited leave allowance
+Project-URL: Homepage, https://github.com/adekola/holiplan
+Project-URL: Issues, https://github.com/adekola/holiplan/issues
+Project-URL: Privacy, https://github.com/adekola/holiplan/blob/main/PRIVACY.md
+Author: adekola
+License: MIT
+License-File: LICENSE
+Keywords: annual leave,bridge days,family,mcp,model-context-protocol,school holidays
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# holiplan
+
+An MCP server for planning a family's year around school holidays and a limited leave allowance.
+
+<!-- mcp-name: io.github.adekola/holiplan -->
+
+Assistants are good at suggesting destinations and bad at remembering that Whit Monday is a
+public holiday, that five carried-over days expire in June, and that you already said no
+drive over three and a half hours. This server does the parts that should be calculated;
+the assistant does the parts that need judgement.
+
+Holiday data comes from [OpenHolidays](https://openholidaysapi.org) (CC BY 4.0), which covers
+public and school holidays for a growing list of countries, with no API key.
+
+## Status
+
+Pre-release (0.1). Stateless: your ledger is a JSON file you keep, and the server stores nothing.
+See [PRIVACY.md](https://github.com/adekola/holiplan/blob/main/PRIVACY.md) for exactly what goes where, and
+[docs/examples.md](https://github.com/adekola/holiplan/blob/main/docs/examples.md) for what a conversation looks like.
+
+## Use it in Claude Desktop
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then add holiplan to
+`claude_desktop_config.json` and restart Claude:
+
+```json
+{
+  "mcpServers": {
+    "holiplan": {
+      "command": "uvx",
+      "args": ["holiplan"]
+    }
+  }
+}
+```
+
+`uvx` fetches holiplan from PyPI and runs it; there is nothing else to install. Without uv,
+`pip install holiplan` and use `"command": "holiplan"` with no `args`.
+
+Start with the **Set up my family profile** prompt, which builds a ledger with you one
+question at a time, or copy [`examples/ledger.example.json`](https://github.com/adekola/holiplan/blob/main/examples/ledger.example.json) to `my-ledger.json` and edit it.
+Tell Claude where the file is, and save the updated ledger whenever Claude hands it back.
+A conversation then looks like:
+
+> Here's my ledger. What do the 2027 school holidays look like, and what can I afford?
+
+> Add two weeks on the Danish coast from 17 July.
+
+> What needs booking next?
+
+[docs/examples.md](https://github.com/adekola/holiplan/blob/main/docs/examples.md) has these conversations in full, with real figures.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `get_holiday_windows` | School holidays (official and effective dates), single-day closures, and public holidays marked local, half-day and observed |
+| `calculate_leave_cost` | Leave days a given trip needs, with the holidays inside it listed |
+| `find_bridge_days` | The leave days that buy the most time off, and whether the kids are off too |
+| `get_year_budget` | Planned versus available leave, including carryover expiry |
+| `upsert_trip` | Add or update a trip, then re-check the ledger |
+| `check_ledger` | Overlaps, budget breaches, bad dates, trips outside school holidays |
+| `list_deadlines` | Booking deadlines and cancel-by dates, soonest first |
+| `summarise_plan` | The whole plan at a glance, for a brief to your partner |
+| `export_ics` | The plan as a calendar file |
+
+Resources: JSON schemas for the ledger, profile and trip (`holiplan://schema/...`), and a blank
+starter ledger (`holiplan://ledger/starter`).
+
+Prompts: *Set up my family profile*, *Plan my year*, *Plan this holiday window*,
+*What needs doing next?*, *Make a brief for my partner*.
+
+## Design notes
+
+- **The ledger is the source of truth.** Tools take it in and hand it back, so the plan
+  doesn't drift between conversations.
+- **Intent decides leave.** A week with intent `home` or `camp` occupies a school holiday
+  window without costing leave. Override with `takes_leave`.
+- **Carryover is spent first**, but only by trips ending before the expiry date, so
+  "these days expire in June" shows up as a warning while you can still act on it.
+- **A trip over New Year** costs each year only its own days.
+- **Local holidays follow your home town.** Some holidays cover only part of a region, like
+  Augsburg's Peace Festival in Bavaria. With the profile's `home` set to a town, only that
+  town's local holidays count as days off; without a home they all do. Set `local_holidays`
+  to `"include"` or `"exclude"` to override. `ignore_holidays` (`"MM-DD"`) covers what the
+  data can't tell apart, such as Assumption Day (`"08-15"`), which is only a holiday in
+  Catholic-majority Bavarian towns.
+- **School windows include the free days around them.** The official Monday-to-Friday dates
+  are stretched over adjacent weekends and public holidays before trips are checked against them.
+  School holidays of two school days or fewer, like All Souls' Day in Austria, are listed
+  separately as closures.
+- **Half-day holidays cost half a day.** Zürich's Sechseläuten afternoon is a half day off,
+  not a full one.
+- **Regions accept ISO codes.** OpenHolidays uses its own codes where they differ (Vienna is
+  `AT-WI`, not `AT-9`); either works, and an unknown region is an error rather than a quietly
+  incomplete year.
+- **Ledgers are versioned.** Older ledgers are migrated when read, a newer one is refused, and
+  a malformed one gets an error naming the trip and field at fault.
+- **When OpenHolidays is down**, the server serves the last copy it fetched, or says plainly
+  that it can't check dates right now. It never guesses.
+- **No real names.** Children are identified by alias and interests only.
+- **The server never books anything.** It knows what needs booking and by when; you book it
+  and record the result.
+
+## Roadmap
+
+- [ ] Drive-time filtering (OpenRouteService or self-hosted OSRM)
+- [ ] Remote deployment over Streamable HTTP
+- [ ] Publish to the MCP registry
+- [ ] School holiday windows by school type, where the data supports it (Zürich splits
+  primary, secondary and vocational; windows already list the types they apply to)
+
+## Development
+
+```bash
+git clone https://github.com/adekola/holiplan.git
+cd holiplan
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+python -m unittest discover -s tests                # offline
+```
+
+To run your working copy in Claude Desktop, point `command` at the venv's Python
+(`.venv/bin/python`, or `.venv\Scripts\python.exe` on Windows) with
+`"args": ["-m", "holiplan.server"]`.
+
+## Licence
+
+MIT, see [LICENSE](https://github.com/adekola/holiplan/blob/main/LICENSE). Holiday data: [OpenHolidays](https://openholidaysapi.org), CC BY 4.0.

holiplan-0.1.0/PRIVACY.md

@@ -0,0 +1,55 @@
+# Privacy
+
+holiplan is built to know as little about your family as it can and to keep nothing.
+
+This note covers the server as you install and run it yourself (stdio, for example in Claude
+Desktop). There is no hosted holiplan endpoint yet; this note will be updated before one exists.
+
+## What holiplan stores
+
+Nothing. The server has no database and writes no files. Your plan lives in a ledger file that
+you keep. Each tool receives the ledger from your assistant, works on it in memory, and hands
+the result back. When the server stops, nothing about you remains in it.
+
+## What the ledger contains
+
+Only what you or your assistant put in it. The format is designed to need very little:
+
+- **Children** are identified by an alias you choose ("older", "A"), and optionally a birth year
+  and interests. Never a name, photo or school.
+- **Where you live** is a region code (such as `DE-BY`) and optionally a home town, used to work
+  out which local holidays apply to you.
+- **Your plan**: trip dates, destinations, booking status and deadlines, and your leave
+  allowance.
+
+## Who sees what
+
+| Recipient | What it receives |
+| --- | --- |
+| Your AI assistant (e.g. Claude) | The whole ledger, because it passes the ledger to the tools. Its provider's privacy terms apply to your conversations. |
+| [OpenHolidays](https://openholidaysapi.org) | Only a country code, a region code, date ranges and a language, to fetch holiday dates. Never your ledger, home town, children or trips. |
+| Anyone else | Nothing. holiplan calls no other service. |
+
+Your home town is matched against OpenHolidays' public list of towns on your own machine; the
+town itself is never sent anywhere.
+
+## Logs
+
+The server writes logs to its standard error, which your assistant app may save (Claude Desktop
+keeps them in its logs folder). They contain:
+
+- the OpenHolidays requests made (country, region, dates), and
+- when a tool call fails, the error message, which can name a trip id or quote a value that was
+  invalid, such as a malformed date.
+
+They never contain the ledger itself. They stay on your machine.
+
+## Booking and payments
+
+holiplan never books anything and never sees payment details or provider accounts. It only
+tracks what you tell it needs booking and by when.
+
+## Holiday data
+
+Holiday data comes from OpenHolidays under CC BY 4.0. It is fetched as needed and cached in
+memory for up to a week.

holiplan-0.1.0/README.md

@@ -0,0 +1,129 @@
+# holiplan
+
+An MCP server for planning a family's year around school holidays and a limited leave allowance.
+
+<!-- mcp-name: io.github.adekola/holiplan -->
+
+Assistants are good at suggesting destinations and bad at remembering that Whit Monday is a
+public holiday, that five carried-over days expire in June, and that you already said no
+drive over three and a half hours. This server does the parts that should be calculated;
+the assistant does the parts that need judgement.
+
+Holiday data comes from [OpenHolidays](https://openholidaysapi.org) (CC BY 4.0), which covers
+public and school holidays for a growing list of countries, with no API key.
+
+## Status
+
+Pre-release (0.1). Stateless: your ledger is a JSON file you keep, and the server stores nothing.
+See [PRIVACY.md](https://github.com/adekola/holiplan/blob/main/PRIVACY.md) for exactly what goes where, and
+[docs/examples.md](https://github.com/adekola/holiplan/blob/main/docs/examples.md) for what a conversation looks like.
+
+## Use it in Claude Desktop
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then add holiplan to
+`claude_desktop_config.json` and restart Claude:
+
+```json
+{
+  "mcpServers": {
+    "holiplan": {
+      "command": "uvx",
+      "args": ["holiplan"]
+    }
+  }
+}
+```
+
+`uvx` fetches holiplan from PyPI and runs it; there is nothing else to install. Without uv,
+`pip install holiplan` and use `"command": "holiplan"` with no `args`.
+
+Start with the **Set up my family profile** prompt, which builds a ledger with you one
+question at a time, or copy [`examples/ledger.example.json`](https://github.com/adekola/holiplan/blob/main/examples/ledger.example.json) to `my-ledger.json` and edit it.
+Tell Claude where the file is, and save the updated ledger whenever Claude hands it back.
+A conversation then looks like:
+
+> Here's my ledger. What do the 2027 school holidays look like, and what can I afford?
+
+> Add two weeks on the Danish coast from 17 July.
+
+> What needs booking next?
+
+[docs/examples.md](https://github.com/adekola/holiplan/blob/main/docs/examples.md) has these conversations in full, with real figures.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `get_holiday_windows` | School holidays (official and effective dates), single-day closures, and public holidays marked local, half-day and observed |
+| `calculate_leave_cost` | Leave days a given trip needs, with the holidays inside it listed |
+| `find_bridge_days` | The leave days that buy the most time off, and whether the kids are off too |
+| `get_year_budget` | Planned versus available leave, including carryover expiry |
+| `upsert_trip` | Add or update a trip, then re-check the ledger |
+| `check_ledger` | Overlaps, budget breaches, bad dates, trips outside school holidays |
+| `list_deadlines` | Booking deadlines and cancel-by dates, soonest first |
+| `summarise_plan` | The whole plan at a glance, for a brief to your partner |
+| `export_ics` | The plan as a calendar file |
+
+Resources: JSON schemas for the ledger, profile and trip (`holiplan://schema/...`), and a blank
+starter ledger (`holiplan://ledger/starter`).
+
+Prompts: *Set up my family profile*, *Plan my year*, *Plan this holiday window*,
+*What needs doing next?*, *Make a brief for my partner*.
+
+## Design notes
+
+- **The ledger is the source of truth.** Tools take it in and hand it back, so the plan
+  doesn't drift between conversations.
+- **Intent decides leave.** A week with intent `home` or `camp` occupies a school holiday
+  window without costing leave. Override with `takes_leave`.
+- **Carryover is spent first**, but only by trips ending before the expiry date, so
+  "these days expire in June" shows up as a warning while you can still act on it.
+- **A trip over New Year** costs each year only its own days.
+- **Local holidays follow your home town.** Some holidays cover only part of a region, like
+  Augsburg's Peace Festival in Bavaria. With the profile's `home` set to a town, only that
+  town's local holidays count as days off; without a home they all do. Set `local_holidays`
+  to `"include"` or `"exclude"` to override. `ignore_holidays` (`"MM-DD"`) covers what the
+  data can't tell apart, such as Assumption Day (`"08-15"`), which is only a holiday in
+  Catholic-majority Bavarian towns.
+- **School windows include the free days around them.** The official Monday-to-Friday dates
+  are stretched over adjacent weekends and public holidays before trips are checked against them.
+  School holidays of two school days or fewer, like All Souls' Day in Austria, are listed
+  separately as closures.
+- **Half-day holidays cost half a day.** Zürich's Sechseläuten afternoon is a half day off,
+  not a full one.
+- **Regions accept ISO codes.** OpenHolidays uses its own codes where they differ (Vienna is
+  `AT-WI`, not `AT-9`); either works, and an unknown region is an error rather than a quietly
+  incomplete year.
+- **Ledgers are versioned.** Older ledgers are migrated when read, a newer one is refused, and
+  a malformed one gets an error naming the trip and field at fault.
+- **When OpenHolidays is down**, the server serves the last copy it fetched, or says plainly
+  that it can't check dates right now. It never guesses.
+- **No real names.** Children are identified by alias and interests only.
+- **The server never books anything.** It knows what needs booking and by when; you book it
+  and record the result.
+
+## Roadmap
+
+- [ ] Drive-time filtering (OpenRouteService or self-hosted OSRM)
+- [ ] Remote deployment over Streamable HTTP
+- [ ] Publish to the MCP registry
+- [ ] School holiday windows by school type, where the data supports it (Zürich splits
+  primary, secondary and vocational; windows already list the types they apply to)
+
+## Development
+
+```bash
+git clone https://github.com/adekola/holiplan.git
+cd holiplan
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+python -m unittest discover -s tests                # offline
+```
+
+To run your working copy in Claude Desktop, point `command` at the venv's Python
+(`.venv/bin/python`, or `.venv\Scripts\python.exe` on Windows) with
+`"args": ["-m", "holiplan.server"]`.
+
+## Licence
+
+MIT, see [LICENSE](https://github.com/adekola/holiplan/blob/main/LICENSE). Holiday data: [OpenHolidays](https://openholidaysapi.org), CC BY 4.0.