find_homologs

Instructions

Implementation Reference

• src/index.ts:699-755 (handler)

  The main handler function for the 'find_homologs' tool. Validates input using isValidHomologyArgs, calls the STRING API '/tsv/homology' endpoint, parses the TSV response into HomologyResult objects using parseTsvData, groups results by species, and returns a formatted JSON response with homologs organized by species.

  private async handleFindHomologs(args: any) {
    if (!isValidHomologyArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid homology arguments');
    }
  
    try {
      const species = args.species || '9606';
  
      const params: any = {
        identifiers: args.protein_id,
        species: species,
      };
  
      if (args.target_species) {
        params.target_species = args.target_species.join(',');
      }
  
      const response = await this.apiClient.get('/tsv/homology', { params });
  
      const homologs = this.parseTsvData<HomologyResult>(response.data);
  
      // Group by species
      const groupedHomologs: Record<string, HomologyResult[]> = {};
      homologs.forEach(homolog => {
        const speciesKey = `${homolog.ncbiTaxonId}_${homolog.taxonName}`;
        if (!groupedHomologs[speciesKey]) {
          groupedHomologs[speciesKey] = [];
        }
        groupedHomologs[speciesKey].push(homolog);
      });
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              query_protein: args.protein_id,
              source_species: species,
              total_homologs: homologs.length,
              species_count: Object.keys(groupedHomologs).length,
              homologs_by_species: groupedHomologs,
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error finding homologs: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:362-374 (registration)

  Registration of the 'find_homologs' tool in the ListToolsRequestSchema handler. Defines the tool name, description, and input schema returned to clients.

  {
    name: 'find_homologs',
    description: 'Find homologous proteins across different species',
    inputSchema: {
      type: 'object',
      properties: {
        protein_id: { type: 'string', description: 'Protein identifier (gene name, UniProt ID, or STRING ID)' },
        species: { type: 'string', description: 'Source species name or NCBI taxonomy ID (default: 9606 for human)' },
        target_species: { type: 'array', items: { type: 'string' }, description: 'Target species to search for homologs (optional)' },
      },
      required: ['protein_id'],
    },
  },

• src/index.ts:115-128 (schema)

  Input validation function (type guard) for 'find_homologs' tool arguments, ensuring protein_id is a non-empty string, species is optional string, and target_species is optional array of strings.

  const isValidHomologyArgs = (
    args: any
  ): args is { protein_id: string; species?: string; target_species?: string[] } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.protein_id === 'string' &&
      args.protein_id.length > 0 &&
      (args.species === undefined || typeof args.species === 'string') &&
      (args.target_species === undefined ||
       (Array.isArray(args.target_species) &&
        args.target_species.every((sp: any) => typeof sp === 'string')))
    );
  };

• src/index.ts:52-58 (schema)

  TypeScript interface defining the structure of individual homology results used by the parseTsvData function and handler response.

  interface HomologyResult {
    stringId: string;
    ncbiTaxonId: number;
    taxonName: string;
    preferredName: string;
    annotation: string;
  }

• src/index.ts:403-404 (registration)

  Dispatcher case in CallToolRequestSchema handler that routes 'find_homologs' tool calls to the handleFindHomologs method.

  case 'find_homologs':
    return this.handleFindHomologs(args);