get_top_expressed_genes

Instructions

Implementation Reference

• src/handlers/expression-handlers.ts:304-368 (handler)

  Core handler function that validates tissueId input, calls apiClient to fetch top expressed genes, handles errors, computes expression statistics, and returns formatted markdown response with top genes list and stats.

  async getTopExpressedGenes(args: any) {
    if (!args.tissueId || typeof args.tissueId !== 'string') {
      throw new Error('tissueId parameter is required and must be a tissue ID string');
    }
  
    const result = await this.apiClient.getTopExpressedGenes(
      args.tissueId,
      args.datasetId || 'gtex_v8',
      args.filterMtGene !== false, // Default to true
      args.limit || 50
    );
  
    if (result.error) {
      return {
        content: [{
          type: "text",
          text: `Error retrieving top expressed genes: ${result.error}`
        }],
        isError: true
      };
    }
  
    const genes = result.data || [];
    if (genes.length === 0) {
      return {
        content: [{
          type: "text",
          text: `No expression data found for tissue: ${args.tissueId}`
        }]
      };
    }
  
    const tissueDisplayName = this.getTissueDisplayName(args.tissueId);
    let output = `**Top Expressed Genes in ${tissueDisplayName}**\n`;
    output += `Dataset: ${genes[0]?.datasetId}\n`;
    output += `Mitochondrial genes ${args.filterMtGene !== false ? 'excluded' : 'included'}\n`;
    output += `Showing top ${genes.length} genes\n\n`;
  
    genes.forEach((gene, index) => {
      output += `${(index + 1).toString().padStart(2)}. **${gene.geneSymbol}** (${gene.gencodeId})\n`;
      output += `    Expression: ${gene.median.toFixed(3)} ${gene.unit}\n`;
    });
  
    // Expression level analysis
    const expressions = genes.map(g => g.median);
    const stats = {
      highest: Math.max(...expressions),
      lowest: Math.min(...expressions),
      mean: expressions.reduce((sum, val) => sum + val, 0) / expressions.length,
      median: expressions[Math.floor(expressions.length / 2)]
    };
  
    output += `\n**Expression Statistics:**\n`;
    output += `  • Highest: ${stats.highest.toFixed(3)} ${genes[0].unit}\n`;
    output += `  • Lowest: ${stats.lowest.toFixed(3)} ${genes[0].unit}\n`;
    output += `  • Mean: ${stats.mean.toFixed(3)} ${genes[0].unit}\n`;
    output += `  • Median: ${stats.median.toFixed(3)} ${genes[0].unit}\n`;
  
    return {
      content: [{
        type: "text",
        text: output
      }]
    };
  }

• src/index.ts:92-125 (schema)

  Input schema defining parameters for the tool: tissueSiteDetailId (required), filterMtGenes, sortBy (median/mean), sortDirection, datasetId.

  name: "get_top_expressed_genes",
  description: "Get top expressed genes in a specific tissue",
  inputSchema: {
    type: "object",
    properties: {
      tissueSiteDetailId: {
        type: "string", 
        description: "Tissue site detail ID (e.g., Muscle_Skeletal, Brain_Cortex)"
      },
      filterMtGenes: {
        type: "boolean",
        description: "Filter out mitochondrial genes (default: true)",
        default: true
      },
      sortBy: {
        type: "string",
        description: "Sort criteria (default: median)",
        enum: ["median", "mean"],
        default: "median"
      },
      sortDirection: {
        type: "string",
        description: "Sort direction (default: desc)",
        enum: ["asc", "desc"], 
        default: "desc"
      },
      datasetId: {
        type: "string",
        description: "GTEx dataset ID (default: gtex_v8)",
        default: "gtex_v8"
      }
    },
    required: ["tissueSiteDetailId"]
  }

• src/index.ts:637-642 (registration)

  Registration in main request handler: dispatches 'get_top_expressed_genes' tool calls to expressionHandlers.getTopExpressedGenes with mapped arguments.

  if (name === "get_top_expressed_genes") {
    return await expressionHandlers.getTopExpressedGenes({
      tissueId: args?.tissueSiteDetailId,
      filterMtGene: args?.filterMtGenes,
      datasetId: args?.datasetId
    });

• src/utils/api-client.ts:354-376 (helper)

  Supporting API client utility that queries GTEx API endpoint for top expressed genes data in a tissue, handling pagination and errors.

  async getTopExpressedGenes(
    tissueSiteDetailId: string,
    datasetId: string = 'gtex_v8',
    filterMtGene: boolean = true,
    limit: number = 100
  ): Promise<GTExApiResponse<TopExpressedGene[]>> {
    try {
      const queryParams = this.buildQueryParams({
        tissueSiteDetailId,
        datasetId,
        filterMtGene,
        page: 0,
        itemsPerPage: limit
      });
      const response = await this.axiosInstance.get(`/expression/topExpressedGene?${queryParams}`);
      return { 
        data: response.data.data,
        paging_info: response.data.paging_info
      };
    } catch (error) {
      return error as GTExApiResponse<TopExpressedGene[]>;
    }
  }