search-spaces
Find Hugging Face Spaces endpoints using semantic search. Enter a task description to discover relevant AI models and tools for your project.
Instructions
Use semantic search to find an endpoint on the Hugging Face Spaces service. The search term will usually be 3-7 words describing a task or activity the Person is trying to accomplish. The results are returned in a markdown table. Present all results to the Person. Await specific guidance from the Person before making further Tool calls.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | The semantic search term to use. |
Implementation Reference
- src/index.ts:132-165 (handler)Handler for the 'search-spaces' tool call. Extracts the query argument, performs semantic search using SemanticSearch instance, formats results into markdown table, and returns as text content. Includes error handling.if (SEARCH_FOR_SPACE === request.params.name) { try { const query = request.params.arguments?.query as string; if (!query || typeof query !== "string") { throw new Error("Search query must be a non-empty string"); } const results = await semanticSearch.search(query); const markdownTable = semanticSearch.formatSearchResults(results); return { content: [ { type: "text", text: markdownTable, }, ], }; } catch (error) { if (error instanceof Error) { return { content: [ { type: "text", text: `Search error: ${error.message}`, }, ], isError: true, }; } throw error; } }
- src/index.ts:92-109 (registration)Tool registration for 'search-spaces' in the ListToolsRequestSchema handler, including name, description, and input schema definition.{ name: SEARCH_FOR_SPACE, description: "Use semantic search to find an endpoint on the `Hugging Face Spaces` service. The search term will usually " + "be 3-7 words describing a task or activity the Person is trying to accomplish. The results are returned in a markdown table. " + "Present all results to the Person. Await specific guidance from the Person before making further Tool calls.", inputSchema: { type: "object", properties: { query: { type: "string", // TODO description assumes user is using claude desktop which has knowledge of HF Spaces. // consider updating for not CLAUDE_DESKTOP mode. 3.7 sys prompt refers to Human as Person description: "The semantic search term to use.", }, }, }, },
- src/index.ts:98-108 (schema)Input schema definition for the 'search-spaces' tool, specifying an object with a required 'query' string parameter.inputSchema: { type: "object", properties: { query: { type: "string", // TODO description assumes user is using claude desktop which has knowledge of HF Spaces. // consider updating for not CLAUDE_DESKTOP mode. 3.7 sys prompt refers to Human as Person description: "The semantic search term to use.", }, }, },
- src/semantic_search.ts:25-65 (helper)Core search logic in SemanticSearch class: performs HTTP GET to Hugging Face Spaces semantic search API, filters for Gradio SDK, limits results, with auth and error handling.async search( query: string, limit: number = RESULTS_TO_RETURN, ): Promise<SearchResult[]> { try { if (!query) { return []; } const url = `${this.apiUrl}?` + new URLSearchParams({ q: query, sdk: "gradio" }); const headers: HeadersInit = { "Content-Type": "application/json", }; if (config.hfToken) { headers["Authorization"] = `Bearer ${config.hfToken}`; } const response = await fetch(url, headers); if (!response.ok) { throw new Error( `Search request failed: ${response.status} ${response.statusText}`, ); } const results = (await response.json()) as SearchResult[]; // Filter for gradio results and limit by count return results .filter((result) => result.sdk === "gradio") .slice(0, limit); } catch (error) { if (error instanceof Error) { throw new Error(`Failed to search for spaces: ${error.message}`); } throw error; } }
- src/semantic_search.ts:67-93 (helper)Formats the SemanticSearch results into a markdown table with links to HF Spaces, including title, description, author, and ID.formatSearchResults(results: SearchResult[]): string { if (results.length === 0) { return "No matching Hugging Face Spaces found. Try a different query."; } let markdown = "# Search Results for Hugging Face Spaces\n\n"; markdown += "| Space | Description | Author | ID |\n"; markdown += "|-------|-------------|--------|----|\n"; for (const result of results) { const title = result.title || "Untitled"; const description = result.shortDescription || "No description"; const author = result.authorData?.fullname || result.author || "Unknown"; const id = result.id || ""; markdown += `| [${escapeMarkdown(title)}](https://hf.co/spaces/${id}) ` + `| ${escapeMarkdown(description)} ` + `| ${escapeMarkdown(author)} ` + `| \`${escapeMarkdown(id)}\` |\n`; } markdown += "\nTo use one of these spaces, you can provide the ID in the format: `owner/space` or `owner/space/endpoint`"; return markdown; }