search_genes
Find genes by name, description, or identifier using species-specific queries. Filter results by feature type, biotype, or limit output for targeted genomic data analysis on the Ensembl MCP Server.
Instructions
Search for genes by name, description, or identifier
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| biotype | No | Filter by biotype (e.g., protein_coding, lncRNA) | |
| feature | No | Feature type to search (default: gene) | |
| limit | No | Maximum results (1-200, default: 25) | |
| query | Yes | Search term (gene name, description, or partial match) | |
| species | No | Species name (default: homo_sapiens) |
Implementation Reference
- src/index.ts:597-610 (registration)Registration of the 'search_genes' tool including name, description, and input schema definition.name: 'search_genes', description: 'Search for genes by name, description, or identifier', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search term (gene name, description, or partial match)' }, species: { type: 'string', description: 'Species name (default: homo_sapiens)' }, feature: { type: 'string', enum: ['gene', 'transcript'], description: 'Feature type to search (default: gene)' }, biotype: { type: 'string', description: 'Filter by biotype (e.g., protein_coding, lncRNA)' }, limit: { type: 'number', description: 'Maximum results (1-200, default: 25)', minimum: 1, maximum: 200 }, }, required: ['query'], }, },
- src/index.ts:839-840 (registration)Dispatch/registration of the 'search_genes' handler in the CallToolRequestSchema switch statement.case 'search_genes': return this.handleSearchGenes(args);
- src/index.ts:996-1029 (handler)Core handler implementation for 'search_genes': validates input, constructs API parameters, queries Ensembl REST /search endpoint, and returns formatted JSON results.private async handleSearchGenes(args: any) { if (!isValidSearchArgs(args)) { throw new McpError(ErrorCode.InvalidParams, 'Invalid search arguments'); } try { const species = this.getDefaultSpecies(args.species); const feature = args.feature || 'gene'; const limit = args.limit || 25; const params: any = { q: args.query, species, feature, limit, }; if (args.biotype) { params.biotype = args.biotype; } const response = await this.apiClient.get('/search', { params }); return { content: [ { type: 'text', text: JSON.stringify(response.data, null, 2), }, ], }; } catch (error) { return this.handleError(error, 'searching genes'); }
- src/index.ts:184-197 (schema)Input validation type guard (schema enforcement) for 'search_genes' tool arguments used in the handler.const isValidSearchArgs = ( args: any ): args is { query: string; species?: string; feature?: string; biotype?: string; limit?: number } => { return ( typeof args === 'object' && args !== null && typeof args.query === 'string' && args.query.length > 0 && (args.species === undefined || typeof args.species === 'string') && (args.feature === undefined || ['gene', 'transcript'].includes(args.feature)) && (args.biotype === undefined || typeof args.biotype === 'string') && (args.limit === undefined || (typeof args.limit === 'number' && args.limit > 0 && args.limit <= 200)) ); };
- src/index.ts:890-892 (helper)Helper utility to provide default species ('homo_sapiens') used in 'search_genes' handler.private getDefaultSpecies(species?: string): string { return species || 'homo_sapiens'; }