search_genes
Find genes by symbol, name, or description to analyze expression patterns and genetic associations across human and mouse tissues.
Instructions
Search for genes by symbol, name, or description
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination (default: 0) | |
| pageSize | No | Number of results per page (default: 250) | |
| query | Yes | Search query (gene symbol, name, or description) | |
| species | No | Species (default: human) | human |
Implementation Reference
- src/handlers/reference-handlers.ts:19-83 (handler)Core handler function implementing the search_genes MCP tool. Validates input query, calls the API client to search genes, handles errors and empty results, formats results as formatted markdown text output with gene details including location, type, status, description, Entrez ID, and TSS position.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)Tool dispatch/registration in the main CallToolRequestSchema handler. Routes search_genes calls to the referenceHandlers.searchGenes method, mapping MCP input parameters (query, page, pageSize as itemsPerPage).if (name === "search_genes") { return await referenceHandlers.searchGenes({ query: args?.query, page: args?.page, itemsPerPage: args?.pageSize });
- src/index.ts:374-401 (schema)MCP tool schema registration in ListToolsRequestSchema response. Defines the input schema for search_genes including required 'query' parameter and optional pagination/species fields.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)API client helper method that performs the actual HTTP request to GTEx Portal /reference/geneSearch endpoint, handling query parameters (geneId as query, defaults, pagination) and returning typed response with genes and paging info.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 input parameters for the searchGenes API call, used by api-client.ts and handler for type safety and validation.export interface SearchGenesParams { geneId: string; gencodeVersion?: string; genomeBuild?: string; page?: number; itemsPerPage?: number; }