Agentic Travel Recommendations API

AI Concierge Proof of Concept — MCP Server

---

Section A — Architecture & Trade-offs

Architecture Overview

The Agentic Travel Recommendations API is a TypeScript/Node.js service that exposes personalized travel recommendations to AI agents via the Model Context Protocol (MCP). The service sits between two upstream dependencies — a member data service and a partner configuration service — and a downstream AI agent such as Claude Code.

At runtime the flow works as follows: an AI agent connects to the MCP server and discovers available tools via the list_tools endpoint. The agent calls get_member_profile to retrieve a member's loyalty tier, travel history, and partner ID. It then calls get_recommendations, which fetches the member profile, retrieves the partner's configuration rules, loads the full recommendation catalog, and applies three sequential filters — category exclusions, loyalty tier eligibility, and recommendation cap — before returning an auditable response that includes both the filtered recommendations and the rules that were applied.

Both upstream services are mocked via static JSON files for this proof of concept. The mock structure mirrors what real API calls would look like, meaning the service layer can be swapped from file reads to HTTP calls without changing any business logic.

Design Trade-offs

Pre-populated catalog vs. LLM-generated recommendations

The recommendation pool is a static catalog rather than dynamically generated by a language model. An LLM-based approach might seem more "agentic" but would introduce significant reliability problems in a production context — generated hotel names and prices cannot be verified, category classification would be ambiguous making rule enforcement fragile, and outputs would be non-deterministic making the service untestable. A curated catalog ensures that category exclusions and recommendation caps are enforced against typed, validated data. The intelligence of the service lies in personalized selection and rule enforcement, not content generation.

Single partner per member

Each member is associated with exactly one partner, reflecting the reality that a member accessing the AI Concierge does so through a specific partner's branded portal. Supporting multiple partners per member would add complexity without demonstrating new behavior in the rule enforcement logic. In a production system this could be extended by passing an explicit partnerId alongside memberId in the request, allowing the caller to specify which partner context applies.

Handling Partner Configuration Changes

Because the partner configuration service is treated as read-only and loaded fresh on each request, configuration changes take effect immediately without requiring a service restart or cache invalidation. If a partner adds a new category exclusion or lowers their recommendation cap, the next request for any member under that partner will automatically reflect the updated rules. The only change required in this service would be adding the new category to the TravelCategory union type in types.ts if it is a category not previously defined — a one-line change. This design intentionally avoids caching partner config, accepting slightly higher read overhead in exchange for always-current rule enforcement.

Four-Week Delivery Plan

Ships first (Weeks 1–2):

• MCP server with get_member_profile, get_recommendations, and list_members tools
• Partner rule enforcement (category exclusions, recommendation cap, tier filtering)
• Static catalog with typed data model
• CLI demo and README documentation

Ships later (Weeks 3–4):

• Replace file-based mocks with real HTTP calls to member data and partner config services
• Add response caching for partner config with cache invalidation on config change events
• Add support for multiple partner contexts per member
• Add integration tests asserting rule enforcement across all partner configurations
• Add logging and observability (structured logs per request with rulesApplied metadata)
• Add pagination for recommendation results

---

Section B — Production Readiness & Incident Response

Incident Runbook Entry

Symptom: A member reports that the AI Concierge is showing cruise recommendations even though their partner's configuration excludes cruises.

Initial Diagnosis Steps:

1. Identify the member ID and partner ID from the report. Check the member's profile via get_member_profile to confirm their partnerId is correct and matches the expected partner.

2. Query the partner configuration service directly for that partnerId and verify that "cruise" is present in excludedCategories. If it is not present, the issue is in the partner config data itself — escalate to the partner configuration team as the config may have been accidentally modified or not yet propagated.

3. If "cruise" is correctly in the partner config, check the recommendation catalog and confirm that the cruise offerings have "cruise" as their exact category value. A mismatch in casing or spelling — for example "Cruise" vs "cruise" — would cause the filter to silently pass cruise offers through.

4. Check the version of the recommendation service that is currently deployed. If a recent deployment occurred, review the diff for any changes to the filtering logic in recommendationService.ts, particularly the category exclusion filter.

5. Check service logs for the member's recent sessions to see the raw rulesApplied field in the response. If excludedCategories shows an empty array despite the partner config containing exclusions, the issue is in how partner config is being read or deserialized.

Resolution:

• If the issue is a data mismatch in category strings, correct the catalog entry and redeploy
• If the issue is in the partner config data, escalate to the partner config team with specific partnerId and expected vs actual values
• If the issue is a code regression, roll back to the previous deployment and open a bug ticket with the specific commit that introduced the change
• In all cases, verify the fix by calling get_recommendations for an affected member and confirming cruises no longer appear in the response before closing the incident

Prevention: Add an integration test that specifically asserts cruise recommendations never appear for partners with cruise exclusions configured. This test should run on every deployment.

---

Running the Demo

Prerequisites

• Node.js 18+
• npm

Installation

npm install

Run the full demo

npm run cli

Query a specific member

ts-node cli.ts WI001
ts-node cli.ts WI002
ts-node cli.ts WI003

Start the MCP server

npm run dev

Available MCP Tools

• list_members — discover valid member IDs
• get_member_profile — retrieve member profile by ID
• get_recommendations — get partner-rule-enforced recommendations for a member