@chrischall/tripadvisor-mcp 0.0.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/.claude-plugin/marketplace.json +4 -4
  2. package/.claude-plugin/plugin.json +2 -2
  3. package/.mcp.json +3 -2
  4. package/README.md +32 -12
  5. package/SKILL.md +18 -16
  6. package/dist/bundle.js +303 -127
  7. package/dist/client.js +18 -25
  8. package/dist/projection.js +78 -0
  9. package/dist/tools/location.js +31 -25
  10. package/dist/tools/search.js +72 -15
  11. package/dist/tools/shared.js +13 -15
  12. package/dist/tools/web.js +19 -0
  13. package/dist/version.js +1 -1
  14. package/dist/web/client.js +5 -0
  15. package/dist/web/parse.js +70 -0
  16. package/dist/web/transport.js +1 -1
  17. package/package.json +4 -3
  18. package/server.json +4 -4
package/.claude-plugin/marketplace.json CHANGED
@@ -6,16 +6,16 @@
6
6
  "email": "chris.c.hall@gmail.com"
7
7
  },
8
8
  "metadata": {
9
- "description": "MCP server for the TripAdvisor Content API — location search, details, photos, and reviews",
10
- "version": "0.0.0"
9
+ "description": "MCP server for the TripAdvisor Terra API — location search, details, photos, and reviews",
10
+ "version": "0.2.0"
11
11
  },
12
12
  "plugins": [
13
13
  {
14
14
  "name": "tripadvisor-mcp",
15
15
  "displayName": "TripAdvisor",
16
16
  "source": "./",
17
- "description": "TripAdvisor travel data via the official Content API — search hotels, restaurants, and attractions, with details, photos, and reviews",
18
- "version": "0.0.0",
17
+ "description": "TripAdvisor travel data via the Terra API — search hotels, restaurants, and attractions, with details, photos, and reviews",
18
+ "version": "0.2.0",
19
19
  "author": {
20
20
  "name": "Chris Hall"
21
21
  },
package/.claude-plugin/plugin.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "tripadvisor-mcp",
3
3
  "displayName": "TripAdvisor",
4
- "version": "0.0.0",
5
- "description": "MCP server for the TripAdvisor Content API — location search, details, photos, and reviews",
4
+ "version": "0.2.0",
5
+ "description": "MCP server for the TripAdvisor Terra API — location search, details, photos, and reviews",
6
6
  "author": {
7
7
  "name": "Chris Hall",
8
8
  "email": "chris.c.hall@gmail.com"
package/.mcp.json CHANGED
@@ -5,9 +5,10 @@
5
5
  "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"],
6
6
  "env": {
7
7
  "TRIPADVISOR_API_KEY": "${TRIPADVISOR_API_KEY}",
8
- "TRIPADVISOR_REFERER": "${TRIPADVISOR_REFERER}",
9
8
  "TRIPADVISOR_CACHE_TTL": "${TRIPADVISOR_CACHE_TTL}",
10
- "TRIPADVISOR_STATIC_CACHE_TTL": "${TRIPADVISOR_STATIC_CACHE_TTL}"
9
+ "TRIPADVISOR_STATIC_CACHE_TTL": "${TRIPADVISOR_STATIC_CACHE_TTL}",
10
+ "TRIPADVISOR_REQUEST_TIMEOUT_MS": "${TRIPADVISOR_REQUEST_TIMEOUT_MS}",
11
+ "TRIPADVISOR_DEBUG_LOG": "${TRIPADVISOR_DEBUG_LOG}"
11
12
  }
12
13
  }
13
14
  }
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@chrischall/tripadvisor-mcp)](https://www.npmjs.com/package/@chrischall/tripadvisor-mcp)
4
4
 
5
- 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.
5
+ 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.)
6
6
 
7
7
  > Developed and maintained by AI (Claude Code). Use at your own discretion.
8
8
 
@@ -14,34 +14,54 @@ MCP server for the **TripAdvisor Content API** — travel data for Claude. Searc
14
14
  "tripadvisor": {
15
15
  "command": "npx",
16
16
  "args": ["-y", "@chrischall/tripadvisor-mcp"],
17
- "env": { "TRIPADVISOR_API_KEY": "your-content-api-key-here" }
17
+ "env": { "TRIPADVISOR_API_KEY": "your-terra-api-key-here" }
18
18
  }
19
19
  }
20
20
  }
