search_images
Find openly-licensed images for projects by searching Openverse with filters for license type, creator, source, size, and format.
Instructions
Search for openly-licensed images on Openverse
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search terms (required) | |
| page | No | Page number (default: 1) | |
| page_size | No | Results per page (default: 20, max: 500) | |
| license | No | License filter (e.g., by, by-sa, cc0) | |
| license_type | No | License type (commercial or modification) | |
| creator | No | Filter by creator name | |
| source | No | Filter by source (e.g., flickr, wikimedia) | |
| extension | No | File type (jpg, png, gif, svg) | |
| aspect_ratio | No | Image shape (tall, wide, square) | |
| size | No | Image size (small, medium, large) | |
| mature | No | Include mature content (default: false) |
Implementation Reference
- src/index.ts:51-87 (handler)Handler function that executes the search_images tool by constructing query parameters and fetching from Openverse API.execute: async (args) => { const params: Record<string, string> = { q: args.query, page: String(args.page || 1), page_size: String(Math.min(args.page_size || DEFAULT_PAGE_SIZE, 500)), mature: String(args.mature || false) }; // Add optional parameters if (args.license) params.license = args.license; if (args.license_type) params.license_type = args.license_type; if (args.creator) params.creator = args.creator; if (args.source) params.source = args.source; if (args.extension) params.extension = args.extension; if (args.aspect_ratio) params.aspect_ratio = args.aspect_ratio; if (args.size) params.size = args.size; try { const queryParams = new URLSearchParams(params); const response = await fetch(`${OPENVERSE_API_BASE}/images/?${queryParams}`, { headers: { 'User-Agent': 'MCP-Openverse/1.0' } }); if (!response.ok) { throw new Error(`API request failed: ${response.status} ${response.statusText}`); } const data = await response.json(); return JSON.stringify(data, null, 2); } catch (error) { return JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error' }); } }
- src/index.ts:15-27 (schema)Zod schema defining input parameters for the search_images tool.const searchImagesSchema = z.object({ query: z.string().describe('Search terms (required)'), page: z.number().optional().describe('Page number (default: 1)'), page_size: z.number().optional().describe('Results per page (default: 20, max: 500)'), license: z.string().optional().describe('License filter (e.g., by, by-sa, cc0)'), license_type: z.string().optional().describe('License type (commercial or modification)'), creator: z.string().optional().describe('Filter by creator name'), source: z.string().optional().describe('Filter by source (e.g., flickr, wikimedia)'), extension: z.string().optional().describe('File type (jpg, png, gif, svg)'), aspect_ratio: z.string().optional().describe('Image shape (tall, wide, square)'), size: z.string().optional().describe('Image size (small, medium, large)'), mature: z.boolean().optional().describe('Include mature content (default: false)') });
- src/index.ts:46-88 (registration)Registration of the search_images tool using server.addTool, including name, description, schema, and handler.// Tool: search_images server.addTool({ name: 'search_images', description: 'Search for openly-licensed images on Openverse', parameters: searchImagesSchema, execute: async (args) => { const params: Record<string, string> = { q: args.query, page: String(args.page || 1), page_size: String(Math.min(args.page_size || DEFAULT_PAGE_SIZE, 500)), mature: String(args.mature || false) }; // Add optional parameters if (args.license) params.license = args.license; if (args.license_type) params.license_type = args.license_type; if (args.creator) params.creator = args.creator; if (args.source) params.source = args.source; if (args.extension) params.extension = args.extension; if (args.aspect_ratio) params.aspect_ratio = args.aspect_ratio; if (args.size) params.size = args.size; try { const queryParams = new URLSearchParams(params); const response = await fetch(`${OPENVERSE_API_BASE}/images/?${queryParams}`, { headers: { 'User-Agent': 'MCP-Openverse/1.0' } }); if (!response.ok) { throw new Error(`API request failed: ${response.status} ${response.statusText}`); } const data = await response.json(); return JSON.stringify(data, null, 2); } catch (error) { return JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error' }); } } });
- src/index.ts:200-229 (helper)Helper function named searchImages used within the search_images_for_essay tool.const searchImages = async (query: string, pageSize: number, filters: Record<string, string> = {}): Promise<{results: any[]}> => { const params: Record<string, string> = { q: query, page_size: String(pageSize), mature: 'false', ...filters }; if (style === 'photo') { params.extension = 'jpg,png'; } const queryParams = new URLSearchParams(params); try { const response = await fetch(`${OPENVERSE_API_BASE}/images/?${queryParams}`, { headers: { 'User-Agent': 'MCP-Openverse/1.0' } }); if (!response.ok) { return { results: [] }; } return await response.json() as {results: any[]}; } catch { return { results: [] }; } };