@chrischall/tripadvisor-mcp 0.0.0 → 0.2.0

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/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,53 +1,59 @@
 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';
+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: 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,86 @@
 import { z } from 'zod';
-import { textResult } from '@chrischall/mcp-utils';
+import { textResult, McpToolError } from '@chrischall/mcp-utils';
 import { client } from '../client.js';
-import { LatLong, searchFilterParams, qs } from './shared.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 (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. Pass compact:true for slim summaries.',
         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,
+            ...compactParam,
         },
-    }, 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' });
-        return textResult(data);
+    }, 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(compact ? compactList(data) : 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 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: {
-            latLong: LatLong.describe('Center point, e.g. "42.3455,-71.10767"'),
-            ...searchFilterParams,
+            // 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 ({ 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' });
-        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/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.2.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.2.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.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/tripadvisor-mcp",
-      "version": "0.0.0",
+      "version": "0.2.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