AviBase MCP Server

Instructions

Implementation Reference

• mcp-server.js:542-565 (handler)

  The main handler function for the 'get_random_birds' tool. It extracts the count parameter (default 10, max 50), calls the backend API at /random, and formats a markdown response listing random birds with their details.
  async handleGetRandomBirds(args) { const { count = 10 } = args; const endpoint = `/random?count=${Math.min(count, 50)}`; const response = await this.makeAPIRequest(endpoint); return { content: [ { type: 'text', text: `# Random Bird Discovery 🎲 **${response.data.length}** randomly selected birds for exploration: ${response.data.map((bird, i) => `${i + 1}. **${bird.Scientific_name}** - Common name: ${bird.English_name_AviList || 'No common name'} - Family: ${bird.Family} (${bird.Order}) - Conservation: ${bird.IUCN_Red_List_Category || 'Not assessed'} - Range: ${bird.Range ? bird.Range.substring(0, 100) + '...' : 'No range data'}`).join('\n\n')} These random selections showcase the incredible diversity of avian species in the database!`, }, ], }; }
• mcp-server.js:201-216 (schema)

  The tool schema definition including name, description, and inputSchema for 'get_random_birds' used in the ListTools response.
  { name: 'get_random_birds', description: 'Get a random sample of birds for exploration and discovery.', inputSchema: { type: 'object', properties: { count: { type: 'number', description: 'Number of random birds to return (default: 10, max: 50)', default: 10, maximum: 50, }, }, required: [], }, },
• mcp-server.js:309-310 (registration)

  The switch case registration/dispatch for 'get_random_birds' in the CallToolRequestHandler.
  case 'get_random_birds': return await this.handleGetRandomBirds(args);
• mcp-server.js:68-280 (registration)

  The ListToolsRequestHandler where all tools including 'get_random_birds' are registered by returning the tools list.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'get_bird_stats', description: 'Get comprehensive statistics about the bird dataset including total records, species count, families, orders, and conservation categories.', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'search_birds', description: 'Search for birds by scientific or common name with fuzzy matching support.', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search term (bird name to search for)', }, exact: { type: 'boolean', description: 'Whether to use exact matching (default: false for fuzzy search)', default: false, }, limit: { type: 'number', description: 'Maximum number of results to return (default: 20)', default: 20, }, }, required: ['query'], }, }, { 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'], }, }, { name: 'get_conservation_status', description: 'Get birds by IUCN Red List conservation status (CR=Critically Endangered, EN=Endangered, VU=Vulnerable, EX=Extinct, etc.).', inputSchema: { type: 'object', properties: { category: { type: 'string', description: 'IUCN Red List category', enum: ['CR', 'EN', 'VU', 'NT', 'LC', 'DD', 'EX', 'EW'], }, limit: { type: 'number', description: 'Maximum number of results to return (default: 50)', default: 50, }, }, required: ['category'], }, }, { name: 'get_birds_by_region', description: 'Find birds by geographic region or range (e.g., Madagascar, Australia, Africa, etc.).', inputSchema: { type: 'object', properties: { region: { type: 'string', description: 'Geographic region to search for in bird ranges', }, limit: { type: 'number', description: 'Maximum number of results to return (default: 50)', default: 50, }, }, required: ['region'], }, }, { name: 'get_extinct_species', description: 'Get all extinct or possibly extinct bird species.', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Maximum number of results to return (default: 100)', default: 100, }, }, required: [], }, }, { name: 'get_birds_by_authority', description: 'Find birds described by a specific taxonomic authority (e.g., Linnaeus, Darwin, etc.).', inputSchema: { type: 'object', properties: { authority: { type: 'string', description: 'Name of the taxonomic authority', }, limit: { type: 'number', description: 'Maximum number of results to return (default: 50)', default: 50, }, }, required: ['authority'], }, }, { name: 'get_random_birds', description: 'Get a random sample of birds for exploration and discovery.', inputSchema: { type: 'object', properties: { count: { type: 'number', description: 'Number of random birds to return (default: 10, max: 50)', default: 10, maximum: 50, }, }, required: [], }, }, { name: 'get_bird_report', description: 'Get a detailed report for a specific bird species including related species and comprehensive information.', inputSchema: { type: 'object', properties: { scientific_name: { type: 'string', description: 'Scientific name of the bird species (e.g., "Aquila chrysaetos")', }, }, required: ['scientific_name'], }, }, { name: 'custom_bird_query', description: 'Perform complex queries with multiple filters for advanced bird data analysis.', inputSchema: { type: 'object', properties: { filters: { type: 'object', description: 'Object containing field-value pairs for filtering', properties: { Family: { type: 'string' }, Order: { type: 'string' }, IUCN_Red_List_Category: { type: 'array', items: { type: 'string' } }, Taxon_rank: { type: 'string' }, }, }, limit: { type: 'number', description: 'Maximum number of results to return (default: 50)', default: 50, }, }, required: ['filters'], }, }, { name: 'execute_jsonata_query', description: 'Execute a raw JSONata query for advanced data analysis and transformation. JSONata is a powerful query language for JSON data.', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'JSONata query expression (e.g., "$count($[Taxon_rank = \\"species\\"])" to count species)', }, limit: { type: 'number', description: 'Maximum number of results to return for array results (default: 50)', default: 50, }, }, required: ['query'], }, }, ], }; });