Flight + Stay Search MCP

Implementation Reference

• src/api/duffelStaysClient.ts:86-101 (handler)

  Core handler function in DuffelStaysClient that fetches stay reviews from the Duffel API via HTTP GET request, processes pagination parameters, and formats the response.

  async getStayReviews(params: StayReviewRequest): Promise<StayReviewResponse> {
    const { stay_id, after, before, limit } = params;
    const query: Record<string, string | number> = {};
    if (after) query.after = after;
    if (before) query.before = before;
    if (limit) query.limit = limit;
    const response = await this.client.get(`/accommodation/${stay_id}/reviews`, { params: query, headers: { 'Duffel-Version': 'v2' } });
    const meta = response.data.meta || {};
    const reviews = (response.data.data?.reviews || []).map((r: any) => ({
      text: r.text,
      score: r.score,
      reviewer_name: r.reviewer_name,
      created_at: r.created_at,
    }));
    return { meta, reviews };
  }

• src/server.ts:205-224 (registration)

  MCP server tool registration for 'get_stay_reviews'. Specifies the tool name, input schema, and a thin async handler that delegates to DuffelStaysClient.getStayReviews and formats the MCP response.

  server.tool(
    'get_stay_reviews',
    stayReviewSchema.shape,
    async (params: StayReviewRequest) => {
      try {
        const response = await staysClient.getStayReviews(params);
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(response, null, 2)
            }
          ]
        };
      } catch (error) {
        console.error(`Error fetching stay reviews: ${error}`);
        throw error;
      }
    }
  );

• src/models/stayReview.ts:4-9 (schema)

  Zod input schema defining parameters for get_stay_reviews: required stay_id and optional pagination fields (after, before, limit). Referenced in server registration.

  export const stayReviewSchema = z.object({
    stay_id: z.string().describe('Duffel stay/hotel ID (e.g., acc_0000AWr2VsUNIF1Vl91xg0)'),
    after: z.string().optional().describe('Pagination cursor: after'),
    before: z.string().optional().describe('Pagination cursor: before'),
    limit: z.number().int().min(1).max(200).optional().describe('Max reviews to return (1-200)'),
  });

• src/server.ts:27-27 (handler)

  Initialization of the DuffelStaysClient instance used by the get_stay_reviews handler.

  const staysClient = new DuffelStaysClient();

• src/models/stayReview.ts:11-28 (schema)

  Type definitions for StayReviewRequest (inferred from schema), individual StayReview, and StayReviewResponse structure used by the handler.

  export type StayReviewRequest = z.infer<typeof stayReviewSchema>;
  
  export interface StayReview {
    text: string;
    score: number;
    reviewer_name: string;
    created_at: string;
  }
  
  export interface StayReviewResponse {
    meta: {
      limit: number;
      after?: string;
      before?: string;
    };
    reviews: StayReview[];
  }