ITIS MCP Server

Instructions

Implementation Reference

• src/tools.ts:552-589 (handler)

  MCP tool handler for 'get_random_species' that processes input arguments, calls ITISClient.getRandomSpecies, and returns formatted JSON response with species details.
  case 'get_random_species': { const args = request.params.arguments as any; const { count = 1, requireVernacular = false, vernacularLanguage = 'English', ...filters } = args; // Limit count to reasonable maximum const limitedCount = Math.min(count, 10); const result = await itisClient.getRandomSpecies({ ...filters, count: limitedCount, requireVernacular, vernacularLanguage }); return { content: [ { type: 'text', text: JSON.stringify({ searchType: 'random species', filters: filters, requireVernacular, vernacularLanguage, totalPossible: result.response.numFound, results: result.response.docs.map((doc: any) => ({ tsn: doc.tsn, scientificName: doc.nameWInd, kingdom: doc.kingdom, rank: doc.rank, commonNames: processVernacularNames(doc.vernacular, vernacularLanguage), hierarchy: doc.hierarchySoFarWRanks?.[0] || '', usage: doc.usage, })), }, null, 2), }, ], }; }
• src/tools.ts:212-256 (schema)

  Input schema definition for the 'get_random_species' tool, including all optional taxonomic filters, count, vernacular options.
  { 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/tools.ts:11-257 (registration)

  The tools array registers 'get_random_species' among other tools, returned by ListToolsRequestHandler.
  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:212-324 (helper)

  ITISClient.getRandomSpecies method: core logic for retrieving random species using strategic random sampling via SOLR queries with varying sorts and offsets for better taxonomic diversity.
  async getRandomSpecies(options: { kingdom?: string; phylum?: string; class?: string; order?: string; family?: string; genus?: string; count?: number; requireVernacular?: boolean; vernacularLanguage?: string; } = {}): Promise<ITISResponse> { const { count = 1, requireVernacular = false, vernacularLanguage = 'English' } = options; // Build query with taxonomic filters const queryParts: string[] = ['rank:Species']; if (options.kingdom) queryParts.push(`kingdom:"${options.kingdom}"`); if (options.phylum) queryParts.push(`hierarchySoFarWRanks:*Phylum\\:${options.phylum}*`); if (options.class) queryParts.push(`hierarchySoFarWRanks:*Class\\:${options.class}*`); if (options.order) queryParts.push(`hierarchySoFarWRanks:*Order\\:${options.order}*`); if (options.family) queryParts.push(`hierarchySoFarWRanks:*Family\\:${options.family}*`); if (options.genus) queryParts.push(`unit1:"${options.genus}"`); // Only include species with vernacular names if requested if (requireVernacular) { if (vernacularLanguage) { queryParts.push(`vernacular:*${vernacularLanguage}*`); } else { queryParts.push('vernacular:[* TO *]'); } } const query = queryParts.join(' AND '); // Strategy 1: Try to get taxonomic diversity using facets let facetResult; try { // Try using facets to understand taxonomic distribution (experimental) const facetUrl = `${this.baseUrl}?q=${encodeURIComponent(query)}&rows=0&facet=true&facet.field=rank&facet.limit=20&wt=json`; const facetResponse = await fetch(facetUrl); facetResult = await facetResponse.json(); } catch (error) { // If facets fail, proceed without them facetResult = null; } // Get total count for random offset calculation const countResult = (facetResult as ITISResponse) || await this.search({ query, rows: 0 }); const totalSpecies = countResult.response.numFound; if (totalSpecies === 0) { return countResult; // Return empty result if no species found } // Strategy 2: Use hierarchical sorting for better diversity const results: any[] = []; const existingTsns = new Set<string>(); const maxAttempts = Math.min(count * 3, 15); // Slightly fewer attempts but more strategic // Try different sort orders to maximize diversity const sortOrders = [ 'hierarchicalSort asc', 'hierarchicalSort desc', 'tsn asc', 'updateDate desc', 'nameWInd asc' ]; for (let attempt = 0; attempt < maxAttempts && results.length < count; attempt++) { // Pick a random sort order to ensure diversity const sortOrder = sortOrders[attempt % sortOrders.length]; // Use wider random distribution const segmentSize = Math.floor(totalSpecies / (count * 2)); const randomSegment = Math.floor(Math.random() * Math.max(1, count * 2)); const randomStart = randomSegment * segmentSize + Math.floor(Math.random() * Math.min(segmentSize, 100)); const actualStart = Math.min(randomStart, totalSpecies - 5); try { const offsetResult = await this.search({ query, start: actualStart, rows: Math.min(3, count - results.length + 1), // Smaller fetch size for more diversity sort: sortOrder }); // Add unique results for (const doc of offsetResult.response.docs) { if (!existingTsns.has(doc.tsn) && results.length < count) { results.push(doc); existingTsns.add(doc.tsn); } } } catch (error) { // Skip this attempt and try another continue; } } // Final shuffle const finalResults = results.sort(() => Math.random() - 0.5); return { response: { numFound: totalSpecies, start: 0, docs: finalResults } }; }