Hugging Face MCP Server

Instructions

Implementation Reference

• src/huggingface/server.py:525-564 (handler)

  Handler function block that implements the core logic for the 'search-collections' tool. It processes input arguments, constructs API parameters, calls the Hugging Face collections endpoint via make_hf_request, handles errors, formats the results, and returns them as JSON.

  elif name == "search-collections":
      owner = arguments.get("owner")
      item = arguments.get("item")
      query = arguments.get("query")
      limit = arguments.get("limit", 10)
  
      params = {"limit": limit}
      if owner:
          params["owner"] = owner
      if item:
          params["item"] = item
      if query:
          params["q"] = query
  
      data = await make_hf_request("collections", params)
  
      if "error" in data:
          return [
              types.TextContent(
                  type="text", text=f"Error searching collections: {data['error']}"
              )
          ]
  
      # Format the results
      results = []
      for collection in data:
          collection_info = {
              "id": collection.get("id", ""),
              "title": collection.get("title", ""),
              "owner": collection.get("owner", {}).get("name", ""),
              "description": collection.get(
                  "description", "No description available"
              ),
              "items_count": collection.get("itemsCount", 0),
              "upvotes": collection.get("upvotes", 0),
              "last_modified": collection.get("lastModified", ""),
          }
          results.append(collection_info)
  
      return [types.TextContent(type="text", text=json.dumps(results, indent=2))]

• src/huggingface/server.py:193-214 (registration)

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

  types.Tool(
      name="search-collections",
      description="Search for collections on Hugging Face Hub",
      inputSchema={
          "type": "object",
          "properties": {
              "owner": {"type": "string", "description": "Filter by owner"},
              "item": {
                  "type": "string",
                  "description": "Filter by item (e.g., 'models/teknium/OpenHermes-2.5-Mistral-7B')",
              },
              "query": {
                  "type": "string",
                  "description": "Search term for titles and descriptions",
              },
              "limit": {
                  "type": "integer",
                  "description": "Maximum number of results to return",
              },
          },
      },
  ),

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

  Helper function used by the search-collections handler (and others) to perform HTTP GET requests to the Hugging Face API endpoints, with error handling.

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

• src/huggingface/server.py:197-213 (schema)

  JSON schema defining the input parameters for the search-collections tool.

      "type": "object",
      "properties": {
          "owner": {"type": "string", "description": "Filter by owner"},
          "item": {
              "type": "string",
              "description": "Filter by item (e.g., 'models/teknium/OpenHermes-2.5-Mistral-7B')",
          },
          "query": {
              "type": "string",
              "description": "Search term for titles and descriptions",
          },
          "limit": {
              "type": "integer",
              "description": "Maximum number of results to return",
          },
      },
  },