Restaurant Booking MCP Server

Instructions

Implementation Reference

• src/index.ts:57-135 (registration)

  Registers the 'search_restaurants' MCP tool, defining its name, title, description, detailed Zod input schema for parameters like location, cuisine, mood, etc., and the handler callback.

  server.registerTool(
    'search_restaurants',
    {
      title: 'Search for restaurants',
      description:
        'Search for restaurants based on location, cuisine, keyword, mood, event, radius, price level, and locale',
      inputSchema: {
        latitude: z
          .number()
          .optional()
          .describe(
            `Latitude of the search location (default: ${DEFAULT_LATITUDE} - Taiwan)`
          ),
        longitude: z
          .number()
          .optional()
          .describe(
            `Longitude of the search location (default: ${DEFAULT_LONGITUDE} - Taiwan)`
          ),
        placeName: z
          .string()
          .optional()
          .describe(
            'Place name to search near (e.g., "New York", "Tokyo", "London"). Alternative to providing latitude/longitude coordinates.'
          ),
        cuisineTypes: z
          .array(z.string())
          .optional()
          .describe(
            'Array of preferred cuisine types (e.g., ["Italian", "Japanese", "Mexican"])'
          ),
        keyword: z
          .string()
          .optional()
          .describe(
            'Search for specific food types or dishes (e.g., "hotpot", "sushi", "pizza", "ramen", "dim sum", "barbecue")'
          ),
        mood: z
          .string()
          .describe(
            'Desired mood/atmosphere (e.g., "romantic", "casual", "upscale", "fun", "quiet")'
          ),
        event: z
          .string()
          .describe(
            "Type of event or occasion (e.g., 'dating', 'gathering', 'business', 'casual', 'celebration')"
          ),
        radius: z
          .number()
          .optional()
          .describe(
            `Search radius in meters (default: ${DEFAULT_SEARCH_RADIUS} = ${DEFAULT_SEARCH_RADIUS / 1000}km)`
          ),
        priceLevel: z
          .number()
          .min(1)
          .max(4)
          .optional()
          .describe(
            'Price level preference (1=inexpensive, 4=very expensive)'
          ),
        locale: z
          .string()
          .optional()
          .describe(
            'Locale for search results and Google API responses (e.g., "en" for English, "zh-TW" for Traditional Chinese, "ja" for Japanese, "ko" for Korean, "th" for Thai). Affects restaurant names, reviews, and other text content.'
          ),
        strictCuisineFiltering: z
          .boolean()
          .optional()
          .describe(
            'If true, only restaurants that match the specified cuisine types will be returned. If false (default), all restaurants will be returned but cuisine matches will be scored higher.'
          ),
      },
    },
    async args => {
      return await this.handleSearchRestaurants(args);
    }
  );

