sketchfab-search
Search Sketchfab for 3D models using keywords, tags, categories, and filters like downloadable status. Retrieve relevant models with customizable result limits for efficient exploration.
Instructions
Search for 3D models on Sketchfab based on keywords and filters
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| categories | No | Filter by categories (e.g., ["characters", "architecture", "vehicles"]) | |
| downloadable | No | Set to true to show only downloadable models, false to show all models | |
| limit | No | Maximum number of results to return (1-24, default: 10) | |
| query | No | Text search query (e.g., "car", "house", "character") to find relevant models | |
| tags | No | Filter by specific tags (e.g., ["animated", "rigged", "pbr"]) |
Implementation Reference
- index.ts:289-365 (handler)Handler function that implements the core logic of the 'sketchfab-search' tool: validates inputs, initializes API client, performs search, formats and returns results or errors.async ({ query, tags, categories, downloadable, limit }) => { try { // Validate input if (!query && (!tags || tags.length === 0) && (!categories || categories.length === 0)) { return { content: [ { type: "text", text: "Please provide at least one search parameter: query, tags, or categories.", }, ], }; } // Check if API key is available if (!apiKey) { return { content: [ { type: "text", text: "No Sketchfab API key provided. Please provide an API key using the --api-key parameter or set the SKETCHFAB_API_KEY environment variable.", }, ], }; } // Create API client const client = new SketchfabApiClient(apiKey); // Search for models const searchResults = await client.searchModels({ q: query, tags, categories, downloadable, count: limit || 10, }); // Handle no results if (!searchResults.results || searchResults.results.length === 0) { return { content: [ { type: "text", text: "No models found matching your search criteria. Try different keywords or filters.", }, ], }; } // Format results const formattedResults = searchResults.results .map((model, index) => `[${index + 1}] ${model.name}\nID: ${model.uid}\nDownloadable: ${model.isDownloadable ? "Yes" : "No"}\n`) .join("\n"); return { content: [ { type: "text", text: `Found ${searchResults.results.length} models:\n\n${formattedResults}`, }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error searching Sketchfab: ${errorMessage}`, }, ], }; } } );
- index.ts:282-288 (schema)Zod schema defining the input parameters for the 'sketchfab-search' tool.{ query: z.string().optional().describe("Text search query (e.g., \"car\", \"house\", \"character\") to find relevant models"), tags: z.array(z.string()).optional().describe("Filter by specific tags (e.g., [\"animated\", \"rigged\", \"pbr\"])"), categories: z.array(z.string()).optional().describe("Filter by categories (e.g., [\"characters\", \"architecture\", \"vehicles\"])"), downloadable: z.boolean().optional().describe("Set to true to show only downloadable models, false to show all models"), limit: z.number().optional().describe("Maximum number of results to return (1-24, default: 10)"), },
- index.ts:279-281 (registration)Registration of the 'sketchfab-search' tool with McpServer using server.tool(name, description, schema, handler).server.tool( "sketchfab-search", "Search for 3D models on Sketchfab based on keywords and filters",
- index.ts:84-131 (helper)The searchModels helper method in SketchfabApiClient class, which makes the actual HTTP request to Sketchfab's search API and handles responses/errors. Called by the tool handler.async searchModels(options: { q?: string; tags?: string[]; categories?: string[]; downloadable?: boolean; count?: number; }): Promise<{ results: SketchfabModel[]; next?: string; previous?: string; }> { try { const { q, tags, categories, downloadable, count = 24 } = options; // Build query parameters const params: Record<string, any> = { type: "models" }; if (q) params.q = q; if (tags?.length) params.tags = tags; if (categories?.length) params.categories = categories; if (downloadable !== undefined) params.downloadable = downloadable; if (count) params.count = Math.min(count, 24); // API limit is 24 // Make API request const response = await axios.get(`${SketchfabApiClient.API_BASE}/search`, { params, headers: this.getAuthHeader(), }); return { results: response.data.results || [], next: response.data.next, previous: response.data.previous, }; } catch (error: unknown) { if (axios.isAxiosError(error) && error.response) { const status = error.response.status; if (status === 401) { throw new Error("Invalid Sketchfab API key"); } else if (status === 429) { throw new Error("Sketchfab API rate limit exceeded. Try again later."); } throw new Error(`Sketchfab API error (${status}): ${error.message}`); } throw error instanceof Error ? error : new Error(String(error)); } }