updates

DOCKER_VS_GRADIO.md

@@ -0,0 +1,412 @@
+# Docker vs Gradio Deployment Guide
+
+## Overview
+
+This document explains the difference between Docker and Gradio deployments on Hugging Face Spaces and why we chose Docker for your MCP server.
+
+## Quick Comparison
+
+```
+Gradio:  Python Code → Automatic UI → Human Users
+Docker:  Dockerfile → Custom Server → API Clients (AI, Apps, Services)
+```
+
+## Your Current Setup (Docker)
+
+### Architecture
+```
+┌─────────────────────────────────────┐
+│       Hugging Face Space            │
+│  ┌───────────────────────────────┐  │
+│  │     Docker Container          │  │
+│  │  ┌─────────────────────────┐  │  │
+│  │  │  FastAPI Server         │  │  │
+│  │  │  (app.py)               │  │  │
+│  │  │  Port: 7860             │  │  │
+│  │  │                         │  │  │
+│  │  │  REST API Endpoints:    │  │  │
+│  │  │  - GET  /health         │  │  │
+│  │  │  - GET  /               │  │  │
+│  │  │  - GET  /tools          │  │  │
+│  │  │  - POST /search         │  │  │
+│  │  └─────────────────────────┘  │  │
+│  │           ↓                    │  │
+│  │  ┌─────────────────────────┐  │  │
+│  │  │  MCP Server (server.py) │  │  │
+│  │  │  YouTube Search Tool    │  │  │
+│  │  └─────────────────────────┘  │  │
+│  └───────────────────────────────┘  │
+└─────────────────────────────────────┘
+         ↓
+    REST API Calls
+         ↓
+  ┌──────────────────┐
+  │  AI Assistants   │
+  │  Python Scripts  │
+  │  Web Apps        │
+  └──────────────────┘
+```
+
+### Access Methods
+```bash
+# API Access (Programmatic)
+curl -X POST https://your-space.hf.space/search \
+  -d '{"query": "Python"}'
+
+# Python Integration
+import requests
+response = requests.post(
+    "https://your-space.hf.space/search",
+    json={"query": "Python", "max_results": 5}
+)
+
+# Claude Desktop Integration
+# Add to MCP settings and use via chat
+```
+
+## Alternative: Gradio Approach
+
+### What It Would Look Like
+```
+┌─────────────────────────────────────┐
+│       Hugging Face Space            │
+│  ┌───────────────────────────────┐  │
+│  │     Gradio App                │  │
+│  │  ┌─────────────────────────┐  │  │
+│  │  │  Auto-generated UI:     │  │  │
+│  │  │  [Search Query    ]     │  │  │
+│  │  │  [Max Results: 5  ]     │  │  │
+│  │  │  [  Search Button ]     │  │  │
+│  │  │                         │  │  │
+│  │  │  Results:               │  │  │
+│  │  │  { ... json ... }       │  │  │
+│  │  └─────────────────────────┘  │  │
+│  └───────────────────────────────┘  │
+└─────────────────────────────────────┘
+         ↓
+   Browser Access Only
+         ↓
+  ┌──────────────────┐
+  │  Human Users     │
+  │  (via browser)   │
+  └──────────────────┘
+```
+
+### Gradio Code Example
+```python
+# app.py for Gradio
+import gradio as gr
+from server import search_youtube_videos
+
+def search(query, max_results):
+    return search_youtube_videos(query, max_results)
+
+demo = gr.Interface(
+    fn=search,
+    inputs=[
+        gr.Textbox(label="Search Query"),
+        gr.Slider(1, 10, value=5, label="Max Results")
+    ],
+    outputs=gr.JSON()
+)
+
+demo.launch()
+```
+
+### README.md for Gradio
+```yaml
+---
+title: Basicsearch
+sdk: gradio
+sdk_version: 5.49.1
+app_file: app.py
+---
+```
+
+## Feature Comparison Matrix
+
+| Feature | Docker (Your Choice) | Gradio Alternative |
+|---------|---------------------|-------------------|
+| **Primary Use Case** | API Service | Interactive Demo |
+| **Target Users** | AI systems, apps | Humans via browser |
+| **Setup Complexity** | Medium | Low |
+| **Build Time** | 5-15 minutes | 2-3 minutes |
+| **Deployment Method** | Dockerfile | Python script |
+| | | |
+| **Capabilities** | | |
+| REST API | ✅ Full | ⚠️ Limited |
+| Custom Server | ✅ Yes | ❌ No |
+| MCP Protocol | ✅ Yes | ❌ No |
+| Visual UI | ⚠️ Manual | ✅ Automatic |
+| WebSocket Support | ✅ Yes | ⚠️ Limited |
+| Multiple Endpoints | ✅ Yes | ⚠️ Limited |
+| | | |
+| **Integration** | | |
+| cURL/HTTP Clients | ✅ Yes | ⚠️ Limited |
+| Python requests | ✅ Yes | ⚠️ Via API |
+| JavaScript fetch | ✅ Yes | ⚠️ Via API |
+| Claude Desktop | ✅ Yes | ❌ No |
+| Mobile Apps | ✅ Yes | ⚠️ Browser only |
+| | | |
+| **Control & Flexibility** | | |
+| Custom Dependencies | ✅ Full control | ⚠️ Limited |
+| Port Configuration | ✅ Yes | ⚠️ Fixed |
+| Environment Variables | ✅ Full access | ✅ Yes |
+| Multi-container | ✅ Possible | ❌ No |
+| Background Tasks | ✅ Yes | ⚠️ Limited |
+| | | |
+| **Development** | | |
+| Local Testing | ✅ Docker/Direct | ✅ Easy |
+| Debugging | ⚠️ Moderate | ✅ Easy |
+| Hot Reload | ⚠️ Manual | ✅ Automatic |
+| Custom Middleware | ✅ Yes | ❌ No |
+
+## Why Docker for Your MCP Server?
+
+### ✅ Reasons We Chose Docker
+
+1. **MCP Protocol Support**
+   - MCP servers need custom server implementations
+   - Gradio doesn't support STDIO protocol
+   - Need full control over server lifecycle
+
+2. **API-First Design**
+   - Your service is consumed by AI assistants, not humans
+   - REST API is the primary interface
+   - Need multiple endpoints with different methods
+
+3. **Production Requirements**
+   - Needs to be reliable and production-ready
+   - Full control over dependencies and environment
+   - Better error handling and logging
+
+4. **Integration Flexibility**
+   - Can be called from any language/platform
+   - Works with Claude Desktop MCP settings
+   - Compatible with future integrations
+
+5. **Scalability**
+   - Can add more endpoints easily
+   - Can add authentication/rate limiting
+   - Can integrate with databases or other services
+
+### ❌ Why Gradio Wasn't Suitable
+
+1. **No API Focus**
+   - Gradio is UI-first, API-second
+   - Limited REST API capabilities
+   - Harder to integrate programmatically
+
+2. **Limited Server Control**
+   - Can't customize server behavior
+   - Fixed port and route structure
+   - Limited middleware support
+
+3. **Not Designed for Services**
+   - Designed for demos, not production services
+   - MCP protocol requires custom setup
+   - No native support for service-to-service communication
+
+## Hybrid Approach (Best of Both Worlds!)
+
+You can actually use **BOTH** Docker and Gradio:
+
+### Option 1: Gradio as Testing UI
+```dockerfile
+# Dockerfile
+FROM python:3.13-slim
+
+# Install all dependencies
+RUN pip install fastapi uvicorn gradio
+
+# Copy both apps
+COPY app.py ./          # FastAPI server
+COPY gradio_ui.py ./    # Gradio UI
+
+# Run both (using a process manager)
+CMD ["python", "app.py"]  # Main API
+# Access Gradio separately for testing
+```
+
+### Option 2: Separate Spaces
+```
+Space 1 (Docker): API Service
+├── FastAPI REST API
+├── MCP Server
+└── Production endpoints
+
+Space 2 (Gradio): Testing UI  
+├── Gradio Interface
+├── Calls Space 1 API
+└── Human-friendly testing
+```
+
+### Option 3: Gradio + FastAPI in Same Docker
+```python
+# Combined approach in app.py
+from fastapi import FastAPI
+import gradio as gr
+
+# FastAPI for APIs
+app = FastAPI()
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+@app.post("/search")
+def search(query: str):
+    return search_youtube_videos(query)
+
+# Gradio for UI
+with gr.Blocks() as gradio_app:
+    # Your UI here
+    pass
+
+# Mount Gradio on FastAPI
+app = gr.mount_gradio_app(app, gradio_app, path="/ui")
+
+# Now you have:
+# - API: https://your-space.hf.space/search
+# - UI:  https://your-space.hf.space/ui
+```
+
+## Migration: Docker ↔ Gradio
+
+### From Docker to Gradio (if you want simpler demo)
+
+**Current (Docker):**
+```yaml
+# README.md
+sdk: docker
+```
+
+**Change to:**
+```yaml
+# README.md
+sdk: gradio
+sdk_version: 5.49.1
+app_file: gradio_ui.py
+```
+
+Then push. HF will rebuild automatically.
+
+### From Gradio to Docker (if you need more power)
+
+**Current:**
+```yaml
+sdk: gradio
+app_file: app.py
+```
+
+**Change to:**
+```yaml
+sdk: docker
+app_port: 7860
+```
+
+Add `Dockerfile`, push, and HF rebuilds.
+
+## Performance Comparison
+
+| Metric | Docker | Gradio |
+|--------|--------|--------|
+| Cold Start | 10-30s | 5-15s |
+| Build Time | 5-15 min | 2-3 min |
+| Memory Usage | ~500MB | ~300MB |
+| Request Latency | <100ms | <100ms |
+| Concurrent Users | High | Medium |
+| API Throughput | High | Medium |
+
+## Cost Considerations
+
+Both are **FREE** on Hugging Face Spaces free tier:
+- Docker: Same resources as Gradio
+- Gradio: Same resources as Docker
+- No difference in hosting cost
+- Both support custom domains on Pro
+
+## Real-World Examples
+
+### Docker Deployments
+```
+✅ API Services (your case)
+✅ Database-backed apps
+✅ Multi-service architectures
+✅ WebSocket servers
+✅ Custom protocols (MCP, gRPC)
+✅ Background job processors
+```
+
+### Gradio Deployments
+```
+✅ ML model demos
+✅ Image classifiers
+✅ Text generators
+✅ Quick prototypes
+✅ Research showcases
+✅ Educational tools
+```
+
+## Testing Your Current Setup
+
+Since you're using Docker, you can test both ways locally:
+
+### Test 1: API Mode (Docker)
+```bash
+# Start your Docker container
+docker build -t basicsearch .
+docker run -p 7860:7860 basicsearch
+
+# Test API
+curl http://localhost:7860/health
+```
+
+### Test 2: Gradio UI (Optional)
+```bash
+# Run the Gradio UI we created
+uv run python gradio_ui.py
+
+# Visit http://localhost:7860 in browser
+```
+
+## Recommendation for Your Project
+
+**Stick with Docker** because:
+1. ✅ Your MCP server needs API access (primary requirement)
+2. ✅ You need integration with Claude and other tools
+3. ✅ Production-ready service is the goal
+4. ✅ You may need to add features (auth, logging, etc.)
+5. ✅ Better for long-term maintenance
+
+**Optional:** Add Gradio UI later for:
+- Human testing interface
+- Demo purposes
+- Visual debugging
+- Client presentations
+
+## Summary
+
+| Aspect | Your Choice (Docker) | Alternative (Gradio) |
+|--------|---------------------|---------------------|
+| **What You Built** | API Service | Would be Demo UI |
+| **Who Uses It** | AI Assistants | Humans in Browser |
+| **How They Use It** | HTTP Requests | Click & Type |
+| **Best For** | Production Services | Quick Demos |
+| **Your Needs** | ✅ Perfect Match | ❌ Wrong Tool |
+
+## Next Steps
+
+1. ✅ Continue with Docker deployment
+2. ⏳ Wait for build to complete
+3. 🧪 Test with `uv run python test_deployment.py`
+4. 📝 (Optional) Try Gradio UI: `uv run python gradio_ui.py`
+5. 🚀 Integrate with your AI workflows
+
+---
+
+**TL;DR:** 
+- **Gradio** = Easy UI for demos (humans clicking buttons)
+- **Docker** = Powerful API for services (programs making requests)
+- **Your choice (Docker)** = Correct for MCP server! ✅
+

