search_itis
Query the ITIS database using SOLR syntax to retrieve taxonomic data. Specify fields, filters, sorting, and pagination for precise results.
Instructions
Search ITIS database using SOLR queries. Supports general search with flexible query parameters.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Specific fields to return (default: all available fields) | |
| filters | No | Additional filters as key-value pairs (e.g., {"kingdom": "Animalia", "rank": "Species"}) | |
| query | No | SOLR query string (e.g., "nameWInd:Homo*", "kingdom:Plantae", or "*:*" for all) | |
| rows | No | Number of results to return (default: 10, max: 100) | |
| sort | No | Sort order (e.g., "nameWInd asc", "tsn desc") | |
| start | No | Starting index for pagination (default: 0) |
Implementation Reference
- src/itis-client.ts:97-151 (handler)ITISClient.search(): the core function executing the SOLR search against ITIS API using provided query, pagination, sort, fields, and filters.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/tools.ts:273-287 (handler)MCP CallToolRequest handler case for 'search_itis': calls ITISClient.search and formats response as MCP content.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 definition and input schema for 'search_itis' in the exported tools array used for MCP tool registration.{ 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/tools.ts:261-265 (registration)Registration of tools list handler: returns the tools array including search_itis for MCP ListTools requests.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools, }; });
- src/itis-client.ts:3-10 (helper)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>; }