search_structures
Retrieve protein structures from the PDB database using keywords, protein names, or PDB IDs. Filter and sort results by experimental method, resolution range, or release date. Ideal for targeted biological research.
Instructions
Search PDB database for protein structures by keyword, protein name, or PDB ID
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| experimental_method | No | Filter by experimental method (X-RAY, NMR, ELECTRON MICROSCOPY) | |
| limit | No | Number of results to return (1-1000, default: 25) | |
| query | Yes | Search query (protein name, keyword, PDB ID, etc.) | |
| resolution_range | No | Resolution range filter (e.g., "1.0-2.0") | |
| sort_by | No | Sort results by (release_date, resolution, etc.) |
Implementation Reference
- src/index.ts:331-427 (handler)The handler function that validates arguments, constructs a complex search query for the RCSB API (full_text search with optional filters for experimental method and resolution range), executes the API call, and returns the results as formatted JSON or an 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)JSON Schema defining the input parameters for the search_structures tool, including required query and optional filters.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)Registration of the search_structures tool in the ListToolsRequestSchema handler, providing name, description, and input schema.{ 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 helper function that validates the input arguments match the expected schema for search_structures.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)Switch case in CallToolRequestSchema handler that routes calls to the search_structures handler function.case 'search_structures': return this.handleSearchStructures(args);