@chrischall/tripadvisor-mcp 0.2.0 → 0.3.0

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.0"
+    "version": "0.3.0"
   },
   "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.0",
+      "version": "0.3.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tripadvisor-mcp",
   "displayName": "TripAdvisor",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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

@@ -34718,8 +34718,12 @@ var API_KEY_RE = new RegExp([
   // webhook signing secret (Stripe-style)
 ].map((p) => `\\b${p}`).join("|"), "g");
 var QUERY_SECRET_RE = /([?&](?:access_token|refresh_token|client_secret|api_?key|signature|token|key|sig)=)[^&#\s"'<>`]+/gi;
+var AWS_SIGV4_RE = /([?&]X-Amz-(?:Signature|Security-Token|Credential)=)[^&#\s"'<>`]+/gi;
+var JSON_SECRET_KEYS = "access_token|refresh_token|client_secret|api_?key|password|passwd|secret|token";
+var JSON_SECRET_DQ_RE = new RegExp(`("(?:${JSON_SECRET_KEYS})"\\s*:\\s*")[^"]*(")`, "gi");
+var JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')[^']*(')`, "gi");
 function redactSecrets(text) {
-  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(JWT_RE, "[REDACTED]");
+  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JWT_RE, "[REDACTED]");
 }
 function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
   const str2 = text === null || text === void 0 ? "" : String(text);
@@ -34795,6 +34799,100 @@ async function loadDotenvSafely(opts = {}) {
     return false;
   }
 }
