get_functional_enrichment

Instructions

Implementation Reference

• src/index.ts:592-649 (handler)

  The handler function that validates input, calls the STRING API enrichment endpoint, parses the TSV response, groups results by category, and returns formatted JSON output.

  private async handleGetFunctionalEnrichment(args: any) {
    if (!isValidEnrichmentArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid enrichment arguments');
    }
  
    try {
      const species = args.species || '9606';
  
      const params: any = {
        identifiers: args.protein_ids.join('%0d'),
        species: species,
        caller_identity: 'string-mcp-server',
      };
  
      if (args.background_string_identifiers) {
        params.background_string_identifiers = args.background_string_identifiers.join('%0d');
      }
  
      const response = await this.apiClient.get('/tsv/enrichment', { params });
  
      const enrichments = this.parseTsvData<EnrichmentTerm>(response.data);
  
      // Group by category
      const groupedEnrichments: Record<string, EnrichmentTerm[]> = {};
      enrichments.forEach(term => {
        if (!groupedEnrichments[term.category]) {
          groupedEnrichments[term.category] = [];
        }
        groupedEnrichments[term.category].push(term);
      });
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              query_proteins: args.protein_ids,
              species: species,
              total_terms: enrichments.length,
              enrichment_categories: Object.keys(groupedEnrichments),
              enrichments: groupedEnrichments,
              significant_terms: enrichments.filter(term => term.pvalue_fdr < 0.05).length,
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error performing functional enrichment: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:337-349 (registration)

  Tool registration in the list of tools returned by ListToolsRequestSchema, including name, description, and input schema.

  {
    name: 'get_functional_enrichment',
    description: 'Perform functional enrichment analysis on a set of 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)' },
        background_string_identifiers: { type: 'array', items: { type: 'string' }, description: 'Background protein set for enrichment (optional)' },
      },
      required: ['protein_ids'],
    },
  },

• src/index.ts:340-348 (schema)

  JSON schema defining the input parameters for the get_functional_enrichment tool.

  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'],
  },

• src/index.ts:99-113 (helper)

  Type guard function that validates the input arguments for the functional enrichment tool.

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

• src/index.ts:39-50 (helper)

  TypeScript interface defining the structure of enrichment term data returned from the STRING API.

  interface EnrichmentTerm {
    category: string;
    term: string;
    number_of_genes: number;
    number_of_genes_in_background: number;
    ncbiTaxonId: number;
    inputGenes: string;
    preferredNames: string;
    pvalue: number;
    pvalue_fdr: number;
    description: string;
  }