BioOntology MCP Server

Instructions

Implementation Reference

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

  Main handler function for executing the annotate_text tool. Validates arguments, constructs API parameters for BioOntology's /annotator endpoint, makes the request, and formats the response.
  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)

  Input validation schema as a type guard function (isValidAnnotateTextArgs) ensuring arguments match the expected structure for the annotate_text tool.
  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:599-620 (registration)

  Registration of the annotate_text tool in the tools list returned by ListToolsRequestSchema, including name, description, and full JSON inputSchema.
  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 case in the CallToolRequestSchema handler that routes annotate_text calls to the handleAnnotateText method.
  case 'annotate_text': return this.handleAnnotateText(args);