21
21
  ```
22
22
 
23
- 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.
23
+ 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.
24
24
 
25
25
  ## Tools
26
26
 
27
27
  | Tool | What it does |
28
28
  | --- | --- |
29
- | `ta_search_locations` | Search locations by name (optionally scoped by category, lat/long + radius, address, phone) — up to 10 matches |
30
- | `ta_search_nearby` | Find locations near a latitude/longitude — up to 10 matches |
31
- | `ta_get_location_details` | Full details: rating, ranking, subratings, awards, review count, amenities, hours, listing URLs |
32
- | `ta_get_location_photos` | Photos with multi-size image URLs, captions, and source filter |
33
- | `ta_get_location_reviews` | Most recent reviews (up to 5 per call, pageable with `offset`) |
34
-
35
- All tools are read-only — the Content API has no write endpoints.
29
+ | `ta_search_locations` | Search locations by name (optionally scoped by category, country/geo/postal code) — paginated; `compact:true` for slim summaries |
30
+ | `ta_search_nearby` | Find locations near a lat/lon+radius, a `location_id`+radius, or inside a sw/ne bounding box (category, min rating, sort) — `compact:true` supported |
31
+ | `ta_get_location_details` | Full details: names, descriptions, address, coordinates, traveler ratings, phone, listing URLs |
32
+ | `ta_get_locations` | Batch — details for **multiple** location ids in one call (cheaper than N detail calls); `compact:true` supported |
33
+ | `ta_get_location_photos` | Photos with multi-size image URLs, source, and dimensions — paginated |
34
+ | `ta_get_location_reviews` | Traveler reviews — paginated |
35
+ | `ta_web_healthcheck` | Diagnose the optional tripadvisor.com browser-bridge connection (see below) |
36
+ | `ta_web_get_location` | Location details (rating, address, coords, phone, photo) read from the public page via the browser bridge — **no API key needed** |
37
+
38
+ All tools are read-only — Terra has no write endpoints.
39
+
40
+ ### Browser bridge (optional)
41
+
42
+ `ta_web_healthcheck` is the first tool of an optional second tier that reaches
43
+ tripadvisor.com's consumer site (bot-walled, so unreachable server-side) by
44
+ routing same-origin fetches through your signed-in browser tab via the
45
+ [fetchproxy](https://github.com/chrischall/fetchproxy) Transporter extension.
46
+ It needs the extension installed and a one-time pairing approval; the Content
47
+ API tools above never touch the bridge.
48
+
49
+ `ta_web_get_location` uses this bridge to read a location's details straight
50
+ from its public TripAdvisor page — so it works **without an API key**,
51
+ covering attractions, hotels, and restaurants. It returns core business data
52
+ (rating, review count, address, coordinates, phone, primary photo, listing
53
+ URL) but not individual review text. Request shapes are pinned in
54
+ [docs/TRIPADVISOR-WEB-API.md](docs/TRIPADVISOR-WEB-API.md).
36
55
 
37
56
  ## Environment
38
57
 
39
58
  | Var | Required | Purpose |
40
59
  | --- | --- | --- |
41
- | `TRIPADVISOR_API_KEY` | yes | Content API key, sent as the `key` query parameter. |
42
- | `TRIPADVISOR_REFERER` | no | `Referer` header for domain-restricted keys (the API 403s without a matching referer). |
60
+ | `TRIPADVISOR_API_KEY` | yes | Terra API key, sent as the `X-API-Key` header. |
43
61
  | `TRIPADVISOR_CACHE_TTL` | no | Seconds to cache search responses (default: 300; `0` disables). |
44
62
  | `TRIPADVISOR_STATIC_CACHE_TTL` | no | Seconds to cache details/photos/reviews (default: 3600; `0` disables). |
63
+ | `TRIPADVISOR_REQUEST_TIMEOUT_MS` | no | Per-request timeout for the optional browser bridge (default: 30000). |
64
+ | `TRIPADVISOR_DEBUG_LOG` | no | Set to `1` to log browser-bridge requests to stderr. |
45
65
 
46
66
  ## Development
47
67
 
package/SKILL.md CHANGED
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: tripadvisor-mcp
3
- 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.
3
+ 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.
4
4
  ---
5
5
 
6
6
  # tripadvisor-mcp
7
7
 
8
- MCP server for the **TripAdvisor Content API** — location search, details, photos, and reviews for hotels, restaurants, attractions, and destinations, exposed to Claude over stdio.
8
+ 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.)
9
9
 
10
10
  - **npm:** [npmjs.com/package/@chrischall/tripadvisor-mcp](https://www.npmjs.com/package/@chrischall/tripadvisor-mcp)
11
11
  - **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`:
