Hugging Face Hub Tagging Bot

Note: This project is based on the Hugging Face MCP Course - Unit 3: Webhooks & Agents.

This project is an automated tagging agent for Hugging Face model repositories. It serves as a webhook listener built with FastAPI that automatically monitors model discussions. When a user asks a question or leaves a comment suggesting a machine learning tag (e.g., #nlp, #vision), this bot automatically extracts the tags, verifies them using an intelligent MCP agent, and creates a Pull Request on the Hugging Face Hub to add those tags to the model's README.md metadata!

🚀 Features

Webhook Integration: Listens for discussion.comment events from Hugging Face Hub.
Smart Tag Extraction: Recognizes both explicit tags (tags: nlp, vision) and implicit hashtag usage (#question-answering).
Automated PRs: Uses the Hugging Face HfApi and an LLM-powered FastMCP Agent to automatically verify and create Pull Requests for new tags.

🛠️ Setup & Installation

1. Install Dependencies

You can install the required packages using pip or uv. This project requires Python 3.11+.

Using pip:

pip install .

Using uv (recommended for speed):

uv pip install -r pyproject.toml

2. Environment Variables

Create a .env file in the root of your project (you can copy .env.example if it exists) and add your Hugging Face credentials:

HF_TOKEN=your_huggingface_access_token_here
HF_MODEL=Qwen/Qwen2.5-Coder-32B-Instruct
WEBHOOK_SECRET=your_custom_secret_string

Note: Your HF_TOKEN must have write permissions to the repositories you are monitoring to successfully create Pull Requests!

Running the Application

To run the project locally, you will need to start three separate processes in their own terminal windows.

1. Start the MCP Server

First, start the Model Context Protocol (MCP) server:

python run_mcp.py

2. Start the FastAPI Webhook Server

Next, start the FastAPI server to listen for webhook events:

uvicorn src.api.server:app --reload --port 8000

The application will now be running locally at http://127.0.0.1:8000.

3. Expose the Server with Ngrok

Hugging Face webhooks require a public, internet-accessible URL. Expose your local port 8000 to the internet using ngrok:

ngrok http 8000

This will generate a Forwarding URL (e.g., https://1a2b3c4d.ngrok.app).

2. Configure Hugging Face

Go to your Hugging Face account settings and navigate to the Webhooks section.
Click Create a webhook.
Target Repositories: Select the repositories you want to monitor (e.g., MohmaedElnamir/test).
Webhook URL: Enter your Ngrok URL followed by /webhook (e.g., https://1a2b3c4d.ngrok.app/webhook).
Webhook Secret: Enter the same secret string you put in your .env file under WEBHOOK_SECRET.
Save and enable the webhook!

3. Test It!

Go to the Hugging Face discussion tab on your monitored repository and leave a comment like:

"Does this model support #text-generation?"

Watch your uvicorn console as the Tagging Bot processes the webhook and creates a PR on your repository!

Hugging Face Hub Tagging Bot