search_proteins

Instructions

Implementation Reference

• src/index.ts:757-808 (handler)

  The core handler function that implements the search_proteins tool. Validates input, queries the STRING API endpoint '/tsv/get_string_ids', parses the TSV response into ProteinAnnotation objects, and formats the results as JSON.

  private async handleSearchProteins(args: any) {
    if (!isValidSearchArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid search arguments');
    }
  
    try {
      const species = args.species || '';
      const limit = args.limit || 10;
  
      const params: any = {
        identifiers: args.query,
        limit: limit,
      };
  
      if (species) {
        params.species = species;
      }
  
      const response = await this.apiClient.get('/tsv/get_string_ids', { params });
  
      const results = this.parseTsvData<ProteinAnnotation>(response.data);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              query: args.query,
              species_filter: species || 'all',
              total_results: results.length,
              proteins: results.map(protein => ({
                string_id: protein.stringId,
                preferred_name: protein.preferredName,
                ncbi_taxon_id: protein.ncbiTaxonId,
                annotation: protein.annotation,
                protein_size: protein.protein_size,
              }))
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error searching proteins: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }

• src/index.ts:375-387 (registration)

  Registration of the search_proteins tool in the ListToolsRequestHandler response, including name, description, and input schema definition.

  {
    name: 'search_proteins',
    description: 'Search for proteins by name or identifier across species',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query (protein name, gene name, or identifier)' },
        species: { type: 'string', description: 'Species name or NCBI taxonomy ID (optional)' },
        limit: { type: 'number', description: 'Maximum number of results (default: 10)', minimum: 1, maximum: 100 },
      },
      required: ['query'],
    },
  },

• src/index.ts:405-406 (registration)

  Dispatch to the search_proteins handler in the CallToolRequestSchema switch statement.

  case 'search_proteins':
    return this.handleSearchProteins(args);

• src/index.ts:130-141 (schema)

  Type guard function for validating search_proteins input arguments, matching the declared input schema.

  const isValidSearchArgs = (
    args: any
  ): args is { query: string; species?: string; limit?: number } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.query === 'string' &&
      args.query.length > 0 &&
      (args.species === undefined || typeof args.species === 'string') &&
      (args.limit === undefined || (typeof args.limit === 'number' && args.limit > 0 && args.limit <= 100))
    );
  };

• src/index.ts:417-444 (helper)

  Utility function used by the handler to parse TSV data from the STRING API into typed objects.

  private parseTsvData<T>(tsvData: string): T[] {
    const lines = tsvData.trim().split('\n');
    if (lines.length < 2) return [];
  
    const headers = lines[0].split('\t');
    const results: T[] = [];
  
    for (let i = 1; i < lines.length; i++) {
      const values = lines[i].split('\t');
      const obj: any = {};
  
      headers.forEach((header, index) => {
        const value = values[index] || '';
        // Convert numeric fields
        if (['score', 'nscore', 'fscore', 'pscore', 'ascore', 'escore', 'dscore', 'tscore',
             'ncbiTaxonId', 'protein_size', 'number_of_genes', 'number_of_genes_in_background',
             'pvalue', 'pvalue_fdr'].includes(header)) {
          obj[header] = parseFloat(value) || 0;
        } else {
          obj[header] = value;
        }
      });
  
      results.push(obj as T);
    }
  
    return results;
  }