• src/index.ts:138-226 (handler)

  Main execution handler for the tool. Parses arguments into RestaurantSearchParams, performs restaurant search via GoogleMapsService, generates ranked recommendations using RestaurantRecommendationService, and returns formatted JSON output with search criteria, total found, and top recommendations.

  private async handleSearchRestaurants(args: any) {
    const searchParams: RestaurantSearchParams = {
      // Only include location if placeName is not provided
      ...(args.placeName
        ? { placeName: args.placeName }
        : {
            location: {
              latitude: args.latitude || DEFAULT_LATITUDE,
              longitude: args.longitude || DEFAULT_LONGITUDE,
            },
          }),
      cuisineTypes: args.cuisineTypes || [],
      keyword: args.keyword,
      mood: args.mood,
      event: args.event,
      radius: args.radius || DEFAULT_SEARCH_RADIUS,
      priceLevel: args.priceLevel,
      locale: args.locale || 'en',
      strictCuisineFiltering: args.strictCuisineFiltering || false,
    };
  
    // Search for restaurants
    const restaurants =
      await this.googleMapsService.searchRestaurants(searchParams);
  
    if (restaurants.length === 0) {
      return {
        content: [
          {
            type: 'text' as const,
            text: 'No restaurants found matching your criteria. Try expanding your search radius or adjusting your preferences.',
          },
        ],
      };
    }
  
    // Get AI recommendations
    const recommendations = await this.recommendationService.getRecommendations(
      restaurants,
      searchParams
    );
  
    const result = {
      searchCriteria: searchParams,
      totalFound: restaurants.length,
      recommendations: recommendations.map(rec => ({
        restaurant: {
          placeId: rec.restaurant.placeId,
          name: rec.restaurant.name,
          address: rec.restaurant.address,
          rating: rec.restaurant.rating,
          userRatingsTotal: rec.restaurant.userRatingsTotal,
          priceLevel: rec.restaurant.priceLevel,
          cuisineTypes: rec.restaurant.cuisineTypes,
          phoneNumber: rec.restaurant.phoneNumber,
          website: rec.restaurant.website,
          googleMapsUrl: rec.restaurant.googleMapsUrl,
          openingHours: rec.restaurant.openingHours,
          distance: rec.restaurant.distance,
          bookingInfo: rec.restaurant.bookingInfo,
          reservable: rec.restaurant.reservable,
          curbsidePickup: rec.restaurant.curbsidePickup,
          delivery: rec.restaurant.delivery,
          dineIn: rec.restaurant.dineIn,
          takeout: rec.restaurant.takeout,
          servesBreakfast: rec.restaurant.servesBreakfast,
          servesLunch: rec.restaurant.servesLunch,
          servesDinner: rec.restaurant.servesDinner,
          servesBrunch: rec.restaurant.servesBrunch,
          servesBeer: rec.restaurant.servesBeer,
          servesWine: rec.restaurant.servesWine,
          servesVegetarianFood: rec.restaurant.servesVegetarianFood,
        },
        score: Math.round(rec.score * 10) / 10,
        reasoning: rec.reasoning,
        suitabilityForEvent: rec.suitabilityForEvent,
        moodMatch: rec.moodMatch,
      })),
    };
  
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/services/googleMapsService.ts:55-208 (helper)

  Key helper function implementing the restaurant search logic using Google Places API Text Search or Nearby Search, handling various parameter combinations, API field selection for restaurant data, result conversion including cuisine extraction, distance calculation, and booking info analysis.

  async searchRestaurants(
    params: RestaurantSearchParams
  ): Promise<Restaurant[]> {
    try {
      const {
        location,
        placeName,
        cuisineTypes,
        keyword,
        radius = 2000,
        locale = 'en',
      } = params;
  
      // Build search query for Text Search API
      let textQuery = '';
  
      // If keyword is provided, prioritize it
      if (keyword) {
        textQuery = keyword;
        // Add location context
        if (placeName) {
          textQuery += ` in ${placeName}`;
        }
        // If cuisine types are also provided, combine them
        if (cuisineTypes && cuisineTypes.length > 0) {
          textQuery += ` ${cuisineTypes.join(' OR ')}`;
        }
      } else {
        // Build query from cuisine types and location
        const cuisineQuery =
          cuisineTypes && cuisineTypes.length > 0
            ? cuisineTypes.join(' OR ') + ' restaurant'
            : 'good restaurant';
  
        if (placeName) {
          textQuery = `${cuisineQuery} in ${placeName}`;
        } else {
          textQuery = cuisineQuery;
        }
      }
  
      // Prepare field mask based on required fields
      const fieldMask = this.getSearchFieldMask();
  
      // Build request for Text Search API
      let request;
      let response;
  
      // Use searchNearby only when we have coordinates AND no specific cuisine is requested
      if (
        location &&
        (!cuisineTypes || cuisineTypes.length === 0) &&
        !placeName
      ) {
        request = {
          includedTypes: ['restaurant'],
          locationRestriction: {
            circle: {
              center: {
                latitude: location.latitude,
                longitude: location.longitude,
              },
              radius: radius,
            },
          },
          maxResultCount: 20,
          languageCode: locale,
        };
        console.info('request', request);
        response = await this.client.searchNearby(request, {
          otherArgs: {
            headers: {
              'X-Goog-FieldMask': fieldMask,
            },
          },
        });
      } else {
        // Use searchText for:
        // 1. Place name searches (with or without cuisine)
        // 2. Coordinate searches with specific cuisine
        // 3. Keyword searches
        if (location && !placeName) {
          // Coordinate-based search with cuisine - add location bias
          request = {
            textQuery,
            locationBias: {
              circle: {
                center: {
                  latitude: location.latitude,
                  longitude: location.longitude,
                },
                radius: radius,
              },
            },
            maxResultCount: 20,
            languageCode: locale,
          };
        } else {
          // Place name search or no location provided
          request = {
            textQuery,
            maxResultCount: 20,
            languageCode: locale,
          };
        }
        console.info('request', request);
        response = await this.client.searchText(request, {
          otherArgs: {
            headers: {
              'X-Goog-FieldMask': fieldMask,
            },
          },
        });
      }
  
      if (!response?.[0]?.places) {
        return [];
      }
  
      const places = response[0].places;
  
      // Convert API response to Restaurant objects
      const restaurants: Restaurant[] = [];
  
      for (const place of places) {
        try {
          const restaurant = this.convertPlaceToRestaurant(place, location);
          if (restaurant) {
            restaurants.push(restaurant);
          }
        } catch (error) {
          console.error('Error converting place to restaurant:', error);
        }
      }
  
      // Sort restaurants by distance if location provided
      if (location) {
        restaurants.sort((a, b) => {
          const distanceA = a.distance || 0;
          const distanceB = b.distance || 0;
          return distanceA - distanceB;
        });
      }
  
      return restaurants;
    } catch (error) {
      console.error('Error searching restaurants:', error);
      throw new Error(
        `Failed to search restaurants: ${
          error instanceof Error ? error.message : 'Unknown error'
        }`
      );
    }
  }

• src/types/index.ts:6-17 (schema)

  TypeScript interface defining the structure of search parameters used throughout the tool handler and services for type safety.

  export interface RestaurantSearchParams {
    location?: Location; // Made optional when placeName is provided
    placeName?: string; // 🆕 NEW: Alternative to location - place name to geocode
    cuisineTypes: string[];
    mood: string;
    event: string;
    radius?: number; // in meters, default 20km
    priceLevel?: 1 | 2 | 3 | 4; // 1 = inexpensive, 4 = very expensive
    keyword?: string; // 🆕 NEW: Search for specific food types like "hotpot", "sushi", "pizza", etc.
    locale?: string; // 🆕 NEW: Locale for search results (e.g., "en", "zh-TW", "ja", "ko")
    strictCuisineFiltering?: boolean; // 🆕 NEW: If true, exclude restaurants that don't match cuisine criteria
  }