Bookrail

An agent-bookable holiday-let engine. It lets an AI assistant (Claude, ChatGPT, or anything speaking MCP) check real availability, quote a real price, and request a booking — direct, commission-free, with a human owner approving every single request before anything is confirmed or charged.

This is the code behind bookrail.co.uk. It's live today at Rose Cottage, Fife — believed to be the first holiday let in the UK an AI assistant can book end to end.

This repo is a deliberately curated, sanitized copy of the production codebase: real architecture and logic, fictional example property data, no business records. See What's not here below.

---

Why this exists

More travellers are starting trip planning by asking an AI assistant rather than scrolling a search engine. Most holiday-let websites are readable by an assistant — the text is there — but not bookable: there's no way for the assistant to check a real calendar, get a real price, or actually request a stay. The guest gets bounced back to a contact form, or the property just doesn't come up at all.

Bookrail closes that gap for independent owners, without asking them to give up the one thing that makes a human owner different from a platform: the owner still says yes.

The core idea: agent-bookable, owner-approved

guest's AI assistant                Bookrail engine                 owner's phone
──────────────────────              ────────────────                ─────────────
"find a dog-friendly      ──MCP──▶  check_availability   
 cottage near X for                 get_quote
 these dates"                       get_verified_stay_offer (signed)

"book it"                 ──MCP──▶  request_booking       ──Telegram──▶  Approve / Decline
                                                                              │
                           ◀────────────────── on approve ──────────────────┘
                           Stripe Checkout link (deposit only)
                           ◀── guest pays ── Stripe confirms ──▶ booking confirmed,
                                                                   calendar blocked

Nothing is ever auto-confirmed. request_booking creates a pending hold, not a booking. A human has to tap Approve on their phone before a guest can even see a payment link. This is the one hard rule the whole codebase is built around — see src/holds.js and src/telegram.js.

What an agent actually sees

Four MCP tools, exposed over Streamable HTTP at /mcp (src/mcp.js):

Tool	Does
check_availability	Open date ranges from a live iCal sync (booleans/ranges only — never guest details)
get_quote	Total, deposit, and a breakdown for specific dates
get_verified_stay_offer	The same quote, but cryptographically signed (see below)
request_booking	Creates a pending hold and pings the owner — never confirms anything itself

Before an agent even calls a tool, it can find the property at all via a discovery layer generated straight from the property's config (src/discovery.js):

• /.well-known/agent.json — a machine-readable capabilities card
• /llms.txt — a declarative facts block first, rules after (an assistant that fetches this to answer a question, not to act, needs to find facts in the first screenful — see the comment at the top of that generator)
• schema.org JSON-LD (VacationRental, AggregateOffer) embedded in the actual marketing page, not just a side file
• A public sitemap and robots.txt pointed at all of it

Signed offers (VRP)

get_verified_stay_offer returns an Ed25519-signed JWS, not just a JSON blob (src/vrp.js). An agent that has never talked to this property before can fetch the offer, fetch this domain's public keys from its own /.well-known/jwks.json, and verify the price cryptographically before it acts on it — instead of just trusting whatever a random MCP response says. Field names and the JWKS convention follow an existing published VRP-style convention rather than inventing a new one, so a VRP-aware agent recognises the document; the implementation here is independent.

Pricing has exactly one source of truth — quoteStay() — and every other surface (the MCP tool, the signed offer, the JSON-LD price range) calls through it rather than recomputing anything.

Testing against real AI failures, not just code paths

The test suite (test/discovery.test.js especially) isn't just unit tests — several are regression guards for specific incidents where a real model, live, got something wrong. For example: on one occasion Gemini fetched the live page and told a guest the property was "listed on Airbnb/Booking.com" when it explicitly isn't. That specific hallucination now has a permanent test (anti-hallucination: no OTA listings) checking the correcting statement is present, worded exactly right, and positioned right next to the claim it corrects. When an assistant gets something wrong about the property in the wild, the fix is a config or copy change plus a test that would have caught it — the same discipline as any other regression bug, just triggered by a model instead of a stack trace.

Multi-property, by design

Every property-specific fact lives in one config file (template/property.json, scaffolded per property in properties/) — nothing about a specific property is hardcoded in src/. network/ is a small discovery service that lets multiple properties be found and compared from one endpoint, for a regional network of independent owners rather than a single listing.

Getting started

npm install
npm test                     # 270 tests, all pass against the example property below
cp .env.example .env         # fill in Stripe + Telegram credentials to run for real
npm run migrate
npm start                    # serves the example property on :3000

config/property.json and config/rates.json in this repo are a fully worked fictional example ("Example Cottage") — filled in, not a blank template — so the test suite and a local npm start both work out of the box. template/ has the blank version to copy when setting up a real property.

What's not here

This repo is derived from a live, real business — the production repo also contains real customer/lead data, deployment credentials, infrastructure details, and sales strategy, none of which belongs in a public repo. Deliberately excluded:

• Real property configuration, guest data, and booking records
• Deployment/infrastructure specifics (server details, nginx configs, ops runbooks)
• Business planning, competitive research, and outreach material
• The live marketing site's real content (see bookrail.co.uk and rosecottagefife.co.uk directly instead)

Every example domain, email, phone number, and location in this repo (example-cottage.test, Fiveways, Barleyknowe, etc.) is fictional.

License

PolyForm Noncommercial 1.0.0 — free to read, study, fork, and use for any noncommercial purpose. Not licensed for running a commercial holiday-let booking service, whether that's a direct copy or a substantially similar product. For commercial use, contact hello@bookrail.co.uk.

---

Built by Grant Kirkhope, Fife, Scotland.