first commit

.python-version

@@ -0,0 +1 @@
+3.11

Dockerfile

@@ -0,0 +1,33 @@
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy project files
+COPY pyproject.toml .
+COPY server.py .
+COPY mcp_server.py .
+COPY env.example .
+COPY README.md .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -e .
+
+# Create a non-root user
+RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
+USER appuser
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/ || exit 1
+
+# Run the application
+CMD ["python", "server.py"] 

README.md

@@ -9,4 +9,246 @@ app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🤖 Hugging Face Discussion Bot
+
+A FastAPI and Gradio application that automatically responds to Hugging Face Hub discussion comments using AI-powered responses via Hugging Face Inference API with MCP integration.
+
+## ✨ Features
+
+- **Webhook Integration**: Receives real-time webhooks from Hugging Face Hub when new discussion comments are posted
+- **AI-Powered Responses**: Uses Hugging Face Inference API with MCP support for intelligent, context-aware responses
+- **Interactive Dashboard**: Beautiful Gradio interface to monitor comments and test functionality
+- **Automatic Posting**: Posts AI responses back to the original discussion thread
+- **Testing Tools**: Built-in webhook simulation and AI testing capabilities
+- **MCP Server**: Includes a Model Context Protocol server for advanced tool integration
+
+## 🚀 Quick Start
+
+### 1. Installation
+
+```bash
+# Clone the repository
+git clone <your-repo-url>
+cd mcp-course-unit3-example
+
+# Install dependencies
+pip install -e .
+```
+
+### 2. Environment Setup
+
+Copy the example environment file and configure your API keys:
+
+```bash
+cp env.example .env
+```
+
+Edit `.env` with your credentials:
+
+```env
+# Webhook Configuration
+WEBHOOK_SECRET=your-secure-webhook-secret
+
+# Hugging Face Configuration  
+HF_TOKEN=hf_your_hugging_face_token_here
+
+# Model Configuration (optional)
+HF_MODEL=microsoft/DialoGPT-medium
+HF_PROVIDER=huggingface
+```
+
+### 3. Run the Application
+
+```bash
+python server.py
+```
+
+The application will start on `http://localhost:8000` with:
+- 📊 **Gradio Dashboard**: `http://localhost:8000/gradio`
+- 🔗 **Webhook Endpoint**: `http://localhost:8000/webhook`
+- 📋 **API Documentation**: `http://localhost:8000/docs`
+
+## 🔧 Configuration
+
+### Hugging Face Hub Webhook Setup
+
+1. Go to your Hugging Face repository settings
+2. Navigate to the "Webhooks" section
+3. Create a new webhook with:
+   - **URL**: `https://your-domain.com/webhook`
+   - **Secret**: Same as `WEBHOOK_SECRET` in your `.env`
+   - **Events**: Subscribe to "Community (PR & discussions)"
+
+### Required API Keys
+
+#### Hugging Face Token
+1. Go to [Hugging Face Settings](https://huggingface.co/settings/tokens)
+2. Create a new token with "Write" permissions
+3. Add it to your `.env` as `HF_TOKEN`
+
+## 📊 Dashboard Features
+
+### Recent Comments Tab
+- View all processed discussion comments
+- See AI responses in real-time
+- Refresh and filter capabilities
+
+### Test HF Inference Tab
+- Direct testing of the Hugging Face Inference API
+- Custom prompt input
+- Response preview
+
+### Simulate Webhook Tab
+- Test webhook processing without real HF events
+- Mock discussion scenarios
+- Validate AI response generation
+
+### Configuration Tab
+- View current setup status
+- Check API key configuration
+- Monitor processing statistics
+
+## 🔌 API Endpoints
+
+### POST `/webhook`
+Receives webhooks from Hugging Face Hub.
+
+**Headers:**
+- `X-Webhook-Secret`: Your webhook secret
+
+**Body:** HF Hub webhook payload
+
+### GET `/comments`
+Returns all processed comments and responses.
+
+### GET `/`
+Basic API information and available endpoints.
+
+## 🤖 MCP Server
+
+The application includes a Model Context Protocol (MCP) server that provides tools for:
+
+- **get_discussions**: Retrieve discussions from HF repositories
+- **get_discussion_details**: Get detailed information about specific discussions
+- **comment_on_discussion**: Add comments to discussions
+- **generate_ai_response**: Generate AI responses using HF Inference
+- **respond_to_discussion**: Generate and post AI responses automatically
+
+### Running the MCP Server
+
+```bash
+python mcp_server.py
+```
+
+The MCP server uses stdio transport and can be integrated with MCP clients following the [Tiny Agents pattern](https://huggingface.co/blog/python-tiny-agents).
+
+## 🧪 Testing
+
+### Local Testing
+Use the "Simulate Webhook" tab in the Gradio dashboard to test without real webhooks.
+
+### Webhook Testing
+You can test the webhook endpoint directly:
+
+```bash
+curl -X POST http://localhost:8000/webhook \
+  -H "Content-Type: application/json" \
+  -H "X-Webhook-Secret: your-webhook-secret" \
+  -d '{
+    "event": {"action": "create", "scope": "discussion.comment"},
+    "comment": {
+      "content": "@discussion-bot How do I use this model?",
+      "author": "test-user",
+      "created_at": "2024-01-01T00:00:00Z"
+    },
+    "discussion": {
+      "title": "Test Discussion",
+      "num": 1,
+      "url": {"api": "https://huggingface.co/api/repos/test/repo/discussions"}
+    },
+    "repo": {"name": "test/repo"}
+  }'
+```
+
+## 🏗️ Architecture
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   HF Hub        │───▶│   FastAPI       │───▶│   HF Inference  │
+│   Webhook       │    │   Server        │    │   API           │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+                              │
+                              ▼
+                       ┌─────────────────┐
+                       │   Gradio        │
+                       │   Dashboard     │
+                       └─────────────────┘
+                              │
+                              ▼
+                       ┌─────────────────┐
+                       │   MCP Server    │
+                       │   (Tools)       │
+                       └─────────────────┘
+```
+
+## 🔒 Security
+
+- Webhook secret verification prevents unauthorized requests
+- Environment variables keep sensitive data secure
+- CORS middleware configured for safe cross-origin requests
+
+## 🚀 Deployment
+
+### Using Docker (Recommended)
+
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY . .
+RUN pip install -e .
+
+EXPOSE 8000
+CMD ["python", "server.py"]
+```
+
+### Using Cloud Platforms
+
+The application can be deployed on:
+- **Hugging Face Spaces** (recommended for HF integration)
+- **Railway**
+- **Render**
+- **Heroku**
+- **AWS/GCP/Azure**
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## 📝 License
+
+This project is licensed under the MIT License.
+
+## 🆘 Support
+
+If you encounter issues:
+
+1. Check the Configuration tab in the dashboard
+2. Verify your API keys are correct
+3. Ensure webhook URL is accessible
+4. Check the application logs
+
+For additional help, please open an issue in the repository.
+
+## 🔗 Related Links
+
+- [Hugging Face Webhooks Guide](https://huggingface.co/docs/hub/en/webhooks-guide-discussion-bot)
+- [Hugging Face Hub Python Library](https://huggingface.co/docs/huggingface_hub/en/guides/community)
+- [Tiny Agents in Python Blog Post](https://huggingface.co/blog/python-tiny-agents)
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+- [Gradio Documentation](https://gradio.app/)
+- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)

env.example

@@ -0,0 +1,12 @@
+# Webhook Configuration
+WEBHOOK_SECRET=your-webhook-secret-here
+
+# Hugging Face Configuration
+HF_TOKEN=your-huggingface-token-here
+
+# Model Configuration (optional)
+HF_MODEL=microsoft/DialoGPT-medium
+HF_PROVIDER=huggingface
+
+# Optional: Custom bot username for mention detection
+BOT_USERNAME=discussion-bot 

mcp_server.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""
+Simplified MCP Server for HuggingFace Hub Operations using FastMCP
+"""
+
+import os
+from fastmcp import FastMCP
+from huggingface_hub import comment_discussion, InferenceClient
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Configuration
+HF_TOKEN = os.getenv("HF_TOKEN")
+DEFAULT_MODEL = os.getenv("HF_MODEL", "Qwen/Qwen2.5-72B-Instruct")
+
+# Initialize HF client
+inference_client = (
+    InferenceClient(model=DEFAULT_MODEL, token=HF_TOKEN) if HF_TOKEN else None
+)
+
+# Create the FastMCP server
+mcp = FastMCP("hf-discussion-bot")
+
+
+@mcp.tool()
+def generate_discussion_response(
+    discussion_title: str, comment_content: str, repo_name: str
+) -> str:
+    """Generate AI response for a HuggingFace discussion comment"""
+    if not inference_client:
+        return "Error: HF token not configured for inference"
+
+    prompt = f"""
+    Discussion: {discussion_title}
+    Repository: {repo_name}
+    Comment: {comment_content}
+    
+    Provide a helpful response to this comment.
+    """
+
+    try:
+        messages = [
+            {
+                "role": "system",
+                "content": ("You are a helpful AI assistant for ML discussions."),
+            },
+            {"role": "user", "content": prompt},
+        ]
+
+        response = inference_client.chat_completion(messages=messages, max_tokens=150)
+        content = response.choices[0].message.content
+        ai_response = content.strip() if content else "No response generated"
+        return ai_response
+
+    except Exception as e:
+        return f"Error generating response: {str(e)}"
+
+
+@mcp.tool()
+def post_discussion_comment(repo_id: str, discussion_num: int, comment: str) -> str:
+    """Post a comment to a HuggingFace discussion"""
+    if not HF_TOKEN:
+        return "Error: HF token not configured"
+
+    try:
+        comment_discussion(
+            repo_id=repo_id,
+            discussion_num=discussion_num,
+            comment=comment,
+            token=HF_TOKEN,
+        )
+        success_msg = f"Successfully posted comment to discussion #{discussion_num}"
+        return success_msg
+
+    except Exception as e:
+        return f"Error posting comment: {str(e)}"
+
+
+if __name__ == "__main__":
+    mcp.run()

pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "mcp-course-unit3-example"
+version = "0.1.0"
+description = "FastAPI and Gradio app for Hugging Face Hub discussion webhooks"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.104.0",
+    "uvicorn[standard]>=0.24.0",
+    "gradio>=4.0.0",
+    "huggingface-hub[mcp]>=0.32.0",
+    "pydantic>=2.0.0",
+    "python-multipart>=0.0.6",
+    "requests>=2.31.0",
+    "python-dotenv>=1.0.0",
+    "fastmcp>=2.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]

requirements.txt

@@ -0,0 +1,78 @@
+# This file was autogenerated by uv via the following command:
+#    uv export --format requirements-txt --no-hashes
+-e .
+aiofiles==24.1.0
+aiohappyeyeballs==2.6.1
+aiohttp==3.12.2
+aiosignal==1.3.2
+annotated-types==0.7.0
+anyio==4.9.0
+attrs==25.3.0
+audioop-lts==0.2.1 ; python_full_version >= '3.13'
+certifi==2025.4.26
+charset-normalizer==3.4.2
+click==8.2.1
+colorama==0.4.6 ; sys_platform == 'win32' or platform_system == 'Windows'
+exceptiongroup==1.3.0
+fastapi==0.115.12
+fastmcp==2.5.1
+ffmpy==0.5.0
+filelock==3.18.0
+frozenlist==1.6.0
+fsspec==2025.5.1
+gradio==5.31.0
+gradio-client==1.10.1
+groovy==0.1.2
+h11==0.16.0
+hf-xet==1.1.2 ; platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+httpcore==1.0.9
+httptools==0.6.4
+httpx==0.28.1
+httpx-sse==0.4.0
+huggingface-hub==0.32.2
+idna==3.10
+jinja2==3.1.6
+markdown-it-py==3.0.0
+markupsafe==3.0.2
+mcp==1.9.1
+mdurl==0.1.2
+multidict==6.4.4
+numpy==2.2.6
+openapi-pydantic==0.5.1
+orjson==3.10.18
+packaging==25.0
+pandas==2.2.3
+pillow==11.2.1
+propcache==0.3.1
+pydantic==2.11.5
+pydantic-core==2.33.2
+pydantic-settings==2.9.1
+pydub==0.25.1
+pygments==2.19.1
+python-dateutil==2.9.0.post0
+python-dotenv==1.1.0
+python-multipart==0.0.20
+pytz==2025.2
+pyyaml==6.0.2
+requests==2.32.3
+rich==14.0.0
+ruff==0.11.11 ; sys_platform != 'emscripten'
+safehttpx==0.1.6
+semantic-version==2.10.0
+shellingham==1.5.4
+six==1.17.0
+sniffio==1.3.1
+sse-starlette==2.3.5
+starlette==0.46.2
+tomlkit==0.13.2
+tqdm==4.67.1
+typer==0.16.0
+typing-extensions==4.13.2
+typing-inspection==0.4.1
+tzdata==2025.2
+urllib3==2.4.0
+uvicorn==0.34.2
+uvloop==0.21.0 ; platform_python_implementation != 'PyPy' and sys_platform != 'cygwin' and sys_platform != 'win32'
+watchfiles==1.0.5
+websockets==15.0.1
+yarl==1.20.0

server.py

@@ -0,0 +1,192 @@
+import os
+from datetime import datetime
+from typing import List, Dict, Any, Optional
+
+from fastapi import FastAPI, Request, BackgroundTasks
+from fastapi.middleware.cors import CORSMiddleware
+import gradio as gr
+import uvicorn
+from pydantic import BaseModel
+from huggingface_hub.inference._mcp.agent import Agent
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Configuration
+WEBHOOK_SECRET = os.getenv("WEBHOOK_SECRET", "your-webhook-secret")
+HF_TOKEN = os.getenv("HF_TOKEN")
+HF_MODEL = os.getenv("HF_MODEL", "microsoft/DialoGPT-medium")
+HF_PROVIDER = os.getenv("HF_PROVIDER", "huggingface")
+
+# Simple storage for processed comments
+comments_store: List[Dict[str, Any]] = []
+
+# Agent instance
+agent_instance: Optional[Agent] = None
+
+
+class WebhookEvent(BaseModel):
+    event: Dict[str, str]
+    comment: Dict[str, Any]
+    discussion: Dict[str, Any]
+    repo: Dict[str, str]
+
+
+app = FastAPI(title="HF Discussion Bot")
+app.add_middleware(CORSMiddleware, allow_origins=["*"])
+
+
+async def get_agent():
+    """Get or create Agent instance"""
+    global agent_instance
+    if agent_instance is None and HF_TOKEN:
+        agent_instance = Agent(
+            model=HF_MODEL,
+            provider=HF_PROVIDER,
+            api_key=HF_TOKEN,
+            servers=[
+                {
+                    "type": "stdio",
+                    "config": {"command": "python", "args": ["mcp_server.py"]},
+                }
+            ],
+        )
+        await agent_instance.load_tools()
+    return agent_instance
+
+
+async def process_webhook_comment(webhook_data: Dict[str, Any]):
+    """Process webhook using Agent with MCP tools"""
+    comment_content = webhook_data["comment"]["content"]
+    discussion_title = webhook_data["discussion"]["title"]
+    repo_name = webhook_data["repo"]["name"]
+    discussion_num = webhook_data["discussion"]["num"]
+
+    agent = await get_agent()
+    if not agent:
+        ai_response = "Error: Agent not configured (missing HF_TOKEN)"
+    else:
+        # Use Agent to respond to the discussion
+        prompt = f"""
+        Please respond to this HuggingFace discussion comment using the available tools.
+        
+        Repository: {repo_name}
+        Discussion: {discussion_title} (#{discussion_num})
+        Comment: {comment_content}
+        
+        First use generate_discussion_response to create a helpful response, then use post_discussion_comment to post it.
+        """
+
+        try:
+            response_parts = []
+            async for item in agent.run(prompt):
+                # Collect the agent's response
+                if hasattr(item, "content") and item.content:
+                    response_parts.append(item.content)
+                elif isinstance(item, str):
+                    response_parts.append(item)
+
+            ai_response = (
+                " ".join(response_parts) if response_parts else "No response generated"
+            )
+        except Exception as e:
+            ai_response = f"Error using agent: {str(e)}"
+
+    # Store the interaction with reply link
+    discussion_url = f"https://huggingface.co/{repo_name}/discussions/{discussion_num}"
+
+    interaction = {
+        "timestamp": datetime.now().isoformat(),
+        "repo": repo_name,
+        "discussion_title": discussion_title,
+        "discussion_num": discussion_num,
+        "discussion_url": discussion_url,
+        "original_comment": comment_content,
+        "ai_response": ai_response,
+        "comment_author": webhook_data["comment"]["author"],
+    }
+
+    comments_store.append(interaction)
+    return ai_response
+
+
+@app.post("/webhook")
+async def webhook_handler(request: Request, background_tasks: BackgroundTasks):
+    """Handle HF Hub webhooks"""
+    webhook_secret = request.headers.get("X-Webhook-Secret")
+    if webhook_secret != WEBHOOK_SECRET:
+        return {"error": "Invalid webhook secret"}
+
+    payload = await request.json()
+    event = payload.get("event", {})
+
+    if event.get("action") == "create" and event.get("scope") == "discussion.comment":
+        background_tasks.add_task(process_webhook_comment, payload)
+        return {"status": "processing"}
+
+    return {"status": "ignored"}
+
+
+async def simulate_webhook(
+    repo_name: str, discussion_title: str, comment_content: str
+) -> str:
+    """Simulate webhook for testing"""
+    if not all([repo_name, discussion_title, comment_content]):
+        return "Please fill in all fields."
+
+    mock_payload = {
+        "event": {"action": "create", "scope": "discussion.comment"},
+        "comment": {
+            "content": comment_content,
+            "author": "test-user",
+            "created_at": datetime.now().isoformat(),
+        },
+        "discussion": {
+            "title": discussion_title,
+            "num": len(comments_store) + 1,
+        },
+        "repo": {"name": repo_name},
+    }
+
+    response = await process_webhook_comment(mock_payload)
+    return f"✅ Processed! AI Response: {response}"
+
+
+def create_gradio_app():
+    """Create Gradio interface"""
+    with gr.Blocks(title="HF Discussion Bot", theme=gr.themes.Soft()) as demo:
+        gr.Markdown("# 🤖 HF Discussion Bot Dashboard")
+        gr.Markdown("*Powered by HuggingFace Tiny Agents + FastMCP*")
+
+        with gr.Column():
+            sim_repo = gr.Textbox(label="Repository", value="microsoft/DialoGPT-medium")
+            sim_title = gr.Textbox(label="Discussion Title", value="Test Discussion")
+            sim_comment = gr.Textbox(
+                label="Comment",
+                lines=3,
+                value="How do I use this model?",
+            )
+            sim_btn = gr.Button("📤 Test Webhook")
+
+        with gr.Column():
+            sim_result = gr.Textbox(label="Result", lines=8)
+
+        sim_btn.click(
+            fn=simulate_webhook,
+            inputs=[sim_repo, sim_title, sim_comment],
+            outputs=[sim_result],
+        )
+
+    return demo
+
+
+# Mount Gradio app
+gradio_app = create_gradio_app()
+app = gr.mount_gradio_app(app, gradio_app, path="/gradio")
+
+
+if __name__ == "__main__":
+    print("🚀 Starting HF Discussion Bot with Tiny Agents...")
+    print("📊 Dashboard: http://localhost:8001/gradio")
+    print("🔗 Webhook: http://localhost:8001/webhook")
+    uvicorn.run("server:app", host="0.0.0.0", port=8001, reload=True)