PRIVATE_SPACE_GUIDE.md

@@ -0,0 +1,283 @@
+# Private Space Testing Guide
+
+## The 404 Problem: Is Your Space Private?
+
+If you're getting 404 errors, your Space might be **PRIVATE**, which requires authentication to access.
+
+## Check Your Space Visibility
+
+The settings page should now be open in your browser. Look for:
+
+### 🔒 Private Space
+```
+Visibility: Private
+Only you and approved users can access this Space
+```
+
+### 🌐 Public Space
+```
+Visibility: Public
+Anyone can access this Space
+```
+
+## Solution 1: Make Your Space Public (Recommended for APIs)
+
+### Steps:
+1. Go to: https://huggingface.co/spaces/ocx2025/basicsearch/settings
+2. Scroll to **"Visibility"** section
+3. Click **"Make public"**
+4. Confirm the change
+
+### After Making Public:
+```bash
+# Wait 30 seconds, then test again
+sleep 30
+cd /Users/marjorie/Documents/GitHub/xctopus/mcp2/basicsearch
+uv run python test_deployment.py
+```
+
+### ✅ Pros:
+- No authentication needed
+- Easy to test
+- Anyone can use your API
+- Better for integrations
+
+### ❌ Cons:
+- Anyone can see your code
+- Anyone can use your API
+- Public usage counts
+
+## Solution 2: Keep Private + Use Authentication Token
+
+If you want to keep the Space private, you'll need a Hugging Face token.
+
+### Get Your Token:
+1. Visit: https://huggingface.co/settings/tokens
+2. Click **"New token"**
+3. Name it: `basicsearch-testing`
+4. Select permissions: **Read**
+5. Click **"Generate"**
+6. Copy the token (starts with `hf_...`)
+
+### Test with Token:
+```bash
+cd /Users/marjorie/Documents/GitHub/xctopus/mcp2/basicsearch
+
+# Replace YOUR_TOKEN with actual token
+python test_private_space.py https://ocx2025-basicsearch.hf.space hf_YourTokenHere
+```
+
+### Set as Environment Variable:
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+export HF_TOKEN="hf_YourTokenHere"
+
+# Then you can just run:
+python test_private_space.py
+```
+
+### Update Test Script to Use Token:
+```python
+# test_deployment.py with auth
+import os
+import requests
+
+token = os.getenv("HF_TOKEN")
+headers = {}
+if token:
+    headers["Authorization"] = f"Bearer {token}"
+
+response = requests.get(
+    "https://ocx2025-basicsearch.hf.space/health",
+    headers=headers
+)
+```
+
+### ✅ Pros:
+- Code stays private
+- Control who can access
+- Better security
+
+### ❌ Cons:
+- Requires token management
+- More complex testing
+- Harder to share
+
+## Test Right Now
+
+### Quick Check:
+```bash
+# Test without auth (works if public)
+curl https://ocx2025-basicsearch.hf.space/health
+
+# Test with auth (works if private)
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  https://ocx2025-basicsearch.hf.space/health
+```
+
+### Expected Results:
+
+#### If Space is Building:
+```
+404 - Page not found (with HF branding page)
+```
+**Action:** Wait 5-10 more minutes
+
+#### If Space is Private:
+```
+404 - Page not found
+```
+**Action:** Make public OR use token
+
+#### If Space is Public and Running:
+```json
+{"status": "ok"}
+```
+**Action:** Celebrate! 🎉
+
+## How to Use Private Space with Claude
+
+If you keep it private, you'll need to configure Claude with your token:
+
+### Claude Desktop Config:
+```json
+{
+  "mcpServers": {
+    "basicsearch": {
+      "url": "https://ocx2025-basicsearch.hf.space",
+      "headers": {
+        "Authorization": "Bearer hf_YourTokenHere"
+      }
+    }
+  }
+}
+```
+
+## Docker App with Authentication
+
+If you want your Docker app to handle authentication, update `app.py`:
+
+```python
+from fastapi import FastAPI, Header, HTTPException
+
+app = FastAPI()
+
+# Simple token check
+API_TOKEN = os.getenv("API_TOKEN", "")
+
+@app.get("/health")
+async def health(authorization: str = Header(None)):
+    if API_TOKEN and authorization != f"Bearer {API_TOKEN}":
+        raise HTTPException(status_code=401, detail="Unauthorized")
+    return {"status": "ok"}
+```
+
+## Comparison: Public vs Private
+
+| Feature | Public | Private |
+|---------|--------|---------|
+| **Access** | Anyone | Token required |
+| **Testing** | Easy | Needs token |
+| **Security** | Low | High |
+| **Sharing** | Easy | Controlled |
+| **API Use** | Simple | Complex |
+| **Best For** | Demos, Open APIs | Internal tools |
+
+## Recommendation for Your MCP Server
+
+### Choose Public If:
+- ✅ You want easy testing
+- ✅ You plan to share with others
+- ✅ Your API is meant to be public
+- ✅ No sensitive data involved
+- ✅ You want Claude integration to be simple
+
+### Choose Private If:
+- ✅ You have sensitive code
+- ✅ You want to control access
+- ✅ You're in development phase
+- ✅ You need usage tracking
+- ✅ You have private API keys (like YouTube API)
+
+## Current Status Check
+
+Run this to determine what's happening:
+
+```bash
+cd /Users/marjorie/Documents/GitHub/xctopus/mcp2/basicsearch
+
+# Check 1: Is it accessible at all?
+curl -I https://ocx2025-basicsearch.hf.space/health
+
+# Check 2: What's the space status?
+open https://huggingface.co/spaces/ocx2025/basicsearch
+
+# Check 3: What are the settings?
+open https://huggingface.co/spaces/ocx2025/basicsearch/settings
+```
+
+Look for:
+1. **"Building"** → Wait and try again
+2. **"Running" + Private** → Make public or use token
+3. **"Running" + Public** → Should work!
+4. **"Error"** → Check logs
+
+## Quick Fix Checklist
+
+- [ ] Visit: https://huggingface.co/spaces/ocx2025/basicsearch/settings
+- [ ] Check visibility: Public or Private?
+- [ ] If Private: Click "Make public"
+- [ ] If keeping Private: Get HF token from https://huggingface.co/settings/tokens
+- [ ] Wait 30 seconds after change
+- [ ] Run: `uv run python test_deployment.py`
+- [ ] Should see: `✓ PASSED` messages!
+
+## Troubleshooting Matrix
+
+| Status | Visibility | Result | Action |
+|--------|-----------|--------|--------|
+| Building | Any | 404 | Wait |
+| Running | Public | 200 OK | ✅ Success |
+| Running | Public | 404 | Check logs |
+| Running | Private | 404 | Use token or make public |
+| Running | Private | 401 | Invalid token |
+| Error | Any | 404 | Check build logs |
+
+## After Making Public
+
+Once you make it public, test immediately:
+
+```bash
+# Should work now!
+curl https://ocx2025-basicsearch.hf.space/health
+
+# Full test
+uv run python test_deployment.py
+
+# If it works, you'll see:
+# ✓ PASSED - Health Check
+# ✓ PASSED - Service Info
+# ... etc
+```
+
+## Security Note
+
+If you make the Space public, your code will be visible. Make sure:
+- ✅ No API keys in code (use Hugging Face secrets)
+- ✅ No passwords or tokens committed
+- ✅ Your `.gitignore` includes `.env` files
+- ✅ Secrets are set in Space settings, not code
+
+Your `YOUTUBE_API_KEY` is safe because it's in Space secrets, not code! ✅
+
+## Summary
+
+**Most likely issue:** Your Space is **private** and needs authentication.
+
+**Quick fix:**
+1. Open settings (should be open now)
+2. Click "Make public"
+3. Wait 30 seconds
+4. Run test again
+5. Profit! 🚀
+

STATUS_CHECK.md

@@ -0,0 +1,208 @@
+# 🔍 Space Status Check
+
+## Current Status: Building or Configuration Needed
+
+Your test shows **404 errors**, which means one of the following:
+
+### 1. Space is Still Building ⏳
+Docker builds can take 5-15 minutes.
+
+**Check build status:**
+1. Visit: https://huggingface.co/spaces/ocx2025/basicsearch
+2. Look at the top of the page for:
+   - ⏳ "Building..." - Wait a few more minutes
+   - ✅ "Running" - Space is live (404 might be a different issue)
+   - ❌ "Build Failed" - Check logs
+
+### 2. Check Build Logs 📋
+
+Visit: https://huggingface.co/spaces/ocx2025/basicsearch/logs
+
+Look for errors like:
+- Python package installation failures
+- Missing dependencies
+- Docker build errors
+- Port binding issues
+
+### 3. Common Issues & Solutions
+
+#### Issue: Build Timeout
+**Symptoms:** Build stops after 10 minutes
+**Solution:** 
+- Optimize Dockerfile
+- Use smaller base image
+- Pre-build dependencies
+
+#### Issue: Port Not Exposed
+**Symptoms:** Build succeeds but 404 errors
+**Solution:** Check that app.py is running on port 7860
+
+#### Issue: Missing API Key
+**Symptoms:** Build succeeds, endpoints work but search fails
+**Solution:** Set `YOUTUBE_API_KEY` in Space secrets
+
+#### Issue: Wrong Entry Point
+**Symptoms:** Container starts but doesn't respond
+**Solution:** Verify Dockerfile CMD is correct:
+```dockerfile
+CMD ["python", "app.py"]
+```
+
+## Quick Diagnostic Steps
+
+### Step 1: Check Space Page
+```bash
+open https://huggingface.co/spaces/ocx2025/basicsearch
+```
+
+### Step 2: Check Build Logs
+```bash
+open https://huggingface.co/spaces/ocx2025/basicsearch/logs
+```
+
+### Step 3: Wait and Retry
+```bash
+# Wait 2 minutes, then test again
+sleep 120
+cd /Users/marjorie/Documents/GitHub/xctopus/mcp2/basicsearch
+uv run python test_deployment.py
+```
+
+### Step 4: Manual Test
+```bash
+# Test with curl
+curl -v https://ocx2025-basicsearch.hf.space/health
+
+# Look for:
+# - Connection refused = Space not started
+# - 404 = Space running but wrong route
+# - 200 = Success!
+```
+
+## What to Look for in Logs
+
+### ✅ Good Signs
+```
+Installing dependencies...
+Successfully installed...
+Server running on 0.0.0.0:7860
+Application startup complete
+```
+
+### ❌ Bad Signs
+```
+Error: Could not find...
+ModuleNotFoundError...
+Permission denied...
+Port already in use...
+Build timeout...
+```
+
+## Next Actions
+
+### If Still Building:
+⏰ **Wait 5-10 more minutes**, then run:
+```bash
+uv run python test_deployment.py
+```
+
+### If Build Failed:
+1. Check logs for specific error
+2. Fix the issue locally
+3. Commit and push:
+```bash
+git add .
+git commit -m "Fix: [describe fix]"
+git push origin main
+```
+
+### If Running but 404:
+Check if the Dockerfile is correct:
+```bash
+cat Dockerfile
+```
+
+Should end with:
+```dockerfile
+CMD ["python", "app.py"]
+```
+
+### If Need Help Debugging:
+1. Copy build logs
+2. Check TESTING_GUIDE.md
+3. Verify all files are pushed:
+```bash
+git status
+git log -1
+```
+
+## Monitoring Script
+
+Run this to continuously monitor your Space:
+
+```bash
+#!/bin/bash
+while true; do
+  clear
+  echo "Checking Space Status at $(date)"
+  echo "=================================="
+  STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://ocx2025-basicsearch.hf.space/health)
+  
+  if [ "$STATUS" = "200" ]; then
+    echo "✅ Space is LIVE!"
+    exit 0
+  elif [ "$STATUS" = "404" ]; then
+    echo "⏳ Still building or config needed (404)"
+  else
+    echo "❓ Unexpected status: $STATUS"
+  fi
+  
+  echo "Checking again in 30 seconds..."
+  sleep 30
+done
+```
+
+Save as `monitor.sh`, make executable, and run:
+```bash
+chmod +x monitor.sh
+./monitor.sh
+```
+
+## Expected Timeline
+
+| Time | Status |
+|------|--------|
+| 0-2 min | Initializing build |
+| 2-5 min | Installing dependencies |
+| 5-8 min | Building Docker image |
+| 8-10 min | Starting container |
+| 10+ min | Should be live (if not, check logs) |
+
+## When Space is Live
+
+You'll see:
+```bash
+$ curl https://ocx2025-basicsearch.hf.space/health
+{"status":"ok"}
+```
+
+Then run full tests:
+```bash
+uv run python test_deployment.py
+```
+
+## Resources
+
+- **Your Space:** https://huggingface.co/spaces/ocx2025/basicsearch
+- **Logs:** https://huggingface.co/spaces/ocx2025/basicsearch/logs  
+- **Settings:** https://huggingface.co/spaces/ocx2025/basicsearch/settings
+- **HF Status:** https://status.huggingface.co/
+
+## TL;DR - What to Do Now
+
+1. Visit https://huggingface.co/spaces/ocx2025/basicsearch
+2. Check if it says "Building" at the top
+3. If yes: ☕ Take a coffee break (5-10 minutes)
+4. If no: Check logs for errors
+5. After waiting, run: `uv run python test_deployment.py`
+

TESTING_GUIDE.md

@@ -0,0 +1,341 @@
+# Testing Guide for Deployed Space
+
+## Quick Status Check
+
+Your Space is deployed at: **https://huggingface.co/spaces/ocx2025/basicsearch**
+
+### Check Build Status
+
+1. Visit https://huggingface.co/spaces/ocx2025/basicsearch
+2. Look for the build status indicator at the top
+3. If building, you'll see "Building..." with logs
+4. If running, you'll see "Running" status
+
+### View Build Logs
+
+1. Go to https://huggingface.co/spaces/ocx2025/basicsearch/logs
+2. Check for any errors during Docker build
+3. Common issues:
+   - Missing dependencies
+   - Python version mismatch
+   - Docker build timeout
+
+## Testing Methods
+
+### Method 1: Automated Test Scripts (Recommended)
+
+#### Using Python Script
+```bash
+cd /Users/marjorie/Documents/GitHub/xctopus/mcp2/basicsearch
+
+# Run all tests
+python test_deployment.py
+
+# Or test a custom URL
+python test_deployment.py https://your-space-url.hf.space
+```
+
+#### Using Bash Script
+```bash
+cd /Users/marjorie/Documents/GitHub/xctopus/mcp2/basicsearch
+
+# Run all tests
+./test_deployment.sh
+
+# Or test a custom URL
+./test_deployment.sh https://your-space-url.hf.space
+```
+
+The scripts will test:
+- ✅ Health check endpoint
+- ✅ Service info endpoint
+- ✅ Tools listing
+- ✅ YouTube search functionality
+- ✅ Error handling
+
+### Method 2: Manual cURL Commands
+
+#### 1. Health Check
+```bash
+curl https://ocx2025-basicsearch.hf.space/health
+```
+
+**Expected Response:**
+```json
+{"status": "ok"}
+```
+
+#### 2. Service Information
+```bash
+curl https://ocx2025-basicsearch.hf.space/
+```
+
+**Expected Response:**
+```json
+{
+  "status": "healthy",
+  "service": "basicsearch-mcp-server",
+  "tools": ["search_youtube_videos"]
+}
+```
+
+#### 3. List Available Tools
+```bash
+curl https://ocx2025-basicsearch.hf.space/tools
+```
+
+**Expected Response:**
+```json
+{
+  "tools": [
+    {
+      "name": "search_youtube_videos",
+      "description": "Searches YouTube for videos based on a query.",
+      "parameters": {
+        "query": "string (required)",
+        "max_results": "integer (optional, default: 5)"
+      }
+    }
+  ]
+}
+```
+
+#### 4. Search YouTube Videos
+```bash
+curl -X POST https://ocx2025-basicsearch.hf.space/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "Python programming tutorial",
+    "max_results": 3
+  }'
+```
+
+**Expected Response (if API key is set):**
+```json
+{
+  "results": [
+    {
+      "title": "Python Tutorial for Beginners",
+      "video_id": "abc123xyz",
+      "description": "Learn Python programming..."
+    },
+    ...
+  ]
+}
+```
+
+**Expected Error (if API key NOT set):**
+```json
+{
+  "error": "YOUTUBE_API_KEY environment variable is not set"
+}
+```
+
+### Method 3: Using Python `requests` Library
+
+```python
+import requests
+import json
+
+BASE_URL = "https://ocx2025-basicsearch.hf.space"
+
+# Test health
+response = requests.get(f"{BASE_URL}/health")
+print(f"Health: {response.json()}")
+
+# Test search
+payload = {"query": "Python", "max_results": 2}
+response = requests.post(f"{BASE_URL}/search", json=payload)
+print(f"Search Results: {json.dumps(response.json(), indent=2)}")
+```
+
+### Method 4: Using Browser
+
+Simply visit these URLs in your browser:
+
+1. **Health Check:** https://ocx2025-basicsearch.hf.space/health
+2. **Service Info:** https://ocx2025-basicsearch.hf.space/
+3. **Tools List:** https://ocx2025-basicsearch.hf.space/tools
+
+For POST requests, use a browser extension like:
+- [Postman](https://www.postman.com/)
+- [Thunder Client](https://www.thunderclient.com/) (VS Code extension)
+- [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) (VS Code extension)
+
+## Troubleshooting
+
+### Space Returns 404
+**Cause:** Space is still building or failed to start
+**Solution:**
+1. Check build logs at https://huggingface.co/spaces/ocx2025/basicsearch/logs
+2. Wait for build to complete (can take 5-10 minutes)
+3. Look for error messages in logs
+
+### API Key Error
+**Cause:** `YOUTUBE_API_KEY` not set or invalid
+**Solution:**
+1. Go to https://huggingface.co/spaces/ocx2025/basicsearch/settings
+2. Click "Repository secrets"
+3. Add secret: Name=`YOUTUBE_API_KEY`, Value=`your_actual_key`
+4. Restart the Space
+
+### Build Timeout
+**Cause:** Docker build taking too long
+**Solution:**
+1. Check Dockerfile for optimization opportunities
+2. Verify all dependencies are necessary
+3. Consider using a lighter base image
+
+### Connection Timeout
+**Cause:** Space is sleeping (free tier) or overloaded
+**Solution:**
+1. Visit the Space page to wake it up
+2. Wait a few seconds and retry
+3. Check Space status
+
+### Rate Limiting
+**Cause:** Too many requests to YouTube API
+**Solution:**
+1. Check your Google Cloud Console quota
+2. Default is 10,000 units/day
+3. Each search costs ~100 units
+
+## Monitoring
+
+### Real-time Logs
+```bash
+# Using curl to monitor health
+watch -n 5 'curl -s https://ocx2025-basicsearch.hf.space/health'
+```
+
+### Check Space Status
+```bash
+# Simple status check
+curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" \
+  https://ocx2025-basicsearch.hf.space/health
+```
+
+### Continuous Testing
+```bash
+# Run tests every minute
+while true; do
+  echo "Testing at $(date)"
+  python test_deployment.py
+  sleep 60
+done
+```
+
+## Performance Testing
+
+### Load Test with Apache Bench
+```bash
+# Test 100 requests with 10 concurrent connections
+ab -n 100 -c 10 https://ocx2025-basicsearch.hf.space/health
+```
+
+### Load Test with Python
+```python
+import time
+import requests
+from concurrent.futures import ThreadPoolExecutor
+
+def test_endpoint():
+    start = time.time()
+    response = requests.get("https://ocx2025-basicsearch.hf.space/health")
+    end = time.time()
+    return response.status_code, end - start
+
+# Run 50 concurrent requests
+with ThreadPoolExecutor(max_workers=10) as executor:
+    results = list(executor.map(lambda _: test_endpoint(), range(50)))
+
+successful = sum(1 for status, _ in results if status == 200)
+avg_time = sum(t for _, t in results) / len(results)
+
+print(f"Successful: {successful}/50")
+print(f"Average response time: {avg_time:.3f}s")
+```
+
+## Expected Response Times
+
+| Endpoint | Expected Time |
+|----------|--------------|
+| `/health` | < 100ms |
+| `/` | < 100ms |
+| `/tools` | < 100ms |
+| `/search` | 500ms - 2s (depends on YouTube API) |
+
+## Security Testing
+
+### Test Invalid Input
+```bash
+# Test with missing query
+curl -X POST https://ocx2025-basicsearch.hf.space/search \
+  -H "Content-Type: application/json" \
+  -d '{}'
+
+# Test with invalid JSON
+curl -X POST https://ocx2025-basicsearch.hf.space/search \
+  -H "Content-Type: application/json" \
+  -d 'invalid json'
+
+# Test with excessive max_results
+curl -X POST https://ocx2025-basicsearch.hf.space/search \
+  -H "Content-Type: application/json" \
+  -d '{"query": "test", "max_results": 1000}'
+```
+
+## Integration Testing
+
+### Test in Claude Desktop
+
+If using with Claude Desktop, add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "basicsearch": {
+      "url": "https://ocx2025-basicsearch.hf.space"
+    }
+  }
+}
+```
+
+### Test with Python SDK
+
+```python
+from mcp import ClientSession
+from mcp.client.stdio import stdio_client
+
+# Connect to your MCP server
+async with stdio_client() as (read, write):
+    async with ClientSession(read, write) as session:
+        # Initialize
+        await session.initialize()
+        
+        # Call search tool
+        result = await session.call_tool(
+            "search_youtube_videos",
+            arguments={"query": "Python", "max_results": 3}
+        )
+        print(result)
+```
+
+## Next Steps
+
+1. ✅ Run automated test script: `python test_deployment.py`
+2. ✅ Check build logs if tests fail
+3. ✅ Set YOUTUBE_API_KEY if not already set
+4. ✅ Monitor Space status
+5. ✅ Test all endpoints manually
+6. ✅ Perform load testing if needed
+7. ✅ Integrate with your applications
+
+## Useful Links
+
+- **Your Space:** https://huggingface.co/spaces/ocx2025/basicsearch
+- **Logs:** https://huggingface.co/spaces/ocx2025/basicsearch/logs
+- **Settings:** https://huggingface.co/spaces/ocx2025/basicsearch/settings
+- **HF Spaces Docs:** https://huggingface.co/docs/hub/spaces
+- **YouTube API Console:** https://console.cloud.google.com/apis/dashboard
+

