Hugging Face MCP Server

Instructions

Implementation Reference

• src/huggingface/server.py:397-437 (handler)

  Handler function that executes the search-spaces tool by querying the Hugging Face Spaces API and formatting the results as JSON.

  elif name == "search-spaces":
      query = arguments.get("query")
      author = arguments.get("author")
      tags = arguments.get("tags")
      sdk = arguments.get("sdk")
      limit = arguments.get("limit", 10)
  
      params = {"limit": limit}
      if query:
          params["search"] = query
      if author:
          params["author"] = author
      if tags:
          params["filter"] = tags
      if sdk:
          params["filter"] = params.get("filter", "") + f" sdk:{sdk}"
  
      data = await make_hf_request("spaces", params)
  
      if "error" in data:
          return [
              types.TextContent(
                  type="text", text=f"Error searching spaces: {data['error']}"
              )
          ]
  
      # Format the results
      results = []
      for space in data:
          space_info = {
              "id": space.get("id", ""),
              "name": space.get("spaceId", ""),
              "author": space.get("author", ""),
              "sdk": space.get("sdk", ""),
              "tags": space.get("tags", []),
              "likes": space.get("likes", 0),
              "lastModified": space.get("lastModified", ""),
          }
          results.append(space_info)
  
      return [types.TextContent(type="text", text=json.dumps(results, indent=2))]

• src/huggingface/server.py:132-154 (registration)

  Registration of the search-spaces tool within the @server.list_tools() handler, including its description and input schema.

  types.Tool(
      name="search-spaces",
      description="Search for Spaces on Hugging Face Hub",
      inputSchema={
          "type": "object",
          "properties": {
              "query": {"type": "string", "description": "Search term"},
              "author": {
                  "type": "string",
                  "description": "Filter by author/organization",
              },
              "tags": {"type": "string", "description": "Filter by tags"},
              "sdk": {
                  "type": "string",
                  "description": "Filter by SDK (e.g., 'streamlit', 'gradio', 'docker')",
              },
              "limit": {
                  "type": "integer",
                  "description": "Maximum number of results to return",
              },
          },
      },
  ),

• src/huggingface/server.py:135-152 (schema)

  JSON Schema defining the input parameters for the search-spaces tool.

  inputSchema={
      "type": "object",
      "properties": {
          "query": {"type": "string", "description": "Search term"},
          "author": {
              "type": "string",
              "description": "Filter by author/organization",
          },
          "tags": {"type": "string", "description": "Filter by tags"},
          "sdk": {
              "type": "string",
              "description": "Filter by SDK (e.g., 'streamlit', 'gradio', 'docker')",
          },
          "limit": {
              "type": "integer",
              "description": "Maximum number of results to return",
          },
      },

• src/huggingface/server.py:36-47 (helper)

  Helper function used by the search-spaces handler to make HTTP requests to the Hugging Face API.

  async def make_hf_request(
      endpoint: str, params: Optional[Dict[str, Any]] = None
  ) -> Dict:
      """Make a request to the Hugging Face API with proper error handling."""
      url = f"{HF_API_BASE}/{endpoint}"
      try:
          response = await http_client.get(url, params=params)
          response.raise_for_status()
          return response.json()
      except Exception as e:
          return {"error": str(e)}