BioOntology MCP Server

Instructions

Implementation Reference

• src/index.ts:734-781 (handler)

  The primary handler for the 'search_terms' tool. Validates input args, builds query parameters for the BioOntology.org /search API endpoint, performs the HTTP GET request via axios, and returns the JSON response or formatted error.
  private async handleSearchTerms(args: any) { if (!isValidSearchTermsArgs(args)) { throw new McpError(ErrorCode.InvalidParams, 'Invalid search terms arguments'); } try { const params: any = { q: args.query, apikey: this.apiKey, }; // Add optional parameters if (args.ontologies) params.ontologies = args.ontologies; if (args.require_exact_match !== undefined) params.require_exact_match = args.require_exact_match; if (args.suggest !== undefined) params.suggest = args.suggest; if (args.also_search_views !== undefined) params.also_search_views = args.also_search_views; if (args.require_definitions !== undefined) params.require_definitions = args.require_definitions; if (args.also_search_properties !== undefined) params.also_search_properties = args.also_search_properties; if (args.also_search_obsolete !== undefined) params.also_search_obsolete = args.also_search_obsolete; if (args.cui) params.cui = args.cui; if (args.semantic_types) params.semantic_types = args.semantic_types; if (args.include) params.include = args.include; if (args.page) params.page = args.page; if (args.pagesize) params.pagesize = args.pagesize; if (args.language) params.language = args.language; const response = await this.apiClient.get('/search', { params }); return { content: [ { type: 'text', text: JSON.stringify(response.data, null, 2), }, ], }; } catch (error: any) { return { content: [ { type: 'text', text: `Error searching terms: ${error instanceof Error ? error.message : 'Unknown error'}`, }, ], isError: true, }; } }
• src/index.ts:58-94 (schema)

  Input validation schema (type guard) for search_terms tool arguments, enforcing types and constraints like query required string, pagesize 1-500, etc. Used in the handler.
  const isValidSearchTermsArgs = ( args: any ): args is { query: string; ontologies?: string; require_exact_match?: boolean; suggest?: boolean; also_search_views?: boolean; require_definitions?: boolean; also_search_properties?: boolean; also_search_obsolete?: boolean; cui?: string; semantic_types?: string; include?: string; page?: number; pagesize?: number; language?: string; } => { return ( typeof args === 'object' && args !== null && typeof args.query === 'string' && (args.ontologies === undefined || typeof args.ontologies === 'string') && (args.require_exact_match === undefined || typeof args.require_exact_match === 'boolean') && (args.suggest === undefined || typeof args.suggest === 'boolean') && (args.also_search_views === undefined || typeof args.also_search_views === 'boolean') && (args.require_definitions === undefined || typeof args.require_definitions === 'boolean') && (args.also_search_properties === undefined || typeof args.also_search_properties === 'boolean') && (args.also_search_obsolete === undefined || typeof args.also_search_obsolete === 'boolean') && (args.cui === undefined || typeof args.cui === 'string') && (args.semantic_types === undefined || typeof args.semantic_types === 'string') && (args.include === undefined || typeof args.include === 'string') && (args.page === undefined || (typeof args.page === 'number' && args.page > 0)) && (args.pagesize === undefined || (typeof args.pagesize === 'number' && args.pagesize > 0 && args.pagesize <= 500)) && (args.language === undefined || typeof args.language === 'string') ); };
• src/index.ts:527-549 (registration)

  Tool registration in ListToolsRequestHandler. Defines the tool name, description, and complete inputSchema matching the validator.
  name: 'search_terms', description: 'Search across ontology terms with advanced filtering options', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query for ontology terms' }, ontologies: { type: 'string', description: 'Comma-separated list of ontology acronyms to search in' }, require_exact_match: { type: 'boolean', description: 'Require exact match (default: false)' }, suggest: { type: 'boolean', description: 'Enable suggestion mode for type-ahead (default: false)' }, also_search_views: { type: 'boolean', description: 'Include ontology views in search (default: false)' }, require_definitions: { type: 'boolean', description: 'Only return terms with definitions (default: false)' }, also_search_properties: { type: 'boolean', description: 'Search in properties as well (default: false)' }, also_search_obsolete: { type: 'boolean', description: 'Include obsolete terms (default: false)' }, cui: { type: 'string', description: 'Comma-separated CUIs to filter by' }, semantic_types: { type: 'string', description: 'Comma-separated semantic types to filter by' }, include: { type: 'string', description: 'Comma-separated attributes to include (e.g., prefLabel,synonym,definition)' }, page: { type: 'number', description: 'Page number (default: 1)', minimum: 1 }, pagesize: { type: 'number', description: 'Results per page (default: 50, max: 500)', minimum: 1, maximum: 500 }, language: { type: 'string', description: 'Language code (e.g., en, fr)' }, }, required: ['query'], }, },
• src/index.ts:701-702 (registration)

  Dispatcher switch case in CallToolRequestHandler that routes 'search_terms' calls to the handleSearchTerms method.
  case 'search_terms': return this.handleSearchTerms(args);