PRIVATE_SPACE_GUIDE.md

# 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! 🚀