search-spaces

Instructions

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;
  }