fortrip 0.3.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FortripEngineering
+
+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.

package/README.md

@@ -1,105 +1,216 @@
-# fortrip-cli
+# fortrip
 
-Search, price and book Fortrip hotels from the terminal or an AI agent. The
-The npm package and the command are both `fortrip`.
+Search hotels, check live room rates and book with a payment link, from the
+terminal or an AI agent. Hotels only for now. The npm package and the command
+are both `fortrip`.
 
 ```bash
-npx fortrip login          # sign in through the browser
-npx fortrip search --query Bangkok --check-in 2026-11-10 --check-out 2026-11-12
+npx -y fortrip login
+npx -y fortrip search --query Bangkok --check-in 2026-11-10 --check-out 2026-11-12
 ```
 
-Requires Node.js 22 or newer. No runtime dependencies.
+## Install and run
+
+Node.js 22 or newer. Run it with `npx`, which needs no install:
+
+```bash
+npx -y fortrip <command>
+```
+
+or install it once and run `fortrip <command>`:
+
+```bash
+npm install --global fortrip
+```
+
+`fortrip --help` lists the commands, `fortrip <command> --help` one command's
+flags, and `fortrip --version` prints the version.
+
+Upgrading from 0.3: 1.0 signs in with OAuth, so a 0.3 sign-in is not reused;
+run `fortrip login` once. A `FORTRIP_TOKEN` from 0.3 is no longer accepted.
+`fortrip mcp` replaces the separate `fortrip-mcp` package.
+
+## Sign in
+
+```bash
+fortrip login
+```
+
+`login` prints a code and a link on stderr, opens the link in your browser
+(not with `--no-browser`), and waits until you sign in to Fortrip and approve.
+It then prints your account.
+
+An AI agent can't sit in `login`, so any other command that needs a sign-in
+doesn't wait: it exits with code 3 and prints `loginUrl`, `userCode` and
+`expiresInSeconds` as JSON on stderr. The agent shows the link to the user;
+once the user has approved it in the browser, the agent reruns the same
+command, which finishes signing in and carries on. Commands that run in
+parallel share one link. When Fortrip stops accepting the saved sign-in (it
+was revoked, or it expired and couldn't be renewed), the command does the same
+and keeps the old sign-in until the new link is approved.
+
+You stay signed in. Access tokens last 24 hours and the CLI renews them
+itself, before they run out; refresh tokens don't expire, so the sign-in lasts
+until you run `fortrip logout`, which revokes this machine's sign-in and
+deletes it (other machines stay signed in). `fortrip whoami` prints the
+signed-in account.
+
+The sign-in is saved in `~/.config/fortrip/credentials.json` (`$XDG_CONFIG_HOME`
+is honoured), mode `0600`, per API URL, so a token is only sent to the server
+that issued it.
+
+If a new or renewed sign-in can't be saved (the file stays busy or turns out to
+be damaged), `search`, `hotel`, `rates`, `book` and `whoami` still work for that
+run, with the new token. The sign-in is kept in a `credentials.recovered-*.json`
+file next to the credentials file, and the command's JSON output carries a
+`warning` and, when the sign-in could be kept, that file in `recoveryFile`.
+Later commands use it, and the next successful save merges it back. `login`
+doesn't carry on in that case: it exits 1, with `recoveryFile` in the error, and
+the sign-in is kept in that file all the same.
+
+If the directory itself can't be written (a read-only home, as in some agent
+sandboxes), `login` exits 1 before it asks you to approve anything, and any
+other command that needs to save a sign-in exits 1 too. The error says to set
+`XDG_CONFIG_HOME` to a directory that can be written, or to set `FORTRIP_TOKEN`.
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `login [--no-browser]` | Device-code login: prints a code, opens `/cli/authorize`, waits for you to approve |
-| `logout` | Revokes the saved token on the server and deletes it locally |
-| `whoami` | The signed-in account |
-| `search` | Hotels with indicative prices |
-| `hotel <hotelId> [--with-rooms]` | Static hotel detail |
-| `rates` | Live rooms and rates |
-| `book` | Order + Stripe payment link |
+| `search` | Find hotels with indicative prices |
+| `hotel <hotelId>` | Static hotel detail: description, policies, facilities and photos |
+| `rates` | Live rooms and rates for up to 15 hotels |
+| `book` | Create an order and get a payment link |
+| `login` | Sign in through the browser (device code) |
+| `logout` | Revoke and forget the saved token |
+| `whoami` | Show the signed-in account |
+| `guide [topic]` | Print the guide for AI agents (Markdown) |
+| `mcp` | Run an MCP server over stdio for local clients, bridged to Fortrip's hosted server |
 
