@chrischall/tripadvisor-mcp 0.0.0 → 0.1.0

package/.claude-plugin/marketplace.json

@@ -6,16 +6,16 @@
     "email": "chris.c.hall@gmail.com"
   },
   "metadata": {
-    "description": "MCP server for the TripAdvisor Content API — location search, details, photos, and reviews",
-    "version": "0.0.0"
+    "description": "MCP server for the TripAdvisor Terra API — location search, details, photos, and reviews",
+    "version": "0.1.0"
   },
   "plugins": [
     {
       "name": "tripadvisor-mcp",
       "displayName": "TripAdvisor",
       "source": "./",
-      "description": "TripAdvisor travel data via the official Content API — search hotels, restaurants, and attractions, with details, photos, and reviews",
-      "version": "0.0.0",
+      "description": "TripAdvisor travel data via the Terra API — search hotels, restaurants, and attractions, with details, photos, and reviews",
+      "version": "0.1.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "tripadvisor-mcp",
   "displayName": "TripAdvisor",
-  "version": "0.0.0",
-  "description": "MCP server for the TripAdvisor Content API — location search, details, photos, and reviews",
+  "version": "0.1.0",
+  "description": "MCP server for the TripAdvisor Terra API — location search, details, photos, and reviews",
   "author": {
     "name": "Chris Hall",
     "email": "chris.c.hall@gmail.com"

package/.mcp.json

@@ -5,9 +5,10 @@
       "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"],
       "env": {
         "TRIPADVISOR_API_KEY": "${TRIPADVISOR_API_KEY}",
-        "TRIPADVISOR_REFERER": "${TRIPADVISOR_REFERER}",
         "TRIPADVISOR_CACHE_TTL": "${TRIPADVISOR_CACHE_TTL}",
-        "TRIPADVISOR_STATIC_CACHE_TTL": "${TRIPADVISOR_STATIC_CACHE_TTL}"
+        "TRIPADVISOR_STATIC_CACHE_TTL": "${TRIPADVISOR_STATIC_CACHE_TTL}",
+        "TRIPADVISOR_REQUEST_TIMEOUT_MS": "${TRIPADVISOR_REQUEST_TIMEOUT_MS}",
+        "TRIPADVISOR_DEBUG_LOG": "${TRIPADVISOR_DEBUG_LOG}"
       }
     }
   }

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@chrischall/tripadvisor-mcp)](https://www.npmjs.com/package/@chrischall/tripadvisor-mcp)
 
-MCP server for the **TripAdvisor Content API** — travel data for Claude. Search hotels, restaurants, attractions, and destinations by name or coordinates, then pull full details, photos, and recent reviews, all over stdio.
+MCP server for the **TripAdvisor Terra API** — travel data for Claude. Search hotels, restaurants, and attractions by name or coordinates, then pull full details, photos, and reviews, all over stdio. (Terra is TripAdvisor's current API; the legacy Content API is sunset on 2026-08-31.)
 
 > Developed and maintained by AI (Claude Code). Use at your own discretion.
 
@@ -14,34 +14,53 @@ MCP server for the **TripAdvisor Content API** — travel data for Claude. Searc
     "tripadvisor": {
       "command": "npx",
       "args": ["-y", "@chrischall/tripadvisor-mcp"],
-      "env": { "TRIPADVISOR_API_KEY": "your-content-api-key-here" }
+      "env": { "TRIPADVISOR_API_KEY": "your-terra-api-key-here" }
     }
   }
 }
 ```
 
-Get a key at [tripadvisor.com/developers](https://www.tripadvisor.com/developers). The free tier is **5,000 calls/month**; responses are cached in-memory to stretch it.
+Get a key at [tripadvisor.com/developers](https://www.tripadvisor.com/developers). The free **Discover** tier is pay-as-you-go (10 QPS, **10,000 calls/day**); responses are cached in-memory to stretch it. Make sure it's a **Terra** key — a legacy Content API key returns 403.
 
 ## Tools
 
 | Tool | What it does |
 | --- | --- |
-| `ta_search_locations` | Search locations by name (optionally scoped by category, lat/long + radius, address, phone) — up to 10 matches |
-| `ta_search_nearby` | Find locations near a latitude/longitude — up to 10 matches |
-| `ta_get_location_details` | Full details: rating, ranking, subratings, awards, review count, amenities, hours, listing URLs |
-| `ta_get_location_photos` | Photos with multi-size image URLs, captions, and source filter |
-| `ta_get_location_reviews` | Most recent reviews (up to 5 per call, pageable with `offset`) |
-
-All tools are read-only — the Content API has no write endpoints.
+| `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_get_location_details` | Full details: names, descriptions, address, coordinates, traveler ratings, phone, listing URLs |
+| `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) |
+| `ta_web_get_location` | Location details (rating, address, coords, phone, photo) read from the public page via the browser bridge — **no API key needed** |
+
+All tools are read-only — Terra has no write endpoints.
+
+### Browser bridge (optional)
+
+`ta_web_healthcheck` is the first tool of an optional second tier that reaches
+tripadvisor.com's consumer site (bot-walled, so unreachable server-side) by
+routing same-origin fetches through your signed-in browser tab via the
+[fetchproxy](https://github.com/chrischall/fetchproxy) Transporter extension.
+It needs the extension installed and a one-time pairing approval; the Content
+API tools above never touch the bridge.
+
+`ta_web_get_location` uses this bridge to read a location's details straight
+from its public TripAdvisor page — so it works **without an API key**,
+covering attractions, hotels, and restaurants. It returns core business data
+(rating, review count, address, coordinates, phone, primary photo, listing
+URL) but not individual review text. Request shapes are pinned in
+[docs/TRIPADVISOR-WEB-API.md](docs/TRIPADVISOR-WEB-API.md).
 
 ## Environment
 
 | Var | Required | Purpose |
 | --- | --- | --- |
-| `TRIPADVISOR_API_KEY` | yes | Content API key, sent as the `key` query parameter. |
-| `TRIPADVISOR_REFERER` | no | `Referer` header for domain-restricted keys (the API 403s without a matching referer). |
+| `TRIPADVISOR_API_KEY` | yes | Terra API key, sent as the `X-API-Key` header. |
 | `TRIPADVISOR_CACHE_TTL` | no | Seconds to cache search responses (default: 300; `0` disables). |
 | `TRIPADVISOR_STATIC_CACHE_TTL` | no | Seconds to cache details/photos/reviews (default: 3600; `0` disables). |
+| `TRIPADVISOR_REQUEST_TIMEOUT_MS` | no | Per-request timeout for the optional browser bridge (default: 30000). |
+| `TRIPADVISOR_DEBUG_LOG` | no | Set to `1` to log browser-bridge requests to stderr. |
 
 ## Development
 

package/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: tripadvisor-mcp
-description: TripAdvisor travel data via the official Content API through MCP. Use when the user asks to find hotels, restaurants, attractions, or destinations, look up a place's TripAdvisor rating/reviews/photos, compare places to stay or eat, or find what's near a location. Triggers on phrases like "find a hotel in", "best restaurants near", "TripAdvisor reviews for", "what's the rating of", "things to do in", or "attractions near me". Requires the @chrischall/tripadvisor-mcp package installed and the tripadvisor server registered (see Setup), plus a TripAdvisor Content API key.
+description: TripAdvisor travel data via the Terra API through MCP. Use when the user asks to find hotels, restaurants, or attractions, look up a place's TripAdvisor rating/reviews/photos, compare places to stay or eat, or find what's near a location. Triggers on phrases like "find a hotel in", "best restaurants near", "TripAdvisor reviews for", "what's the rating of", "things to do in", or "attractions near me". Requires the @chrischall/tripadvisor-mcp package installed and the tripadvisor server registered (see Setup), plus a TripAdvisor Terra API key.
 ---
 
 # tripadvisor-mcp
 
-MCP server for the **TripAdvisor Content API** — location search, details, photos, and reviews for hotels, restaurants, attractions, and destinations, exposed to Claude over stdio.
+MCP server for the **TripAdvisor Terra API** — location search, details, photos, and reviews for hotels, restaurants, and attractions, exposed to Claude over stdio. (Terra is TripAdvisor's current API; the legacy Content API is sunset on 2026-08-31.)
 
 - **npm:** [npmjs.com/package/@chrischall/tripadvisor-mcp](https://www.npmjs.com/package/@chrischall/tripadvisor-mcp)
 - **Source:** [github.com/chrischall/tripadvisor-mcp](https://github.com/chrischall/tripadvisor-mcp)
@@ -23,14 +23,14 @@ Add to `.mcp.json` in your project or `~/.claude/mcp.json`:
       "command": "npx",
       "args": ["-y", "@chrischall/tripadvisor-mcp"],
       "env": {
-        "TRIPADVISOR_API_KEY": "your-content-api-key-here"
+        "TRIPADVISOR_API_KEY": "your-terra-api-key-here"
       }
     }
   }
 }
 ```
 
-Get a key at [tripadvisor.com/developers](https://www.tripadvisor.com/developers). The free tier is **5,000 calls/month**; the server caches responses in-memory to stretch it.
+Get a key at [tripadvisor.com/developers](https://www.tripadvisor.com/developers). The free **Discover** tier is pay-as-you-go (10 QPS, **10,000 calls/day**); the server caches responses in-memory to stretch it. Must be a **Terra** key — a legacy key returns 403.
 
 ### Option B — from source
 
@@ -44,8 +44,7 @@ npm install && npm run build
 
 | Var | Required | Purpose |
 | --- | --- | --- |
-| `TRIPADVISOR_API_KEY` | yes | Content API key (sent as the `key` query parameter). |
-| `TRIPADVISOR_REFERER` | no | `Referer` header — required if your key was created with a domain restriction. |
+| `TRIPADVISOR_API_KEY` | yes | Terra API key (sent as the `X-API-Key` header). A legacy key returns 403. |
 | `TRIPADVISOR_CACHE_TTL` | no | Seconds to cache identical search responses (default: 300; `0` disables). |
 | `TRIPADVISOR_STATIC_CACHE_TTL` | no | Longer TTL for details/photos/reviews (default: 3600; `0` disables). |
 
@@ -53,18 +52,20 @@ npm install && npm run build
 
 | Tool | Use for |
 | --- | --- |
-| `ta_search_locations` | Find places by name — `searchQuery` required; filter with `category` (hotels/attractions/restaurants/geos), `latLong` + `radius`/`radiusUnit`, `address`, `phone`, `language`. Returns up to 10 matches with `location_id`. |
-| `ta_search_nearby` | Find places near coordinates — `latLong` ("lat,long") required; same filters. |
-| `ta_get_location_details` | Full listing for a `location_id`: rating, ranking, subratings, awards, review count, amenities, hours, URLs. Optional `language`, `currency`. |
-| `ta_get_location_photos` | Photos (multi-size URLs + captions). Page with `limit`/`offset`; filter `source` to `Expert`, `Management`, `Traveler`. |
-| `ta_get_location_reviews` | Up to 5 most-recent reviews per call; page with `offset`. |
+| `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_get_location_details` | Full listing for a location `id`: names, descriptions, address, coordinates, traveler ratings, phone, URLs. Optional `locale`. |
+| `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. |
+| `ta_web_get_location` | Get a location's details (rating, review count, address, coordinates, phone, photo, URL) from its public TripAdvisor page via the browser bridge — **works without an API key**. Covers attractions/hotels/restaurants; no individual review text. |
 
 ## Workflow
 
-1. `ta_search_locations` (or `ta_search_nearby`) to get `location_id`s.
-2. `ta_get_location_details` for ratings/amenities; `ta_get_location_reviews` and `ta_get_location_photos` for review text and images.
+1. `ta_search_locations` (or `ta_search_nearby`) to get a location `id`.
+2. `ta_get_location_details` for ratings/address; `ta_get_location_reviews` and `ta_get_location_photos` for reviews and images.
 
 Notes:
-- Everything is **read-only** — the Content API has no write endpoints.
-- A `403` usually means a domain/IP-restricted key: set `TRIPADVISOR_REFERER` to a matching domain.
-- Reviews come back at most 5 per call — page with `offset` for more.
+- Everything is **read-only** — Terra has no write endpoints.
+- A `403`/`401` means the key isn't a valid Terra key (a legacy Content API key won't work) or its plan isn't active.
+- List endpoints paginate with `page`/`size` (max 20 per page).

