BioOntology MCP Server

Instructions

Implementation Reference

• src/index.ts:903-949 (handler)

  The handler function that validates input arguments using isValidAnnotateTextArgs and makes an API call to the BioOntology annotator endpoint with all supported parameters, returning JSON results or error.

  private async handleAnnotateText(args: any) {
    if (!isValidAnnotateTextArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid annotate text arguments');
    }
  
    try {
      const params: any = {
        text: args.text,
        apikey: this.apiKey,
      };
  
      // Add optional parameters
      if (args.ontologies) params.ontologies = args.ontologies;
      if (args.semantic_types) params.semantic_types = args.semantic_types;
      if (args.expand_semantic_types_hierarchy !== undefined) params.expand_semantic_types_hierarchy = args.expand_semantic_types_hierarchy;
      if (args.expand_class_hierarchy !== undefined) params.expand_class_hierarchy = args.expand_class_hierarchy;
      if (args.class_hierarchy_max_level !== undefined) params.class_hierarchy_max_level = args.class_hierarchy_max_level;
      if (args.expand_mappings !== undefined) params.expand_mappings = args.expand_mappings;
      if (args.stop_words) params.stop_words = args.stop_words;
      if (args.minimum_match_length !== undefined) params.minimum_match_length = args.minimum_match_length;
      if (args.exclude_numbers !== undefined) params.exclude_numbers = args.exclude_numbers;
      if (args.whole_word_only !== undefined) params.whole_word_only = args.whole_word_only;
      if (args.exclude_synonyms !== undefined) params.exclude_synonyms = args.exclude_synonyms;
      if (args.longest_only !== undefined) params.longest_only = args.longest_only;
  
      const response = await this.apiClient.get('/annotator', { params });
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: 'text',
            text: `Error annotating text: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:126-161 (schema)

  Type guard function that validates the input arguments for the annotate_text tool against the expected schema.

  const isValidAnnotateTextArgs = (
    args: any
  ): args is {
    text: string;
    ontologies?: string;
    semantic_types?: string;
    expand_semantic_types_hierarchy?: boolean;
    expand_class_hierarchy?: boolean;
    class_hierarchy_max_level?: number;
    expand_mappings?: boolean;
    stop_words?: string;
    minimum_match_length?: number;
    exclude_numbers?: boolean;
    whole_word_only?: boolean;
    exclude_synonyms?: boolean;
    longest_only?: boolean;
  } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.text === 'string' &&
      args.text.length > 0 &&
      (args.ontologies === undefined || typeof args.ontologies === 'string') &&
      (args.semantic_types === undefined || typeof args.semantic_types === 'string') &&
      (args.expand_semantic_types_hierarchy === undefined || typeof args.expand_semantic_types_hierarchy === 'boolean') &&
      (args.expand_class_hierarchy === undefined || typeof args.expand_class_hierarchy === 'boolean') &&
      (args.class_hierarchy_max_level === undefined || (typeof args.class_hierarchy_max_level === 'number' && args.class_hierarchy_max_level >= 0)) &&
      (args.expand_mappings === undefined || typeof args.expand_mappings === 'boolean') &&
      (args.stop_words === undefined || typeof args.stop_words === 'string') &&
      (args.minimum_match_length === undefined || (typeof args.minimum_match_length === 'number' && args.minimum_match_length > 0)) &&
      (args.exclude_numbers === undefined || typeof args.exclude_numbers === 'boolean') &&
      (args.whole_word_only === undefined || typeof args.whole_word_only === 'boolean') &&
      (args.exclude_synonyms === undefined || typeof args.exclude_synonyms === 'boolean') &&
      (args.longest_only === undefined || typeof args.longest_only === 'boolean')
    );
  };

• src/index.ts:598-620 (registration)

  Registration of the 'annotate_text' tool in the ListTools response, including full inputSchema definition.

  {
    name: 'annotate_text',
    description: 'Analyze text and identify relevant ontology terms with configurable parameters',
    inputSchema: {
      type: 'object',
      properties: {
        text: { type: 'string', description: 'Text to annotate with ontology terms' },
        ontologies: { type: 'string', description: 'Comma-separated ontology acronyms to use for annotation' },
        semantic_types: { type: 'string', description: 'Comma-separated semantic types to filter by' },
        expand_semantic_types_hierarchy: { type: 'boolean', description: 'Include children of semantic types (default: false)' },
        expand_class_hierarchy: { type: 'boolean', description: 'Include class ancestors in annotation (default: false)' },
        class_hierarchy_max_level: { type: 'number', description: 'Maximum hierarchy depth (default: 0)', minimum: 0 },
        expand_mappings: { type: 'boolean', description: 'Use manual mappings (UMLS, REST, CUI, OBOXREF) (default: false)' },
        stop_words: { type: 'string', description: 'Comma-separated custom stop words' },
        minimum_match_length: { type: 'number', description: 'Minimum character length for matches', minimum: 1 },
        exclude_numbers: { type: 'boolean', description: 'Exclude numeric matches (default: false)' },
        whole_word_only: { type: 'boolean', description: 'Match whole words only (default: true)' },
        exclude_synonyms: { type: 'boolean', description: 'Exclude synonym matches (default: false)' },
        longest_only: { type: 'boolean', description: 'Return only longest matches (default: false)' },
      },
      required: ['text'],
    },
  },

• src/index.ts:710-711 (registration)

  Dispatch registration in the CallToolRequestSchema switch statement that routes to the handleAnnotateText method.

  case 'annotate_text':
    return this.handleAnnotateText(args);