search_by_vernacular_name
Search the ITIS database for organisms using common names like 'human', 'dog', or 'oak tree' to retrieve taxonomic information and scientific classifications.
Instructions
Search for organisms by their common/vernacular names in ITIS database.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| vernacularName | Yes | Common/vernacular name to search for (e.g., "human", "dog", "oak tree") | |
| rows | No | Number of results to return (default: 10) | |
| start | No | Starting index for pagination (default: 0) |
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; }); }