ITIS MCP Server

Instructions

Implementation Reference

• src/tools.ts:413-437 (handler)

  MCP tool handler implementation for search_by_vernacular_name: extracts parameters (vernacularName, rows, start), invokes ITISClient.searchByVernacularName, processes results by extracting key fields and formatting common names using processVernacularNames, returns JSON response with search metadata and mapped results.

  case 'search_by_vernacular_name': {
    const { vernacularName, rows, start } = args as any;
    const result = await itisClient.searchByVernacularName(vernacularName, { rows, start });
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            searchTerm: vernacularName,
            searchType: 'vernacular/common name',
            totalResults: result.response.numFound,
            start: result.response.start,
            results: result.response.docs.map((doc: any) => ({
              tsn: doc.tsn,
              scientificName: doc.nameWInd,
              kingdom: doc.kingdom,
              rank: doc.rank,
              commonNames: processVernacularNames(doc.vernacular, 'English'),
              usage: doc.usage,
            })),
          }, null, 2),
        },
      ],
    };
  }

• src/tools.ts:167-188 (schema)

  Tool definition including name, description, and input schema for search_by_vernacular_name, defining required vernacularName and optional pagination parameters.

  {
    name: 'search_by_vernacular_name',
    description: 'Search for organisms by their common/vernacular names in ITIS database.',
    inputSchema: {
      type: 'object',
      properties: {
        vernacularName: {
          type: 'string',
          description: 'Common/vernacular name to search for (e.g., "human", "dog", "oak tree")',
        },
        rows: {
          type: 'number',
          description: 'Number of results to return (default: 10)',
        },
        start: {
          type: 'number',
          description: 'Starting index for pagination (default: 0)',
        },
      },
      required: ['vernacularName'],
    },
  },

• src/tools.ts:11-257 (registration)

  The tools array exports all MCP tools including search_by_vernacular_name, used by ListToolsRequestHandler to list available tools.

  export const tools: Tool[] = [
    {
      name: 'search_itis',
      description: 'Search ITIS database using SOLR queries. Supports general search with flexible query parameters.',
      inputSchema: {
        type: 'object',
        properties: {
          query: {
            type: 'string',
            description: 'SOLR query string (e.g., "nameWInd:Homo*", "kingdom:Plantae", or "*:*" for all)',
          },
          start: {
            type: 'number',
            description: 'Starting index for pagination (default: 0)',
          },
          rows: {
            type: 'number',
            description: 'Number of results to return (default: 10, max: 100)',
          },
          sort: {
            type: 'string',
            description: 'Sort order (e.g., "nameWInd asc", "tsn desc")',
          },
          fields: {
            type: 'array',
            items: { type: 'string' },
            description: 'Specific fields to return (default: all available fields)',
          },
          filters: {
            type: 'object',
            additionalProperties: { type: 'string' },
            description: 'Additional filters as key-value pairs (e.g., {"kingdom": "Animalia", "rank": "Species"})',
          },
        },
      },
    },
    {
      name: 'search_by_scientific_name',
      description: 'Search for organisms by their scientific name in ITIS database.',
      inputSchema: {
        type: 'object',
        properties: {
          name: {
            type: 'string',
            description: 'Scientific name to search for (e.g., "Homo sapiens", "Quercus")',
          },
          rows: {
            type: 'number',
            description: 'Number of results to return (default: 10)',
          },
          start: {
            type: 'number',
            description: 'Starting index for pagination (default: 0)',
          },
        },
        required: ['name'],
      },
    },
    {
      name: 'search_by_tsn',
      description: 'Search for organisms by their Taxonomic Serial Number (TSN) in ITIS database.',
      inputSchema: {
        type: 'object',
        properties: {
          tsn: {
            type: 'string',
            description: 'Taxonomic Serial Number (TSN) to search for',
          },
        },
        required: ['tsn'],
      },
    },
    {
      name: 'search_by_kingdom',
      description: 'Search for organisms within a specific kingdom in ITIS database.',
      inputSchema: {
        type: 'object',
        properties: {
          kingdom: {
            type: 'string',
            description: 'Kingdom name (e.g., "Animalia", "Plantae", "Fungi", "Bacteria")',
          },
          rows: {
            type: 'number',
            description: 'Number of results to return (default: 10)',
          },
          start: {
            type: 'number',
            description: 'Starting index for pagination (default: 0)',
          },
        },
        required: ['kingdom'],
      },
    },
    {
      name: 'search_by_rank',
      description: 'Search for organisms by their taxonomic rank in ITIS database.',
      inputSchema: {
        type: 'object',
        properties: {
          rank: {
            type: 'string',
            description: 'Taxonomic rank (e.g., "Species", "Genus", "Family", "Order", "Class", "Phylum", "Kingdom")',
          },
          rows: {
            type: 'number',
            description: 'Number of results to return (default: 10)',
          },
          start: {
            type: 'number',
            description: 'Starting index for pagination (default: 0)',
          },
        },
        required: ['rank'],
      },
    },
    {
      name: 'get_hierarchy',
      description: 'Get the complete taxonomic hierarchy for a given TSN.',
      inputSchema: {
        type: 'object',
        properties: {
          tsn: {
            type: 'string',
            description: 'Taxonomic Serial Number (TSN) to get hierarchy for',
          },
        },
        required: ['tsn'],
      },
    },
    {
      name: 'autocomplete_search',
      description: 'Search for organisms with autocomplete functionality using partial names.',
      inputSchema: {
        type: 'object',
        properties: {
          partialName: {
            type: 'string',
            description: 'Partial scientific name for autocomplete (e.g., "Homo", "Quer")',
          },
          rows: {
            type: 'number',
            description: 'Number of results to return (default: 10)',
          },
        },
        required: ['partialName'],
      },
    },
    {
      name: 'get_statistics',
      description: 'Get basic statistics about the ITIS database (total number of records).',
      inputSchema: {
        type: 'object',
        properties: {},
      },
    },
    {
      name: 'search_by_vernacular_name',
      description: 'Search for organisms by their common/vernacular names in ITIS database.',
      inputSchema: {
        type: 'object',
        properties: {
          vernacularName: {
            type: 'string',
            description: 'Common/vernacular name to search for (e.g., "human", "dog", "oak tree")',
          },
          rows: {
            type: 'number',
            description: 'Number of results to return (default: 10)',
          },
          start: {
            type: 'number',
            description: 'Starting index for pagination (default: 0)',
          },
        },
        required: ['vernacularName'],
      },
    },
    {
      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'],
      },
    },
    {
      name: 'get_random_species',
      description: 'Get random species from ITIS database with optional taxonomic filters.',
      inputSchema: {
        type: 'object',
        properties: {
          kingdom: {
            type: 'string',
            description: 'Kingdom filter (e.g., "Animalia", "Plantae", "Fungi")',
          },
          phylum: {
            type: 'string',
            description: 'Phylum filter (e.g., "Chordata", "Arthropoda")',
          },
          class: {
            type: 'string',
            description: 'Class filter (e.g., "Mammalia", "Aves", "Reptilia")',
          },
          order: {
            type: 'string',
            description: 'Order filter (e.g., "Carnivora", "Primates")',
          },
          family: {
            type: 'string',
            description: 'Family filter (e.g., "Felidae", "Canidae")',
          },
          genus: {
            type: 'string',
            description: 'Genus filter (e.g., "Panthera", "Canis")',
          },
          count: {
            type: 'number',
            description: 'Number of random species to return (default: 1, max: 10)',
          },
          requireVernacular: {
            type: 'boolean',
            description: 'Only return species that have common names (default: false)',
          },
          vernacularLanguage: {
            type: 'string',
            description: 'Language for vernacular names (default: "English"). Other options: "French", "Spanish", etc.',
          },
        },
      },
    },
  ];