gradio_ui.py

@@ -0,0 +1,70 @@
+"""
+Optional Gradio UI for the MCP server.
+This can run alongside the FastAPI server for visual testing.
+"""
+import gradio as gr
+from server import search_youtube_videos
+import json
+
+def search_interface(query: str, max_results: int = 5):
+    """Gradio interface for YouTube search"""
+    if not query:
+        return {"error": "Please enter a search query"}
+    
+    try:
+        results = search_youtube_videos(query, int(max_results))
+        return {
+            "success": True,
+            "count": len(results),
+            "results": results
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e)
+        }
+
+# Create Gradio interface
+with gr.Blocks(title="YouTube Search MCP Server") as demo:
+    gr.Markdown("# 🔍 YouTube Search MCP Server")
+    gr.Markdown("Test the YouTube search functionality with a visual interface.")
+    
+    with gr.Row():
+        with gr.Column():
+            query_input = gr.Textbox(
+                label="Search Query",
+                placeholder="Enter search term (e.g., 'Python tutorial')",
+                lines=1
+            )
+            max_results = gr.Slider(
+                minimum=1,
+                maximum=10,
+                value=5,
+                step=1,
+                label="Maximum Results"
+            )
+            search_btn = gr.Button("🔍 Search", variant="primary")
+        
+        with gr.Column():
+            output = gr.JSON(label="Search Results")
+    
+    # Examples
+    gr.Examples(
+        examples=[
+            ["Python programming tutorial", 5],
+            ["Machine learning basics", 3],
+            ["FastAPI tutorial", 5],
+        ],
+        inputs=[query_input, max_results],
+    )
+    
+    # Connect button
+    search_btn.click(
+        fn=search_interface,
+        inputs=[query_input, max_results],
+        outputs=output
+    )
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)
+

