get_birds_by_taxonomy
Retrieve bird data filtered by taxonomic classification such as Order, Family, or Taxa from AviBase MCP Server. Specify rank and value to fetch results efficiently.
Instructions
Get birds filtered by taxonomic classification (Order, Family, or taxonomic rank).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| level | Yes | Taxonomic level to filter by | |
| limit | No | Maximum number of results to return (default: 50) | |
| value | Yes | Value to filter by (e.g., "Strigiformes" for owls, "Accipitridae" for hawks) |
Implementation Reference
- mcp-server.js:398-425 (handler)The handler function that implements the tool logic: extracts parameters, makes API call to taxonomy endpoint, computes species count, and returns formatted markdown response with sample records.async handleGetBirdsByTaxonomy(args) { const { level, value, limit = 50 } = args; const endpoint = `/taxonomy/${level}/${encodeURIComponent(value)}?limit=${limit}`; const response = await this.makeAPIRequest(endpoint); const speciesCount = response.data.filter(bird => bird.Taxon_rank === 'species').length; return { content: [ { type: 'text', text: `# ${level}: ${value} 📊 **Summary:** - **Total records:** ${response.pagination.totalItems} - **Species in results:** ${speciesCount} **Sample records:** ${response.data.slice(0, 10).map((bird, i) => `${i + 1}. **${bird.Scientific_name}** (${bird.Taxon_rank}) - Common name: ${bird.English_name_AviList || 'No common name'} - Family: ${bird.Family} - Conservation: ${bird.IUCN_Red_List_Category || 'Not assessed'}`).join('\n\n')} ${response.pagination.hasNext ? `\n*Note: Showing first ${response.data.length} of ${response.pagination.totalItems} total records.*` : ''}`, }, ], }; }
- mcp-server.js:107-126 (schema)Input schema defining parameters for the tool: level (Order/Family/Taxon_rank), value (filter value), and optional limit.inputSchema: { type: 'object', properties: { level: { type: 'string', description: 'Taxonomic level to filter by', enum: ['Order', 'Family', 'Taxon_rank'], }, value: { type: 'string', description: 'Value to filter by (e.g., "Strigiformes" for owls, "Accipitridae" for hawks)', }, limit: { type: 'number', description: 'Maximum number of results to return (default: 50)', default: 50, }, }, required: ['level', 'value'], },
- mcp-server.js:104-127 (registration)Tool registration in the ListTools response, including name, description, and input schema.{ name: 'get_birds_by_taxonomy', description: 'Get birds filtered by taxonomic classification (Order, Family, or taxonomic rank).', inputSchema: { type: 'object', properties: { level: { type: 'string', description: 'Taxonomic level to filter by', enum: ['Order', 'Family', 'Taxon_rank'], }, value: { type: 'string', description: 'Value to filter by (e.g., "Strigiformes" for owls, "Accipitridae" for hawks)', }, limit: { type: 'number', description: 'Maximum number of results to return (default: 50)', default: 50, }, }, required: ['level', 'value'], }, },
- mcp-server.js:294-295 (registration)Dispatch case in the CallToolRequestSchema handler that routes to the specific handler function.case 'get_birds_by_taxonomy': return await this.handleGetBirdsByTaxonomy(args);
- mcp-server.js:41-64 (helper)Helper method used by the handler to make requests to the backend bird data API, with error handling.async makeAPIRequest(endpoint, options = {}) { try { const url = `${API_BASE_URL}${endpoint}`; const response = await fetch(url, { headers: { 'Content-Type': 'application/json', ...options.headers, }, ...options, }); if (!response.ok) { throw new Error(`API request failed: ${response.status} ${response.statusText}`); } return await response.json(); } catch (error) { console.error(`API request error for ${endpoint}:`, error); throw new McpError( ErrorCode.InternalError, `Failed to fetch data from bird API: ${error.message}` ); } }