search_structures
Find protein structures in the PDB database using keywords, protein names, or PDB IDs. Filter results by experimental method, resolution range, and sort criteria to locate specific structural data.
Instructions
Search PDB database for protein structures by keyword, protein name, or PDB ID
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (protein name, keyword, PDB ID, etc.) | |
| limit | No | Number of results to return (1-1000, default: 25) | |
| sort_by | No | Sort results by (release_date, resolution, etc.) | |
| experimental_method | No | Filter by experimental method (X-RAY, NMR, ELECTRON MICROSCOPY) | |
| resolution_range | No | Resolution range filter (e.g., "1.0-2.0") |
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);