alltrails-mcp: Instructions file for Claude Code

alltrails-mcp

Unofficial MCP server for AllTrails. Read-only access to trail search, trail details, reviews, photos, weather, and a signed-in user's saved lists / completed trails / activity feed. stdio transport.

AllTrails has no public API. This reverse-engineers the internal one (alltrails.com), which is fronted by DataDome bot protection and governed by AllTrails' ToS. It may break at any time and automated use may violate their terms. This project is one of a fleet of sibling MCP servers (ofw-mcp is the canonical template); it copies that fleet's auth/validation/packaging patterns.

Commands

npm run build        # tsc → dist/, then esbuild bundle → dist/bundle.js
npm test             # vitest run (all tests)
npm run test:watch   # vitest in watch mode
npm run dev          # node --env-file=.env dist/index.js (requires built dist)

dist/ is gitignored — it is produced at build/release time and shipped in the npm package (package.json files).

Architecture

src/
  index.ts          MCP server entry — runMcp() from @chrischall/mcp-utils (builds McpServer, applies registrars with client as deps, prints banner, wires shutdown + stdio transport)
  protocol.ts       Wire-level constants (BASE_URL, embedded x-at-key app key, header/UA defaults)
  transport.ts      createAllTrailsTransport(): the fetchproxy bridge transport (createFetchproxyTransport, port 37149, domains alltrails.com, defaultSubdomain www, createServer test seam)
  client.ts         AllTrailsClient — bridge requests (transport.fetch inside the signed-in tab), live x-at-key capture (memory-only), 429 wait-and-replay, non-JSON interstitial guard
  config.ts         env-driven header/UA/api-key/user-id/timeout/ws-port/debug getters
  validate.ts       parseAllTrails(): zod validation of AllTrails responses at call sites (lenient reads / strict where a mistype must halt)
  gpx.ts            decodePolyline() (generalized Google polyline varint decoder) + trailToGpx() (offline-detail route geometry → GPX 1.1) + OfflineTrailSchema
  tools/
    _shared.ts      response helpers + resolveUserId (arg → ALLTRAILS_USER_ID → /api/alltrails/me users[0].id) + the compact projections, applied BY DEFAULT via the fleet `view` param (summarizeTrail/TrailDetail/Review/Photo/SearchResult/FeedItem/ListItem/Location + their loose schemas + ALLTRAILS_VIEWS)
    trails.ts       get_trail, get_trail_reviews, get_trail_photos, get_trail_weather, get_trail_gpx
    explore.ts      search, resolve_location (suggestions → place records: kind/coords/slug)
    user.ts         get_profile, list_user_lists, get_list_items (GET /lists/{id}/items — sparse trailId refs), list_completed_trails, get_activity_feed (feed?: local|timeline|personal follows the actual feed; omitted → directory)
    healthcheck.ts  alltrails_healthcheck via registerBridgeHealthcheckTool (probes a real trail-detail path through the client)
tests/              mirrors src/; mocks AllTrailsClient.request via vi.spyOn; client tests inject a stub FetchproxyTransport; transport tests use the createServer seam