@chrischall/tripadvisor-mcp 0.2.1 → 0.3.1

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for the TripAdvisor Terra API — location search, details, photos, and reviews",
-    "version": "0.2.1"
+    "version": "0.3.1"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "TripAdvisor",
       "source": "./",
       "description": "TripAdvisor travel data via the Terra API — search hotels, restaurants, and attractions, with details, photos, and reviews",
-      "version": "0.2.1",
+      "version": "0.3.1",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tripadvisor-mcp",
   "displayName": "TripAdvisor",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "MCP server for the TripAdvisor Terra API — location search, details, photos, and reviews",
   "author": {
     "name": "Chris Hall",
@@ -19,6 +19,6 @@
     "reviews",
     "mcp"
   ],
-  "skills": "./SKILL.md",
+  "skills": "./skills/",
   "mcp": "./.mcp.json"
 }

package/dist/bundle.js

@@ -3776,6 +3776,7 @@ var require_fast_uri = __commonJS({
       return uriTokens.join("");
     }
     var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
+    var AUTHORITY_PREFIX = /^(?:[^#/:?]+:)?\/\/([^/?#]*)/;
     function getParseError(parsed, matches) {
       if (matches[2] !== void 0 && parsed.path && parsed.path[0] !== "/") {
         return 'URI path must start with "/" when authority is present.';
@@ -3805,6 +3806,11 @@ var require_fast_uri = __commonJS({
           uri = "//" + uri;
         }
       }
+      const authorityMatch = uri.match(AUTHORITY_PREFIX);
+      if (authorityMatch !== null && authorityMatch[1].indexOf("\\") !== -1) {
+        parsed.error = "URI authority must not contain a literal backslash.";
+        malformedAuthorityOrPort = true;
+      }
       const matches = uri.match(URI_PARSE);
       if (matches) {
         parsed.scheme = matches[1];
@@ -7693,6 +7699,7 @@ var require_receiver = __commonJS({
         this._opcode = 0;
         this._totalPayloadLength = 0;
         this._messageLength = 0;
+        this._numFragments = 0;
         this._fragments = [];
         this._errored = false;
         this._loop = false;
@@ -8043,23 +8050,23 @@ var require_receiver = __commonJS({
           this.controlMessage(data, cb);
           return;
         }
+        if (this._maxFragments > 0 && ++this._numFragments > this._maxFragments) {
+          const error51 = this.createError(
+            RangeError,
+            "Too many message fragments",
+            false,
+            1008,
+            "WS_ERR_TOO_MANY_BUFFERED_PARTS"
+          );
+          cb(error51);
+          return;
+        }
         if (this._compressed) {
           this._state = INFLATING;
           this.decompress(data, cb);
           return;
         }
         if (data.length) {
-          if (this._maxFragments > 0 && this._fragments.length >= this._maxFragments) {
-            const error51 = this.createError(
-              RangeError,
-              "Too many message fragments",
-              false,
-              1008,
-              "WS_ERR_TOO_MANY_BUFFERED_PARTS"
-            );
-            cb(error51);
-            return;
-          }
           this._messageLength = this._totalPayloadLength;
           this._fragments.push(data);
         }
@@ -8089,17 +8096,6 @@ var require_receiver = __commonJS({
               cb(error51);
               return;
             }
-            if (this._maxFragments > 0 && this._fragments.length >= this._maxFragments) {
-              const error51 = this.createError(
-                RangeError,
-                "Too many message fragments",
-                false,
-                1008,
-                "WS_ERR_TOO_MANY_BUFFERED_PARTS"
-              );
-              cb(error51);
-              return;
-            }
             this._fragments.push(buf);
           }
           this.dataMessage(cb);
@@ -8122,6 +8118,7 @@ var require_receiver = __commonJS({
         this._totalPayloadLength = 0;
         this._messageLength = 0;
         this._fragmented = 0;
+        this._numFragments = 0;
         this._fragments = [];
         if (this._opcode === 2) {
           let data;
@@ -9622,8 +9619,8 @@ var require_websocket = __commonJS({
         autoPong: true,
         closeTimeout: CLOSE_TIMEOUT,
         protocolVersion: protocolVersions[1],
-        maxBufferedChunks: 1024 * 1024,
-        maxFragments: 128 * 1024,
+        maxBufferedChunks: 256 * 1024,
+        maxFragments: 16 * 1024,
         maxPayload: 100 * 1024 * 1024,
         skipUTF8Validation: false,
         perMessageDeflate: true,
@@ -10210,9 +10207,9 @@ var require_websocket_server = __commonJS({
        *     called
        * @param {Function} [options.handleProtocols] A hook to handle protocols
        * @param {String} [options.host] The hostname where to bind the server
-       * @param {Number} [options.maxBufferedChunks=1048576] The maximum number of
+       * @param {Number} [options.maxBufferedChunks=262144] The maximum number of
        *     buffered data chunks
-       * @param {Number} [options.maxFragments=131072] The maximum number of message
+       * @param {Number} [options.maxFragments=16384] The maximum number of message
        *     fragments
        * @param {Number} [options.maxPayload=104857600] The maximum allowed message
        *     size
@@ -10235,8 +10232,8 @@ var require_websocket_server = __commonJS({
         options = {
           allowSynchronousEvents: true,
           autoPong: true,
-          maxBufferedChunks: 1024 * 1024,
-          maxFragments: 128 * 1024,
+          maxBufferedChunks: 256 * 1024,
+          maxFragments: 16 * 1024,
           maxPayload: 100 * 1024 * 1024,
           skipUTF8Validation: false,
           perMessageDeflate: false,
@@ -34939,7 +34936,7 @@ var pageSchema = {
 };
 
 // src/version.ts
-var VERSION = "0.2.1";
+var VERSION = "0.3.1";
 
 // src/client.ts
 import { dirname, join } from "node:path";
@@ -35273,6 +35270,7 @@ var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "capture_request_header",
   "capture_redirect",
   "read_indexed_db",
+  "read_dom",
   "download"
 ]);
 
@@ -35574,6 +35572,44 @@ function assertIndexedDbScopesArray(value, label) {
     }
   }
 }
+var DOM_SELECTOR_RE = /^[^-]{1,512}$/;
+var DOM_ATTRIBUTE_RE = /^[A-Za-z_:][A-Za-z0-9_:.\-]{0,127}$/;
+function assertDomSelectorsArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new ProtocolError(`${label}: expected array, got ${typeof value}`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (let i = 0; i < value.length; i++) {
+    const entry = value[i];
+    assertObject(entry, `${label}[${i}]`);
+    if (entry.name === void 0) {
+      throw new ProtocolError(`${label}[${i}].name: missing`);
+    }
+    if (entry.selector === void 0) {
+      throw new ProtocolError(`${label}[${i}].selector: missing`);
+    }
+    if (typeof entry.name !== "string" || !SCOPE_KEY_RE.test(entry.name)) {
+      throw new ProtocolError(`${label}[${i}].name: invalid ${JSON.stringify(entry.name)}`);
+    }
+    if (typeof entry.selector !== "string" || !DOM_SELECTOR_RE.test(entry.selector)) {
+      throw new ProtocolError(`${label}[${i}].selector: invalid ${JSON.stringify(entry.selector)}`);
+    }
+    if (entry.attribute !== void 0) {
+      if (typeof entry.attribute !== "string" || !DOM_ATTRIBUTE_RE.test(entry.attribute)) {
+        throw new ProtocolError(`${label}[${i}].attribute: invalid ${JSON.stringify(entry.attribute)}`);
+      }
+    }
+    if (seen.has(entry.name)) {
+      throw new ProtocolError(`${label}: duplicate name ${JSON.stringify(entry.name)}`);
+    }
+    seen.add(entry.name);
+    for (const k of Object.keys(entry)) {
+      if (k !== "name" && k !== "selector" && k !== "attribute") {
+        throw new ProtocolError(`${label}[${i}]: unexpected field ${JSON.stringify(k)}`);
+      }
+    }
+  }
+}
 function validateFrame(raw) {
   assertObject(raw, "frame");
   const t = raw.type;
@@ -35649,6 +35685,9 @@ function validateHello(raw) {
     if (raw.sessionStoragePointers !== void 0) {
       assertStoragePointersArray(raw.sessionStoragePointers, "hello.sessionStoragePointers", raw.sessionStorageKeys);
     }
+    if (raw.domSelectors !== void 0) {
+      assertDomSelectorsArray(raw.domSelectors, "hello.domSelectors");
+    }
     assertBase64(raw.identityX25519Pub, "hello.identityX25519Pub");
     assertBase64(raw.identityEd25519Pub, "hello.identityEd25519Pub");
     assertBase64(raw.sessionNonce, "hello.sessionNonce");
@@ -35883,6 +35922,21 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
+  if (raw.op === "read_dom") {
+    assertObject(raw.init, "inner.init");
+    if (raw.init.origin === void 0)
+      throw new ProtocolError("inner.init.origin: missing");
+    if (raw.init.names === void 0)
+      throw new ProtocolError("inner.init.names: missing");
+    assertHttpsOriginOnly(raw.init.origin, "inner.init.origin");
+    assertNonEmptyKeyArray(raw.init.names, "inner.init.names");
+    for (const k of Object.keys(raw.init)) {
+      if (k !== "origin" && k !== "names") {
+        throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on read_dom`);
+      }
+    }
+    return raw;
+  }
   if (raw.op === "download") {
     assertObject(raw.init, "inner.init");
     if (raw.init.url === void 0) {
@@ -35908,7 +35962,7 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
-  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "download"; got ${JSON.stringify(raw.op)}`);
+  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "read_dom", "download"; got ${JSON.stringify(raw.op)}`);
 }
 function assertNonEmptyKeyArray(value, label) {
   if (!Array.isArray(value)) {
@@ -35993,6 +36047,13 @@ function validateInnerResponse(raw) {
       assertObject(raw.values, "inner.values");
       return raw;
     }
+    if (op === "read_dom") {
+      if (raw.values === void 0) {
+        throw new ProtocolError("inner.values: missing on read_dom response");
+      }
+      assertStringMap(raw.values, "inner.values");
+      return raw;
+    }
     if (op === "download") {
       assertObject(raw.value, "inner.value");
       assertString(raw.value.path, "inner.value.path");
@@ -36332,6 +36393,13 @@ async function buildServerHello(opts) {
       jsonPointer: d.jsonPointer
     }));
   }
+  if (opts.domSelectors && opts.domSelectors.length > 0) {
+    hello.domSelectors = opts.domSelectors.map((d) => ({
+      name: d.name,
+      selector: d.selector,
+      ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
+    }));
+  }
   return hello;
 }
 
@@ -36421,7 +36489,8 @@ async function startHost(opts) {
     captureHeaders: opts.ownCaptureHeaders,
     indexedDbScopes: opts.ownIndexedDbScopes,
     localStoragePointers: opts.ownLocalStoragePointers,
-    sessionStoragePointers: opts.ownSessionStoragePointers
+    sessionStoragePointers: opts.ownSessionStoragePointers,
+    domSelectors: opts.ownDomSelectors
   });
   const ownSessionNonce = fromB64(ownHello.sessionNonce);
   let extensionWs = null;
@@ -36656,6 +36725,7 @@ async function startPeer(opts) {
     sessionStorageKeys: opts.sessionStorageKeys,
     captureHeaders: opts.captureHeaders,
     indexedDbScopes: opts.indexedDbScopes,
+    domSelectors: opts.domSelectors,
     localStoragePointers: opts.localStoragePointers,
     sessionStoragePointers: opts.sessionStoragePointers
   });
@@ -37063,6 +37133,11 @@ var FetchproxyServer = class {
         key: d.key,
         jsonPointer: d.jsonPointer
       })),
+      domSelectors: (opts.domSelectors ?? []).map((d) => ({
+        name: d.name,
+        selector: d.selector,
+        ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
+      })),
       // 0.8.0+: timer + lazy-revive default to ON. Every realty MCP
       // adapter was about to set these to the same numbers anyway; the
       // back-door is `0` (explicit opt-out) if a caller genuinely wants
@@ -37183,6 +37258,7 @@ var FetchproxyServer = class {
         ownIndexedDbScopes: this.opts.indexedDbScopes,
         ownLocalStoragePointers: this.opts.localStoragePointers,
         ownSessionStoragePointers: this.opts.sessionStoragePointers,
+        ownDomSelectors: this.opts.domSelectors,
         onPairCode: this.opts.onPairCode
       });
       this.hostHandle.onOwnInner((inner) => this.onInner(inner));
@@ -37210,7 +37286,8 @@ var FetchproxyServer = class {
         captureHeaders: this.opts.captureHeaders,
         indexedDbScopes: this.opts.indexedDbScopes,
         localStoragePointers: this.opts.localStoragePointers,
-        sessionStoragePointers: this.opts.sessionStoragePointers
+        sessionStoragePointers: this.opts.sessionStoragePointers,
+        domSelectors: this.opts.domSelectors
       });
       this.peerHandle.onInner((inner) => this.onInner(inner));
       this.peerHandle.onRenegotiate(() => {
@@ -38185,6 +38262,46 @@ var FetchproxyServer = class {
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingIdb, id, origin);
   }
+  /**
+   * 1.4.0+: read declared DOM values from the user's signed-in tab.
+   * Requires `'read_dom'` in capabilities AND every requested `name` to
+   * match a declared `domSelectors` entry. The extension reads each
+   * declared selector from the matched tab's DOM (isolated-world
+   * `querySelector`, value or attribute) — no page-JS execution.
+   *
+   * Returns a `Record<string, string>` of `name → value`, with names
+   * whose element (or attribute) was absent omitted. Throws
+   * `FetchproxyProtocolError` on bridge failures and a plain `Error` on
+   * developer mistakes (undeclared capability, undeclared name).
+   */
+  async readDom(opts) {
+    if (!this.opts.capabilities.includes("read_dom")) {
+      throw new Error('FetchproxyServer.readDom(): MCP did not declare "read_dom" in capabilities');
+    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    if (!Array.isArray(opts.names) || opts.names.length === 0) {
+      throw new Error("FetchproxyServer.readDom: opts.names must be a non-empty array");
+    }
+    this.assertScopeSubset(opts.names, this.opts.domSelectors.map((d) => d.name), "domSelectors");
+    if (opts.subdomain !== void 0)
+      assertSubdomainLabel(opts.subdomain);
+    const baseDomain = this.resolveBaseDomain(opts.domain);
+    const host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
+    const origin = `https://${host}`;
+    const id = this.nextRequestId++;
+    const inner = {
+      type: "request",
+      id,
+      op: "read_dom",
+      init: { origin, names: [...opts.names] }
+    };
+    const pending = new Promise((resolve, reject) => {
+      this.pendingStorage.set(id, { resolve, reject });
+    });
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingStorage, id, origin);
+  }
   assertScopeSubset(requested, declared, label) {
     const undeclared = undeclaredKeys(requested, declared);
     if (undeclared.length > 0) {
@@ -38256,7 +38373,7 @@ var FetchproxyServer = class {
     if (storageCb) {
       this.pendingStorage.delete(inner.id);
       if (inner.ok) {
-        if ((inner.op === "read_local_storage" || inner.op === "read_session_storage") && inner.values) {
+        if ((inner.op === "read_local_storage" || inner.op === "read_session_storage" || inner.op === "read_dom") && inner.values) {
           storageCb.resolve({ ...inner.values });
         } else {
           storageCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on storage awaiter`));

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Single source of the server version. release-please bumps the literal below. */
-export const VERSION = '0.2.1'; // x-release-please-version
+export const VERSION = '0.3.1'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/tripadvisor-mcp",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "mcpName": "io.github.chrischall/tripadvisor-mcp",
   "description": "TripAdvisor Terra API MCP server for Claude — search locations, details, photos, and reviews. Developed and maintained by AI (Claude Code).",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -31,7 +31,7 @@
   "files": [
     "dist",
     ".claude-plugin",
-    "SKILL.md",
+    "skills",
     ".mcp.json",
     "server.json"
   ],
@@ -44,7 +44,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.12.0",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/server": "^1.3.4",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
@@ -54,7 +54,7 @@
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.2",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.2",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.2"
   },
   "allowScripts": {

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/tripadvisor-mcp",
     "source": "github"
   },
-  "version": "0.2.1",
+  "version": "0.3.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/tripadvisor-mcp",
-      "version": "0.2.1",
+      "version": "0.3.1",
       "transport": {
         "type": "stdio"
       },

package/skills/tripadvisor-api/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: tripadvisor-api
+description: >-
+  Query TripAdvisor location data (search, nearby, details, photos, reviews)
+  straight from a shell with curl against the Terra REST API
+  (terra.tripadvisor.com), instead of running the tripadvisor-mcp server —
+  plus a no-API-key fallback that reads a location's public page through the
+  fpx browser bridge. Use when you want TripAdvisor data without the MCP, in
+  a script, or on a machine where the MCP isn't installed. Triggers on "check
+  TripAdvisor", "TripAdvisor location/restaurant/hotel/attraction search,
+  details, photos, reviews", or any TripAdvisor data request that should hit
+  the API directly.
+---
+
+# TripAdvisor Terra API via curl (no MCP)
+
+TripAdvisor's **Terra** API (`terra.tripadvisor.com/api`) is a plain
+API-key REST API reachable directly from a server or shell — no browser
+bridge needed. This skill shells out to `curl` with the key in an
+`X-API-Key` header, exactly as `tripadvisor-mcp`'s `src/client.ts` does.
+Terra is the current API (the legacy Content API sunsets 2026-08-31); it
+has **no write endpoints** — everything here is a read.
+
+A second, smaller tier at the bottom covers the one thing Terra can't do
+without a key: reading a location's core details from the public
+consumer page via the `fpx` browser bridge.
+
+## One-time setup: get a Terra key
+
+```sh
+# Prefer the env var tripadvisor-mcp itself reads (check its .env first):
+grep -h TRIPADVISOR_API_KEY ~/git/tripadvisor-mcp/.env 2>/dev/null
+export TRIPADVISOR_API_KEY='...'
+```
+
+If you don't have one: create a free **Discover**-tier key at
+https://www.tripadvisor.com/developers (pay-as-you-go, 10 QPS / 10,000
+calls/day). A **legacy** Content API key does NOT work here (and vice
+versa) — a mismatched key gets a `403`.
+
+## Core call pattern
+
+```sh
+BASE=https://terra.tripadvisor.com/api
+
+curl -sS "$BASE/locations/search?query=Golden%20Gate%20Bridge" \
+  -H "X-API-Key: $TRIPADVISOR_API_KEY" -H 'accept: application/json' \
+  | jq '.data[].location | {id, name: (.names[] | select(.primary) | .value)}'
+```
+
+Every call needs just the two headers above — no session/cookie, no
+mutual TLS. Ready-to-run recipes for all 6 endpoints are in
+`references/terra-endpoints.md`.
+
+## The one rule: resolve a location id first
+
+Details/photos/reviews are keyed by numeric `location_id` — get one from
+`ta_search_locations`'s equivalent, `GET /locations/search`, before
+calling the id-scoped endpoints:
+
+```sh
+curl -sS "$BASE/locations/search?query=Golden+Gate+Bridge" \
+  -H "X-API-Key: $TRIPADVISOR_API_KEY" | jq -r '.data[].location.id'
+# 104675
+```
+
+## Response shapes (quick reference)
+
+- List endpoints (`search`, `nearby`, `reviews`, `photos`) wrap results:
+  `{"data": [...], "pagination": {"page","size","total_pages","total_elements"}}`.
+- `GET /locations` (batch) and `GET /locations/{id}` (details) do **not**
+  wrap in `pagination` — batch returns `{"data": [...]}`, details returns
+  the location object directly.
+- A **location** object keys `names`/`descriptions`/`addresses` as
+  **arrays** tagged by language — the primary entry has `"primary": true`
+  (`jq '.names[] | select(.primary) | .value'`), not a flat `name` field.
+
+Full field lists and all 6 curl+jq recipes: `references/terra-endpoints.md`.
+
+## Output / error contract
+
+- A 2xx body is JSON; pipe to `jq`.
+- `400` — validation error; body is `{type, title, status, detail,
+  field_errors: [{field, message}], trace_id}` — `detail`/`field_errors`
+  name the bad param.
+- `401`/`403` — key missing, invalid, or the wrong API family (legacy key
+  on Terra, or vice versa).
+- `404` — unknown id, or a typo'd path (`/locations/{id}` is **plural**;
+  the singular form 404s).
+- `429` — QPS (10) or daily quota (10,000) exceeded on the Discover tier;
+  back off and retry (the response may carry `Retry-After`).
+
+## Fallback tier: no API key (fpx browser bridge)
+
+TripAdvisor's consumer site (`www.tripadvisor.com`) is DataDome-walled, so
+it can't be curled directly — but a location's public detail page is
+plain server-rendered HTML with a clean `application/ld+json` block
+(name, rating, review count, address, phone, coordinates), reachable with
+**no API key** by routing the fetch through your own signed-in browser
+tab via `fpx` (`@fetchproxy/cli`). Use this when you don't have (or don't
+want to use) a Terra key, or `ta_get_location_details` is blocked.
+
+```sh
+npm install -g @fetchproxy/cli                      # provides `fpx`
+fpx profile add tripadvisor --domain tripadvisor.com # fetch capability only
+fpx pair -p tripadvisor                              # prints a pair code → approve in Transporter
+```
+
+Requires the **Transporter** extension with an open `www.tripadvisor.com`
+tab. This covers attractions, hotels, and restaurants — it does **not**
+return individual review text (only the aggregate rating/count). Fetch +
+parse recipe: `references/web-fallback.md`.
+
+### fpx exit codes (fetch verbs)
+
+- `0` — success.
+- `2` — bridge unavailable: extension not connected / pairing pending →
+  `fpx pair -p tripadvisor`.
+- `3` — bot wall: the tab hasn't cleared DataDome → open/refresh a
+  `www.tripadvisor.com` tab and retry.
+- `4` — upstream non-2xx from TripAdvisor.
+
+## Notes
+
+- Terra reads only — nothing here mutates TripAdvisor data.
+- This project (`tripadvisor-mcp`) is developed and maintained by AI
+  (Claude Code).

package/skills/tripadvisor-api/references/terra-endpoints.md

@@ -0,0 +1,118 @@
+# Terra API endpoints (curl + jq)
+
+All paths are relative to `$BASE=https://terra.tripadvisor.com/api`. Every
+call carries `-H "X-API-Key: $TRIPADVISOR_API_KEY" -H 'accept: application/json'`
+(shorthand `"${H[@]}"` below). Shapes captured live with a Discover-plan key;
+transcribed from `tripadvisor-mcp`'s `src/tools/search.ts` + `src/tools/location.ts`
+(each section names its source tool). All 6 are `GET`, all read-only.
+
+```sh
+BASE=https://terra.tripadvisor.com/api
+H=(-H "X-API-Key: $TRIPADVISOR_API_KEY" -H 'accept: application/json')
+```
+
+Categories are `RESTAURANT` | `ATTRACTION` | `HOTEL` (uppercase). `size` on
+list endpoints defaults to 20 and is **capped at 20**.
+
+---
+
+## 1. Location search (`ta_search_locations` / `src/tools/search.ts`)
+
+`GET /locations/search` — `query` (1–500 chars) required; optional
+`category`, `search_type` (default `NAME`), `country_code` (alpha-2),
+`geo_name`, `postal_code` (takes precedence over `geo_name`), `locale`
+(repeated), `page`, `size`.
+
+```sh
+curl -sS "${H[@]}" "$BASE/locations/search?query=Golden+Gate+Bridge&category=ATTRACTION" \
+  | jq '[.data[] | {id: .location.id, name: (.location.names[] | select(.primary) | .value),
+        geo: .location.geo, rating: .location.traveler_ratings.overall.rating}]'
+```
+
+Response: `{"data": [{"location": <Location>, "matched_value": {"language","value"}}], "pagination": {...}}`.
+
+## 2. Nearby search (`ta_search_nearby` / `src/tools/search.ts`)
+
+`GET /locations/nearby` — center is **exactly one** of:
+`lat`+`lon`+`radius` (`unit=MI|KM`, default `MI`), `location_id`+`radius`,
+or the box `sw_lat`,`sw_lon`,`ne_lat`,`ne_lon` (box mode ignores `radius`).
+Plus optional `category`, `min_rating` (1.0–5.0), `include_photo` (bool),
+`sort` (`distance`|`rating`), `page`, `size`, `locale`.
+
+```sh
+# lat/lon + radius
+curl -sS "${H[@]}" "$BASE/locations/nearby?lat=37.8199&lon=-122.4783&radius=5&unit=MI&category=RESTAURANT&sort=rating" \
+  | jq '[.data[] | {id: .location.id, name: (.location.names[] | select(.primary) | .value),
+        distance_mi: .distance_miles, bearing}]'
+
+# location_id + radius (reference location as center)
+curl -sS "${H[@]}" "$BASE/locations/nearby?location_id=104675&radius=2&unit=KM&category=HOTEL" | jq '.data'
+
+# bounding box
+curl -sS "${H[@]}" "$BASE/locations/nearby?sw_lat=37.70&sw_lon=-122.55&ne_lat=37.85&ne_lon=-122.35&category=ATTRACTION" \
+  | jq '.data'
+```
+
+Response item: `{"location": <Location>, "bearing", "distance_miles", "distance_kilometers"}`.
+
+## 3. Batch multi-get (`ta_get_locations` / `src/tools/location.ts`)
+
+`GET /locations` — repeated `id` param (1–50 ids), required; optional
+`locale`. **No `pagination` wrapper.** Unknown/unlicensed ids are silently
+omitted (not an error) — a malformed id, e.g. one exceeding int32, does 400.
+
+```sh
+curl -sS "${H[@]}" "$BASE/locations?id=104675&id=93520&id=423942" \
+  | jq '[.data[] | {id, name: (.names[] | select(.primary) | .value)}]'
+```
+
+Response: `{"data": [<Location>, ...]}` — cheaper than N single-id calls.
+
+## 4. Location details (`ta_get_location_details` / `src/tools/location.ts`)
+
+`GET /locations/{id}` — path `id` (int), **plural** `/locations/{id}` (the
+docs' llms.txt index shows the singular form; that 404s). Optional
+`locale` (repeated).
+
+```sh
+curl -sS "${H[@]}" "$BASE/locations/104675" | jq '{
+  id, geo, name: (.names[] | select(.primary) | .value),
+  rating: .traveler_ratings.overall, address: .addresses[0],
+  phone: .phone_numbers[0].value, url: .urls.tripadvisor.main
+}'
+```
+
+Response: the full `Location` object directly (not wrapped in `data`) —
+`names`/`descriptions`/`addresses` are language-tagged arrays; the primary
+entry has `"primary": true`.
+
+## 5. Location photos (`ta_get_location_photos` / `src/tools/location.ts`)
+
+`GET /locations/{id}/photos` — optional `page`, `size` (max 20), `locale`.
+
+```sh
+curl -sS "${H[@]}" "$BASE/locations/104675/photos?size=10" \
+  | jq '[.data[] | {id, url: .photo.original_size_url, w: .photo.original_width, h: .photo.original_height}]'
+```
+
+Response: `{"data": [{"id","location_id","photo": {"key","original_size_url","original_height","original_width","media_type"}, "publish_ts", "source": {"name"}, "user"}], "pagination": {...}}`.
+
+## 6. Location reviews (`ta_get_location_reviews` / `src/tools/location.ts`)
+
+`GET /locations/{id}/reviews` — optional `page`, `size` (max 20), `locale`.
+
+```sh
+curl -sS "${H[@]}" "$BASE/locations/104675/reviews?size=10" | jq '.data'
+```
+
+Response: `{"data": [...review objects...], "pagination": {...}}`.
+
+---
+
+## Error bodies
+
+- `400` — `{"type","title","status","detail","field_errors": [{"field","message"}],"trace_id"}`.
+- `401`/`403` — `{"Message": "..."}` (a legacy-vs-Terra key mismatch reads
+  as an AWS-gateway "explicit deny" message on the legacy endpoint).
+- `404` — `{"message": "Not Found"}`.
+- `429` — QPS (10) or daily quota (10,000) exceeded on Discover.

package/skills/tripadvisor-api/references/web-fallback.md

@@ -0,0 +1,91 @@
+# Web fallback: location detail via fpx (no API key)
+
+Covers `ta_web_get_location` (`tripadvisor-mcp`'s `src/tools/web.ts` +
+`src/web/parse.ts`) — the one solid endpoint on the consumer site, reached
+with **no Terra key** by routing through your own signed-in browser tab.
+Shapes captured live 2026-07-04; re-verify if parsing drifts (see
+`docs/TRIPADVISOR-WEB-API.md` in the repo for the full recon).
+
+Setup (once): see `../SKILL.md`'s "Fallback tier" section
+(`fpx profile add tripadvisor --domain tripadvisor.com` + `fpx pair -p tripadvisor`).
+
+## Canonical URL — works for every category
+
+TripAdvisor canonicalizes on the `d<id>` segment; the `g<geo>` and the
+`_Review` type prefix are corrected by a same-origin redirect that the
+in-tab fetch follows. **One fixed URL form works whether the id is an
+attraction, hotel, or restaurant** — no need to know the category up front:
+
+```
+https://www.tripadvisor.com/Attraction_Review-g1-d<locationId>-Reviews-a-a.html
+```
+
+## Fetch + parse
+
+```sh
+LOCATION_ID=104675
+fpx get "https://www.tripadvisor.com/Attraction_Review-g1-d${LOCATION_ID}-Reviews-a-a.html" \
+  -p tripadvisor > /tmp/ta-location.html
+
+# The page embeds 3 application/ld+json blocks; the business node is the
+# one with BOTH `name` and `aggregateRating` (its @type varies by category:
+# LocalBusiness=attraction, LodgingBusiness=hotel, FoodEstablishment=restaurant).
+python3 - /tmp/ta-location.html <<'PY'
+import re, json, sys
+html = open(sys.argv[1]).read()
+for m in re.findall(r'<script[^>]*type=["\']application/ld\+json["\'][^>]*>(.*?)</script>', html, re.S | re.I):
+    try:
+        obj = json.loads(m.strip())
+    except Exception:
+        continue
+    if isinstance(obj, dict) and 'name' in obj and 'aggregateRating' in obj:
+        print(json.dumps(obj))
+        break
+PY
+```
+
+Pipe that single-line JSON into `jq` for a slim projection matching what
+`ta_web_get_location` returns:
+
+```sh
+... | jq '{
+  name, type: .["@type"], url,
+  rating: (.aggregateRating.ratingValue | tonumber),
+  review_count: .aggregateRating.reviewCount,
+  best_rating: .aggregateRating.bestRating,
+  telephone, image,
+  latitude: .geo.latitude, longitude: .geo.longitude,
+  same_as: .sameAs, address
+}'
+```
+
+Example fields (attraction, `d104675`):
+
+```jsonc
+{
+  "@type": "LocalBusiness",
+  "name": "Golden Gate Bridge",
+  "url": "https://www.tripadvisor.com/Attraction_Review-g60713-d104675-...html",
+  "address": {"addressLocality": "San Francisco", "addressRegion": "California", "addressCountry": "US", "postalCode": "94129"},
+  "aggregateRating": {"ratingValue": "4.7", "reviewCount": 49969, "bestRating": 5},
+  "image": "https://dynamic-media-cdn.tripadvisor.com/media/photo-o/.../golden-gate-bridge.jpg?...",
+  "telephone": "+1 415-921-5858",
+  "geo": {"latitude": 37.820026, "longitude": -122.47859},
+  "sameAs": "https://www.goldengate.org/"
+}
+```
+
+## Limits
+
+- No key-free search/typeahead endpoint exists — every plausible one
+  (`/TypeAheadJson`, `/data/1.0/typeahead`, `/api/internal/1.14/typeahead`,
+  `/Search?q=`) is a dead end (empty body, 404, needs auth, or a hydrated
+  SPA shell with no SSR data). **Resolve a `locationId` via the Terra
+  `GET /locations/search` endpoint** (`references/terra-endpoints.md` §1),
+  or take it from a TripAdvisor URL, then use this fallback for detail.
+- Individual review **text** is not in the ld+json (no `Review` schema
+  block, no Apollo/redux store) — only the aggregate rating/count. Use the
+  Terra `GET /locations/{id}/reviews` endpoint for review text.
+- If the fetched body isn't valid HTML with an ld+json block (a
+  bot-challenge interstitial slipped through), re-open/refresh the
+  `www.tripadvisor.com` tab and retry.