23
23
  "command": "npx",
24
24
  "args": ["-y", "@chrischall/tripadvisor-mcp"],
25
25
  "env": {
26
- "TRIPADVISOR_API_KEY": "your-content-api-key-here"
26
+ "TRIPADVISOR_API_KEY": "your-terra-api-key-here"
27
27
  }
28
28
  }
29
29
  }
30
30
  }
31
31
  ```
32
32
 
33
- 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.
33
+ 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.
34
34
 
35
35
  ### Option B — from source
36
36
 
@@ -44,8 +44,7 @@ npm install && npm run build
44
44
 
45
45
  | Var | Required | Purpose |
46
46
  | --- | --- | --- |
47
- | `TRIPADVISOR_API_KEY` | yes | Content API key (sent as the `key` query parameter). |
48
- | `TRIPADVISOR_REFERER` | no | `Referer` header — required if your key was created with a domain restriction. |
47
+ | `TRIPADVISOR_API_KEY` | yes | Terra API key (sent as the `X-API-Key` header). A legacy key returns 403. |
49
48
  | `TRIPADVISOR_CACHE_TTL` | no | Seconds to cache identical search responses (default: 300; `0` disables). |
50
49
  | `TRIPADVISOR_STATIC_CACHE_TTL` | no | Longer TTL for details/photos/reviews (default: 3600; `0` disables). |
51
50
 
@@ -53,18 +52,21 @@ npm install && npm run build
53
52
 
54
53
  | Tool | Use for |
55
54
  | --- | --- |
56
- | `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`. |
57
- | `ta_search_nearby` | Find places near coordinates — `latLong` ("lat,long") required; same filters. |
58
- | `ta_get_location_details` | Full listing for a `location_id`: rating, ranking, subratings, awards, review count, amenities, hours, URLs. Optional `language`, `currency`. |
59
- | `ta_get_location_photos` | Photos (multi-size URLs + captions). Page with `limit`/`offset`; filter `source` to `Expert`, `Management`, `Traveler`. |
60
- | `ta_get_location_reviews` | Up to 5 most-recent reviews per call; page with `offset`. |
55
+ | `ta_search_locations` | Find places by name — `query` required; filter with `category` (`RESTAURANT`/`ATTRACTION`/`HOTEL`), `country_code`, `geo_name`, `postal_code`, `locale`; page with `page`/`size` (max 20). `compact:true` → slim summaries. Returns matches with a location `id`. |
56
+ | `ta_search_nearby` | Find places near a center — supply **one** of: `lat`+`lon`+`radius`, `location_id`+`radius`, or a `sw_lat`/`sw_lon`/`ne_lat`/`ne_lon` box (`unit` `MI`/`KM`); filter `category`, `min_rating`, `sort` (`distance`/`rating`), `include_photo`. `compact:true` supported. |
57
+ | `ta_get_location_details` | Full listing for a location `id`: names, descriptions, address, coordinates, traveler ratings, phone, URLs. Optional `locale`. |
58
+ | `ta_get_locations` | Batch details for **multiple** ids (`ids: [..]`, 1–50) in one call — cheaper than repeated details; unknown ids are omitted. `compact:true` supported. |
59
+ | `ta_get_location_photos` | Photos (multi-size URLs, source, dimensions). Page with `page`/`size`. |
60
+ | `ta_get_location_reviews` | Traveler reviews. Page with `page`/`size`. |
61
+ | `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. |
62
+ | `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. |
61
63
 
62
64
  ## Workflow
63
65
 
64
- 1. `ta_search_locations` (or `ta_search_nearby`) to get `location_id`s.
65
- 2. `ta_get_location_details` for ratings/amenities; `ta_get_location_reviews` and `ta_get_location_photos` for review text and images.
66
+ 1. `ta_search_locations` (or `ta_search_nearby`) to get a location `id`.
67
+ 2. `ta_get_location_details` for ratings/address; `ta_get_location_reviews` and `ta_get_location_photos` for reviews and images.
66
68
 
67
69
  Notes:
68
- - Everything is **read-only** — the Content API has no write endpoints.
69
- - A `403` usually means a domain/IP-restricted key: set `TRIPADVISOR_REFERER` to a matching domain.
70
- - Reviews come back at most 5 per call — page with `offset` for more.
70
+ - Everything is **read-only** — Terra has no write endpoints.
71
+ - 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.
72
+ - List endpoints paginate with `page`/`size` (max 20 per page).