get_notable_observations

Retrieve recent notable and rare bird sightings in a specified region using eBird data. Filter by date range, location type, and detail level to track uncommon species observations.

Instructions

Get recent notable/rare bird observations in a region. Notable observations are for locally or nationally rare species.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`region_code`	Yes	Country, subnational1, subnational2, or location code
`back`	No	Number of days back to fetch
`detail`	No	Level of detail in response	simple
`hotspot`	No	Only fetch from hotspots
`max_results`	No	Maximum observations to return
`spp_locale`	No	Language for common names	en

Implementation Reference

src/index.ts:85-96 (handler)

The handler function executes the tool logic by constructing parameters and calling the makeRequest helper to fetch notable observations from the eBird API, then returns the JSON-formatted result.

async (args) => {
  const params: Record<string, string | number | boolean> = {
    back: args.back,
    detail: args.detail,
    hotspot: args.hotspot,
    sppLocale: args.spp_locale,
  };
  if (args.max_results) params.maxResults = args.max_results;

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

src/index.ts:77-84 (schema)

Zod schema defining the input parameters for the get_notable_observations tool.

{
  region_code: z.string().describe("Country, subnational1, subnational2, or location code"),
  back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch"),
  detail: z.enum(["simple", "full"]).default("simple").describe("Level of detail in response"),
  hotspot: z.boolean().default(false).describe("Only fetch from hotspots"),
  max_results: z.number().min(1).max(10000).optional().describe("Maximum observations to return"),
  spp_locale: z.string().default("en").describe("Language for common names"),
},

src/index.ts:74-97 (registration)

Registration of the 'get_notable_observations' tool on the MCP server, including name, description, schema, and handler.

server.tool(
  "get_notable_observations",
  "Get recent notable/rare bird observations in a region. Notable observations are for locally or nationally rare species.",
  {
    region_code: z.string().describe("Country, subnational1, subnational2, or location code"),
    back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch"),
    detail: z.enum(["simple", "full"]).default("simple").describe("Level of detail in response"),
    hotspot: z.boolean().default(false).describe("Only fetch from hotspots"),
    max_results: z.number().min(1).max(10000).optional().describe("Maximum observations to return"),
    spp_locale: z.string().default("en").describe("Language for common names"),
  },
  async (args) => {
    const params: Record<string, string | number | boolean> = {
      back: args.back,
      detail: args.detail,
      hotspot: args.hotspot,
      sppLocale: args.spp_locale,
    };
    if (args.max_results) params.maxResults = args.max_results;

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

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

Shared helper function used by the tool to make authenticated HTTP requests to the eBird API.

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