custom_bird_query

Instructions

Implementation Reference

• mcp-server.js:619-651 (handler)

  The handler function that executes the custom_bird_query tool. It extracts filters and limit from args, makes a POST request to the '/custom' API endpoint with the parameters, formats a descriptive response with results summary and list of matching birds.

    async handleCustomBirdQuery(args) {
      const { filters, limit = 50 } = args;
      const endpoint = `/custom`;
      const response = await this.makeAPIRequest(endpoint, {
        method: 'POST',
        body: JSON.stringify({ filters, limit }),
      });
  
      const filterDescription = Object.entries(filters)
        .map(([key, value]) => `${key}: ${Array.isArray(value) ? value.join(', ') : value}`)
        .join(', ');
  
      return {
        content: [
          {
            type: 'text',
            text: `# Custom Query Results
  
  🎯 **Query Filters:** ${filterDescription}
  📊 **Results:** ${response.pagination.totalItems} birds found
  
  ${response.data.map((bird, i) => `${i + 1}. **${bird.Scientific_name}**
     - Common name: ${bird.English_name_AviList || 'No common name'}
     - Family: ${bird.Family}
     - Order: ${bird.Order}
     - Conservation: ${bird.IUCN_Red_List_Category || 'Not assessed'}
     - Range: ${bird.Range ? bird.Range.substring(0, 80) + '...' : 'No range data'}`).join('\n\n')}
  
  ${response.pagination.hasNext ? `\n*Note: Showing first ${response.data.length} of ${response.pagination.totalItems} total matching records.*` : ''}`,
          },
        ],
      };
    }

• mcp-server.js:234-257 (schema)

  Input schema definition for the custom_bird_query tool, specifying filters object with possible fields like Family, Order, etc., and optional limit.

  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'],
  },

• mcp-server.js:231-258 (registration)

  Tool registration in the ListTools response, defining name, description, and inputSchema for custom_bird_query.

  {
    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'],
    },
  },

• mcp-server.js:315-316 (registration)

  Dispatch case in the CallToolRequest handler switch statement that routes custom_bird_query calls to the handleCustomBirdQuery method.

  case 'custom_bird_query':
    return await this.handleCustomBirdQuery(args);