+function readIntEnv(key, opts = {}) {
+  const raw = readEnvVar(key, opts.env ? { env: opts.env } : {});
+  if (raw === void 0)
+    return opts.default;
+  if (!/^-?\d+$/.test(raw))
+    return opts.default;
+  const n = Number(raw);
+  if (!Number.isSafeInteger(n))
+    return opts.default;
+  const min = opts.min ?? 0;
+  if (n < min)
+    return opts.default;
+  if (opts.max !== void 0 && n > opts.max)
+    return opts.default;
+  return n;
+}
+function readTtlMsEnv(key, defaultMs, opts = {}) {
+  const seconds = readIntEnv(key, { ...opts.env ? { env: opts.env } : {}, min: 0 });
+  return seconds === void 0 ? defaultMs : seconds * 1e3;
+}
+
+// node_modules/@chrischall/mcp-utils/dist/http/response-cache.js
+var RESPONSE_CACHE_MAX_ENTRIES = 256;
+function createResponseCache(opts) {
+  const now = opts.now ?? Date.now;
+  const maxEntries = opts.maxEntries ?? RESPONSE_CACHE_MAX_ENTRIES;
+  const store = /* @__PURE__ */ new Map();
+  const ttlFor = (tier) => opts.ttlMs[tier] ?? 0;
+  function evictForInsert() {
+    if (store.size < maxEntries)
+      return;
+    const t = now();
+    for (const [key, entry] of store) {
+      if (entry.expiresAt <= t)
+        store.delete(key);
+    }
+    while (store.size >= maxEntries) {
+      const oldest = store.keys().next();
+      if (oldest.done)
+        break;
+      store.delete(oldest.value);
+    }
+  }
+  function get(key) {
+    const entry = store.get(key);
+    if (!entry)
+      return void 0;
+    if (entry.expiresAt <= now()) {
+      store.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  function set2(key, value, tier = "dynamic") {
+    const ttl = ttlFor(tier);
+    if (ttl <= 0)
+      return;
+    if (!store.has(key))
+      evictForInsert();
+    else
+      store.delete(key);
+    store.set(key, { expiresAt: now() + ttl, value });
+  }
+  return {
+    get,
+    set: set2,
+    async fetchThrough(key, load, tier = "dynamic") {
+      const hit = get(key);
+      if (hit !== void 0)
+        return hit;
+      const value = await load();
+      set2(key, value, tier);
+      return value;
+    },
+    clear() {
+      store.clear();
+    },
+    get size() {
+      return store.size;
+    }
+  };
+}
+
+// node_modules/@chrischall/mcp-utils/dist/http/net-atoms.js
+function parseRetryAfterMs(header, opts = {}) {
+  const defaultMs = opts.defaultMs ?? 2e3;
+  const capMs = opts.capMs ?? 3e4;
+  if (header == null)
+    return defaultMs;
+  const trimmed = header.trim();
+  if (!/^\d+$/.test(trimmed))
+    return defaultMs;
+  return Math.min(Number(trimmed) * 1e3, capMs);
+}
 
 // node_modules/@chrischall/mcp-utils/dist/http/index.js
 function buildQueryString(params) {
@@ -34841,7 +34939,7 @@ var pageSchema = {
 };
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 
 // src/client.ts
 import { dirname, join } from "node:path";
@@ -34853,33 +34951,24 @@ var SERVICE = "TripAdvisor Terra API";
 var REQUEST_TIMEOUT_MS = 3e4;
 var DEFAULT_CACHE_TTL_MS = 3e5;
 var DEFAULT_STATIC_CACHE_TTL_MS = 36e5;
-var CACHE_MAX_ENTRIES = 256;
 var MAX_RETRY_AFTER_MS = 1e4;
-function readCacheTtlMs(envVar, defaultMs) {
-  const raw = readEnvVar(envVar);
-  if (raw === void 0) return defaultMs;
-  const secs = Number(raw);
-  return Number.isFinite(secs) && secs >= 0 ? secs * 1e3 : defaultMs;
-}
 var TripAdvisorClient = class {
   apiKey;
   configError;
   fetchImpl;
   sleep;
-  cacheTtlMs;
-  staticCacheTtlMs;
-  now;
-  cache = /* @__PURE__ */ new Map();
+  cache;
   /**
    * Defer the config error so the server still boots (and answers the host's
    * install-time tools/list probe) when TRIPADVISOR_API_KEY isn't set yet. The
    * error is re-raised at request time via requireKey().
    */
   constructor(opts = {}) {
-    this.now = opts.now ?? Date.now;
+    const now = opts.now ?? Date.now;
     this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-    this.cacheTtlMs = opts.cacheTtlMs ?? readCacheTtlMs("TRIPADVISOR_CACHE_TTL", DEFAULT_CACHE_TTL_MS);
-    this.staticCacheTtlMs = opts.staticCacheTtlMs ?? readCacheTtlMs("TRIPADVISOR_STATIC_CACHE_TTL", DEFAULT_STATIC_CACHE_TTL_MS);
+    const cacheTtlMs = opts.cacheTtlMs ?? readTtlMsEnv("TRIPADVISOR_CACHE_TTL", DEFAULT_CACHE_TTL_MS);
+    const staticCacheTtlMs = opts.staticCacheTtlMs ?? readTtlMsEnv("TRIPADVISOR_STATIC_CACHE_TTL", DEFAULT_STATIC_CACHE_TTL_MS);
+    this.cache = createResponseCache({ ttlMs: { dynamic: cacheTtlMs, static: staticCacheTtlMs }, now });
     this.fetchImpl = opts.fetchImpl ?? fetch;
     const key = readEnvVar("TRIPADVISOR_API_KEY");
     if (!key) {
@@ -34905,25 +34994,8 @@ var TripAdvisorClient = class {
    * (TRIPADVISOR_CACHE_TTL) is for searches.
    */
   async get(path, opts = {}) {
-    const ttl = opts.cache === "static" ? this.staticCacheTtlMs : this.cacheTtlMs;
-    if (ttl > 0) {
-      const hit = this.cache.get(path);
-      if (hit && hit.expiresAt > this.now()) return hit.value;
-    }
-    const value = await this.request(path);
-    if (ttl > 0) {
-      if (this.cache.size >= CACHE_MAX_ENTRIES) {
-        const t = this.now();
-        for (const [k, v] of this.cache) if (v.expiresAt <= t) this.cache.delete(k);
-        while (this.cache.size >= CACHE_MAX_ENTRIES) {
-          const oldest = this.cache.keys().next().value;
-          if (oldest === void 0) break;
-          this.cache.delete(oldest);
-        }
-      }
-      this.cache.set(path, { expiresAt: this.now() + ttl, value });
-    }
-    return value;
+    const tier = opts.cache === "static" ? "static" : "dynamic";
+    return this.cache.fetchThrough(path, () => this.request(path), tier);
   }
   async request(path, isRetry = false) {
     const key = this.requireKey();
@@ -34932,8 +35004,7 @@ var TripAdvisorClient = class {
     if (res.ok) return await res.json();
     const text = await res.text();
     if (res.status === 429 && !isRetry) {
-      const retryAfter = Number(res.headers.get("retry-after"));
-      const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter * 1e3, MAX_RETRY_AFTER_MS) : 1e3;
+      const delayMs = parseRetryAfterMs(res.headers.get("retry-after"), { defaultMs: 1e3, capMs: MAX_RETRY_AFTER_MS });
       await this.sleep(delayMs);
       return this.request(path, true);
     }
@@ -35202,6 +35273,7 @@ var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "capture_request_header",
   "capture_redirect",
   "read_indexed_db",
+  "read_dom",
   "download"
 ]);
 
@@ -35503,6 +35575,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;
@@ -35578,6 +35688,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");
@@ -35812,6 +35925,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) {
@@ -35837,7 +35965,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)) {
@@ -35922,6 +36050,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");
@@ -36261,6 +36396,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;
 }
 
@@ -36350,7 +36492,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;
@@ -36585,6 +36728,7 @@ async function startPeer(opts) {
     sessionStorageKeys: opts.sessionStorageKeys,
     captureHeaders: opts.captureHeaders,
     indexedDbScopes: opts.indexedDbScopes,
+    domSelectors: opts.domSelectors,
     localStoragePointers: opts.localStoragePointers,
     sessionStoragePointers: opts.sessionStoragePointers
   });
@@ -36992,6 +37136,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
@@ -37112,6 +37261,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));
@@ -37139,7 +37289,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(() => {
@@ -38114,6 +38265,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) {
@@ -38185,7 +38376,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`));
@@ -38511,7 +38702,7 @@ function healthcheckHint(args) {
   return `Unexpected error \u2014 see the error.message field for details.`;
 }
 function registerBridgeHealthcheckTool(args) {
-  const { server, prefix, probePath, hostLabel, transport, probeFn } = args;
+  const { server, prefix, probePath, hostLabel, transport, probeFn, classifyThrown, hints } = args;
   const probeUrl = `https://${hostLabel}${probePath}`;
   server.registerTool(`${prefix}_healthcheck`, {
     title: "Verify the fetchproxy bridge end-to-end",
@@ -38544,16 +38735,39 @@ function registerBridgeHealthcheckTool(args) {
     } : { url: probeUrl, elapsed_ms: probeResult.elapsed_ms };
     let error51;
     let bridgeHint;
+    let customHint;
+    let customDetail;
     if (probeResult.error) {
-      const kind = probeResult.error.kind === "other" ? "unknown" : probeResult.error.kind;
+      let kind = probeResult.error.kind === "other" ? "unknown" : probeResult.error.kind;
       bridgeHint = thrown instanceof FetchproxyBridgeDownError ? thrown.hint : void 0;
+      if (thrown !== void 0 && classifyThrown) {
+        const custom2 = classifyThrown(thrown);
+        if (custom2) {
+          kind = custom2.kind;
+          customHint = custom2.hint;
+          customDetail = custom2.detail;
+        }
+      }
       error51 = {
         kind,
         message: probeResult.error.message,
-        ...bridgeHint !== void 0 ? { bridge_hint: bridgeHint } : {}
+        ...bridgeHint !== void 0 ? { bridge_hint: bridgeHint } : {},
+        ...customDetail !== void 0 ? { detail: customDetail } : {}
       };
     }
     const lastExtensionMessageAt = transport.status().lastExtensionMessageAt;
+    const arm = ok ? "ok" : error51?.kind === "bridge_down" ? "bridge_down" : probeResult.bridge.role === null ? "no_role" : error51?.kind === "timeout" ? "timeout" : error51?.kind === "protocol" || error51?.kind === "http" ? "protocol" : "unknown";
+    const defaultHint = healthcheckHint({
+      ok,
+      role: probeResult.bridge.role,
+      // FIX: the real configured port from bridgeHealth(), not a literal 37149.
+      port: probeResult.bridge.port,
+      hostLabel,
+      prefix,
+      probePath,
+      errorKind: error51?.kind,
+      bridgeHint: error51?.kind === "bridge_down" ? bridgeHint : void 0
+    });
     const result = {
       ok,
       bridge: {
@@ -38562,17 +38776,8 @@ function registerBridgeHealthcheckTool(args) {
       },
       probe,
       ...error51 ? { error: error51 } : {},
-      hint: healthcheckHint({
-        ok,
-        role: probeResult.bridge.role,
-        // FIX: the real configured port from bridgeHealth(), not a literal 37149.
-        port: probeResult.bridge.port,
-        hostLabel,
-        prefix,
-        probePath,
-        errorKind: error51?.kind,
-        bridgeHint: error51?.kind === "bridge_down" ? bridgeHint : void 0
-      })
+      // Precedence: classifyThrown's hint > per-arm override > default ladder.
+      hint: customHint ?? hints?.[arm] ?? defaultHint
     };
     return {
       content: [{ type: "text", text: JSON.stringify(result, null, 2) }]

package/dist/client.js

@@ -1,6 +1,6 @@
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadDotenvSafely, readEnvVar, formatApiError, truncateErrorMessage, McpToolError } from '@chrischall/mcp-utils';
+import { loadDotenvSafely, readEnvVar, readTtlMsEnv, createResponseCache, parseRetryAfterMs, formatApiError, truncateErrorMessage, McpToolError, } from '@chrischall/mcp-utils';
 // Load .env for local dev; silently skip if dotenv is unavailable (e.g. the
 // .mcpb bundle). loadDotenvSafely never lets .env override a host-provided value.
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -15,40 +15,25 @@ const DEFAULT_CACHE_TTL_MS = 300_000;
 // Location details/photos/reviews change slowly — 1 hour by default.
 // Override with TRIPADVISOR_STATIC_CACHE_TTL (seconds; 0 = off).
 const DEFAULT_STATIC_CACHE_TTL_MS = 3_600_000;
-// Bound the cache so a long-lived server doesn't grow unbounded across many
-// distinct paths; oldest entries are evicted first.
-const CACHE_MAX_ENTRIES = 256;
 // Cap a server-supplied Retry-After so one bad header can't stall a tool call.
 const MAX_RETRY_AFTER_MS = 10_000;
-/** Resolve a cache TTL (ms) from an env var holding seconds. A blank or
- * non-numeric value falls back to `defaultMs`; a valid `0` disables caching. */
-function readCacheTtlMs(envVar, defaultMs) {
-    const raw = readEnvVar(envVar);
-    if (raw === undefined)
-        return defaultMs;
-    const secs = Number(raw);
-    return Number.isFinite(secs) && secs >= 0 ? secs * 1000 : defaultMs;
-}
 export class TripAdvisorClient {
     apiKey;
     configError;
     fetchImpl;
     sleep;
-    cacheTtlMs;
-    staticCacheTtlMs;
-    now;
-    cache = new Map();
+    cache;
     /**
      * Defer the config error so the server still boots (and answers the host's
      * install-time tools/list probe) when TRIPADVISOR_API_KEY isn't set yet. The
      * error is re-raised at request time via requireKey().
      */
     constructor(opts = {}) {
-        this.now = opts.now ?? Date.now;
+        const now = opts.now ?? Date.now;
         this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-        this.cacheTtlMs = opts.cacheTtlMs ?? readCacheTtlMs('TRIPADVISOR_CACHE_TTL', DEFAULT_CACHE_TTL_MS);
-        this.staticCacheTtlMs =
-            opts.staticCacheTtlMs ?? readCacheTtlMs('TRIPADVISOR_STATIC_CACHE_TTL', DEFAULT_STATIC_CACHE_TTL_MS);
+        const cacheTtlMs = opts.cacheTtlMs ?? readTtlMsEnv('TRIPADVISOR_CACHE_TTL', DEFAULT_CACHE_TTL_MS);
+        const staticCacheTtlMs = opts.staticCacheTtlMs ?? readTtlMsEnv('TRIPADVISOR_STATIC_CACHE_TTL', DEFAULT_STATIC_CACHE_TTL_MS);
+        this.cache = createResponseCache({ ttlMs: { dynamic: cacheTtlMs, static: staticCacheTtlMs }, now });
         this.fetchImpl = opts.fetchImpl ?? fetch;
         const key = readEnvVar('TRIPADVISOR_API_KEY');
         if (!key) {
@@ -76,31 +61,8 @@ export class TripAdvisorClient {
      * (TRIPADVISOR_CACHE_TTL) is for searches.
      */
     async get(path, opts = {}) {
-        const ttl = opts.cache === 'static' ? this.staticCacheTtlMs : this.cacheTtlMs;
-        if (ttl > 0) {
-            const hit = this.cache.get(path);
-            if (hit && hit.expiresAt > this.now())
-                return hit.value;
-        }
-        const value = await this.request(path);
-        if (ttl > 0) {
-            if (this.cache.size >= CACHE_MAX_ENTRIES) {
-                // Evict expired entries first; if still full, drop the oldest (Map
-                // preserves insertion order, so the first key is the oldest).
-                const t = this.now();
-                for (const [k, v] of this.cache)
-                    if (v.expiresAt <= t)
-                        this.cache.delete(k);
-                while (this.cache.size >= CACHE_MAX_ENTRIES) {
-                    const oldest = this.cache.keys().next().value;
-                    if (oldest === undefined)
-                        break;
-                    this.cache.delete(oldest);
-                }
-            }
-            this.cache.set(path, { expiresAt: this.now() + ttl, value });
-        }
-        return value;
+        const tier = opts.cache === 'static' ? 'static' : 'dynamic';
+        return this.cache.fetchThrough(path, () => this.request(path), tier);
     }
     async request(path, isRetry = false) {
         const key = this.requireKey();
@@ -112,8 +74,7 @@ export class TripAdvisorClient {
             return (await res.json());
         const text = await res.text();
         if (res.status === 429 && !isRetry) {
-            const retryAfter = Number(res.headers.get('retry-after'));
-            const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter * 1000, MAX_RETRY_AFTER_MS) : 1_000;
+            const delayMs = parseRetryAfterMs(res.headers.get('retry-after'), { defaultMs: 1_000, capMs: MAX_RETRY_AFTER_MS });
             await this.sleep(delayMs);
             return this.request(path, true);
         }

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.0'; // x-release-please-version
+export const VERSION = '0.3.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/tripadvisor-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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.10.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.0",
+  "version": "0.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/tripadvisor-mcp",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "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.