sketchfab-search

Instructions

Implementation Reference

• index.ts:289-365 (handler)

  The main handler function for the 'sketchfab-search' tool. Validates inputs, checks for API key, instantiates SketchfabApiClient, performs search, formats results as text, and handles 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:283-288 (schema)

  Zod input schema defining the parameters accepted by 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-282 (registration)

  The server.tool registration call for the 'sketchfab-search' tool, specifying name, description, input schema, and handler function.

  server.tool(
    "sketchfab-search",
    "Search for 3D models on Sketchfab based on keywords and filters",
    {

• index.ts:84-131 (helper)

  The searchModels method in SketchfabApiClient class, which performs the HTTP request to Sketchfab's search endpoint and returns model results. 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));
    }
  }

• index.ts:36-67 (schema)

  TypeScript interface defining the structure of a Sketchfab model object used throughout the codebase for type safety.

  interface SketchfabModel {
    uid: string;
    name: string;
    description?: string;
    viewerUrl?: string;
    thumbnails?: {
      images?: Array<{
        url: string;
        width: number;
        height: number;
      }>;
    };
    user?: {
      username: string;
      displayName?: string;
    };
    isDownloadable: boolean;
    downloadCount?: number;
    viewCount?: number;
    likeCount?: number;
    license?: string;
    createdAt?: string;
    faceCount?: number;
    vertexCount?: number;
    tags?: Array<{
      slug: string;
    }>;
    categories?: Array<{
      name: string;
      slug: string;
    }>;
  }