MCP Server Boilerplate

Instructions

Implementation Reference

• src/maps.ts:145-201 (handler)

  The handler function that performs geocoding using Google Maps API, handles errors, and formats the markdown output.

  export async function geocode(
    params: z.infer<typeof geocodeSchema>,
    extra?: any
  ) {
    const apiKey = process.env.GOOGLE_MAPS_API_KEY;
    if (!apiKey) {
      throw new Error("GOOGLE_MAPS_API_KEY is required");
    }
  
    try {
      const response = await googleMapsClient.geocode({
        params: {
          address: params.address,
          key: apiKey,
        },
      });
  
      const results = response.data.results;
      if (results.length === 0) {
        return {
          content: [
            {
              type: "text" as const,
              text: "No results found for the given address.",
            },
          ],
        };
      }
  
      const location = results[0];
      return {
        content: [
          {
            type: "text" as const,
            text: formatLocationToMarkdown(
              "Geocoded Location", 
              location.formatted_address, 
              location.geometry.location.lat, 
              location.geometry.location.lng,
              location.place_id
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error geocoding address: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  }

• src/maps.ts:105-107 (schema)

  Zod schema defining the input parameters for the geocode tool: an address string.

  export const geocodeSchema = z.object({
    address: z.string().describe("The address to geocode"),
  });

• src/index.ts:60-67 (registration)

  Registration of the 'geocode' tool in the MCP server, providing name, description, input schema, and handler wrapper.

  server.tool(
    "geocode",
    "Convert an address to coordinates",
    geocodeSchema.shape,
    async (params) => {
      return await geocode(params);
    }
  );

• src/maps.ts:7-13 (helper)

  Helper function to format geocoding results into markdown with title, address, coordinates, place ID, and Google Maps link.

  function formatLocationToMarkdown(title: string, address: string, lat: number, lng: number, placeId?: string): string {
    let markdown = `# ${title}\n\n`;
    markdown += `Address: ${address}  \n`;
    markdown += `Coordinates: ${lat}, ${lng}  \n`;
    if (placeId) markdown += `Place ID: \`${placeId}\`  \n`;
    markdown += `Google Maps: [View on Maps](https://maps.google.com/?q=${lat},${lng})`;
    return markdown;