search_genes

Instructions

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;
  }