explore_taxonomy

Instructions

Implementation Reference

• src/tools.ts:439-550 (handler)

  The handler function that implements the core logic of the 'explore_taxonomy' tool. It retrieves the target organism, constructs a SOLR query based on the specified taxonomic level, searches for related species, and formats the response with target details and related results.

  case 'explore_taxonomy': {
    const { scientificName, level, rows } = args as any;
    
    // First, get the target organism's details
    const targetResult = await itisClient.searchByScientificName(scientificName);
    if (targetResult.response.numFound === 0) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: `No organism found with scientific name: ${scientificName}`,
            }, null, 2),
          },
        ],
      };
    }
    
    const target = targetResult.response.docs[0];
    let searchQuery = '';
    let description = '';
    
    switch (level) {
      case 'siblings':
        if (target.unit1) {
          searchQuery = `unit1:"${target.unit1}" AND rank:Species`;
          description = `Other species in genus ${target.unit1}`;
        }
        break;
      case 'family':
        if (target.hierarchySoFarWRanks && target.hierarchySoFarWRanks[0]) {
          const hierarchy = target.hierarchySoFarWRanks[0];
          const familyMatch = hierarchy.match(/Family:([^$]+)/);
          if (familyMatch) {
            const family = familyMatch[1];
            searchQuery = `hierarchySoFarWRanks:*Family\\:${family}* AND rank:Species`;
            description = `Other species in family ${family}`;
          }
        }
        break;
      case 'order':
        if (target.hierarchySoFarWRanks && target.hierarchySoFarWRanks[0]) {
          const hierarchy = target.hierarchySoFarWRanks[0];
          const orderMatch = hierarchy.match(/Order:([^$]+)/);
          if (orderMatch) {
            const order = orderMatch[1];
            searchQuery = `hierarchySoFarWRanks:*Order\\:${order}* AND rank:Species`;
            description = `Other species in order ${order}`;
          }
        }
        break;
      case 'class':
        if (target.hierarchySoFarWRanks && target.hierarchySoFarWRanks[0]) {
          const hierarchy = target.hierarchySoFarWRanks[0];
          const classMatch = hierarchy.match(/Class:([^$]+)/);
          if (classMatch) {
            const cls = classMatch[1];
            searchQuery = `hierarchySoFarWRanks:*Class\\:${cls}* AND rank:Species`;
            description = `Other species in class ${cls}`;
          }
        }
        break;
    }
    
    if (!searchQuery) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: `Unable to find taxonomic information for level: ${level}`,
              target: target,
            }, null, 2),
          },
        ],
      };
    }
    
    const relatedResult = await itisClient.search({
      query: searchQuery,
      rows: rows || 10,
      sort: 'nameWInd asc'
    });
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            target: {
              name: target.nameWInd,
              tsn: target.tsn,
              rank: target.rank,
            },
            exploration: {
              level: level,
              description: description,
              totalResults: relatedResult.response.numFound,
              results: relatedResult.response.docs.map((doc: any) => ({
                tsn: doc.tsn,
                name: doc.nameWInd,
                kingdom: doc.kingdom,
                rank: doc.rank,
                commonNames: processVernacularNames(doc.vernacular, 'English'),
                usage: doc.usage,
              })),
            },
          }, null, 2),
        },
      ],
    };
  }

• src/tools.ts:192-210 (schema)

  Input schema for the 'explore_taxonomy' tool, defining required parameters scientificName and level (with enum), and optional rows.

  inputSchema: {
    type: 'object',
    properties: {
      scientificName: {
        type: 'string',
        description: 'Scientific name to explore (e.g., "Homo sapiens")',
      },
      level: {
        type: 'string',
        description: 'Taxonomic level to explore: "siblings" (same genus), "family" (same family), "order" (same order), "class" (same class)',
        enum: ['siblings', 'family', 'order', 'class']
      },
      rows: {
        type: 'number',
        description: 'Number of results to return (default: 10)',
      },
    },
    required: ['scientificName', 'level'],
  },

• src/tools.ts:189-211 (registration)

  Registration of the 'explore_taxonomy' tool in the tools array, which is used for listing tools and validation.

  {
    name: 'explore_taxonomy',
    description: 'Explore taxonomic relationships by finding related organisms at different taxonomic levels.',
    inputSchema: {
      type: 'object',
      properties: {
        scientificName: {
          type: 'string',
          description: 'Scientific name to explore (e.g., "Homo sapiens")',
        },
        level: {
          type: 'string',
          description: 'Taxonomic level to explore: "siblings" (same genus), "family" (same family), "order" (same order), "class" (same class)',
          enum: ['siblings', 'family', 'order', 'class']
        },
        rows: {
          type: 'number',
          description: 'Number of results to return (default: 10)',
        },
      },
      required: ['scientificName', 'level'],
    },
  },