@chrischall/tripadvisor-mcp 0.1.0 → 0.2.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.1.0"
+    "version": "0.2.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.1.0",
+      "version": "0.2.1",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tripadvisor-mcp",
   "displayName": "TripAdvisor",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "MCP server for the TripAdvisor Terra API — location search, details, photos, and reviews",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -26,9 +26,10 @@ Get a key at [tripadvisor.com/developers](https://www.tripadvisor.com/developers
 
 | Tool | What it does |
 | --- | --- |
-| `ta_search_locations` | Search locations by name (optionally scoped by category, country/geo/postal code) — paginated |
-| `ta_search_nearby` | Find locations near a lat/lon within a radius (category, min rating, sort) — paginated |
+| `ta_search_locations` | Search locations by name (optionally scoped by category, country/geo/postal code) — paginated; `compact:true` for slim summaries |
+| `ta_search_nearby` | Find locations near a lat/lon+radius, a `location_id`+radius, or inside a sw/ne bounding box (category, min rating, sort) — `compact:true` supported |
 | `ta_get_location_details` | Full details: names, descriptions, address, coordinates, traveler ratings, phone, listing URLs |
+| `ta_get_locations` | Batch — details for **multiple** location ids in one call (cheaper than N detail calls); `compact:true` supported |
 | `ta_get_location_photos` | Photos with multi-size image URLs, source, and dimensions — paginated |
 | `ta_get_location_reviews` | Traveler reviews — paginated |
 | `ta_web_healthcheck` | Diagnose the optional tripadvisor.com browser-bridge connection (see below) |

package/SKILL.md

@@ -52,9 +52,10 @@ npm install && npm run build
 
 | Tool | Use for |
 | --- | --- |
-| `ta_search_locations` | Find places by name — `query` required; filter with `category` (`RESTAURANT`/`ATTRACTION`/`HOTEL`), `country_code`, `geo_name`, `postal_code`, `locale`; page with `page`/`size` (max 20). Returns matches with a location `id`. |
-| `ta_search_nearby` | Find places near coordinates — `lat`+`lon`+`radius` required (`unit` `MI`/`KM`); filter `category`, `min_rating`, `sort` (`distance`/`rating`), `include_photo`. |
+| `ta_search_locations` | Find places by name — `query` required; filter with `category` (`RESTAURANT`/`ATTRACTION`/`HOTEL`), `country_code`, `geo_name`, `postal_code`, `locale`; page with `page`/`size` (max 20). `compact:true` → slim summaries. Returns matches with a location `id`. |
+| `ta_search_nearby` | Find places near a center — supply **one** of: `lat`+`lon`+`radius`, `location_id`+`radius`, or a `sw_lat`/`sw_lon`/`ne_lat`/`ne_lon` box (`unit` `MI`/`KM`); filter `category`, `min_rating`, `sort` (`distance`/`rating`), `include_photo`. `compact:true` supported. |
 | `ta_get_location_details` | Full listing for a location `id`: names, descriptions, address, coordinates, traveler ratings, phone, URLs. Optional `locale`. |
+| `ta_get_locations` | Batch details for **multiple** ids (`ids: [..]`, 1–50) in one call — cheaper than repeated details; unknown ids are omitted. `compact:true` supported. |
 | `ta_get_location_photos` | Photos (multi-size URLs, source, dimensions). Page with `page`/`size`. |
 | `ta_get_location_reviews` | Traveler reviews. Page with `page`/`size`. |
 | `ta_web_healthcheck` | Diagnose the optional tripadvisor.com browser-bridge connection (fetchproxy Transporter). Reports bridge role/port/timing and an actionable hint if it's not connected. |

package/dist/bundle.js

@@ -108,7 +108,7 @@ var require_code = __commonJS({
     }
     exports._ = _;
     var plus = new _Code("+");
-    function str(strs, ...args) {
+    function str2(strs, ...args) {
       const expr = [safeStringify(strs[0])];
       let i = 0;
       while (i < args.length) {
@@ -119,7 +119,7 @@ var require_code = __commonJS({
       optimize(expr);
       return new _Code(expr);
     }
-    exports.str = str;
+    exports.str = str2;
     function addCodeArg(code, arg) {
       if (arg instanceof _Code)
         code.push(...arg._items);
@@ -162,7 +162,7 @@ var require_code = __commonJS({
       return;
     }
     function strConcat(c1, c2) {
-      return c2.emptyStr() ? c1 : c1.emptyStr() ? c2 : str`${c1}${c2}`;
+      return c2.emptyStr() ? c1 : c1.emptyStr() ? c2 : str2`${c1}${c2}`;
     }
     exports.strConcat = strConcat;
     function interpolate(x) {
@@ -1124,22 +1124,22 @@ var require_util = __commonJS({
       return (0, codegen_1._)`${topSchemaRef}${schemaPath}${(0, codegen_1.getProperty)(keyword)}`;
     }
     exports.schemaRefOrVal = schemaRefOrVal;
-    function unescapeFragment(str) {
-      return unescapeJsonPointer(decodeURIComponent(str));
+    function unescapeFragment(str2) {
+      return unescapeJsonPointer(decodeURIComponent(str2));
     }
     exports.unescapeFragment = unescapeFragment;
-    function escapeFragment(str) {
-      return encodeURIComponent(escapeJsonPointer(str));
+    function escapeFragment(str2) {
+      return encodeURIComponent(escapeJsonPointer(str2));
     }
     exports.escapeFragment = escapeFragment;
-    function escapeJsonPointer(str) {
-      if (typeof str == "number")
-        return `${str}`;
-      return str.replace(/~/g, "~0").replace(/\//g, "~1");
+    function escapeJsonPointer(str2) {
+      if (typeof str2 == "number")
+        return `${str2}`;
+      return str2.replace(/~/g, "~0").replace(/\//g, "~1");
     }
     exports.escapeJsonPointer = escapeJsonPointer;
-    function unescapeJsonPointer(str) {
-      return str.replace(/~1/g, "/").replace(/~0/g, "~");
+    function unescapeJsonPointer(str2) {
+      return str2.replace(/~1/g, "/").replace(/~0/g, "~");
     }
     exports.unescapeJsonPointer = unescapeJsonPointer;
     function eachItem(xs, f) {
@@ -2164,8 +2164,8 @@ var require_json_schema_traverse = __commonJS({
         post(schema, jsonPtr, rootSchema, parentJsonPtr, parentKeyword, parentSchema, keyIndex);
       }
     }
-    function escapeJsonPtr(str) {
-      return str.replace(/~/g, "~0").replace(/\//g, "~1");
+    function escapeJsonPtr(str2) {
+      return str2.replace(/~/g, "~0").replace(/\//g, "~1");
     }
   }
 });
@@ -2701,8 +2701,8 @@ var require_validate = __commonJS({
         if (!this.allErrors)
           this.gen.if(cond);
       }
-      setParams(obj, assign) {
-        if (assign)
+      setParams(obj, assign2) {
+        if (assign2)
           Object.assign(this.params, obj);
         else
           this.params = obj;
@@ -3229,10 +3229,10 @@ var require_utils = __commonJS({
         return { host, isIPV6: false };
       }
     }
-    function findToken(str, token) {
+    function findToken(str2, token) {
       let ind = 0;
-      for (let i = 0; i < str.length; i++) {
-        if (str[i] === token) ind++;
+      for (let i = 0; i < str2.length; i++) {
+        if (str2[i] === token) ind++;
       }
       return ind;
     }
@@ -3969,7 +3969,7 @@ var require_core = __commonJS({
     var util_1 = require_util();
     var $dataRefSchema = require_data();
     var uri_1 = require_uri();
-    var defaultRegExp = (str, flags) => new RegExp(str, flags);
+    var defaultRegExp = (str2, flags) => new RegExp(str2, flags);
     defaultRegExp.code = "new RegExp";
     var META_IGNORE_OPTIONS = ["removeAdditional", "useDefaults", "coerceTypes"];
     var EXT_SCOPE_NAMES = /* @__PURE__ */ new Set([
@@ -4764,16 +4764,16 @@ var require_ucs2length = __commonJS({
   "node_modules/ajv/dist/runtime/ucs2length.js"(exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    function ucs2length(str) {
-      const len = str.length;
+    function ucs2length(str2) {
+      const len = str2.length;
       let length = 0;
       let pos = 0;
       let value;
       while (pos < len) {
         length++;
-        value = str.charCodeAt(pos++);
+        value = str2.charCodeAt(pos++);
         if (value >= 55296 && value <= 56319 && pos < len) {
-          value = str.charCodeAt(pos);
+          value = str2.charCodeAt(pos);
           if ((value & 64512) === 56320)
             pos++;
         }
@@ -6656,8 +6656,8 @@ var require_formats = __commonJS({
     }
     var DATE = /^(\d\d\d\d)-(\d\d)-(\d\d)$/;
     var DAYS = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
-    function date5(str) {
-      const matches = DATE.exec(str);
+    function date5(str2) {
+      const matches = DATE.exec(str2);
       if (!matches)
         return false;
       const year = +matches[1];
@@ -6676,8 +6676,8 @@ var require_formats = __commonJS({
     }
     var TIME = /^(\d\d):(\d\d):(\d\d(?:\.\d+)?)(z|([+-])(\d\d)(?::?(\d\d))?)?$/i;
     function getTime(strictTimeZone) {
-      return function time3(str) {
-        const matches = TIME.exec(str);
+      return function time3(str2) {
+        const matches = TIME.exec(str2);
         if (!matches)
           return false;
         const hr = +matches[1];
@@ -6723,8 +6723,8 @@ var require_formats = __commonJS({
     var DATE_TIME_SEPARATOR = /t|\s/i;
     function getDateTime(strictTimeZone) {
       const time3 = getTime(strictTimeZone);
-      return function date_time(str) {
-        const dateTime = str.split(DATE_TIME_SEPARATOR);
+      return function date_time(str2) {
+        const dateTime = str2.split(DATE_TIME_SEPARATOR);
         return dateTime.length === 2 && date5(dateTime[0]) && time3(dateTime[1]);
       };
     }
@@ -6749,13 +6749,13 @@ var require_formats = __commonJS({
     }
     var NOT_URI_FRAGMENT = /\/|:/;
     var URI = /^(?:[a-z][a-z0-9+\-.]*:)(?:\/?\/(?:(?:[a-z0-9\-._~!$&'()*+,;=:]|%[0-9a-f]{2})*@)?(?:\[(?:(?:(?:(?:[0-9a-f]{1,4}:){6}|::(?:[0-9a-f]{1,4}:){5}|(?:[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){4}|(?:(?:[0-9a-f]{1,4}:){0,1}[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){3}|(?:(?:[0-9a-f]{1,4}:){0,2}[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){2}|(?:(?:[0-9a-f]{1,4}:){0,3}[0-9a-f]{1,4})?::[0-9a-f]{1,4}:|(?:(?:[0-9a-f]{1,4}:){0,4}[0-9a-f]{1,4})?::)(?:[0-9a-f]{1,4}:[0-9a-f]{1,4}|(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?))|(?:(?:[0-9a-f]{1,4}:){0,5}[0-9a-f]{1,4})?::[0-9a-f]{1,4}|(?:(?:[0-9a-f]{1,4}:){0,6}[0-9a-f]{1,4})?::)|[Vv][0-9a-f]+\.[a-z0-9\-._~!$&'()*+,;=:]+)\]|(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)|(?:[a-z0-9\-._~!$&'()*+,;=]|%[0-9a-f]{2})*)(?::\d*)?(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*|\/(?:(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*)?|(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*)(?:\?(?:[a-z0-9\-._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?(?:#(?:[a-z0-9\-._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?$/i;
-    function uri(str) {
-      return NOT_URI_FRAGMENT.test(str) && URI.test(str);
+    function uri(str2) {
+      return NOT_URI_FRAGMENT.test(str2) && URI.test(str2);
     }
     var BYTE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/gm;
-    function byte(str) {
+    function byte(str2) {
       BYTE.lastIndex = 0;
-      return BYTE.test(str);
+      return BYTE.test(str2);
     }
     var MIN_INT32 = -(2 ** 31);
     var MAX_INT32 = 2 ** 31 - 1;
@@ -6769,11 +6769,11 @@ var require_formats = __commonJS({
       return true;
     }
     var Z_ANCHOR = /[^\\]\\Z/;
-    function regex(str) {
-      if (Z_ANCHOR.test(str))
+    function regex(str2) {
+      if (Z_ANCHOR.test(str2))
         return false;
       try {
-        new RegExp(str);
+        new RegExp(str2);
         return true;
       } catch (e) {
         return false;
@@ -14992,14 +14992,14 @@ function promiseAllObject(promisesObj) {
 }
 function randomString(length = 10) {
   const chars = "abcdefghijklmnopqrstuvwxyz";
-  let str = "";
+  let str2 = "";
   for (let i = 0; i < length; i++) {
-    str += chars[Math.floor(Math.random() * chars.length)];
+    str2 += chars[Math.floor(Math.random() * chars.length)];
   }
-  return str;
+  return str2;
 }
-function esc(str) {
-  return JSON.stringify(str);
+function esc(str2) {
+  return JSON.stringify(str2);
 }
 function slugify(input) {
   return input.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_-]+/g, "-").replace(/^-+|-+$/g, "");
@@ -15113,8 +15113,8 @@ var primitiveTypes = /* @__PURE__ */ new Set([
   "symbol",
   "undefined"
 ]);
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function escapeRegex(str2) {
+  return str2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function clone(inst, def, params) {
   const cl = new inst._zod.constr(def ?? inst._zod.def);
@@ -34718,12 +34718,16 @@ 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 str = text === null || text === void 0 ? "" : String(text);
-  const redacted = redactSecrets(str);
+  const str2 = text === null || text === void 0 ? "" : String(text);
+  const redacted = redactSecrets(str2);
   if (redacted.length <= max)
     return redacted;
   return `${redacted.slice(0, max)}\u2026 [truncated]`;
@@ -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.1.0";
+var VERSION = "0.2.1";
 
 // 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);
     }
@@ -34970,12 +35041,74 @@ function qs(params) {
   return buildQueryString(params);
 }
 
+// src/projection.ts
+var str = (v) => typeof v === "string" ? v : void 0;
+var numOf = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+function primaryValue(arr) {
+  if (!Array.isArray(arr) || arr.length === 0) return void 0;
+  const primary = arr.find((e) => e && typeof e === "object" && e.primary === true);
+  const pick2 = primary ?? arr[0];
+  return str(pick2?.value);
+}
+function categoryFromUrl(url2) {
+  if (!url2) return void 0;
+  const m = /\/(Attraction|Hotel|Restaurant)_Review/.exec(url2);
+  return m ? m[1].toUpperCase() : void 0;
+}
+function assign(o, k, v) {
+  if (v !== void 0) o[k] = v;
+}
+function compactLocation(loc) {
+  const addr = Array.isArray(loc.addresses) ? loc.addresses[0] : void 0;
+  const url2 = str(loc.urls?.tripadvisor && loc.urls.tripadvisor.main);
+  const overall = loc.traveler_ratings?.overall ?? {};
+  const out = {};
+  assign(out, "id", numOf(loc.id));
+  assign(out, "name", primaryValue(loc.names));
+  assign(out, "category", categoryFromUrl(url2));
+  assign(out, "geo", str(loc.geo));
+  assign(out, "city", str(addr?.city));
+  assign(out, "state", str(addr?.state));
+  assign(out, "rating", numOf(overall.rating));
+  assign(out, "review_count", numOf(overall.count));
+  assign(out, "url", url2);
+  return out;
+}
+function compactList(raw) {
+  const env = raw;
+  const rows = env?.data;
+  if (!Array.isArray(rows) || !rows.every((r) => r && typeof r === "object" && "location" in r)) {
+    console.error("[tripadvisor] compact: unexpected response shape, returning raw payload");
+    return raw;
+  }
+  const data = rows.map((r) => {
+    const row = r;
+    const item = compactLocation(row.location);
+    assign(item, "distance_miles", numOf(row.distance_miles));
+    assign(item, "distance_kilometers", numOf(row.distance_kilometers));
+    return item;
+  });
+  return env.pagination !== void 0 ? { data, pagination: env.pagination } : { data };
+}
+function compactLocationList(raw) {
+  const env = raw;
+  const rows = env?.data;
+  if (!Array.isArray(rows) || !rows.every((r) => r && typeof r === "object" && "id" in r)) {
+    console.error("[tripadvisor] compact: unexpected response shape, returning raw payload");
+    return raw;
+  }
+  return { data: rows.map((r) => compactLocation(r)) };
+}
+
 // src/tools/search.ts
+var compactParam = {
+  compact: external_exports.boolean().optional().describe("Return a slim summary per result (id, name, category, city, rating, review_count, url) instead of full records")
+};
 function registerSearchTools(server) {
   server.registerTool(
     "ta_search_locations",
     {
-      description: "Search TripAdvisor locations (restaurants, attractions, hotels) by name. Returns matches with a location id for the detail tools, plus pagination.",
+      description: "Search TripAdvisor locations (restaurants, attractions, hotels) by name. Returns matches with a location id for the detail tools, plus pagination. Pass compact:true for slim summaries.",
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: {
         query: external_exports.string().min(1).max(500).describe("Text to search location names for"),
@@ -34984,47 +35117,98 @@ function registerSearchTools(server) {
         geo_name: external_exports.string().optional().describe("City, town, or country name to scope the search"),
         postal_code: external_exports.string().optional().describe("Postal/ZIP code (takes precedence over geo_name)"),
         locale: LocaleList,
-        ...pageParams
+        ...pageParams,
+        ...compactParam
       }
     },
-    async ({ query, category, country_code, geo_name, postal_code, locale, page, size }) => {
+    async ({ query, category, country_code, geo_name, postal_code, locale, page, size, compact }) => {
       const data = await client.get(
         `/locations/search${qs({ query, category, country_code, geo_name, postal_code, locale, page, size })}`,
         { cache: "dynamic" }
       );
-      return textResult(data);
+      return textResult(compact ? compactList(data) : data);
     }
   );
   server.registerTool(
     "ta_search_nearby",
     {
-      description: "Find TripAdvisor locations near a latitude/longitude within a radius. Returns matches with distance and a location id for the detail tools.",
+      description: "Find TripAdvisor locations near a point within a radius, or inside a bounding box. Center by lat+lon+radius, by a reference location_id+radius, or by a sw/ne bounding box. Returns matches with distance and a location id. Pass compact:true for slim summaries.",
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: {
-        lat: external_exports.number().min(-90).max(90).describe("Center latitude"),
-        lon: external_exports.number().min(-180).max(180).describe("Center longitude"),
-        radius: external_exports.number().positive().describe("Search radius (must be > 0)"),
+        // Center — supply exactly one of: lat+lon, location_id, or the sw/ne box.
+        lat: external_exports.number().min(-90).max(90).optional().describe("Center latitude (with lon+radius)"),
+        lon: external_exports.number().min(-180).max(180).optional().describe("Center longitude (with lat+radius)"),
+        location_id: external_exports.number().int().positive().optional().describe("Reference location as center (with radius)"),
+        radius: external_exports.number().positive().optional().describe("Search radius (required with lat/lon or location_id; must be > 0)"),
         unit: external_exports.enum(["MI", "KM"]).optional().describe("Radius unit (default MI)"),
+        sw_lat: external_exports.number().min(-90).max(90).optional().describe("Bounding box SW latitude"),
+        sw_lon: external_exports.number().min(-180).max(180).optional().describe("Bounding box SW longitude"),
+        ne_lat: external_exports.number().min(-90).max(90).optional().describe("Bounding box NE latitude"),
+        ne_lon: external_exports.number().min(-180).max(180).optional().describe("Bounding box NE longitude"),
         category: Category.optional().describe("Restrict to one category"),
         min_rating: external_exports.number().min(1).max(5).optional().describe("Minimum traveler rating (1.0\u20135.0)"),
         include_photo: external_exports.boolean().optional().describe("Include a photo per result"),
         sort: external_exports.enum(["distance", "rating"]).optional().describe("Sort order (default distance)"),
         locale: LocaleList,
-        ...pageParams
+        ...pageParams,
+        ...compactParam
       }
     },
-    async ({ lat, lon, radius, unit, category, min_rating, include_photo, sort, locale, page, size }) => {
+    async (args) => {
+      const { lat, lon, location_id, radius, sw_lat, sw_lon, ne_lat, ne_lon, compact, ...rest } = args;
+      const boxParts = [sw_lat, sw_lon, ne_lat, ne_lon];
+      const boxGiven = boxParts.filter((v) => v !== void 0).length;
+      if (boxGiven > 0 && boxGiven < 4) {
+        throw new McpToolError("ta_search_nearby bounding box needs all four of sw_lat, sw_lon, ne_lat, ne_lon.", {
+          hint: "Provide all four box corners, or use lat+lon+radius or location_id+radius instead."
+        });
+      }
+      if (lat === void 0 !== (lon === void 0)) {
+        throw new McpToolError("ta_search_nearby needs both lat and lon together (or neither).", {
+          hint: "Provide lat AND lon with a radius, or use location_id+radius or a sw/ne box."
+        });
+      }
+      const hasLatLon = lat !== void 0 && lon !== void 0;
+      const hasBox = boxGiven === 4;
+      const centers = [hasLatLon, location_id !== void 0, hasBox].filter(Boolean).length;
+      if (centers !== 1) {
+        throw new McpToolError(
+          "ta_search_nearby needs exactly one center: lat+lon (+radius), location_id (+radius), or the sw/ne bounding box.",
+          { hint: "Provide lat AND lon, OR location_id, OR all four of sw_lat/sw_lon/ne_lat/ne_lon \u2014 not more than one." }
+        );
+      }
+      if ((hasLatLon || location_id !== void 0) && radius === void 0) {
+        throw new McpToolError("lat/lon and location_id center modes require radius.", {
+          hint: "Add radius (with optional unit MI/KM), or switch to a sw/ne bounding box."
+        });
+      }
       const data = await client.get(
-        `/locations/nearby${qs({ lat, lon, radius, unit, category, min_rating, include_photo, sort, locale, page, size })}`,
+        `/locations/nearby${qs({ lat, lon, location_id, radius, sw_lat, sw_lon, ne_lat, ne_lon, ...rest })}`,
         { cache: "dynamic" }
       );
-      return textResult(data);
+      return textResult(compact ? compactList(data) : data);
     }
   );
 }
 
 // src/tools/location.ts
 function registerLocationTools(server) {
+  server.registerTool(
+    "ta_get_locations",
+    {
+      description: "Get details for MULTIPLE locations in one call (batch). Pass an array of location ids \u2014 cheaper than repeated ta_get_location_details. Unknown or unlicensed ids are silently omitted. Pass compact:true for slim summaries.",
+      annotations: { readOnlyHint: true, openWorldHint: true },
+      inputSchema: {
+        ids: external_exports.array(LocationId).min(1).max(50).describe("Location IDs to fetch (1\u201350)"),
+        locale: LocaleList,
+        compact: external_exports.boolean().optional().describe("Return a slim summary per location instead of full records")
+      }
+    },
+    async ({ ids, locale, compact }) => {
+      const data = await client.get(`/locations${qs({ id: ids, locale })}`, { cache: "static" });
+      return textResult(compact ? compactLocationList(data) : data);
+    }
+  );
   server.registerTool(
     "ta_get_location_details",
     {
@@ -38398,7 +38582,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",
@@ -38431,16 +38615,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: {
@@ -38449,17 +38656,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) }]
@@ -38529,19 +38727,19 @@ function parseLocationDetail(html) {
   const rating = node.aggregateRating ?? {};
   const geo = node.geo ?? {};
   const detail = { name: node.name };
-  const assign = (key, value) => {
+  const assign2 = (key, value) => {
     if (value !== void 0) detail[key] = value;
   };
-  assign("type", typeof node["@type"] === "string" ? node["@type"] : void 0);
-  assign("url", typeof node.url === "string" ? node.url : void 0);
-  assign("rating", num(rating.ratingValue));
-  assign("review_count", num(rating.reviewCount));
-  assign("best_rating", num(rating.bestRating));
-  assign("telephone", typeof node.telephone === "string" ? node.telephone : void 0);
-  assign("image", typeof node.image === "string" ? node.image : void 0);
-  assign("latitude", num(geo.latitude));
-  assign("longitude", num(geo.longitude));
-  assign("same_as", typeof node.sameAs === "string" ? node.sameAs : void 0);
+  assign2("type", typeof node["@type"] === "string" ? node["@type"] : void 0);
+  assign2("url", typeof node.url === "string" ? node.url : void 0);
+  assign2("rating", num(rating.ratingValue));
+  assign2("review_count", num(rating.reviewCount));
+  assign2("best_rating", num(rating.bestRating));
+  assign2("telephone", typeof node.telephone === "string" ? node.telephone : void 0);
+  assign2("image", typeof node.image === "string" ? node.image : void 0);
+  assign2("latitude", num(geo.latitude));
+  assign2("longitude", num(geo.longitude));
+  assign2("same_as", typeof node.sameAs === "string" ? node.sameAs : void 0);
   if (node.address && typeof node.address === "object") {
     const addr = {};
     for (const [k, v] of Object.entries(node.address)) {

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/projection.js

@@ -0,0 +1,78 @@
+// Opt-in compact projection for the verbose Terra list responses. Pure and
+// unit-tested against captured shapes (docs/TRIPADVISOR-API.md). Keyed only off
+// fields observed live; on shape drift it warns and returns the RAW payload so
+// an undocumented API change degrades instead of silently emitting empties.
+const str = (v) => (typeof v === 'string' ? v : undefined);
+const numOf = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+/** Primary-language value from a Terra `names`/`descriptions` array (or the first entry). */
+function primaryValue(arr) {
+    if (!Array.isArray(arr) || arr.length === 0)
+        return undefined;
+    const primary = arr.find((e) => e && typeof e === 'object' && e.primary === true);
+    const pick = (primary ?? arr[0]);
+    return str(pick?.value);
+}
+/** ATTRACTION | HOTEL | RESTAURANT from the `/{Type}_Review-…` listing URL. */
+function categoryFromUrl(url) {
+    if (!url)
+        return undefined;
+    const m = /\/(Attraction|Hotel|Restaurant)_Review/.exec(url);
+    return m ? m[1].toUpperCase() : undefined;
+}
+function assign(o, k, v) {
+    if (v !== undefined)
+        o[k] = v;
+}
+/** Project one Terra location object to a {@link CompactLocation}. */
+export function compactLocation(loc) {
+    const addr = (Array.isArray(loc.addresses) ? loc.addresses[0] : undefined);
+    const url = str(loc.urls?.tripadvisor && loc.urls.tripadvisor.main);
+    const overall = (loc.traveler_ratings?.overall ?? {});
+    const out = {};
+    assign(out, 'id', numOf(loc.id));
+    assign(out, 'name', primaryValue(loc.names));
+    assign(out, 'category', categoryFromUrl(url));
+    assign(out, 'geo', str(loc.geo));
+    assign(out, 'city', str(addr?.city));
+    assign(out, 'state', str(addr?.state));
+    assign(out, 'rating', numOf(overall.rating));
+    assign(out, 'review_count', numOf(overall.count));
+    assign(out, 'url', url);
+    return out;
+}
+/**
+ * Project a Terra list envelope (`{data:[{location,…}], pagination}`) to compact
+ * items, preserving `pagination` and any per-item `distance_*` (nearby). If the
+ * shape isn't the expected `data:[{location}]`, warn to stderr and return the raw
+ * payload unchanged — undocumented APIs drift, so degrade rather than break.
+ */
+export function compactList(raw) {
+    const env = raw;
+    const rows = env?.data;
+    if (!Array.isArray(rows) || !rows.every((r) => r && typeof r === 'object' && 'location' in r)) {
+        console.error('[tripadvisor] compact: unexpected response shape, returning raw payload');
+        return raw;
+    }
+    const data = rows.map((r) => {
+        const row = r;
+        const item = compactLocation(row.location);
+        assign(item, 'distance_miles', numOf(row.distance_miles));
+        assign(item, 'distance_kilometers', numOf(row.distance_kilometers));
+        return item;
+    });
+    return env.pagination !== undefined ? { data, pagination: env.pagination } : { data };
+}
+/**
+ * Compact projection for the multi-get envelope (`{data:[<Location>]}` — the
+ * items ARE locations, not `{location}` wrappers). Same drift-fallback contract
+ * as {@link compactList}.
+ */
+export function compactLocationList(raw) {
+    const env = raw;
+    const rows = env?.data;
+    if (!Array.isArray(rows) || !rows.every((r) => r && typeof r === 'object' && 'id' in r)) {
+        console.error('[tripadvisor] compact: unexpected response shape, returning raw payload');
+        return raw;
+    }
+    return { data: rows.map((r) => compactLocation(r)) };
+}

package/dist/tools/location.js

@@ -1,7 +1,24 @@
+import { z } from 'zod';
 import { textResult } from '@chrischall/mcp-utils';
 import { client } from '../client.js';
 import { LocationId, LocaleList, pageParams, qs } from './shared.js';
+import { compactLocationList } from '../projection.js';
 export function registerLocationTools(server) {
+    server.registerTool('ta_get_locations', {
+        description: 'Get details for MULTIPLE locations in one call (batch). Pass an array of location ids — cheaper than repeated ta_get_location_details. Unknown or unlicensed ids are silently omitted. Pass compact:true for slim summaries.',
+        annotations: { readOnlyHint: true, openWorldHint: true },
+        inputSchema: {
+            ids: z.array(LocationId).min(1).max(50).describe('Location IDs to fetch (1–50)'),
+            locale: LocaleList,
+            compact: z
+                .boolean()
+                .optional()
+                .describe('Return a slim summary per location instead of full records'),
+        },
+    }, async ({ ids, locale, compact }) => {
+        const data = await client.get(`/locations${qs({ id: ids, locale })}`, { cache: 'static' });
+        return textResult(compact ? compactLocationList(data) : data);
+    });
     server.registerTool('ta_get_location_details', {
         description: 'Get full details for a TripAdvisor location: names, descriptions, address, coordinates, traveler ratings, phone, category, and listing URLs.',
         annotations: { readOnlyHint: true, openWorldHint: true },

package/dist/tools/search.js

@@ -1,10 +1,18 @@
 import { z } from 'zod';
-import { textResult } from '@chrischall/mcp-utils';
+import { textResult, McpToolError } from '@chrischall/mcp-utils';
 import { client } from '../client.js';
 import { Category, LocaleList, pageParams, qs } from './shared.js';
+import { compactList } from '../projection.js';
+/** `compact` arg shared by the list-returning search tools. */
+const compactParam = {
+    compact: z
+        .boolean()
+        .optional()
+        .describe('Return a slim summary per result (id, name, category, city, rating, review_count, url) instead of full records'),
+};
 export function registerSearchTools(server) {
     server.registerTool('ta_search_locations', {
-        description: 'Search TripAdvisor locations (restaurants, attractions, hotels) by name. Returns matches with a location id for the detail tools, plus pagination.',
+        description: 'Search TripAdvisor locations (restaurants, attractions, hotels) by name. Returns matches with a location id for the detail tools, plus pagination. Pass compact:true for slim summaries.',
         annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: {
             query: z.string().min(1).max(500).describe('Text to search location names for'),
@@ -14,28 +22,65 @@ export function registerSearchTools(server) {
             postal_code: z.string().optional().describe('Postal/ZIP code (takes precedence over geo_name)'),
             locale: LocaleList,
             ...pageParams,
+            ...compactParam,
         },
-    }, async ({ query, category, country_code, geo_name, postal_code, locale, page, size }) => {
+    }, async ({ query, category, country_code, geo_name, postal_code, locale, page, size, compact }) => {
         const data = await client.get(`/locations/search${qs({ query, category, country_code, geo_name, postal_code, locale, page, size })}`, { cache: 'dynamic' });
-        return textResult(data);
+        return textResult(compact ? compactList(data) : data);
     });
     server.registerTool('ta_search_nearby', {
-        description: 'Find TripAdvisor locations near a latitude/longitude within a radius. Returns matches with distance and a location id for the detail tools.',
+        description: 'Find TripAdvisor locations near a point within a radius, or inside a bounding box. Center by lat+lon+radius, by a reference location_id+radius, or by a sw/ne bounding box. Returns matches with distance and a location id. Pass compact:true for slim summaries.',
         annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: {
-            lat: z.number().min(-90).max(90).describe('Center latitude'),
-            lon: z.number().min(-180).max(180).describe('Center longitude'),
-            radius: z.number().positive().describe('Search radius (must be > 0)'),
+            // Center — supply exactly one of: lat+lon, location_id, or the sw/ne box.
+            lat: z.number().min(-90).max(90).optional().describe('Center latitude (with lon+radius)'),
+            lon: z.number().min(-180).max(180).optional().describe('Center longitude (with lat+radius)'),
+            location_id: z.number().int().positive().optional().describe('Reference location as center (with radius)'),
+            radius: z.number().positive().optional().describe('Search radius (required with lat/lon or location_id; must be > 0)'),
             unit: z.enum(['MI', 'KM']).optional().describe('Radius unit (default MI)'),
+            sw_lat: z.number().min(-90).max(90).optional().describe('Bounding box SW latitude'),
+            sw_lon: z.number().min(-180).max(180).optional().describe('Bounding box SW longitude'),
+            ne_lat: z.number().min(-90).max(90).optional().describe('Bounding box NE latitude'),
+            ne_lon: z.number().min(-180).max(180).optional().describe('Bounding box NE longitude'),
             category: Category.optional().describe('Restrict to one category'),
             min_rating: z.number().min(1).max(5).optional().describe('Minimum traveler rating (1.0–5.0)'),
             include_photo: z.boolean().optional().describe('Include a photo per result'),
             sort: z.enum(['distance', 'rating']).optional().describe('Sort order (default distance)'),
             locale: LocaleList,
             ...pageParams,
+            ...compactParam,
         },
-    }, async ({ lat, lon, radius, unit, category, min_rating, include_photo, sort, locale, page, size }) => {
-        const data = await client.get(`/locations/nearby${qs({ lat, lon, radius, unit, category, min_rating, include_photo, sort, locale, page, size })}`, { cache: 'dynamic' });
-        return textResult(data);
+    }, async (args) => {
+        const { lat, lon, location_id, radius, sw_lat, sw_lon, ne_lat, ne_lon, compact, ...rest } = args;
+        const boxParts = [sw_lat, sw_lon, ne_lat, ne_lon];
+        const boxGiven = boxParts.filter((v) => v !== undefined).length;
+        // A partial box (1–3 of 4) is never valid: it can't form a center on its
+        // own, and if it rode alongside a lat/lon or location_id center it would
+        // bleed into the Terra URL and 400. Reject it before the center count.
+        if (boxGiven > 0 && boxGiven < 4) {
+            throw new McpToolError('ta_search_nearby bounding box needs all four of sw_lat, sw_lon, ne_lat, ne_lon.', {
+                hint: 'Provide all four box corners, or use lat+lon+radius or location_id+radius instead.',
+            });
+        }
+        // Same defect class: a lone lat or lon can't form a center and would bleed
+        // into the URL alongside another center — require them together or not at all.
+        if ((lat === undefined) !== (lon === undefined)) {
+            throw new McpToolError('ta_search_nearby needs both lat and lon together (or neither).', {
+                hint: 'Provide lat AND lon with a radius, or use location_id+radius or a sw/ne box.',
+            });
+        }
+        const hasLatLon = lat !== undefined && lon !== undefined;
+        const hasBox = boxGiven === 4;
+        const centers = [hasLatLon, location_id !== undefined, hasBox].filter(Boolean).length;
+        if (centers !== 1) {
+            throw new McpToolError('ta_search_nearby needs exactly one center: lat+lon (+radius), location_id (+radius), or the sw/ne bounding box.', { hint: 'Provide lat AND lon, OR location_id, OR all four of sw_lat/sw_lon/ne_lat/ne_lon — not more than one.' });
+        }
+        if ((hasLatLon || location_id !== undefined) && radius === undefined) {
+            throw new McpToolError('lat/lon and location_id center modes require radius.', {
+                hint: 'Add radius (with optional unit MI/KM), or switch to a sw/ne bounding box.',
+            });
+        }
+        const data = await client.get(`/locations/nearby${qs({ lat, lon, location_id, radius, sw_lat, sw_lon, ne_lat, ne_lon, ...rest })}`, { cache: 'dynamic' });
+        return textResult(compact ? compactList(data) : data);
     });
 }

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/tripadvisor-mcp",
-  "version": "0.1.0",
+  "version": "0.2.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>",
@@ -44,7 +44,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.10.0",
+    "@chrischall/mcp-utils": "^0.12.0",
     "@fetchproxy/server": "^1.3.4",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",

package/server.json

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