eBird MCP Server

Instructions

Implementation Reference

• src/index.ts:298-304 (handler)

  The handler function for the 'get_top_100' tool. It constructs parameters, makes an API request to retrieve top 100 contributors for a specific date and region, and returns the result as formatted JSON.

  async (args) => {
    const params: Record<string, string | number | boolean> = { rankedBy: args.ranked_by };
    if (args.max_results) params.maxResults = args.max_results;
  
    const result = await makeRequest(`/product/top100/${args.region_code}/${args.year}/${args.month}/${args.day}`, params);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }

• src/index.ts:290-297 (schema)

  Zod schema defining the input parameters for the 'get_top_100' tool, including region, date components, ranking metric, and optional max results.

  {
    region_code: z.string().describe("Country or subnational1 code"),
    year: z.number().min(1800).describe("Year"),
    month: z.number().min(1).max(12).describe("Month"),
    day: z.number().min(1).max(31).describe("Day of month"),
    ranked_by: z.enum(["spp", "cl"]).default("spp").describe("'spp' for species count, 'cl' for checklist count"),
    max_results: z.number().min(1).max(100).optional().describe("Limit results"),
  },

• src/index.ts:287-305 (registration)

  The server.tool call that registers the 'get_top_100' tool with its description, input schema, and handler function.

  server.tool(
    "get_top_100",
    "Get the top 100 contributors on a given date.",
    {
      region_code: z.string().describe("Country or subnational1 code"),
      year: z.number().min(1800).describe("Year"),
      month: z.number().min(1).max(12).describe("Month"),
      day: z.number().min(1).max(31).describe("Day of month"),
      ranked_by: z.enum(["spp", "cl"]).default("spp").describe("'spp' for species count, 'cl' for checklist count"),
      max_results: z.number().min(1).max(100).optional().describe("Limit results"),
    },
    async (args) => {
      const params: Record<string, string | number | boolean> = { rankedBy: args.ranked_by };
      if (args.max_results) params.maxResults = args.max_results;
  
      const result = await makeRequest(`/product/top100/${args.region_code}/${args.year}/${args.month}/${args.day}`, params);
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    }
  );