Strava MCP Server

Instructions

Implementation Reference

• src/tools/listSegmentEfforts.ts:55-109 (handler)

  The tool implementation for `list-segment-efforts`, containing the tool definition and the execution logic.

  export const listSegmentEffortsTool = {
      name: "list-segment-efforts",
      description: "Lists the authenticated athlete's efforts on a specific segment, optionally filtering by date.",
      inputSchema: ListSegmentEffortsInputSchema,
      execute: async ({ segmentId, startDateLocal, endDateLocal, perPage }: ListSegmentEffortsInput) => {
          const token = process.env.STRAVA_ACCESS_TOKEN;
  
          if (!token) {
              console.error("Missing STRAVA_ACCESS_TOKEN environment variable.");
              return {
                  content: [{ type: "text" as const, text: "Configuration error: Missing Strava access token." }],
                  isError: true
              };
          }
  
          try {
              console.error(`Fetching segment efforts for segment ID: ${segmentId}...`);
              
              // Use the new params object structure
              const efforts = await fetchSegmentEfforts(token, segmentId, {
                  startDateLocal,
                  endDateLocal,
                  perPage
              });
  
              if (!efforts || efforts.length === 0) {
                  console.error(`No efforts found for segment ${segmentId} with the given filters.`);
                  return { content: [{ type: "text" as const, text: `No efforts found for segment ${segmentId} matching the criteria.` }] };
              }
  
              console.error(`Successfully fetched ${efforts.length} efforts for segment ${segmentId}.`);
              const effortSummaries = efforts.map(effort => formatSegmentEffort(effort)); // Use metric formatter
              const responseText = `**Segment ${segmentId} Efforts:**\n\n${effortSummaries.join("\n")}`;
  
              return { content: [{ type: "text" as const, text: responseText }] };
          } catch (error) {
              const errorMessage = error instanceof Error ? error.message : String(error);
              console.error(`Error listing efforts for segment ${segmentId}: ${errorMessage}`);
  
              let userFriendlyMessage;
              if (errorMessage.startsWith("SUBSCRIPTION_REQUIRED:")) {
                  userFriendlyMessage = `🔒 Accessing segment efforts requires a Strava subscription. Please check your subscription status.`;
              } else if (errorMessage.includes("Record Not Found") || errorMessage.includes("404")) {
                  userFriendlyMessage = `Segment with ID ${segmentId} not found (when listing efforts).`;
              } else {
                  userFriendlyMessage = `An unexpected error occurred while listing efforts for segment ${segmentId}. Details: ${errorMessage}`;
              }
  
              return {
                  content: [{ type: "text" as const, text: `❌ ${userFriendlyMessage}` }],
                  isError: true
              };
          }
      }
  };

• src/tools/listSegmentEfforts.ts:12-17 (schema)

  Zod schema defining the input parameters for the list-segment-efforts tool.

  const ListSegmentEffortsInputSchema = z.object({
      segmentId: z.number().int().positive().describe("The ID of the segment for which to list efforts."),
      startDateLocal: z.string().datetime({ message: "Invalid start date format. Use ISO 8601." }).optional().describe("Filter efforts starting after this ISO 8601 date-time (optional)."),
      endDateLocal: z.string().datetime({ message: "Invalid end date format. Use ISO 8601." }).optional().describe("Filter efforts ending before this ISO 8601 date-time (optional)."),
      perPage: z.number().int().positive().max(200).optional().default(30).describe("Number of efforts to return per page (default: 30, max: 200).")
  });