search_itis
Search the ITIS taxonomic database using SOLR queries to find species by scientific name, TSN, kingdom, or rank with customizable filters and pagination.
Instructions
Search ITIS database using SOLR queries. Supports general search with flexible query parameters.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | SOLR query string (e.g., "nameWInd:Homo*", "kingdom:Plantae", or "*:*" for all) | |
| start | No | Starting index for pagination (default: 0) | |
| rows | No | Number of results to return (default: 10, max: 100) | |
| sort | No | Sort order (e.g., "nameWInd asc", "tsn desc") | |
| fields | No | Specific fields to return (default: all available fields) | |
| filters | No | Additional filters as key-value pairs (e.g., {"kingdom": "Animalia", "rank": "Species"}) |
Implementation Reference
- src/tools.ts:273-287 (handler)MCP tool handler for 'search_itis': calls ITISClient.search with input args and returns formatted JSON response with results.
case 'search_itis': { const result = await itisClient.search(args as any); return { content: [ { type: 'text', text: JSON.stringify({ totalResults: result.response.numFound, start: result.response.start, results: result.response.docs, }, null, 2), }, ], }; } - src/tools.ts:12-46 (schema)Tool registration and input schema definition for 'search_itis'.
{ 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"})', }, }, }, }, - src/itis-client.ts:97-151 (helper)Core helper method ITISClient.search() that constructs SOLR query parameters and fetches data from ITIS API.
async search(options: ITISSearchOptions = {}): Promise<ITISResponse> { const params = new URLSearchParams(); // Default parameters params.append('wt', 'json'); params.append('indent', 'true'); // Query parameter if (options.query) { params.append('q', options.query); } else { params.append('q', '*:*'); } // Pagination if (options.start !== undefined) { params.append('start', options.start.toString()); } if (options.rows !== undefined) { params.append('rows', options.rows.toString()); } else { params.append('rows', '10'); // Default to 10 rows } // Sorting if (options.sort) { params.append('sort', options.sort); } // Field selection if (options.fields && options.fields.length > 0) { params.append('fl', options.fields.join(',')); } // Filters if (options.filters) { Object.entries(options.filters).forEach(([key, value]) => { params.append('fq', `${key}:${value}`); }); } const url = `${this.baseUrl}?${params.toString()}`; try { const response = await fetch(url); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json() as ITISResponse; return data; } catch (error) { throw new Error(`Failed to fetch ITIS data: ${error}`); } } - src/itis-client.ts:3-10 (schema)Type definition for search options matching the tool input schema.
export interface ITISSearchOptions { query?: string; start?: number; rows?: number; sort?: string; fields?: string[]; filters?: Record<string, string>; }