MCP Server Boilerplate

Instructions

Implementation Reference

• src/maps.ts:331-397 (handler)

  Main handler function for get-directions tool that calls Google Maps Directions API, processes the route data, and formats the response using formatDirectionsToMarkdown.

  export async function getDirections(
    params: z.infer<typeof directionsSchema>,
    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.directions({
        params: {
          origin: params.origin,
          destination: params.destination,
          mode: (params.mode || "driving") as any,
          key: apiKey,
        },
      });
  
      const routes = response.data.routes;
      if (routes.length === 0) {
        return {
          content: [
            {
              type: "text" as const,
              text: "No routes found between the given locations.",
            },
          ],
        };
      }
  
      const route = routes[0];
      const leg = route.legs[0];
  
      const routeData = {
        distance: leg.distance.text,
        duration: leg.duration.text,
        start_address: leg.start_address,
        end_address: leg.end_address,
        steps: leg.steps.map((step) => ({
          instruction: step.html_instructions.replace(/<[^>]*>/g, ""),
          distance: step.distance.text,
          duration: step.duration.text,
        })),
      };
  
      return {
        content: [
          {
            type: "text" as const,
            text: formatDirectionsToMarkdown(routeData),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error getting directions: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  }

• src/maps.ts:123-130 (schema)

  Zod schema defining input parameters for the get-directions tool: origin, destination, and optional mode.

  export const directionsSchema = z.object({
    origin: z.string().describe("Starting location (address or lat,lng)"),
    destination: z.string().describe("Ending location (address or lat,lng)"),
    mode: z
      .enum(["driving", "walking", "bicycling", "transit"])
      .optional()
      .describe("Travel mode"),
  });

• src/index.ts:90-97 (registration)

  Registration of the get-directions tool on the MCP server using server.tool, referencing directionsSchema and getDirections handler.

  server.tool(
    "get-directions",
    "Get directions between two locations",
    directionsSchema.shape,
    async (params) => {
      return await getDirections(params);
    }
  );

• src/maps.ts:40-53 (helper)

  Helper function to format directions data into Markdown for the tool response.

  function formatDirectionsToMarkdown(route: any): string {
    let markdown = `# Directions: ${route.start_address} → ${route.end_address}\n\n`;
    markdown += `Distance: ${route.distance}  \n`;
    markdown += `Duration: ${route.duration}  \n\n`;
    
    if (route.steps && route.steps.length) {
      markdown += `## Step-by-Step Directions\n\n`;
      route.steps.forEach((step: any, index: number) => {
        markdown += `${index + 1}. ${step.instruction} *(${step.distance}, ${step.duration})*\n`;
      });
    }
    
    return markdown;
  }