• src/itis-client.ts:202-210 (helper)

  Core search logic in ITISClient: transforms vernacular name by replacing spaces with wildcards for SOLR query on vernacular field, delegates to general search method.

  async searchByVernacularName(vernacularName: string, options: Partial<ITISSearchOptions> = {}): Promise<ITISResponse> {
    // Replace spaces with asterisks for SOLR wildcard search in vernacular field
    const searchTerm = vernacularName.replace(/\s+/g, '*');
    return this.search({
      ...options,
      query: `vernacular:*${searchTerm}*`,
      sort: options.sort || 'nameWInd asc'
    });
  }

• src/itis-client.ts:46-92 (helper)

  Utility function to parse and format vernacular names from ITIS data: extracts names/languages from delimited strings, prioritizes preferred language (English), sorts preferred first, deduplicates case-insensitively. Used in tool handler response formatting.

  export function processVernacularNames(vernacularArray: string[] = [], preferredLanguage: string = 'English'): string[] {
    if (!vernacularArray || vernacularArray.length === 0) return [];
    
    const processed: { name: string; language: string; preferred: boolean }[] = [];
    
    vernacularArray.forEach(vernacularString => {
      // Parse format: $name$language$preferred$id$date$
      const parts = vernacularString.split('$');
      if (parts.length >= 4) {
        const name = parts[1]?.trim();
        const language = parts[2]?.trim();
        const preferred = parts[3]?.trim() === 'Y';
        
        if (name && language) {
          processed.push({ name, language, preferred });
        }
      }
    });
    
    // Filter to preferred language first, then others as fallback
    const preferredLanguageNames = processed.filter(item => item.language === preferredLanguage);
    const otherLanguageNames = processed.filter(item => item.language !== preferredLanguage);
    
    // Sort within each language group: preferred names first, then alphabetical
    const sortByPreference = (a: any, b: any) => {
      if (a.preferred && !b.preferred) return -1;
      if (b.preferred && !a.preferred) return 1;
      return a.name.localeCompare(b.name);
    };
    
    preferredLanguageNames.sort(sortByPreference);
    otherLanguageNames.sort(sortByPreference);
    
    // Combine: preferred language first, then others
    const sortedProcessed = [...preferredLanguageNames, ...otherLanguageNames];
    
    // Remove duplicates and return just the names
    const uniqueNames = new Set<string>();
    return sortedProcessed
      .map(item => item.name)
      .filter(name => {
        const lowerName = name.toLowerCase();
        if (uniqueNames.has(lowerName)) return false;
        uniqueNames.add(lowerName);
        return true;
      });
  }