webhotelier-mcp

webhotelier-mcp

A read-only Model Context Protocol (MCP) server for theWebHotelier REST API.

It lets an AI assistant (Claude Code, Claude Desktop, or any MCP-compatible client) answerquestions like these with live hotel data:

"Is there a double room at GOLDENSAND for Sep 3–5 for 2 adults, and at what price?""Which days in August still have availability?""What's the cheapest rate this weekend, and what's the cancellation policy?"

The assistant picks the right tool, the server calls WebHotelier, and the answer comes backgrounded in real availability and real prices — not guesses.

Table of contents

• How it works
• The tools
• Quickstart
• Configuration
• Connecting a client
• Architecture
• Design decisions
• Development & testing
• Troubleshooting

How it works

MCP is an open protocol that gives language models a standard way to call external systems.The flow for every question:

┌────────────┐   JSON-RPC over stdio   ┌─────────────┐      HTTPS       ┌──────────────────────────┐
│ MCP client │ ──────────────────────▶ │  server.js  │ ───────────────▶ │ rest.reserve-online.net  │
│ (Claude)   │ ◀────────────────────── │  (this repo)│ ◀─────────────── │ (WebHotelier REST API)   │
└────────────┘    tool results         └─────────────┘   JSON payloads  └──────────────────────────┘

1. On startup, the client launches node server.js as a subprocess and performs the MCPhandshake over stdin/stdout.
2. The server advertises its 8 tools, each with a name, a natural-language description,and a JSON Schema for its parameters. The model reads these to decide when and how tocall each tool.
3. When the model calls a tool, the server validates the arguments (zod), calls theWebHotelier endpoint with HTTP Basic Auth, slims the response (seeDesign decisions), and returns JSON text that lands in the model'scontext.
4. Errors come back as readable results, not crashes — the model sees a message thattells it what to do next (e.g. "Unknown property code — call list_properties for validcodes.").

The tools

All eight tools are read-only. The server implements no write endpoint of any kind.

All dates use YYYY-MM-DD. property is the WebHotelier property code (e.g. GOLDENSAND);the model is instructed to call list_properties first when it doesn't know a code.

* get_reservations requires a WebHotelier account with reservations privileges. Withoutthem the API returns 403 NO_PRIVILEGES, and the tool degrades to a clear message —"The configured WebHotelier account does not have reservations access; all other toolswork normally." If your credentials are later upgraded, the tool starts working with zerocode changes.

Quickstart

Requires Node.js ≥ 20.

git clone <this repo>
cd webhotelier-mcp
npm install
cp .env.example .env    # then fill in WH_USERNAME / WH_PASSWORD
npm run smoke           # optional: verify your credentials against the live API

npm run smoke should end with SMOKE PASS.

Configuration

All configuration lives in .env (gitignored — credentials never enter the repo):

The hotel registry

list_properties reads a local JSON file so the model can discover valid property codesinstead of guessing them. Shape:

{
  "hotels": {
    "my-hotel": {
      "id": "my-hotel",
      "name": "My Hotel",
      "webHotelierCode": "MYHOTEL",
      "rating": 4,
      "active": true
    }
  }
}

Only these five fields are ever exposed — anything else in the file is filtered out (and aunit test enforces that). Without a registry, list_properties explains it is notconfigured; every other tool still works if you already know your property codes.

Connecting a client

Claude Code

Add to your project's .mcp.json (or to ~/.claude.json for user-wide scope):

{
  "mcpServers": {
    "webhotelier": {
      "command": "node",
      "args": ["/absolute/path/to/webhotelier-mcp/server.js"]
    }
  }
}

Restart the session (MCP servers are launched at startup) and check with /mcp — youshould see webhotelier with 8 tools.

Claude Desktop

Add the same entry under mcpServers in claude_desktop_config.json(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), then restartthe app.

Any other MCP client

Anything that speaks MCP over stdio can use this server — point it at node server.jswith the repo as working directory or use absolute paths as above.

Architecture

webhotelier-mcp/
├── server.js           # entry point: McpServer + stdio transport
├── tools.js            # the 8 tool definitions (zod schema + thin handler each)
├── format.js           # response slimming before data reaches model context
├── registry.js         # hotel-registry loader with strict field whitelist
├── errors.js           # WebHotelier errors → actionable text for the model
├── env.js              # dotenv loading (must stay the FIRST import of server.js)
├── lib/
│   └── wh-client.cjs   # vendored WebHotelier REST client (CommonJS)
└── tests/
    ├── unit/           # offline unit tests (node:test, no framework deps)
    ├── fixtures/       # fake registry used by the privacy tests
    └── smoke.js        # live-API smoke test

Everything testable without a network — formatting, registry filtering, error mapping —is a pure module with unit tests. tools.js stays declarative: schema in, client call,slimmed JSON out.

lib/wh-client.cjs is a vendored, battle-tested HTTP client: Basic Auth, requesttimeouts, and a retry policy for transient failures (408/429/5xx and common networkerrors; backoff 500 ms → 1.5 s → 4.5 s, honoring Retry-After on 429). Permanent errors(400/401/403/404) are never retried.

Design decisions

Read-only by construction. The safety guarantee is structural, not a permission flag:no create/modify/cancel endpoint exists anywhere in the codebase, so no prompt or bug canreach one.

Errors are results, not crashes. A tool failure returns isError: true with textwritten for the model: what happened and what to do next. The server process never diesmid-session because one API call failed.

Responses are slimmed for context windows. WebHotelier payloads carry bulk that alanguage model doesn't need: a single property-info response can exceed 100 KB, largelyphoto URLs and HTML descriptions. format.js replaces photo arrays with photo_countand strips/truncates HTML descriptions — while passing every number (prices, allotments,capacities) through untouched. The model should never quote an altered price.

Registry privacy is tested, not promised. The registry loader whitelists five fields;a unit test feeds it a fixture full of fake sensitive data (emails, credential paths) andasserts none of it survives into the output.

stdout is sacred. stdio-transport MCP servers speak JSON-RPC on stdout. A singlestray console.log corrupts the protocol stream — all logging here goes to console.error(stderr), which clients surface as server logs.

Credential loading is order-sensitive. The vendored client computes its Basic-Authheader at module load, so import "./env.js" must remain the first import inserver.js — ESM executes imports in declaration order.

Development & testing

npm test          # offline unit tests (node:test — zero test-framework dependencies)
npm run smoke     # live smoke test: registry, property info, availability, 403 handling
npm run inspect   # MCP Inspector web UI — call tools manually, watch raw JSON-RPC

The MCP Inspector also has a CLI mode, useful for scripted checks:

npx @modelcontextprotocol/inspector --cli node server.js --method tools/list
npx @modelcontextprotocol/inspector --cli node server.js --method tools/call --tool-name list_properties

Troubleshooting