get_hotspots_in_region

Find birding hotspots within a specific region using eBird data. Filter results by recent visitor activity and choose output format.

Instructions

Get birding hotspots in a region.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`region_code`	Yes	Country, subnational1, or subnational2 code
`back`	No	Only hotspots visited in last N days
`fmt`	No	Response format	json

Implementation Reference

src/index.ts:399-414 (registration)

Registration of the 'get_hotspots_in_region' tool using server.tool(), including name, description, input schema with Zod validation, and the handler function.

server.tool(
  "get_hotspots_in_region",
  "Get birding hotspots in a region.",
  {
    region_code: z.string().describe("Country, subnational1, or subnational2 code"),
    back: z.number().min(1).max(30).optional().describe("Only hotspots visited in last N days"),
    fmt: z.enum(["json", "csv"]).default("json").describe("Response format"),
  },
  async (args) => {
    const params: Record<string, string | number | boolean> = { fmt: args.fmt };
    if (args.back) params.back = args.back;

    const result = await makeRequest(`/ref/hotspot/${args.region_code}`, params);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }
);

src/index.ts:407-413 (handler)

Handler function that prepares query parameters (fmt and optional back) and calls the shared makeRequest helper to fetch hotspot data from the eBird API endpoint `/ref/hotspot/${region_code}`, returning the JSON-stringified result wrapped in MCP content format.

async (args) => {
  const params: Record<string, string | number | boolean> = { fmt: args.fmt };
  if (args.back) params.back = args.back;

  const result = await makeRequest(`/ref/hotspot/${args.region_code}`, params);
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
}

src/index.ts:402-406 (schema)

Input schema defined using Zod for parameter validation: region_code (required string), back (optional number 1-30), fmt (enum json/csv, default json).

{
  region_code: z.string().describe("Country, subnational1, or subnational2 code"),
  back: z.number().min(1).max(30).optional().describe("Only hotspots visited in last N days"),
  fmt: z.enum(["json", "csv"]).default("json").describe("Response format"),
},

src/index.ts:19-36 (helper)

Shared helper function used by all tools to make authenticated HTTP requests to the eBird API, handling URL params, fetch, error checking, and JSON parsing.

async function makeRequest(endpoint: string, params: Record<string, string | number | boolean> = {}): Promise<unknown> {
  const url = new URL(`${BASE_URL}${endpoint}`);
  Object.entries(params).forEach(([key, value]) => {
    if (value !== undefined && value !== null) {
      url.searchParams.append(key, String(value));
    }
  });

  const response = await fetch(url.toString(), {
    headers: { "X-eBirdApiToken": API_KEY! },
  });

  if (!response.ok) {
    throw new Error(`eBird API error: ${response.status} ${response.statusText}`);
  }

  return response.json();
}

eBird MCP Server