hostaway-mcp AGENTS.md

Hostaway MCP — Agent Instructions (Canonical)

This is the canonical agent kernel for the hostaway-mcp repo. CLAUDE.md is a thin Claude-specific delta that points back here. Any unique operating signal lives in this file.

This repo owns the open-source Hostaway MCP server: the operator product only — local/npm stdio, a small set of read-only, hospitality-shaped tools.

Scope & Write-Safety Contract (READ FIRST)

This is the safety-critical part of this repo. Get it exactly right.

• main is read-only. There are no write paths and no "safe" exceptions. src/server.ts registers six read tools and nothing else: list_unread_guest_threads, get_conversation_context, get_reservation_brief, get_listing_brief, search_reservations, search_conversations. There is no write-tool registration, no HOSTAWAY_MCP_READONLY flag, and no src/write-infra/ on main.
• No PMS mutation. Sending guest messages and mutating reservations or listings are explicit V1 Non-Goals (see README.md). The server only reads from Hostaway; it never writes to a guest, a reservation, or a listing.
• The only credential is HOSTAWAY_API_TOKEN (required, secret) with an optional HOSTAWAY_BASE_URL override for testing. The token authenticates read requests. Never print, echo, or commit token values, and never read or echo the contents of .mcp.local.json or .mcpregistry_* files.
• Introducing any write path is a [SENSITIVE CHANGE]. If a future plan adds guest messaging, reservation/listing mutation, or any other write surface, it must be an explicit, approved scope change with: a confirmation/dry-run guard so writes never execute by default, an audit trail for every write, rate limiting, and regression tests covering the guard. Do not add write tools as an incidental part of unrelated work, and do not weaken the read-only default. Default to read-only.
• No booking/distribution Worker in this repo. Cloudflare Worker transport and Seascape booking/distribution flows are Non-Goals. Do not add a Worker, wrangler.toml, webhook ingestion, or background sync pipelines here.