io.github.CloudCorpRecords/stayport

stayport

stayport talks to a Hostex property-management account from the terminal and from MCP clients: properties and room types, reservations (including direct-booking creation, cancellation, lock codes, and per-stay custom fields), availability, guest conversations, reviews, webhooks, listing calendars and prices, custom channels, and income methods. One binary serves a command-line interface and a stdio MCP server, exposing the same 23 operations as hostex_* tools.

Two credentials are involved. Every v3 API call sends a Hostex-Access-Token header whose value comes from the HOSTEX_ACCESS_TOKEN environment variable; calls go to https://api.hostex.io/v3 unless HOSTEX_API_URL overrides the base URL. When the token is not set, commands fail with an error that names the env var — stayport never invents a result. The guest-review operation is the one exception to the token flow: it posts through the Hostex web app, so it logs in with HOSTEX_EMAIL and HOSTEX_PASSWORD (optionally overriding the web base URL, default https://hostex.io/api, with HOSTEX_WEB_API_URL) and fails the same honest way when they are unset.

A v3 call counts as successful only when the response envelope reports error_code 200; the envelope's data is what you get back. Any other envelope is an error carrying the upstream error_msg and request_id.

Install

npx @reneturcios/stayport properties

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/stayport

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead, and pass the env vars above with -e so the server can reach your account.

CLI

export HOSTEX_ACCESS_TOKEN=...   # from your Hostex account settings

stayport properties --limit 10
stayport room-types
stayport reservations --status accepted --start-check-in-date 2026-11-01
stayport create-reservation --property-id 123 --custom-channel-id 9 \
  --check-in-date 2026-11-10 --check-out-date 2026-11-12 \
  --guest-name "Ada Lovelace" --currency USD --rate-amount 20000 \
  --commission-amount 1000 --received-amount 20000 --income-method-id 3
stayport cancel-reservation RES-123
stayport update-lock-code STAY-9 4321
stayport get-custom-fields STAY-9
stayport update-custom-fields STAY-9 '{"gate_code":"88"}'
stayport availabilities --property-ids 1,2 --start-date 2026-11-01 --end-date 2026-11-07
stayport update-availabilities --property-ids 1,2 --available false --dates 2026-11-03
stayport conversations --limit 5
stayport conversation conv-9
stayport send-message conv-9 --message "Welcome! Check-in is at 3pm."
stayport reviews --property-id 123
stayport create-review RES-123 --score 5 --content "Great guest"
stayport webhooks
stayport create-webhook https://example.com/hook
stayport delete-webhook 17
stayport listing-calendar --start-date 2026-11-01 --end-date 2026-11-30 \
  --listings '[{"channel_type":"airbnb","listing_id":"L1"}]'
stayport update-listing-prices --channel-type airbnb --listing-id L1 \
  --prices '[{"date":"2026-11-05","price":15000}]'
stayport custom-channels
stayport income-methods

stayport --version

The guest-review command additionally needs the web-app login:

export HOSTEX_EMAIL=you@example.com
export HOSTEX_PASSWORD=...
stayport post-guest-review --reservation-order-code 0-ABC123-xyz \
  --content "Lovely stay" --recommend 1 --overall-rating 5 \
  --cleanliness 4 --respect-of-house-rules 5 --communication 5

Successful commands print the response data as JSON. Exit codes: 0 on success, 1 when a call fails (missing credential, upstream envelope error, network failure), 2 for usage errors. Amounts on reservation creation are in cents, exactly as the Hostex API takes them; listing prices are passed through in the shape the API expects.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/stayport mcp

MCP client configuration:

{
  "mcpServers": {
    "stayport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/stayport", "mcp"],
      "env": {
        "HOSTEX_ACCESS_TOKEN": "..."
      }
    }
  }
}

Add HOSTEX_EMAIL and HOSTEX_PASSWORD to that env block if you want the guest-review tool to work; the other 22 tools only need the access token.

Tools

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.