ITIS MCP Server

Instructions

Implementation Reference

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

  Executes the explore_taxonomy tool: finds target organism by scientific name, constructs SOLR query for related species at specified taxonomic level (siblings, family, order, class), performs search via ITIS client, and formats 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:189-211 (schema)

  Input schema and metadata for the explore_taxonomy tool, defining parameters: scientificName (required), level (required, enum), rows (optional).
  { 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'], }, },
• src/tools.ts:11-257 (registration)

  The tools array exports all tool definitions, including explore_taxonomy, which is used for listing available tools via 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.', }, }, }, }, ];