-Run `fortrip --help` for every flag. `search`, `rates` and `book` also accept
-`--body '<json>'` or `--body @file.json` with the raw request body; flags
-override its fields.
+```bash
+fortrip rates --hotel <hotelId> --check-in 2026-11-10 --check-out 2026-11-12 --rooms 1 --adults 2
+```
 
-Output is JSON on stdout. Errors are JSON on stderr, with fixed exit codes:
+`search`, `rates` and `book` also accept `--body '<json>'` or
+`--body @file.json` with the raw request body; flags override its fields.
 
-| Code | Meaning |
-|---|---|
-| 0 | Success |
-| 1 | Other error |
-| 2 | Invalid arguments (local or HTTP 400) |
-| 3 | Not logged in / token revoked (HTTP 401) |
-| 4 | Rate limited (HTTP 429; `retryAfterSeconds` on stderr) |
+`--adults` and `--child-age` are per room, and every room has the same
+occupancy: 2 rooms for 4 adults is `--rooms 2 --adults 2`. `rates` and `book`
+both require `--rooms` and `--adults`.
 
-## Credentials
+`book` creates an unpaid order and prints a payment link for it. Nothing is
+charged until the person pays on the page the link opens.
 
-- `login` saves the token to `~/.config/fortrip/credentials.json`
-  (`$XDG_CONFIG_HOME` is honoured), mode `0600`. Tokens are stored per API URL,
-  so a token is only ever sent to the server that issued it.
-- Without a token, any other command starts a device login and exits 3 with
-  `loginUrl` on stderr instead of waiting. Once that link is approved in the
-  browser, rerunning the command saves the token and carries on. This is how
-  AI agents sign in, since they can't sit in `login`.
-- `FORTRIP_TOKEN` overrides the saved login (CI, remote sandboxes).
-- `FORTRIP_API_URL` overrides the base URL (default `https://fortrip.ai`).
-  Plain `http` is only accepted for `localhost`.
-- `FORTRIP_CURRENCY` sets the default `--currency` for `search` and `rates`
-  (`CNY` or `USD`; the API defaults to `CNY`). Display only: `book`
-  charges the currency it returns.
+## For AI agents
 