package/dist/bundle.js

@@ -7237,26 +7237,26 @@ var require_permessage_deflate = __commonJS({
             value = value[0];
             if (key === "client_max_window_bits") {
               if (value !== true) {
-                const num = +value;
-                if (!Number.isInteger(num) || num < 8 || num > 15) {
+                const num2 = +value;
+                if (!Number.isInteger(num2) || num2 < 8 || num2 > 15) {
                   throw new TypeError(
                     `Invalid value for parameter "${key}": ${value}`
                   );
                 }
-                value = num;
+                value = num2;
               } else if (!this._isServer) {
                 throw new TypeError(
                   `Invalid value for parameter "${key}": ${value}`
                 );
               }
             } else if (key === "server_max_window_bits") {
-              const num = +value;
-              if (!Number.isInteger(num) || num < 8 || num > 15) {
+              const num2 = +value;
+              if (!Number.isInteger(num2) || num2 < 8 || num2 > 15) {
                 throw new TypeError(
                   `Invalid value for parameter "${key}": ${value}`
                 );
               }
-              value = num;
+              value = num2;
             } else if (key === "client_no_context_takeover" || key === "server_no_context_takeover") {
               if (value !== true) {
                 throw new TypeError(
@@ -7969,8 +7969,8 @@ var require_receiver = __commonJS({
           return;
         }
         const buf = this.consume(8);
-        const num = buf.readUInt32BE(0);
-        if (num > Math.pow(2, 53 - 32) - 1) {
+        const num2 = buf.readUInt32BE(0);
+        if (num2 > Math.pow(2, 53 - 32) - 1) {
           const error51 = this.createError(
             RangeError,
             "Unsupported WebSocket frame: payload length > 2^53 - 1",
@@ -7981,7 +7981,7 @@ var require_receiver = __commonJS({
           cb(error51);
           return;
         }
-        this._payloadLength = num * Math.pow(2, 32) + buf.readUInt32BE(4);
+        this._payloadLength = num2 * Math.pow(2, 32) + buf.readUInt32BE(4);
         this.haveLength(cb);
       }
       /**
@@ -34841,15 +34841,15 @@ var pageSchema = {
 };
 
 // src/version.ts
-var VERSION = "0.0.0";
+var VERSION = "0.1.0";
 
 // src/client.ts
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 var __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join(__dirname, "..", ".env"), override: false });
-var BASE_URL = "https://api.content.tripadvisor.com/api/v1";
-var SERVICE = "TripAdvisor Content API";
+var BASE_URL = "https://terra.tripadvisor.com/api";
+var SERVICE = "TripAdvisor Terra API";
 var REQUEST_TIMEOUT_MS = 3e4;
 var DEFAULT_CACHE_TTL_MS = 3e5;
 var DEFAULT_STATIC_CACHE_TTL_MS = 36e5;
@@ -34864,7 +34864,6 @@ function readCacheTtlMs(envVar, defaultMs) {
 var TripAdvisorClient = class {
   apiKey;
   configError;
-  referer;
   fetchImpl;
   sleep;
   cacheTtlMs;
@@ -34882,12 +34881,11 @@ var TripAdvisorClient = class {
     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);
     this.fetchImpl = opts.fetchImpl ?? fetch;
-    this.referer = readEnvVar("TRIPADVISOR_REFERER");
     const key = readEnvVar("TRIPADVISOR_API_KEY");
     if (!key) {
       this.apiKey = null;
       this.configError = new McpToolError("TRIPADVISOR_API_KEY environment variable is required", {
-        hint: "Create a Content API key at https://www.tripadvisor.com/developers and set TRIPADVISOR_API_KEY in your MCP host env or .env (free tier: 5,000 calls/month)."
+        hint: "Create a Terra API key at https://www.tripadvisor.com/developers and set TRIPADVISOR_API_KEY in your MCP host env or .env (free Discover tier: 10,000 calls/day)."
       });
     } else {
       this.apiKey = key;
@@ -34929,11 +34927,8 @@ var TripAdvisorClient = class {
   }
   async request(path, isRetry = false) {
     const key = this.requireKey();
-    const sep = path.includes("?") ? "&" : "?";
-    const url2 = `${BASE_URL}${path}${sep}key=${encodeURIComponent(key)}`;
-    const headers = { Accept: "application/json" };
-    if (this.referer) headers.Referer = this.referer;
-    const res = await this.fetchImpl(url2, { headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    const headers = { "X-API-Key": key, Accept: "application/json" };
+    const res = await this.fetchImpl(`${BASE_URL}${path}`, { headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
     if (res.ok) return await res.json();
     const text = await res.text();
     if (res.status === 429 && !isRetry) {
@@ -34942,22 +34937,20 @@ var TripAdvisorClient = class {
       await this.sleep(delayMs);
       return this.request(path, true);
     }
-    if (res.status === 401) {
-      throw new McpToolError(`${SERVICE} returned 401 Unauthorized \u2014 TRIPADVISOR_API_KEY is missing or invalid.`, {
-        hint: "Check the key in your MCP host env or .env; create one at https://www.tripadvisor.com/developers"
-      });
-    }
-    if (res.status === 403) {
+    if (res.status === 401 || res.status === 403) {
       throw new McpToolError(
-        `${SERVICE} returned 403 Forbidden \u2014 the key is valid but blocked, usually by its domain/IP restriction (set at key creation) or an unapproved application.`,
-        {
-          hint: "If the key is domain-restricted, set TRIPADVISOR_REFERER to a matching https://domain; if IP-restricted, call from a listed address."
-        }
+        `${SERVICE} returned ${res.status} \u2014 TRIPADVISOR_API_KEY is missing, invalid, or not authorized for Terra. A legacy Content API key does NOT work here (and a Terra key does not work on the legacy endpoint).`,
+        { hint: "Confirm the key on the Terra dashboard at https://www.tripadvisor.com/developers and that its plan is active." }
       );
     }
     if (res.status === 429) {
-      throw new McpToolError(`${SERVICE} rate limit or monthly quota exceeded (429).`, {
-        hint: "The free tier is 5,000 calls/month \u2014 check usage at https://www.tripadvisor.com/developers. Cached reads (TRIPADVISOR_CACHE_TTL) stretch the quota."
+      throw new McpToolError(`${SERVICE} rate limit or daily quota exceeded (429).`, {
+        hint: "The Discover tier allows 10 QPS and 10,000 calls/day \u2014 check usage at https://www.tripadvisor.com/developers. Cached reads (TRIPADVISOR_CACHE_TTL) stretch the quota."
+      });
+    }
+    if (res.status === 400) {
+      throw new McpToolError(`${SERVICE} rejected the request (400): ${truncateErrorMessage(text)}`, {
+        hint: "Check the parameters against docs/TRIPADVISOR-API.md (e.g. category must be RESTAURANT/ATTRACTION/HOTEL; nearby needs lat+lon+radius or a bounding box)."
       });
     }
     throw new McpToolError(formatApiError(res.status, "GET", path, text, { service: SERVICE }));
@@ -34967,15 +34960,11 @@ var client = new TripAdvisorClient();
 
 // src/tools/shared.ts
 var LocationId = external_exports.number().int().positive().describe("TripAdvisor location ID (from a search tool)");
-var LatLong = external_exports.string().regex(/^-?\d+(\.\d+)?\s*,\s*-?\d+(\.\d+)?$/, 'must be a "lat,long" pair like "42.3455,-71.10767"');
-var Category = external_exports.enum(["hotels", "attractions", "restaurants", "geos"]);
-var searchFilterParams = {
-  category: Category.optional().describe("Restrict results to one property type"),
-  phone: external_exports.string().optional().describe('Phone number filter (spaces/dashes ok, no leading "+")'),
-  address: external_exports.string().optional().describe("Address filter"),
-  radius: external_exports.number().positive().optional().describe("Search radius around latLong (must be > 0)"),
-  radiusUnit: external_exports.enum(["km", "mi", "m"]).optional().describe("Unit for radius"),
-  language: external_exports.string().optional().describe("Result language code (default: en)")
+var Category = external_exports.enum(["RESTAURANT", "ATTRACTION", "HOTEL"]);
+var LocaleList = external_exports.array(external_exports.string()).optional().describe('Preferred locales for localized fields, in priority order (e.g. ["en","es"])');
+var pageParams = {
+  page: external_exports.number().int().min(1).optional().describe("Page index (1-based)"),
+  size: external_exports.number().int().min(1).max(20).optional().describe("Results per page (max 20)")
 };
 function qs(params) {
   return buildQueryString(params);
@@ -34986,17 +34975,21 @@ function registerSearchTools(server) {
   server.registerTool(
     "ta_search_locations",
     {
-      description: "Search TripAdvisor locations (hotels, restaurants, attractions, geos) by name. Returns up to 10 matches with location_id for the detail tools.",
+      description: "Search TripAdvisor locations (restaurants, attractions, hotels) by name. Returns matches with a location id for the detail tools, plus pagination.",
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: {
-        searchQuery: external_exports.string().min(1).describe("Text to search location names for"),
-        latLong: LatLong.optional().describe('Center point to scope the search, e.g. "42.3455,-71.10767"'),
-        ...searchFilterParams
+        query: external_exports.string().min(1).max(500).describe("Text to search location names for"),
+        category: Category.optional().describe("Restrict to one category"),
+        country_code: external_exports.string().length(2).optional().describe('Alpha-2 country code (e.g. "US")'),
+        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
       }
     },
-    async ({ searchQuery, latLong, category, phone, address, radius, radiusUnit, language }) => {
+    async ({ query, category, country_code, geo_name, postal_code, locale, page, size }) => {
       const data = await client.get(
-        `/location/search${qs({ searchQuery, category, phone, address, latLong, radius, radiusUnit, language })}`,
+        `/locations/search${qs({ query, category, country_code, geo_name, postal_code, locale, page, size })}`,
         { cache: "dynamic" }
       );
       return textResult(data);
@@ -35005,16 +34998,24 @@ function registerSearchTools(server) {
   server.registerTool(
     "ta_search_nearby",
     {
-      description: "Find TripAdvisor locations near a latitude/longitude. Returns up to 10 locations with location_id for the detail tools.",
+      description: "Find TripAdvisor locations near a latitude/longitude within a radius. Returns matches with distance and a location id for the detail tools.",
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: {
-        latLong: LatLong.describe('Center point, e.g. "42.3455,-71.10767"'),
-        ...searchFilterParams
+        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)"),
+        unit: external_exports.enum(["MI", "KM"]).optional().describe("Radius unit (default MI)"),
+        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
       }
     },
-    async ({ latLong, category, phone, address, radius, radiusUnit, language }) => {
+    async ({ lat, lon, radius, unit, category, min_rating, include_photo, sort, locale, page, size }) => {
       const data = await client.get(
-        `/location/nearby_search${qs({ latLong, category, phone, address, radius, radiusUnit, language })}`,
+        `/locations/nearby${qs({ lat, lon, radius, unit, category, min_rating, include_photo, sort, locale, page, size })}`,
         { cache: "dynamic" }
       );
       return textResult(data);
@@ -35023,46 +35024,35 @@ function registerSearchTools(server) {
 }
 
 // src/tools/location.ts
-var PhotoSource = external_exports.string().regex(
-  /^(Expert|Management|Traveler)(,(Expert|Management|Traveler))*$/,
-  "must be a comma-separated list of: Expert, Management, Traveler"
-);
 function registerLocationTools(server) {
   server.registerTool(
     "ta_get_location_details",
     {
-      description: "Get full details for a TripAdvisor location: name, address, coordinates, rating, ranking, subratings, awards, review count, amenities, hours, and listing URLs.",
+      description: "Get full details for a TripAdvisor location: names, descriptions, address, coordinates, traveler ratings, phone, category, and listing URLs.",
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: {
         locationId: LocationId,
-        language: external_exports.string().optional().describe("Result language code (default: en)"),
-        currency: external_exports.string().optional().describe("ISO 4217 currency code for prices (default: USD)")
+        locale: LocaleList
       }
     },
-    async ({ locationId, language, currency }) => {
-      const data = await client.get(`/location/${locationId}/details${qs({ language, currency })}`, {
-        cache: "static"
-      });
+    async ({ locationId, locale }) => {
+      const data = await client.get(`/locations/${locationId}${qs({ locale })}`, { cache: "static" });
       return textResult(data);
     }
   );
   server.registerTool(
     "ta_get_location_photos",
     {
-      description: "Get photos for a TripAdvisor location (multi-size image URLs, captions, sources).",
+      description: "Get photos for a TripAdvisor location (multi-size image URLs, source, dimensions), with pagination.",
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: {
         locationId: LocationId,
-        language: external_exports.string().optional().describe("Caption language code (default: en)"),
-        limit: external_exports.number().int().positive().optional().describe("Number of photos to return"),
-        offset: external_exports.number().int().min(0).optional().describe("Index of the first photo"),
-        source: PhotoSource.optional().describe(
-          "Comma-separated photo sources to allow: Expert, Management, Traveler (default: all)"
-        )
+        locale: LocaleList,
+        ...pageParams
       }
     },
-    async ({ locationId, language, limit, offset, source }) => {
-      const data = await client.get(`/location/${locationId}/photos${qs({ language, limit, offset, source })}`, {
+    async ({ locationId, locale, page, size }) => {
+      const data = await client.get(`/locations/${locationId}/photos${qs({ locale, page, size })}`, {
         cache: "static"
       });
       return textResult(data);
@@ -35071,17 +35061,16 @@ function registerLocationTools(server) {
   server.registerTool(
     "ta_get_location_reviews",
     {
-      description: "Get the most recent reviews for a TripAdvisor location (up to 5 per call; page with offset).",
+      description: "Get traveler reviews for a TripAdvisor location, with pagination.",
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: {
         locationId: LocationId,
-        language: external_exports.string().optional().describe("Review language code (default: en)"),
-        limit: external_exports.number().int().positive().optional().describe("Number of reviews to return"),
-        offset: external_exports.number().int().min(0).optional().describe("Index of the first review")
+        locale: LocaleList,
+        ...pageParams
       }
     },
-    async ({ locationId, language, limit, offset }) => {
-      const data = await client.get(`/location/${locationId}/reviews${qs({ language, limit, offset })}`, {
+    async ({ locationId, locale, page, size }) => {
+      const data = await client.get(`/locations/${locationId}/reviews${qs({ locale, page, size })}`, {
         cache: "static"
       });
       return textResult(data);
@@ -38513,6 +38502,56 @@ function createTripAdvisorTransport(createServer2) {
   });
 }
 
+// src/web/parse.ts
+function locationDetailPath(locationId) {
+  return `/Attraction_Review-g1-d${locationId}-Reviews-a-a.html`;
+}
+function ldJsonBlocks(html) {
+  const out = [];
+  for (const m of html.matchAll(/<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)) {
+    try {
+      out.push(JSON.parse(m[1].trim()));
+    } catch {
+    }
+  }
+  return out;
+}
+function num(v) {
+  if (v === void 0 || v === null) return void 0;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : void 0;
+}
+function parseLocationDetail(html) {
+  const node = ldJsonBlocks(html).find(
+    (b) => typeof b === "object" && b !== null && typeof b.name === "string" && "aggregateRating" in b
+  );
+  if (!node) return null;
+  const rating = node.aggregateRating ?? {};
+  const geo = node.geo ?? {};
+  const detail = { name: node.name };
+  const assign = (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);
+  if (node.address && typeof node.address === "object") {
+    const addr = {};
+    for (const [k, v] of Object.entries(node.address)) {
+      if (k !== "@type" && typeof v === "string") addr[k] = v;
+    }
+    if (Object.keys(addr).length) detail.address = addr;
+  }
+  return detail;
+}
+
 // src/web/client.ts
 var TripAdvisorWebClient = class {
   constructor(injected = {}) {
@@ -38599,6 +38638,10 @@ var TripAdvisorWebClient = class {
       });
     }
   }
+  /** Fetch a location detail page's HTML by numeric d-id (canonicalized by TripAdvisor). */
+  async getLocationHtml(locationId) {
+    return this.getHtml(locationDetailPath(locationId));
+  }
   assertNotWalled(status, body, path) {
     const wall = classifyBotWall(body, status);
     if (wall.blocked) {
@@ -38626,6 +38669,26 @@ function registerWebTools(server) {
     },
     probeFn: (path) => webClient.getHtml(path)
   });
+  server.registerTool(
+    "ta_web_get_location",
+    {
+      description: "Get a TripAdvisor location's core details (name, rating, review count, address, coordinates, phone, photo, listing URL) by location ID, read from the public page via the browser bridge. Works without an API key \u2014 use this when ta_get_location_details is unavailable or its key is blocked. Covers attractions, hotels, and restaurants. Does not return individual review text.",
+      annotations: { readOnlyHint: true, openWorldHint: true },
+      inputSchema: {
+        locationId: LocationId
+      }
+    },
+    async ({ locationId }) => {
+      const html = await webClient.getLocationHtml(locationId);
+      const detail = parseLocationDetail(html);
+      if (!detail) {
+        throw new McpToolError(`Could not parse location ${locationId} from its TripAdvisor page.`, {
+          hint: "The page may be a bot-challenge shell or the id may be wrong \u2014 run ta_web_healthcheck and confirm a signed-in www.tripadvisor.com tab is open, then retry."
+        });
+      }
+      return textResult({ location_id: locationId, ...detail });
+    }
+  );
 }
 
 // src/index.ts

package/dist/client.js

@@ -1,14 +1,14 @@
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadDotenvSafely, readEnvVar, formatApiError, McpToolError } from '@chrischall/mcp-utils';
+import { loadDotenvSafely, readEnvVar, 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));
 await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
-const BASE_URL = 'https://api.content.tripadvisor.com/api/v1';
-const SERVICE = 'TripAdvisor Content API';
+const BASE_URL = 'https://terra.tripadvisor.com/api';
+const SERVICE = 'TripAdvisor Terra API';
 const REQUEST_TIMEOUT_MS = 30_000;
-// The Content API free tier is 5,000 calls/month, so identical GETs in quick
+// The Terra Discover tier is 10,000 calls/day, so identical GETs in quick
 // succession are wasteful. Search results get a 5-minute TTL by default;
 // override with TRIPADVISOR_CACHE_TTL (seconds; 0 = off).
 const DEFAULT_CACHE_TTL_MS = 300_000;
@@ -32,7 +32,6 @@ function readCacheTtlMs(envVar, defaultMs) {
 export class TripAdvisorClient {
     apiKey;
     configError;
-    referer;
     fetchImpl;
     sleep;
     cacheTtlMs;
@@ -51,12 +50,11 @@ export class TripAdvisorClient {
         this.staticCacheTtlMs =
             opts.staticCacheTtlMs ?? readCacheTtlMs('TRIPADVISOR_STATIC_CACHE_TTL', DEFAULT_STATIC_CACHE_TTL_MS);
         this.fetchImpl = opts.fetchImpl ?? fetch;
-        this.referer = readEnvVar('TRIPADVISOR_REFERER');
         const key = readEnvVar('TRIPADVISOR_API_KEY');
         if (!key) {
             this.apiKey = null;
             this.configError = new McpToolError('TRIPADVISOR_API_KEY environment variable is required', {
-                hint: 'Create a Content API key at https://www.tripadvisor.com/developers and set TRIPADVISOR_API_KEY in your MCP host env or .env (free tier: 5,000 calls/month).',
+                hint: 'Create a Terra API key at https://www.tripadvisor.com/developers and set TRIPADVISOR_API_KEY in your MCP host env or .env (free Discover tier: 10,000 calls/day).',
             });
         }
         else {
@@ -106,13 +104,10 @@ export class TripAdvisorClient {
     }
     async request(path, isRetry = false) {
         const key = this.requireKey();
-        const sep = path.includes('?') ? '&' : '?';
-        const url = `${BASE_URL}${path}${sep}key=${encodeURIComponent(key)}`;
-        const headers = { Accept: 'application/json' };
-        // A domain-restricted key requires a matching Referer on every request.
-        if (this.referer)
-            headers.Referer = this.referer;
-        const res = await this.fetchImpl(url, { headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+        // Terra authenticates with the X-API-Key header (not a query param), so the
+        // key never touches the URL — cache keys and error messages are key-free.
+        const headers = { 'X-API-Key': key, Accept: 'application/json' };
+        const res = await this.fetchImpl(`${BASE_URL}${path}`, { headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
         if (res.ok)
             return (await res.json());
         const text = await res.text();
@@ -122,20 +117,18 @@ export class TripAdvisorClient {
             await this.sleep(delayMs);
             return this.request(path, true);
         }
-        // `path` deliberately excludes the key, so these messages can't leak it.
-        if (res.status === 401) {
-            throw new McpToolError(`${SERVICE} returned 401 Unauthorized — TRIPADVISOR_API_KEY is missing or invalid.`, {
-                hint: 'Check the key in your MCP host env or .env; create one at https://www.tripadvisor.com/developers',
-            });
+        if (res.status === 401 || res.status === 403) {
+            throw new McpToolError(`${SERVICE} returned ${res.status} — TRIPADVISOR_API_KEY is missing, invalid, or not authorized for Terra. A legacy Content API key does NOT work here (and a Terra key does not work on the legacy endpoint).`, { hint: 'Confirm the key on the Terra dashboard at https://www.tripadvisor.com/developers and that its plan is active.' });
         }
-        if (res.status === 403) {
-            throw new McpToolError(`${SERVICE} returned 403 Forbidden — the key is valid but blocked, usually by its domain/IP restriction (set at key creation) or an unapproved application.`, {
-                hint: 'If the key is domain-restricted, set TRIPADVISOR_REFERER to a matching https://domain; if IP-restricted, call from a listed address.',
+        if (res.status === 429) {
+            throw new McpToolError(`${SERVICE} rate limit or daily quota exceeded (429).`, {
+                hint: 'The Discover tier allows 10 QPS and 10,000 calls/day — check usage at https://www.tripadvisor.com/developers. Cached reads (TRIPADVISOR_CACHE_TTL) stretch the quota.',
             });
         }
-        if (res.status === 429) {
-            throw new McpToolError(`${SERVICE} rate limit or monthly quota exceeded (429).`, {
-                hint: 'The free tier is 5,000 calls/month — check usage at https://www.tripadvisor.com/developers. Cached reads (TRIPADVISOR_CACHE_TTL) stretch the quota.',
+        if (res.status === 400) {
+            // Terra 400s carry a structured validation body; surface it (it names the bad field).
+            throw new McpToolError(`${SERVICE} rejected the request (400): ${truncateErrorMessage(text)}`, {
+                hint: 'Check the parameters against docs/TRIPADVISOR-API.md (e.g. category must be RESTAURANT/ATTRACTION/HOTEL; nearby needs lat+lon+radius or a bounding box).',
             });
         }
         throw new McpToolError(formatApiError(res.status, 'GET', path, text, { service: SERVICE }));

package/dist/tools/location.js

@@ -1,53 +1,42 @@
-import { z } from 'zod';
 import { textResult } from '@chrischall/mcp-utils';
 import { client } from '../client.js';
-import { LocationId, qs } from './shared.js';
-/** Photo source filter: comma-separated list of the three allowed origins. */
-const PhotoSource = z
-    .string()
-    .regex(/^(Expert|Management|Traveler)(,(Expert|Management|Traveler))*$/, 'must be a comma-separated list of: Expert, Management, Traveler');
+import { LocationId, LocaleList, pageParams, qs } from './shared.js';
 export function registerLocationTools(server) {
     server.registerTool('ta_get_location_details', {
-        description: 'Get full details for a TripAdvisor location: name, address, coordinates, rating, ranking, subratings, awards, review count, amenities, hours, and listing URLs.',
+        description: 'Get full details for a TripAdvisor location: names, descriptions, address, coordinates, traveler ratings, phone, category, and listing URLs.',
         annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: {
             locationId: LocationId,
-            language: z.string().optional().describe('Result language code (default: en)'),
-            currency: z.string().optional().describe('ISO 4217 currency code for prices (default: USD)'),
+            locale: LocaleList,
         },
-    }, async ({ locationId, language, currency }) => {
-        const data = await client.get(`/location/${locationId}/details${qs({ language, currency })}`, {
-            cache: 'static',
-        });
+    }, async ({ locationId, locale }) => {
+        const data = await client.get(`/locations/${locationId}${qs({ locale })}`, { cache: 'static' });
         return textResult(data);
     });
     server.registerTool('ta_get_location_photos', {
-        description: 'Get photos for a TripAdvisor location (multi-size image URLs, captions, sources).',
+        description: 'Get photos for a TripAdvisor location (multi-size image URLs, source, dimensions), with pagination.',
         annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: {
             locationId: LocationId,
-            language: z.string().optional().describe('Caption language code (default: en)'),
-            limit: z.number().int().positive().optional().describe('Number of photos to return'),
-            offset: z.number().int().min(0).optional().describe('Index of the first photo'),
-            source: PhotoSource.optional().describe('Comma-separated photo sources to allow: Expert, Management, Traveler (default: all)'),
+            locale: LocaleList,
+            ...pageParams,
         },
-    }, async ({ locationId, language, limit, offset, source }) => {
-        const data = await client.get(`/location/${locationId}/photos${qs({ language, limit, offset, source })}`, {
+    }, async ({ locationId, locale, page, size }) => {
+        const data = await client.get(`/locations/${locationId}/photos${qs({ locale, page, size })}`, {
             cache: 'static',
         });
         return textResult(data);
     });
     server.registerTool('ta_get_location_reviews', {
-        description: 'Get the most recent reviews for a TripAdvisor location (up to 5 per call; page with offset).',
+        description: 'Get traveler reviews for a TripAdvisor location, with pagination.',
         annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: {
             locationId: LocationId,
-            language: z.string().optional().describe('Review language code (default: en)'),
-            limit: z.number().int().positive().optional().describe('Number of reviews to return'),
-            offset: z.number().int().min(0).optional().describe('Index of the first review'),
+            locale: LocaleList,
+            ...pageParams,
         },
-    }, async ({ locationId, language, limit, offset }) => {
-        const data = await client.get(`/location/${locationId}/reviews${qs({ language, limit, offset })}`, {
+    }, async ({ locationId, locale, page, size }) => {
+        const data = await client.get(`/locations/${locationId}/reviews${qs({ locale, page, size })}`, {
             cache: 'static',
         });
         return textResult(data);

package/dist/tools/search.js

@@ -1,29 +1,41 @@
 import { z } from 'zod';
 import { textResult } from '@chrischall/mcp-utils';
 import { client } from '../client.js';
-import { LatLong, searchFilterParams, qs } from './shared.js';
+import { Category, LocaleList, pageParams, qs } from './shared.js';
 export function registerSearchTools(server) {
     server.registerTool('ta_search_locations', {
-        description: 'Search TripAdvisor locations (hotels, restaurants, attractions, geos) by name. Returns up to 10 matches with location_id for the detail tools.',
+        description: 'Search TripAdvisor locations (restaurants, attractions, hotels) by name. Returns matches with a location id for the detail tools, plus pagination.',
         annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: {
-            searchQuery: z.string().min(1).describe('Text to search location names for'),
-            latLong: LatLong.optional().describe('Center point to scope the search, e.g. "42.3455,-71.10767"'),
-            ...searchFilterParams,
+            query: z.string().min(1).max(500).describe('Text to search location names for'),
+            category: Category.optional().describe('Restrict to one category'),
+            country_code: z.string().length(2).optional().describe('Alpha-2 country code (e.g. "US")'),
+            geo_name: z.string().optional().describe('City, town, or country name to scope the search'),
+            postal_code: z.string().optional().describe('Postal/ZIP code (takes precedence over geo_name)'),
+            locale: LocaleList,
+            ...pageParams,
         },
-    }, async ({ searchQuery, latLong, category, phone, address, radius, radiusUnit, language }) => {
-        const data = await client.get(`/location/search${qs({ searchQuery, category, phone, address, latLong, radius, radiusUnit, language })}`, { cache: 'dynamic' });
+    }, async ({ query, category, country_code, geo_name, postal_code, locale, page, size }) => {
+        const data = await client.get(`/locations/search${qs({ query, category, country_code, geo_name, postal_code, locale, page, size })}`, { cache: 'dynamic' });
         return textResult(data);
     });
     server.registerTool('ta_search_nearby', {
-        description: 'Find TripAdvisor locations near a latitude/longitude. Returns up to 10 locations with location_id for the detail tools.',
+        description: 'Find TripAdvisor locations near a latitude/longitude within a radius. Returns matches with distance and a location id for the detail tools.',
         annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: {
-            latLong: LatLong.describe('Center point, e.g. "42.3455,-71.10767"'),
-            ...searchFilterParams,
+            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)'),
+            unit: z.enum(['MI', 'KM']).optional().describe('Radius unit (default MI)'),
+            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,
         },
-    }, async ({ latLong, category, phone, address, radius, radiusUnit, language }) => {
-        const data = await client.get(`/location/nearby_search${qs({ latLong, category, phone, address, radius, radiusUnit, language })}`, { cache: 'dynamic' });
+    }, 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);
     });
 }

package/dist/tools/shared.js

@@ -2,23 +2,21 @@ import { z } from 'zod';
 import { buildQueryString } from '@chrischall/mcp-utils';
 /** TripAdvisor location id — a positive integer (interpolated into the path). */
 export const LocationId = z.number().int().positive().describe('TripAdvisor location ID (from a search tool)');
-/** `"lat,long"` pair, e.g. `"42.3455,-71.10767"`. */
-export const LatLong = z
-    .string()
-    .regex(/^-?\d+(\.\d+)?\s*,\s*-?\d+(\.\d+)?$/, 'must be a "lat,long" pair like "42.3455,-71.10767"');
-/** Search category filter — the four values the Content API accepts. */
-export const Category = z.enum(['hotels', 'attractions', 'restaurants', 'geos']);
-/** Filters shared by the two search endpoints. */
-export const searchFilterParams = {
-    category: Category.optional().describe('Restrict results to one property type'),
-    phone: z.string().optional().describe('Phone number filter (spaces/dashes ok, no leading "+")'),
-    address: z.string().optional().describe('Address filter'),
-    radius: z.number().positive().optional().describe('Search radius around latLong (must be > 0)'),
-    radiusUnit: z.enum(['km', 'mi', 'm']).optional().describe('Unit for radius'),
-    language: z.string().optional().describe('Result language code (default: en)'),
+/** Terra category filter — the three UPPERCASE values the API accepts. */
+export const Category = z.enum(['RESTAURANT', 'ATTRACTION', 'HOTEL']);
+/** Locale list → Terra's repeated `locale` query param. */
+export const LocaleList = z
+    .array(z.string())
+    .optional()
+    .describe('Preferred locales for localized fields, in priority order (e.g. ["en","es"])');
+/** Paging shared by Terra list endpoints (size is capped at 20 by the API). */
+export const pageParams = {
+    page: z.number().int().min(1).optional().describe('Page index (1-based)'),
+    size: z.number().int().min(1).max(20).optional().describe('Results per page (max 20)'),
 };
 /**
- * Build a `?a=b&c=d` query string, dropping undefined values. Thin wrapper over
+ * Build a `?a=b&c=d` query string, dropping undefined values and expanding
+ * arrays into repeated params (Terra takes `locale` repeated). Thin wrapper over
  * the shared helper so every tool serializes params identically.
  */
 export function qs(params) {

package/dist/tools/web.js

@@ -1,5 +1,8 @@
 import { registerBridgeHealthcheckTool } from '@chrischall/mcp-utils/fetchproxy';
+import { McpToolError, textResult } from '@chrischall/mcp-utils';
 import { webClient } from '../web/client.js';
+import { parseLocationDetail } from '../web/parse.js';
+import { LocationId } from './shared.js';
 /**
  * A small, real page GET the probe round-trips — the homepage exercises the
  * exact bridge + bot-wall guards every web tool uses.
@@ -25,4 +28,20 @@ export function registerWebTools(server) {
         },
         probeFn: (path) => webClient.getHtml(path),
     });
+    server.registerTool('ta_web_get_location', {
+        description: "Get a TripAdvisor location's core details (name, rating, review count, address, coordinates, phone, photo, listing URL) by location ID, read from the public page via the browser bridge. Works without an API key — use this when ta_get_location_details is unavailable or its key is blocked. Covers attractions, hotels, and restaurants. Does not return individual review text.",
+        annotations: { readOnlyHint: true, openWorldHint: true },
+        inputSchema: {
+            locationId: LocationId,
+        },
+    }, async ({ locationId }) => {
+        const html = await webClient.getLocationHtml(locationId);
+        const detail = parseLocationDetail(html);
+        if (!detail) {
+            throw new McpToolError(`Could not parse location ${locationId} from its TripAdvisor page.`, {
+                hint: 'The page may be a bot-challenge shell or the id may be wrong — run ta_web_healthcheck and confirm a signed-in www.tripadvisor.com tab is open, then retry.',
+            });
+        }
+        return textResult({ location_id: locationId, ...detail });
+    });
 }

package/dist/version.js

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

package/dist/web/client.js

@@ -12,6 +12,7 @@ import { McpToolError } from '@chrischall/mcp-utils';
 import { bridgeErrorInfo, classifyBotWall } from '@chrischall/mcp-utils/fetchproxy';
 import { debugLogEnabled } from './config.js';
 import { createTripAdvisorTransport } from './transport.js';
+import { locationDetailPath } from './parse.js';
 export class TripAdvisorWebClient {
     injected;
     transport;
@@ -101,6 +102,10 @@ export class TripAdvisorWebClient {
             });
         }
     }
+    /** Fetch a location detail page's HTML by numeric d-id (canonicalized by TripAdvisor). */
+    async getLocationHtml(locationId) {
+        return this.getHtml(locationDetailPath(locationId));
+    }
     assertNotWalled(status, body, path) {
         const wall = classifyBotWall(body, status);
         if (wall.blocked) {

package/dist/web/parse.js

@@ -0,0 +1,70 @@
+// Pure parsing for the web tier — no bridge, no I/O, so it's unit-testable
+// against captured bytes. Shapes pinned in docs/TRIPADVISOR-WEB-API.md.
+/**
+ * Build the location detail path from a numeric `d`-id. TripAdvisor canonicalizes
+ * on the `d<id>` segment and same-origin-redirects the `g<geo>` + type prefix to
+ * the correct page (verified across attraction/hotel/restaurant), so one fixed
+ * form works for every category — the in-tab fetch follows the redirect.
+ */
+export function locationDetailPath(locationId) {
+    return `/Attraction_Review-g1-d${locationId}-Reviews-a-a.html`;
+}
+/** Extract every `application/ld+json` block's parsed JSON (skipping malformed ones). */
+function ldJsonBlocks(html) {
+    const out = [];
+    for (const m of html.matchAll(/<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)) {
+        try {
+            out.push(JSON.parse(m[1].trim()));
+        }
+        catch {
+            // Undocumented markup can carry a malformed block; skip it and keep scanning.
+        }
+    }
+    return out;
+}
+/** Coerce a schema.org string|number to a finite number, or undefined. */
+function num(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * Parse a location detail page into a {@link LocationDetail}. The business node
+ * is the ld+json block carrying both `name` and `aggregateRating` (its `@type`
+ * varies by category but the shape is identical). Returns null when no such node
+ * is present — a hydrated shell or a bot-challenge page — so the caller can throw
+ * an actionable error instead of emitting an empty projection.
+ */
+export function parseLocationDetail(html) {
+    const node = ldJsonBlocks(html).find((b) => typeof b === 'object' && b !== null && typeof b.name === 'string' && 'aggregateRating' in b);
+    if (!node)
+        return null;
+    const rating = (node.aggregateRating ?? {});
+    const geo = (node.geo ?? {});
+    const detail = { name: node.name };
+    const assign = (key, value) => {
+        if (value !== undefined)
+            detail[key] = value;
+    };
+    assign('type', typeof node['@type'] === 'string' ? node['@type'] : undefined);
+    assign('url', typeof node.url === 'string' ? node.url : undefined);
+    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 : undefined);
+    assign('image', typeof node.image === 'string' ? node.image : undefined);
+    assign('latitude', num(geo.latitude));
+    assign('longitude', num(geo.longitude));
+    assign('same_as', typeof node.sameAs === 'string' ? node.sameAs : undefined);
+    if (node.address && typeof node.address === 'object') {
+        const addr = {};
+        for (const [k, v] of Object.entries(node.address)) {
+            if (k !== '@type' && typeof v === 'string')
+                addr[k] = v;
+        }
+        if (Object.keys(addr).length)
+            detail.address = addr;
+    }
+    return detail;
+}

package/dist/web/transport.js

@@ -7,7 +7,7 @@
 // regardless of cookie freshness. So web-tier requests run through the
 // fetchproxy bridge: each one is a same-origin fetch executed in the user's
 // open tripadvisor.com tab, and the bot wall never sees Node. The official
-// Content API tools (src/client.ts) are unaffected — they never touch the
+// Terra API tools (src/client.ts) are unaffected — they never touch the
 // bridge.
 //
 // This is the fleet's fetchproxy archetype (alltrails/redfin/zillow): a thin

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@chrischall/tripadvisor-mcp",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "mcpName": "io.github.chrischall/tripadvisor-mcp",
-  "description": "TripAdvisor Content API MCP server for Claude \u2014 search locations, details, photos, and reviews. Developed and maintained by AI (Claude Code).",
+  "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>",
   "repository": {
     "type": "git",
@@ -37,7 +37,7 @@
   ],
   "scripts": {
     "build": "tsc && npm run bundle",
-    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --outfile=dist/bundle.js",
+    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --banner:js='import { createRequire as __createRequire } from \"module\"; const require = __createRequire(import.meta.url);' --outfile=dist/bundle.js",
     "dev": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -45,6 +45,7 @@
   },
   "dependencies": {
     "@chrischall/mcp-utils": "^0.10.0",
+    "@fetchproxy/server": "^1.3.4",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "zod": "^4.4.2"

package/server.json

@@ -1,24 +1,24 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.chrischall/tripadvisor-mcp",
-  "description": "TripAdvisor location search, details, photos, and reviews via the official Content API",
+  "description": "TripAdvisor location search, details, photos, and reviews via the Terra API",
   "repository": {
     "url": "https://github.com/chrischall/tripadvisor-mcp",
     "source": "github"
   },
-  "version": "0.0.0",
+  "version": "0.1.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/tripadvisor-mcp",
-      "version": "0.0.0",
+      "version": "0.1.0",
       "transport": {
         "type": "stdio"
       },
       "environmentVariables": [
         {
           "name": "TRIPADVISOR_API_KEY",
-          "description": "Your TripAdvisor Content API key (tripadvisor.com/developers)",
+          "description": "Your TripAdvisor Terra API key (tripadvisor.com/developers)",
           "isRequired": true,
           "format": "string",
           "isSecret": true