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