search_structures

Instructions

Implementation Reference

• src/index.ts:331-427 (handler)

  The main handler function for 'search_structures' tool. Validates input, constructs RCSB search API query with full-text search and optional filters for experimental method and resolution range, executes POST to /query endpoint, and returns JSON results or error message.

  private async handleSearchStructures(args: any) {
    if (!isValidSearchArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid search arguments');
    }
  
    try {
      const searchQuery: any = {
        query: {
          type: "terminal",
          service: "full_text",
          parameters: {
            value: args.query
          }
        },
        return_type: "entry",
        request_options: {
          paginate: {
            start: 0,
            rows: args.limit || 25
          },
          results_content_type: ["experimental"],
          sort: [
            {
              sort_by: args.sort_by || "score",
              direction: "desc"
            }
          ]
        }
      };
  
      // Add filters if provided
      if (args.experimental_method || args.resolution_range) {
        const filters = [];
  
        if (args.experimental_method) {
          filters.push({
            type: "terminal",
            service: "text",
            parameters: {
              attribute: "exptl.method",
              operator: "exact_match",
              value: args.experimental_method
            }
          });
        }
  
        if (args.resolution_range) {
          const [min, max] = args.resolution_range.split('-').map(Number);
          if (min && max) {
            filters.push({
              type: "terminal",
              service: "text",
              parameters: {
                attribute: "rcsb_entry_info.resolution_combined",
                operator: "range",
                value: {
                  from: min,
                  to: max,
                  include_lower: true,
                  include_upper: true
                }
              }
            });
          }
        }
  
        if (filters.length > 0) {
          searchQuery.query = {
            type: "group",
            logical_operator: "and",
            nodes: [searchQuery.query, ...filters]
          };
        }
      }
  
      const response = await this.rcsb_apiClient.post('/query', searchQuery);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error searching structures: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:244-254 (schema)

  Input schema definition for the 'search_structures' tool, specifying parameters like query (required), limit, sort_by, experimental_method, and resolution_range.

  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query (protein name, keyword, PDB ID, etc.)' },
      limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 },
      sort_by: { type: 'string', description: 'Sort results by (release_date, resolution, etc.)' },
      experimental_method: { type: 'string', description: 'Filter by experimental method (X-RAY, NMR, ELECTRON MICROSCOPY)' },
      resolution_range: { type: 'string', description: 'Resolution range filter (e.g., "1.0-2.0")' },
    },
    required: ['query'],
  },

• src/index.ts:241-255 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and inputSchema for 'search_structures'.

  {
    name: 'search_structures',
    description: 'Search PDB database for protein structures by keyword, protein name, or PDB ID',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query (protein name, keyword, PDB ID, etc.)' },
        limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 },
        sort_by: { type: 'string', description: 'Sort results by (release_date, resolution, etc.)' },
        experimental_method: { type: 'string', description: 'Filter by experimental method (X-RAY, NMR, ELECTRON MICROSCOPY)' },
        resolution_range: { type: 'string', description: 'Resolution range filter (e.g., "1.0-2.0")' },
      },
      required: ['query'],
    },
  },

• src/index.ts:65-78 (helper)

  Type guard and validation function for search_structures input arguments, used in the handler to validate params before processing.

  const isValidSearchArgs = (
    args: any
  ): args is { query: string; limit?: number; sort_by?: string; experimental_method?: string; resolution_range?: string } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.query === 'string' &&
      args.query.length > 0 &&
      (args.limit === undefined || (typeof args.limit === 'number' && args.limit > 0 && args.limit <= 1000)) &&
      (args.sort_by === undefined || typeof args.sort_by === 'string') &&
      (args.experimental_method === undefined || typeof args.experimental_method === 'string') &&
      (args.resolution_range === undefined || typeof args.resolution_range === 'string')
    );
  };

• src/index.ts:311-312 (registration)

  Dispatch case in CallToolRequestSchema handler that routes calls to 'search_structures' to the handleSearchStructures method.

  case 'search_structures':
    return this.handleSearchStructures(args);