lookup_gene
Retrieve detailed gene information including annotations, transcripts, and exons from Ensembl by entering a gene ID or symbol.
Instructions
Get detailed gene information by stable ID or symbol
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gene_id | Yes | Ensembl gene ID or gene symbol (e.g., ENSG00000139618, BRCA2) | |
| species | No | Species name (default: homo_sapiens) | |
| expand | No | Include transcript and exon details (default: false) | |
| format | No | Output format (default: json) |
Implementation Reference
- src/index.ts:923-958 (handler)The primary handler function for the 'lookup_gene' tool. Validates input using isValidGeneArgs, constructs the Ensembl REST API request to /lookup/id/{gene_id}, handles expand and format parameters, fetches data, and returns formatted JSON response or error.private async handleLookupGene(args: any) { if (!isValidGeneArgs(args)) { throw new McpError(ErrorCode.InvalidParams, 'Invalid gene lookup arguments'); } try { const species = this.getDefaultSpecies(args.species); const format = args.format || 'json'; let endpoint = `/lookup/id/${args.gene_id}`; const params: any = { species }; if (args.expand) { params.expand = 1; } if (format !== 'json') { params.format = format; } const response = await this.apiClient.get(endpoint, { params }); return { content: [ { type: 'text', text: typeof response.data === 'object' ? JSON.stringify(response.data, null, 2) : String(response.data), }, ], }; } catch (error) { return this.handleError(error, 'looking up gene'); } }
- src/index.ts:835-837 (registration)Registration of the 'lookup_gene' tool in the CallToolRequestSchema switch statement, dispatching to the handleLookupGene method.case 'lookup_gene': return this.handleLookupGene(args); case 'get_transcripts':
- src/index.ts:570-581 (schema)Tool schema definition including inputSchema for 'lookup_gene' provided in the ListToolsRequestSchema response.name: 'lookup_gene', description: 'Get detailed gene information by stable ID or symbol', inputSchema: { type: 'object', properties: { gene_id: { type: 'string', description: 'Ensembl gene ID or gene symbol (e.g., ENSG00000139618, BRCA2)' }, species: { type: 'string', description: 'Species name (default: homo_sapiens)' }, expand: { type: 'boolean', description: 'Include transcript and exon details (default: false)' }, format: { type: 'string', enum: ['json', 'fasta', 'gff'], description: 'Output format (default: json)' }, }, required: ['gene_id'], },
- src/index.ts:155-167 (helper)Type guard function for validating 'lookup_gene' tool arguments before execution.const isValidGeneArgs = ( args: any ): args is { gene_id: string; species?: string; expand?: boolean; format?: string } => { return ( typeof args === 'object' && args !== null && typeof args.gene_id === 'string' && args.gene_id.length > 0 && (args.species === undefined || typeof args.species === 'string') && (args.expand === undefined || typeof args.expand === 'boolean') && (args.format === undefined || ['json', 'fasta', 'gff'].includes(args.format)) ); };
- src/index.ts:489-509 (registration)The handleLookupGene is also invoked in ReadResourceRequestSchema for URI ensembl://gene/{gene_id}, integrating gene lookup as a resource.const geneMatch = uri.match(/^ensembl:\/\/gene\/([^\/]+)$/); if (geneMatch) { const geneId = geneMatch[1]; try { const result = await this.handleLookupGene({ gene_id: geneId }); return { contents: [ { uri: request.params.uri, mimeType: 'application/json', text: result.content[0].text, }, ], }; } catch (error) { throw new McpError( ErrorCode.InternalError, `Failed to fetch gene ${geneId}: ${error instanceof Error ? error.message : 'Unknown error'}` ); } }