search_transcripts

Instructions

Implementation Reference

• src/handlers/reference-handlers.ts:165-230 (handler)

  The handler function getTranscripts that implements the core logic of the 'search_transcripts' tool. It validates input, fetches transcripts from the GTEx API client, sorts them, formats a detailed output with locations, lengths, types, and gene summary statistics.

  async getTranscripts(args: any) {
    if (!args.geneId || typeof args.geneId !== 'string') {
      throw new Error('geneId parameter is required and must be a GENCODE gene ID');
    }
  
    const result = await this.apiClient.getTranscripts(
      args.geneId,
      args.gencodeVersion || 'v26',
      args.genomeBuild || 'GRCh38/hg38'
    );
  
    if (result.error) {
      return {
        content: [{
          type: "text",
          text: `Error retrieving transcripts: ${result.error}`
        }],
        isError: true
      };
    }
  
    const transcripts = result.data || [];
    if (transcripts.length === 0) {
      return {
        content: [{
          type: "text",
          text: `No transcripts found for gene: ${args.geneId}`
        }]
      };
    }
  
    let output = `**Transcripts for ${transcripts[0]?.geneSymbol} (${args.geneId})**\n`;
    output += `Found ${transcripts.length} transcripts\n`;
    output += `Genome: ${transcripts[0]?.genomeBuild}, GENCODE: ${transcripts[0]?.gencodeVersion}\n\n`;
  
    // Sort transcripts by start position
    const sortedTranscripts = transcripts.sort((a, b) => a.start - b.start);
  
    sortedTranscripts.forEach((transcript, index) => {
      output += `${(index + 1).toString().padStart(2)}. **${transcript.transcriptId}**\n`;
      output += `    • Location: ${transcript.chromosome}:${transcript.start.toLocaleString()}-${transcript.end.toLocaleString()} (${transcript.strand})\n`;
      output += `    • Length: ${(transcript.end - transcript.start + 1).toLocaleString()} bp\n`;
      output += `    • Type: ${transcript.featureType}\n`;
      output += `    • Source: ${transcript.source}\n`;
    });
  
    // Calculate gene span and summary
    const geneStart = Math.min(...sortedTranscripts.map(t => t.start));
    const geneEnd = Math.max(...sortedTranscripts.map(t => t.end));
    const geneLengths = sortedTranscripts.map(t => t.end - t.start + 1);
    const avgLength = geneLengths.reduce((sum, len) => sum + len, 0) / geneLengths.length;
  
    output += `\n**Gene Summary:**\n`;
    output += `  • Gene span: ${(geneEnd - geneStart + 1).toLocaleString()} bp\n`;
    output += `  • Total transcripts: ${transcripts.length}\n`;
    output += `  • Average transcript length: ${Math.round(avgLength).toLocaleString()} bp\n`;
    output += `  • Longest transcript: ${Math.max(...geneLengths).toLocaleString()} bp\n`;
    output += `  • Shortest transcript: ${Math.min(...geneLengths).toLocaleString()} bp\n`;
  
    return {
      content: [{
        type: "text",
        text: output
      }]
    };
  }

• src/index.ts:545-562 (schema)

  The input schema definition for the 'search_transcripts' tool, specifying required gencodeId and optional transcriptType filter.

  {
    name: "search_transcripts",
    description: "Search for gene transcripts and isoforms",
    inputSchema: {
      type: "object",
      properties: {
        gencodeId: {
          type: "string",
          description: "GENCODE gene ID (e.g., ENSG00000223972.5)"
        },
        transcriptType: {
          type: "string",
          description: "Transcript type filter (optional)",
          enum: ["protein_coding", "lncRNA", "pseudogene", "miRNA"]
        }
      },
      required: ["gencodeId"]
    }

• src/index.ts:768-772 (registration)

  The registration/dispatch code in the main CallToolRequestHandler that routes calls to 'search_transcripts' to the referenceHandlers.getTranscripts method.

  if (name === "search_transcripts") {
    return await referenceHandlers.getTranscripts({
      geneId: args?.gencodeId
    });
  }