search_genes
Search for genes by symbol, name, or description to analyze gene expression data across human and mouse tissues using GTEx genomics resources.
Instructions
Search for genes by symbol, name, or description
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (gene symbol, name, or description) | |
| species | No | Species (default: human) | human |
| page | No | Page number for pagination (default: 0) | |
| pageSize | No | Number of results per page (default: 250) |
Implementation Reference
- src/handlers/reference-handlers.ts:19-83 (handler)Main handler function that executes the search_genes tool logic: validates query input, calls API client, processes gene search results from GTEx API, formats comprehensive markdown output with gene details.async searchGenes(args: any) { if (!args.query || typeof args.query !== 'string') { throw new Error('query parameter is required and must be a search string (gene symbol, GENCODE ID, or keyword)'); } const result = await this.apiClient.searchGenes({ geneId: args.query, gencodeVersion: args.gencodeVersion || 'v26', genomeBuild: args.genomeBuild || 'GRCh38/hg38', page: args.page || 0, itemsPerPage: args.itemsPerPage || 50 }); if (result.error) { return { content: [{ type: "text", text: `Error searching genes: ${result.error}` }], isError: true }; } const genes = result.data || []; if (genes.length === 0) { return { content: [{ type: "text", text: `No genes found matching query: "${args.query}"` }] }; } let output = `**Gene Search Results for "${args.query}"**\n`; output += `Found ${genes.length} genes\n`; output += `Genome: ${genes[0]?.genomeBuild}, GENCODE: ${genes[0]?.gencodeVersion}\n\n`; genes.forEach((gene, index) => { output += `${(index + 1).toString().padStart(2)}. **${gene.geneSymbol}** (${gene.gencodeId})\n`; output += ` • Location: ${gene.chromosome}:${gene.start.toLocaleString()}-${gene.end.toLocaleString()} (${gene.strand})\n`; output += ` • Type: ${gene.geneType}\n`; output += ` • Status: ${gene.geneStatus}\n`; if (gene.description) { const truncatedDesc = gene.description.length > 80 ? gene.description.substring(0, 80) + '...' : gene.description; output += ` • Description: ${truncatedDesc}\n`; } if (gene.entrezGeneId) { output += ` • Entrez ID: ${gene.entrezGeneId}\n`; } output += ` • TSS: ${gene.tss.toLocaleString()}\n`; }); if (result.paging_info && result.paging_info.totalNumberOfItems > genes.length) { output += `\n**Note:** Showing ${genes.length} of ${result.paging_info.totalNumberOfItems} total results.\n`; } return { content: [{ type: "text", text: output }] }; }
- src/index.ts:715-720 (registration)MCP server tool dispatch/registration: routes 'search_genes' calls to the ReferenceHandlers.searchGenes method with mapped arguments.if (name === "search_genes") { return await referenceHandlers.searchGenes({ query: args?.query, page: args?.page, itemsPerPage: args?.pageSize });
- src/index.ts:374-401 (schema)Tool schema definition including input validation schema for search_genes, listed in ListToolsResponse.name: "search_genes", description: "Search for genes by symbol, name, or description", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query (gene symbol, name, or description)" }, species: { type: "string", description: "Species (default: human)", enum: ["human", "mouse"], default: "human" }, page: { type: "integer", description: "Page number for pagination (default: 0)", default: 0 }, pageSize: { type: "integer", description: "Number of results per page (default: 250)", default: 250 } }, required: ["query"] }
- src/utils/api-client.ts:149-166 (helper)Supporting API client method that makes HTTP request to GTEx Portal /reference/geneSearch endpoint and handles response/error.async searchGenes(params: SearchGenesParams): Promise<GTExApiResponse<Gene[]>> { try { const queryParams = this.buildQueryParams({ geneId: params.geneId, gencodeVersion: params.gencodeVersion || 'v26', genomeBuild: params.genomeBuild || 'GRCh38/hg38', page: params.page || 0, itemsPerPage: params.itemsPerPage || 250 }); const response = await this.axiosInstance.get(`/reference/geneSearch?${queryParams}`); return { data: response.data.data, paging_info: response.data.paging_info }; } catch (error) { return error as GTExApiResponse<Gene[]>; } }
- src/types/gtex-types.ts:385-391 (schema)TypeScript interface defining parameters for gene search API calls, used by GTExApiClient.searchGenes.export interface SearchGenesParams { geneId: string; gencodeVersion?: string; genomeBuild?: string; page?: number; itemsPerPage?: number; }