pyproject.toml

@@ -8,6 +8,7 @@ dependencies = [
     "fastapi>=0.115.0",
     "fastmcp>=2.12.4",
     "google-api-python-client>=2.184.0",
+    "gradio>=5.49.1",
     "mcp[cli]>=1.16.0",
     "python-dotenv>=1.1.1",
     "requests>=2.32.0",

test_deployment.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+Python test script for Hugging Face Space deployment
+Usage: python test_deployment.py [space-url]
+"""
+
+import sys
+import requests
+import json
+from typing import Dict, Any
+
+# ANSI color codes
+GREEN = '\033[0;32m'
+RED = '\033[0;31m'
+YELLOW = '\033[1;33m'
+BLUE = '\033[0;34m'
+NC = '\033[0m'  # No Color
+
+
+def print_test(test_name: str):
+    """Print test header"""
+    print(f"\n{YELLOW}{test_name}{NC}")
+
+
+def print_result(passed: bool, message: str, response: Any = None):
+    """Print test result"""
+    status = f"{GREEN}✓ PASSED{NC}" if passed else f"{RED}✗ FAILED{NC}"
+    print(f"{status} - {message}")
+    if response:
+        try:
+            print(f"Response: {json.dumps(response, indent=2)}")
+        except:
+            print(f"Response: {response}")
+
+
+def test_health(base_url: str) -> bool:
+    """Test health endpoint"""
+    print_test("Test 1: Health Check")
+    print(f"GET {base_url}/health")
+    
+    try:
+        response = requests.get(f"{base_url}/health", timeout=10)
+        passed = response.status_code == 200
+        print_result(
+            passed,
+            f"Status: {response.status_code}",
+            response.json() if passed else response.text
+        )
+        return passed
+    except Exception as e:
+        print_result(False, f"Error: {str(e)}")
+        return False
+
+
+def test_service_info(base_url: str) -> bool:
+    """Test root endpoint"""
+    print_test("Test 2: Service Info")
+    print(f"GET {base_url}/")
+    
+    try:
+        response = requests.get(f"{base_url}/", timeout=10)
+        passed = response.status_code == 200
+        print_result(
+            passed,
+            f"Status: {response.status_code}",
+            response.json() if passed else response.text
+        )
+        return passed
+    except Exception as e:
+        print_result(False, f"Error: {str(e)}")
+        return False
+
+
+def test_list_tools(base_url: str) -> bool:
+    """Test tools listing endpoint"""
+    print_test("Test 3: List Available Tools")
+    print(f"GET {base_url}/tools")
+    
+    try:
+        response = requests.get(f"{base_url}/tools", timeout=10)
+        passed = response.status_code == 200
+        print_result(
+            passed,
+            f"Status: {response.status_code}",
+            response.json() if passed else response.text
+        )
+        return passed
+    except Exception as e:
+        print_result(False, f"Error: {str(e)}")
+        return False
+
+
+def test_youtube_search(base_url: str) -> bool:
+    """Test YouTube search endpoint"""
+    print_test("Test 4: YouTube Video Search")
+    print(f"POST {base_url}/search")
+    
+    payload = {
+        "query": "Python programming",
+        "max_results": 2
+    }
+    
+    try:
+        response = requests.post(
+            f"{base_url}/search",
+            json=payload,
+            timeout=15
+        )
+        
+        if response.status_code == 200:
+            print_result(True, f"Status: {response.status_code}", response.json())
+            return True
+        elif response.status_code == 500 and "YOUTUBE_API_KEY" in response.text:
+            print(f"{YELLOW}⚠ API KEY NOT SET{NC} - Status: {response.status_code}")
+            print("Please set YOUTUBE_API_KEY in your Space settings")
+            print(f"Response: {response.json()}")
+            return False
+        else:
+            print_result(False, f"Status: {response.status_code}", response.text)
+            return False
+    except Exception as e:
+        print_result(False, f"Error: {str(e)}")
+        return False
+
+
+def test_error_handling(base_url: str) -> bool:
+    """Test error handling with missing query"""
+    print_test("Test 5: Error Handling (Missing Query)")
+    print(f"POST {base_url}/search (with empty query)")
+    
+    payload = {}
+    
+    try:
+        response = requests.post(
+            f"{base_url}/search",
+            json=payload,
+            timeout=10
+        )
+        
+        # We expect a 400 error
+        passed = response.status_code == 400
+        print_result(
+            passed,
+            f"Status: {response.status_code} (Expected 400 error)",
+            response.json() if response.status_code == 400 else response.text
+        )
+        return passed
+    except Exception as e:
+        print_result(False, f"Error: {str(e)}")
+        return False
+
+
+def main():
+    """Run all tests"""
+    # Get Space URL from command line or use default
+    base_url = sys.argv[1] if len(sys.argv) > 1 else "https://ocx2025-basicsearch.hf.space"
+    
+    # Remove trailing slash if present
+    base_url = base_url.rstrip('/')
+    
+    print("=" * 50)
+    print(f"Testing Hugging Face Space: {base_url}")
+    print("=" * 50)
+    
+    # Run all tests
+    results = []
+    results.append(("Health Check", test_health(base_url)))
+    results.append(("Service Info", test_service_info(base_url)))
+    results.append(("List Tools", test_list_tools(base_url)))
+    results.append(("YouTube Search", test_youtube_search(base_url)))
+    results.append(("Error Handling", test_error_handling(base_url)))
+    
+    # Print summary
+    print("\n" + "=" * 50)
+    print("Test Summary")
+    print("=" * 50)
+    
+    passed = sum(1 for _, result in results if result)
+    total = len(results)
+    
+    for test_name, result in results:
+        status = f"{GREEN}✓{NC}" if result else f"{RED}✗{NC}"
+        print(f"{status} {test_name}")
+    
+    print(f"\n{BLUE}Results: {passed}/{total} tests passed{NC}")
+    print("=" * 50)
+    
+    # Exit with appropriate code
+    sys.exit(0 if passed == total else 1)
+
+
+if __name__ == "__main__":
+    main()
+

test_deployment.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+
+# Test script for Hugging Face Space deployment
+# Usage: ./test_deployment.sh [space-url]
+
+# Color codes for output
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Default URL (update with your actual Space URL)
+SPACE_URL="${1:-https://ocx2025-basicsearch.hf.space}"
+
+echo "================================================"
+echo "Testing Hugging Face Space: $SPACE_URL"
+echo "================================================"
+echo ""
+
+# Test 1: Health Check
+echo -e "${YELLOW}Test 1: Health Check${NC}"
+echo "GET $SPACE_URL/health"
+RESPONSE=$(curl -s -w "\n%{http_code}" "$SPACE_URL/health")
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY=$(echo "$RESPONSE" | head -n-1)
+
+if [ "$HTTP_CODE" = "200" ]; then
+    echo -e "${GREEN}✓ PASSED${NC} - Status: $HTTP_CODE"
+    echo "Response: $BODY"
+else
+    echo -e "${RED}✗ FAILED${NC} - Status: $HTTP_CODE"
+    echo "Response: $BODY"
+fi
+echo ""
+
+# Test 2: Service Info
+echo -e "${YELLOW}Test 2: Service Info${NC}"
+echo "GET $SPACE_URL/"
+RESPONSE=$(curl -s -w "\n%{http_code}" "$SPACE_URL/")
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY=$(echo "$RESPONSE" | head -n-1)
+
+if [ "$HTTP_CODE" = "200" ]; then
+    echo -e "${GREEN}✓ PASSED${NC} - Status: $HTTP_CODE"
+    echo "Response: $BODY" | jq '.' 2>/dev/null || echo "Response: $BODY"
+else
+    echo -e "${RED}✗ FAILED${NC} - Status: $HTTP_CODE"
+    echo "Response: $BODY"
+fi
+echo ""
+
+# Test 3: List Tools
+echo -e "${YELLOW}Test 3: List Available Tools${NC}"
+echo "GET $SPACE_URL/tools"
+RESPONSE=$(curl -s -w "\n%{http_code}" "$SPACE_URL/tools")
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY=$(echo "$RESPONSE" | head -n-1)
+
+if [ "$HTTP_CODE" = "200" ]; then
+    echo -e "${GREEN}✓ PASSED${NC} - Status: $HTTP_CODE"
+    echo "Response: $BODY" | jq '.' 2>/dev/null || echo "Response: $BODY"
+else
+    echo -e "${RED}✗ FAILED${NC} - Status: $HTTP_CODE"
+    echo "Response: $BODY"
+fi
+echo ""
+
+# Test 4: YouTube Search (requires API key to be set)
+echo -e "${YELLOW}Test 4: YouTube Video Search${NC}"
+echo "POST $SPACE_URL/search"
+RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$SPACE_URL/search" \
+    -H "Content-Type: application/json" \
+    -d '{"query": "Python programming", "max_results": 2}')
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY=$(echo "$RESPONSE" | head -n-1)
+
+if [ "$HTTP_CODE" = "200" ]; then
+    echo -e "${GREEN}✓ PASSED${NC} - Status: $HTTP_CODE"
+    echo "Response: $BODY" | jq '.' 2>/dev/null || echo "Response: $BODY"
+elif [ "$HTTP_CODE" = "500" ] && echo "$BODY" | grep -q "YOUTUBE_API_KEY"; then
+    echo -e "${YELLOW}⚠ API KEY NOT SET${NC} - Status: $HTTP_CODE"
+    echo "Please set YOUTUBE_API_KEY in your Space settings"
+    echo "Response: $BODY"
+else
+    echo -e "${RED}✗ FAILED${NC} - Status: $HTTP_CODE"
+    echo "Response: $BODY"
+fi
+echo ""
+
+# Test 5: Error handling - missing query
+echo -e "${YELLOW}Test 5: Error Handling (Missing Query)${NC}"
+echo "POST $SPACE_URL/search (with empty query)"
+RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$SPACE_URL/search" \
+    -H "Content-Type: application/json" \
+    -d '{}')
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY=$(echo "$RESPONSE" | head -n-1)
+
+if [ "$HTTP_CODE" = "400" ]; then
+    echo -e "${GREEN}✓ PASSED${NC} - Status: $HTTP_CODE (Expected error)"
+    echo "Response: $BODY"
+else
+    echo -e "${YELLOW}⚠ UNEXPECTED${NC} - Status: $HTTP_CODE"
+    echo "Response: $BODY"
+fi
+echo ""
+
+echo "================================================"
+echo "Testing Complete!"
+echo "================================================"
+

test_private_space.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""
+Test script for PRIVATE Hugging Face Spaces with authentication.
+Usage: uv run python test_private_space.py [space-url] [hf-token]
+"""
+
+import sys
+import requests
+import json
+import os
+
+# ANSI color codes
+GREEN = '\033[0;32m'
+RED = '\033[0;31m'
+YELLOW = '\033[1;33m'
+BLUE = '\033[0;34m'
+NC = '\033[0m'  # No Color
+
+
+def get_headers(token: str = None) -> dict:
+    """Get headers with authentication if token provided"""
+    headers = {"Content-Type": "application/json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def test_with_auth(base_url: str, token: str = None):
+    """Test space with optional authentication"""
+    print("=" * 50)
+    print(f"Testing Space: {base_url}")
+    if token:
+        print(f"Using token: {token[:10]}...{token[-5:]}")
+    else:
+        print("No token provided (testing public access)")
+    print("=" * 50)
+    print()
+
+    headers = get_headers(token)
+
+    # Test health endpoint
+    print(f"{YELLOW}Test: Health Check{NC}")
+    try:
+        response = requests.get(f"{base_url}/health", headers=headers, timeout=10)
+        
+        if response.status_code == 200:
+            print(f"{GREEN}✓ SUCCESS{NC} - Space is accessible!")
+            print(f"Response: {response.json()}")
+            return True
+        elif response.status_code == 404:
+            print(f"{RED}✗ 404 ERROR{NC}")
+            print(f"\n{YELLOW}Possible reasons:{NC}")
+            print("1. Space is PRIVATE and needs authentication token")
+            print("2. Space is still building")
+            print("3. Space build failed")
+            print("\nTo fix:")
+            print("• Make space public in settings, OR")
+            print("• Use: uv run python test_private_space.py [url] [your-hf-token]")
+            return False
+        elif response.status_code == 401:
+            print(f"{RED}✗ 401 UNAUTHORIZED{NC}")
+            print("Space is PRIVATE. You need a valid Hugging Face token.")
+            print("\nGet your token:")
+            print("1. Go to https://huggingface.co/settings/tokens")
+            print("2. Create a new token with 'read' permissions")
+            print("3. Run: uv run python test_private_space.py [url] [token]")
+            return False
+        else:
+            print(f"{RED}✗ ERROR{NC} - Status: {response.status_code}")
+            print(f"Response: {response.text[:200]}")
+            return False
+    except Exception as e:
+        print(f"{RED}✗ ERROR{NC} - {str(e)}")
+        return False
+
+
+def main():
+    # Get space URL and token
+    base_url = sys.argv[1] if len(sys.argv) > 1 else "https://ocx2025-basicsearch.hf.space"
+    token = sys.argv[2] if len(sys.argv) > 2 else os.getenv("HF_TOKEN")
+    
+    # Remove trailing slash
+    base_url = base_url.rstrip('/')
+    
+    # Test
+    success = test_with_auth(base_url, token)
+    
+    if success:
+        print(f"\n{GREEN}✅ Space is working!{NC}")
+        print(f"You can now run the full test suite:")
+        if token:
+            print(f"HF_TOKEN={token} uv run python test_deployment.py")
+        else:
+            print("uv run python test_deployment.py")
+    else:
+        print(f"\n{YELLOW}📝 Next Steps:{NC}")
+        print("\n1. Check if space is private:")
+        print(f"   Visit: {base_url.replace('.hf.space', '').replace('https://', 'https://huggingface.co/spaces/').replace('-', '/', 1)}")
+        print("\n2. Make it PUBLIC:")
+        print("   Settings → Make public")
+        print("\n3. OR get your HF token:")
+        print("   https://huggingface.co/settings/tokens")
+        print(f"   Then run: uv run python test_private_space.py {base_url} YOUR_TOKEN")
+
+
+if __name__ == "__main__":
+    main()
+