BioOntology MCP Server

Instructions

Implementation Reference

• src/index.ts:783-826 (handler)

  The primary handler function for the 'search_properties' tool. It validates input arguments using isValidSearchPropertiesArgs, constructs query parameters for the BioOntology API's /property_search endpoint, fetches the data, and returns formatted JSON results or an error message.

  private async handleSearchProperties(args: any) {
    if (!isValidSearchPropertiesArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid search properties 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.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.include) params.include = args.include;
      if (args.ontology_types) params.ontology_types = args.ontology_types;
      if (args.property_types) params.property_types = args.property_types;
      if (args.page) params.page = args.page;
      if (args.pagesize) params.pagesize = args.pagesize;
  
      const response = await this.apiClient.get('/property_search', { params });
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: 'text',
            text: `Error searching properties: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:550-569 (schema)

  The tool schema definition including name, description, and detailed inputSchema with properties, types, descriptions, and required fields, registered in the tools list for ListToolsRequestSchema.

  {
    name: 'search_properties',
    description: 'Search ontology properties by their labels and IDs',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query for properties' },
        ontologies: { type: 'string', description: 'Comma-separated list of ontology acronyms' },
        require_exact_match: { type: 'boolean', description: 'Require exact match (default: false)' },
        also_search_views: { type: 'boolean', description: 'Include ontology views (default: false)' },
        require_definitions: { type: 'boolean', description: 'Only return properties with definitions (default: false)' },
        include: { type: 'string', description: 'Attributes to include (default: label,labelGenerated,definition,parents)' },
        ontology_types: { type: 'string', description: 'Ontology types to include (e.g., ONTOLOGY,VALUE_SET_COLLECTION)' },
        property_types: { type: 'string', description: 'Property types (object,annotation,datatype)' },
        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 },
      },
      required: ['query'],
    },
  },

• src/index.ts:703-704 (registration)

  The switch case registration in the CallToolRequestSchema handler that routes calls to the 'search_properties' tool to its handler function.

  case 'search_properties':
    return this.handleSearchProperties(args);

• src/index.ts:96-124 (helper)

  Helper validation function (type guard) that checks if input arguments match the expected structure for the search_properties tool, used in the handler for input validation.

  const isValidSearchPropertiesArgs = (
    args: any
  ): args is {
    query: string;
    ontologies?: string;
    require_exact_match?: boolean;
    also_search_views?: boolean;
    require_definitions?: boolean;
    include?: string;
    ontology_types?: string;
    property_types?: string;
    page?: number;
    pagesize?: number;
  } => {
    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.also_search_views === undefined || typeof args.also_search_views === 'boolean') &&
      (args.require_definitions === undefined || typeof args.require_definitions === 'boolean') &&
      (args.include === undefined || typeof args.include === 'string') &&
      (args.ontology_types === undefined || typeof args.ontology_types === 'string') &&
      (args.property_types === undefined || typeof args.property_types === 'string') &&
      (args.page === undefined || (typeof args.page === 'number' && args.page > 0)) &&
      (args.pagesize === undefined || (typeof args.pagesize === 'number' && args.pagesize > 0 && args.pagesize <= 500))
    );
  };