get_homologs

Instructions

Implementation Reference

• src/index.ts:1167-1252 (handler)

  The core handler function for the 'get_homologs' tool. It validates inputs, retrieves the source gene from Ensembl, searches for orthologs by gene symbol in a target species (default: mouse), and formats the response with source/ortholog details or fallback info if no ortholog found.

  private async handleGetHomologs(args: any) {
    if (!isValidHomologArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid homolog arguments');
    }
  
    try {
      const species = this.getDefaultSpecies(args.species);
  
      // Use overlap endpoint to get gene information from different species
      // This provides comparative information by looking up the same gene in different organisms
      const geneResponse = await this.apiClient.get(`/lookup/id/${args.gene_id}`, {
        params: { species }
      });
  
      const gene = geneResponse.data;
  
      // Get orthologs by looking up the same gene symbol in other species
      const targetSpecies = args.target_species || 'mus_musculus'; // Default to mouse
  
      try {
        const orthologResponse = await this.apiClient.get(`/lookup/symbol/${targetSpecies}/${gene.display_name}`);
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                source_gene: {
                  id: gene.id,
                  symbol: gene.display_name,
                  species: species,
                  description: gene.description,
                  location: `${gene.seq_region_name}:${gene.start}-${gene.end}`,
                  biotype: gene.biotype
                },
                ortholog: {
                  id: orthologResponse.data.id,
                  symbol: orthologResponse.data.display_name,
                  species: targetSpecies,
                  description: orthologResponse.data.description,
                  location: `${orthologResponse.data.seq_region_name}:${orthologResponse.data.start}-${orthologResponse.data.end}`,
                  biotype: orthologResponse.data.biotype
                },
                analysis: {
                  method: 'Gene symbol ortholog lookup',
                  conservation: 'Symbol-based orthology',
                  note: 'Genes with same symbol across species are typically orthologs'
                }
              }, null, 2),
            },
          ],
        };
      } catch (orthologError) {
        // Return information about the source gene even if ortholog not found
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                source_gene: {
                  id: gene.id,
                  symbol: gene.display_name,
                  species: species,
                  description: gene.description,
                  location: `${gene.seq_region_name}:${gene.start}-${gene.end}`,
                  biotype: gene.biotype
                },
                ortholog_search: {
                  target_species: targetSpecies,
                  result: 'No ortholog found with same gene symbol',
                  suggestion: 'Try different target species or use gene family analysis'
                },
                available_data: {
                  gene_info: 'Complete source gene information available',
                  cross_references: 'Use get_xrefs tool for external database links',
                  sequences: 'Use get_sequence tool for sequence comparison'
                }
              }, null, 2),
            },
          ],
        };
      }
    } catch (error) {
      return this.handleError(error, 'fetching comparative gene data');
    }
  }

• src/index.ts:657-666 (schema)

  JSON schema defining the input parameters for the get_homologs tool, including required gene_id and optional species, target_species, type, and format.

    type: 'object',
    properties: {
      gene_id: { type: 'string', description: 'Ensembl gene ID' },
      species: { type: 'string', description: 'Source species name (default: homo_sapiens)' },
      target_species: { type: 'string', description: 'Target species to search (optional)' },
      type: { type: 'string', enum: ['orthologues', 'paralogues', 'all'], description: 'Homolog type (default: all)' },
      format: { type: 'string', enum: ['json', 'xml'], description: 'Output format (default: json)' },
    },
    required: ['gene_id'],
  },

• src/index.ts:654-667 (registration)

  Registration of the get_homologs tool in the ListToolsRequestSchema handler, providing name, description, and input schema.

    name: 'get_homologs',
    description: 'Find orthologous and paralogous genes across species',
    inputSchema: {
      type: 'object',
      properties: {
        gene_id: { type: 'string', description: 'Ensembl gene ID' },
        species: { type: 'string', description: 'Source species name (default: homo_sapiens)' },
        target_species: { type: 'string', description: 'Target species to search (optional)' },
        type: { type: 'string', enum: ['orthologues', 'paralogues', 'all'], description: 'Homolog type (default: all)' },
        format: { type: 'string', enum: ['json', 'xml'], description: 'Output format (default: json)' },
      },
      required: ['gene_id'],
    },
  },

• src/index.ts:849-850 (registration)

  Tool handler dispatch in the CallToolRequestSchema switch statement, routing 'get_homologs' calls to handleGetHomologs.

  case 'get_homologs':
    return this.handleGetHomologs(args);

• src/index.ts:214-227 (schema)

  Type guard function for validating get_homologs input arguments before execution.

  const isValidHomologArgs = (
    args: any
  ): args is { gene_id: string; species?: string; target_species?: string; type?: string; format?: string } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.gene_id === 'string' &&
      args.gene_id.length > 0 &&
      (args.species === undefined || typeof args.species === 'string') &&
      (args.target_species === undefined || typeof args.target_species === 'string') &&
      (args.type === undefined || ['orthologues', 'paralogues', 'all'].includes(args.type)) &&
      (args.format === undefined || ['json', 'xml'].includes(args.format))
    );
  };