GTEx MCP Server

Instructions

Implementation Reference

• src/handlers/expression-handlers.ts:599-659 (handler)

  The core handler function that implements the get_tissue_specific_genes tool. It fetches top expressed genes for the given tissue using the API client and formats them as tissue-specific gene candidates, including error handling and output formatting.

  async getTissueSpecificGenes(args: any) {
    if (!args.tissueId || typeof args.tissueId !== 'string') {
      throw new Error('tissueId parameter is required and must be a tissue ID string');
    }
  
    // Get top expressed genes for this tissue
    const topGenesResult = await this.apiClient.getTopExpressedGenes(
      args.tissueId,
      args.datasetId || 'gtex_v8',
      true, // Filter MT genes
      100 // Get more genes for specificity analysis
    );
  
    if (topGenesResult.error) {
      return {
        content: [{
          type: "text",
          text: `Error retrieving tissue-specific genes: ${topGenesResult.error}`
        }],
        isError: true
      };
    }
  
    const topGenes = topGenesResult.data || [];
    if (topGenes.length === 0) {
      return {
        content: [{
          type: "text",
          text: `No expression data found for tissue: ${args.tissueId}`
        }]
      };
    }
  
    // For tissue specificity, we'll analyze the top genes
    // In a real implementation, this would compare across all tissues
    const tissueDisplayName = this.getTissueDisplayName(args.tissueId);
    
    let output = `**Tissue-Specific Genes in ${tissueDisplayName}**\n`;
    output += `Dataset: ${topGenes[0]?.datasetId}\n`;
    output += `Analysis: Top expressing genes (tissue specificity analysis)\n\n`;
  
    // Show top tissue-specific candidates
    const specificGenes = topGenes.slice(0, 20);
    
    output += `**Candidate Tissue-Specific Genes (${specificGenes.length}):**\n`;
    specificGenes.forEach((gene, index) => {
      output += `${(index + 1).toString().padStart(2)}. **${gene.geneSymbol}** (${gene.gencodeId})\n`;
      output += `    • Expression: ${gene.median.toFixed(3)} ${gene.unit}\n`;
      output += `    • Rank in tissue: ${index + 1}\n`;
    });
  
    output += `\n**Note:** This analysis shows highly expressed genes in ${tissueDisplayName}. `;
    output += `True tissue specificity requires comparison across all tissues using advanced statistical methods.\n`;
  
    return {
      content: [{
        type: "text",
        text: output
      }]
    };
  }

• src/index.ts:127-151 (schema)

  The tool schema definition in the listTools response, including name, description, and inputSchema with required tissueSiteDetailId and optional parameters.

  {
    name: "get_tissue_specific_genes",
    description: "Get genes with tissue-specific expression patterns",
    inputSchema: {
      type: "object",
      properties: {
        tissueSiteDetailId: {
          type: "string",
          description: "Tissue site detail ID (e.g., Muscle_Skeletal, Brain_Cortex)"
        },
        selectionCriteria: {
          type: "string",
          description: "Selection criteria for tissue specificity (default: highestInGroup)",
          enum: ["highestInGroup", "aboveThreshold"],
          default: "highestInGroup"
        },
        datasetId: {
          type: "string",
          description: "GTEx dataset ID (default: gtex_v8)", 
          default: "gtex_v8"
        }
      },
      required: ["tissueSiteDetailId"]
    }
  },

• src/index.ts:644-650 (registration)

  The dispatch logic in the CallToolRequestHandler that maps the tool name to the ExpressionHandlers.getTissueSpecificGenes method, passing mapped arguments.

  if (name === "get_tissue_specific_genes") {
    return await expressionHandlers.getTissueSpecificGenes({
      tissueId: args?.tissueSiteDetailId,
      selectionCriteria: args?.selectionCriteria,
      datasetId: args?.datasetId
    });
  }