-Tokens don't expire; `logout` revokes them.
+```bash
+npx -y fortrip guide            # when to use the CLI, call order, sign-in, what to show before a payment link
+npx -y fortrip guide planning   # flexible dates, budgets, split stays, several destinations
+```
+
+Both print Markdown, with `fortrip@latest` replaced by the running version, so
+an agent keeps using the same CLI for the whole conversation. The guide is
+written once in
+[`@fortrip/agent-contract`](https://github.com/FortripEngineering/fortrip/tree/main/packages/contract/guide)
+and compiled into the CLI.
 
-## Agent skill
+For agents that can run shell commands, the same guide is also a skill:
 
 ```bash
-npx skills add FortripEngineering/fortrip-cli
+npx skills add FortripEngineering/fortrip --skill fortrip-cli
 ```
 
-[`skills/fortrip-hotels/SKILL.md`](skills/fortrip-hotels/SKILL.md) only tells
-the agent to run `npx -y fortrip@latest skill`, which prints
-[`AGENT_GUIDE.md`](AGENT_GUIDE.md): when to use the CLI, the call order, login,
-and what to show the user before handing over a payment link. The guide ships
-with the package, so a CLI release updates every installed skill. Edit
-`AGENT_GUIDE.md`, not `SKILL.md`.
-
-`fortrip skill planning` prints [`guides/planning.md`](guides/planning.md):
-what to ask, how to rank and how to present options for flexible dates,
-budgets, split stays and several destinations. Both guides are printed with
-`fortrip@latest` replaced by the running version, so an agent keeps using the
-same CLI for the whole conversation.
+## MCP server
+
+`fortrip mcp` runs an MCP server on stdio for clients that start local
+servers. It forwards to Fortrip's hosted MCP server, `https://fortrip.ai/api/mcp`,
+with your saved sign-in. Sign in once with `npx -y fortrip login` before you
+add the server to a client.
+
+If the client starts the server before you have, the server fails to connect:
+its first request, `initialize`, is answered with a JSON-RPC error (`-32001`)
+whose message says to run `npx -y fortrip login` in a terminal, or to open the
+sign-in link it names and approve it. Clients typically close the connection
+after a failed `initialize`, so sign in (or approve that link), then restart the
+server or reconnect it (`/mcp` in Claude Code). If a sign-in stops working
+later, only the request that hit it fails with the same kind of error, and the
+server keeps running.
+
+Claude Desktop (Settings, Developer, Edit Config; on macOS
+`~/Library/Application Support/Claude/claude_desktop_config.json`, on Windows
+`%APPDATA%\Claude\claude_desktop_config.json`) and Cursor (`~/.cursor/mcp.json`,
+or `.cursor/mcp.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "fortrip": {
+      "command": "npx",
+      "args": ["-y", "fortrip", "mcp"]
+    }
+  }
+}
+```
 
-## Development
+Claude Code:
 
 ```bash
-pnpm install
-pnpm dev search --query Bangkok ...      # run from source
-pnpm test
-pnpm typecheck
-pnpm build                               # dist/cli.js
+claude mcp add fortrip -- npx -y fortrip mcp
 ```
 
-Point at a local Fortrip app with `FORTRIP_API_URL=http://localhost:3000`.
+Codex, with `codex mcp add fortrip -- npx -y fortrip mcp` or in
+`~/.codex/config.toml`:
 
-## Releasing
+```toml
+[mcp_servers.fortrip]
+command = "npx"
+args = ["-y", "fortrip", "mcp"]
+```
+
+Clients that support remote MCP servers with OAuth don't need the CLI: add
+`https://fortrip.ai/api/mcp` as a remote server and sign in to Fortrip in the
+browser when the client asks. In Claude Code, that is
+`claude mcp add --transport http fortrip https://fortrip.ai/api/mcp`.
+
+## Environment variables
+
+| Variable | Meaning |
+|---|---|
+| `FORTRIP_TOKEN` | An access token, used instead of the saved sign-in. It lasts at most 24 hours, so it suits one sandbox session or one CI run, not standing CI. It isn't tied to a server: it is sent to whatever `FORTRIP_API_URL` points at. If Fortrip doesn't accept it, or it contains a line break or another character that can't be sent in a header, commands exit 3 with `tokenSource: "FORTRIP_TOKEN"` and no `loginUrl`; the error never repeats the token. |
+| `FORTRIP_API_URL` | The base URL (default `https://fortrip.ai`). Plain `http` is only accepted for `localhost`. |
+| `FORTRIP_CURRENCY` | The default `--currency` for `search` and `rates` (`CNY` or `USD`; the API uses `CNY` when nothing sets one). It only changes how prices are shown: `book` charges the currency it returns. |
 
-Pushing a `v*` tag publishes to npm through
-[`.github/workflows/publish.yml`](.github/workflows/publish.yml), which signs
-in with npm trusted publishing (no npm token in GitHub).
+## Output and exit codes
+
+Data commands (`search`, `hotel`, `rates`, `book`, `login`, `logout`,
+`whoami`) print JSON on stdout. `guide` prints Markdown, and `fortrip mcp`
+speaks MCP over stdio. Errors are JSON on stderr, with an `error` message, the
+`exitCode` and any details.
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Other error (`retryable: true` on stderr: worth one retry) |
+| 2 | Invalid arguments (local or HTTP 400) |
+| 3 | Not signed in, or the sign-in wasn't accepted (HTTP 401); `loginUrl` on stderr |
+| 4 | Rate limited (HTTP 429; `retryAfterSeconds` on stderr) |
+
+## Support
+
+For changes, cancellations, refunds or other help with a booking, email
+[info@fortrip.ai](mailto:info@fortrip.ai) with the booking's order link
+(`orderUrl`).
+
+## Releasing
 
-1. Bump the version in a PR and merge it into `main`:
-   `npm version minor --no-git-tag-version` (or `patch`).
-2. Tag the merged commit on `main` and push the tag:
+Both packages in this repository, `fortrip` and `@fortrip/agent-contract`,
+are released together from a `vX.Y.Z` tag. See
+[Releasing](https://github.com/FortripEngineering/fortrip#releasing) in the
+repository's README.
 
-   ```bash
-   git checkout main && git pull
-   git tag v0.2.0 && git push origin v0.2.0
-   ```
+## License
 
-The workflow refuses a tag that doesn't match `package.json` or isn't on
-`main`, then runs typecheck, tests and the build before publishing. Every
-installed skill picks up the new guide on its next `npx fortrip@latest skill`.
+The code and documentation in this repository are licensed under the
+[MIT License](https://github.com/FortripEngineering/fortrip/blob/main/LICENSE).
+This license does not grant access to the hosted Fortrip service, hotel
+inventory, or third-party data.