get_protein_annotations

Instructions

Implementation Reference

• src/index.ts:651-697 (handler)

  The handler function executes the tool logic: validates args, fetches annotations from STRING API endpoint '/tsv/get_string_ids', parses TSV response using parseTsvData, formats and returns JSON with protein details.

  private async handleGetProteinAnnotations(args: any) {
    if (!isValidNetworkArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid protein annotation arguments');
    }
  
    try {
      const species = args.species || '9606';
  
      const response = await this.apiClient.get('/tsv/get_string_ids', {
        params: {
          identifiers: args.protein_ids.join('%0d'),
          species: species,
        },
      });
  
      const annotations = this.parseTsvData<ProteinAnnotation>(response.data);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              species: species,
              proteins: annotations.map(protein => ({
                query_id: protein.preferredName,
                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 fetching protein annotations: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:350-360 (schema)

  Input schema definition for the get_protein_annotations tool, specifying protein_ids as required array of strings and optional species string.

  {
    name: 'get_protein_annotations',
    description: 'Get detailed annotations and functional information for proteins',
    inputSchema: {
      type: 'object',
      properties: {
        protein_ids: { type: 'array', items: { type: 'string' }, description: 'List of protein identifiers' },
        species: { type: 'string', description: 'Species name or NCBI taxonomy ID (default: 9606 for human)' },
      },
      required: ['protein_ids'],
    },

• src/index.ts:401-402 (registration)

  Dispatch case in the MCP tool request handler switch statement that routes calls to get_protein_annotations to its handler function.

  case 'get_protein_annotations':
    return this.handleGetProteinAnnotations(args);

• src/index.ts:340-389 (registration)

  Tool registration via server.setTools() including the get_protein_annotations tool definition.

        inputSchema: {
          type: 'object',
          properties: {
            protein_ids: { type: 'array', items: { type: 'string' }, description: 'List of protein identifiers' },
            species: { type: 'string', description: 'Species name or NCBI taxonomy ID (default: 9606 for human)' },
            background_string_identifiers: { type: 'array', items: { type: 'string' }, description: 'Background protein set for enrichment (optional)' },
          },
          required: ['protein_ids'],
        },
      },
      {
        name: 'get_protein_annotations',
        description: 'Get detailed annotations and functional information for proteins',
        inputSchema: {
          type: 'object',
          properties: {
            protein_ids: { type: 'array', items: { type: 'string' }, description: 'List of protein identifiers' },
            species: { type: 'string', description: 'Species name or NCBI taxonomy ID (default: 9606 for human)' },
          },
          required: ['protein_ids'],
        },
      },
      {
        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'],
        },
      },
      {
        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:417-444 (helper)

  Utility function to parse TSV data from API responses into typed objects, used by the handler to process annotations.

  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;
  }