Hugging Face MCP Server

Instructions

Implementation Reference

• src/huggingface/server.py:566-613 (handler)

  The handler function for the 'get-collection-info' tool. It extracts namespace and collection_id from arguments, constructs the API endpoint, fetches data using make_hf_request, handles errors, formats the collection info including owner, description, upvotes, last modified, and list of items with their type, id, and note, then returns as JSON.

  elif name == "get-collection-info":
      namespace = arguments.get("namespace")
      collection_id = arguments.get("collection_id")
  
      if not namespace or not collection_id:
          return [
              types.TextContent(
                  type="text", text="Error: namespace and collection_id are required"
              )
          ]
  
      # Extract the slug from the collection_id if it contains a dash
      slug = collection_id.split("-")[0] if "-" in collection_id else collection_id
      endpoint = f"collections/{namespace}/{slug}-{collection_id}"
  
      data = await make_hf_request(endpoint)
  
      if "error" in data:
          return [
              types.TextContent(
                  type="text",
                  text=f"Error retrieving collection information: {data['error']}",
              )
          ]
  
      # Format the result
      collection_info = {
          "id": data.get("id", ""),
          "title": data.get("title", ""),
          "owner": data.get("owner", {}).get("name", ""),
          "description": data.get("description", "No description available"),
          "upvotes": data.get("upvotes", 0),
          "last_modified": data.get("lastModified", ""),
          "items": [],
      }
  
      # Add items
      for item in data.get("items", []):
          item_info = {
              "type": item.get("item", {}).get("type", ""),
              "id": item.get("item", {}).get("id", ""),
              "note": item.get("note", ""),
          }
          collection_info["items"].append(item_info)
  
      return [
          types.TextContent(type="text", text=json.dumps(collection_info, indent=2))
      ]

• src/huggingface/server.py:215-232 (registration)

  Registration of the 'get-collection-info' tool in the list_tools handler, including its name, description, and input schema defining required 'namespace' and 'collection_id' parameters.

  types.Tool(
      name="get-collection-info",
      description="Get detailed information about a specific collection",
      inputSchema={
          "type": "object",
          "properties": {
              "namespace": {
                  "type": "string",
                  "description": "The namespace of the collection (user or organization)",
              },
              "collection_id": {
                  "type": "string",
                  "description": "The ID part of the collection",
              },
          },
          "required": ["namespace", "collection_id"],
      },
  ),

• src/huggingface/server.py:219-231 (schema)

  JSON schema for input validation of the 'get-collection-info' tool, specifying an object with 'namespace' and 'collection_id' properties, both required strings.

      "type": "object",
      "properties": {
          "namespace": {
              "type": "string",
              "description": "The namespace of the collection (user or organization)",
          },
          "collection_id": {
              "type": "string",
              "description": "The ID part of the collection",
          },
      },
      "required": ["namespace", "collection_id"],
  },

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

  Helper function used by the tool handler to make HTTP GET requests to the Hugging Face API endpoints, handling errors and returning JSON or error dict.

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