docs/HF_SPACES_FAQ.md

# HF Spaces Deployment FAQ & Customization

## Frequently Asked Questions

### Q: How do I update the app after deploying?

**A:** Push changes to the Space git repo:
```bash
cd <your-hf-space-directory>
# Make changes to files
git add .
git commit -m "Update: describe changes"
git push origin main
```
Spaces auto-redeploys within 1-2 minutes.

### Q: Can I keep the Space private?

**A:** Yes. In **Space Settings**, toggle **"Private"** to restrict access to collaborators only.

### Q: Will my Space go to sleep?

**A:** Free Spaces don't have persistent servers—they spin up on-demand. Fine for this app. For 24/7 availability, upgrade to a paid compute tier.

### Q: How do I add collaborators?

**A:** In **Space Settings**, add other HF users as collaborators. They can push changes.

### Q: Can I access the MCP endpoint from Claude Desktop?

**A:** Yes. Use `https://<your-username>-weather-server.hf.space/gradio_api/mcp/` in your `claude_desktop_config.json`. See deployment guide for details.

### Q: What if I get API rate limit errors?

**A:** Open-Meteo allows ~10,000 requests/day. If you hit limits, wait a few minutes. Check [Open-Meteo docs](https://open-meteo.com/en/docs) for exact limits.

### Q: How do I disable MCP and just use the web UI?

**A:** MCP is enabled by default but doesn't interfere with the web UI. To disable, edit `mcp_open_meteo/gradio_app.py` and remove `@gr.mcp` decorators and resource/prompt definitions. (Easier to leave enabled.)

### Q: Can I host this on my own server instead?

**A:** Yes. See `CLAUDE.md` for instructions to run locally with `uv run gradio-weather` or `uv run mcp-open-meteo`.

### Q: How do I check deployment logs?

**A:** Go to your Space URL → click **"Logs"** tab on the right. Filter by "Build" or "Runtime".

### Q: What's the difference between this and the FastMCP server?

**A:** This Gradio app combines a web UI + MCP server. FastMCP is CLI-only. For Spaces, use the Gradio app (what we're deploying).

### Q: Can I delete my Space later?

**A:** Yes. Go to **Space Settings** → scroll to bottom → **"Delete this Space"**. ⚠️ **Irreversible!**

---

## Customization Guide

### Change App Title and Icon

Edit `mcp_open_meteo/gradio_app.py` around line 624:

```python
with gr.Blocks(title="🌤️ My Weather Dashboard") as demo:
    gr.Markdown("# 🌤️ My Custom Weather App")
```

### Change App Theme

In `app.py`, modify the Gradio theme:

```python
# Options: Soft, Ocean, Base, Glass, Monochrome, Dark
from mcp_open_meteo.gradio_app import create_gradio_app

app = create_gradio_app()

# In gradio_app.py, change the .launch() call:
demo.launch(mcp_server=True, theme=gr.themes.Dark())
```

### Change Default Location Search

Edit `mcp_open_meteo/gradio_app.py` in the Search Locations tab:

```python
location_input = gr.Textbox(
    label="Location",
    value="Tokyo",  # Change this default
    placeholder="Enter city name..."
)
```

### Add Custom CSS Styling

In `mcp_open_meteo/gradio_app.py` (in `create_gradio_app()`):

```python
with gr.Blocks(
    title="...",
    css="""
    body { font-family: 'Courier New', monospace; }
    h1 { color: #0066cc; }
    .tab-content { background-color: #f9f9f9; }
    """
) as demo:
```

### Change Forecast Days

Edit `mcp_open_meteo/config.py`:

```python
MAX_FORECAST_DAYS = 3  # Default is 7
```

### Add More Weather Parameters

Edit `mcp_open_meteo/api_client.py` in the `get_weather_data()` function:

```python
current_params = [
    "temperature_2m", "relative_humidity_2m", "weather_code",
    "uv_index",       # Add these new parameters
    "visibility",
    "soil_moisture_0_1cm"
]
```

Then use them in the UI by updating the display in `gradio_app.py`.

### Hide the "About MCP" Tab

In `mcp_open_meteo/gradio_app.py`, comment out the MCP tab section (around line 740):

```python
# with gr.Tab("ℹ️ About MCP"):
#     gr.Markdown("...")
```

### Add a Custom Header/Logo

Add to the top of the Gradio app:

```python
gr.Markdown("[![Badge](https://img.shields.io/badge/Built%20with-Gradio-blue)](https://gradio.app)")
gr.Image("path/to/logo.png", scale=0.5)
```

---

## Performance Optimization

### Cache API Responses

To avoid repeated API calls, add caching to `mcp_open_meteo/api_client.py`:

```python
import functools
from datetime import datetime, timedelta

@functools.lru_cache(maxsize=128)
async def get_weather_data_cached(lat: float, lon: float):
    """Cached for up to 128 unique requests"""
    return await get_weather_data(lat, lon)
```

### Reduce API Load

In `mcp_open_meteo/config.py`:

```python
MAX_FORECAST_DAYS = 3   # Reduced from 7
MAX_FORECAST_HOURS = 12 # Reduced from 24
```

---

## Monitoring and Debugging

### Check App Logs

In your Space, click **Logs** (right sidebar):
- **Build logs**: Dependency installation, startup errors
- **Runtime logs**: Request logs, exceptions during execution

### Test MCP Endpoint

From command line:

```bash
curl -X GET https://<your-username>-weather-server.hf.space/gradio_api/mcp/
```

Should return MCP server information.

### Enable Debug Mode

In `app.py`:

```python
import logging
logging.basicConfig(level=logging.DEBUG)
app = create_gradio_app()
```

### Monitor Resource Usage

HF Spaces dashboard shows CPU, memory, and network usage. Weather app should stay well under limits (2 CPU, 16GB RAM).

---

## Updating Dependencies

### When to Update

- Security patches for critical vulnerabilities
- New features in Gradio or MCP
- Bug fixes in httpx or pydantic

### How to Update

1. Update `requirements.txt`:
```txt
gradio>=4.2.0
httpx>=0.30.0
pydantic>=2.12.0
mcp[cli]>=1.12.0
```

2. Test locally:
```bash
uv sync  # or pip install -r requirements.txt
uv run gradio-weather
```

3. Commit and push:
```bash
git add requirements.txt
git commit -m "Update: dependencies"
git push origin main
```

---

## Useful Gradio Settings

### Disable the Mobile Theme
```python
demo.launch(mcp_server=True, theme=gr.themes.Soft(), show_error=True)
```

### Add Custom Footer
```python
gr.Markdown("---\n*Powered by [Open-Meteo](https://open-meteo.com) • Built with [Gradio](https://gradio.app)*")
```

### Enable Share Link
```python
demo.launch(mcp_server=True, share=True)
# Generates a public temporary link
```

---

## Collaboration

### Add Collaborators

In Space **Settings**, invite other HF users. They can:
- Push changes
- View logs
- Manage settings

### Use Git Branches

```bash
git checkout -b feature/new-tab
# Make changes, commit, push
git push origin feature/new-tab
# Test before merging to main
git checkout main
git merge feature/new-tab
git push origin main
```

---

## Cleanup & Maintenance

### Pause the Space (Temporary)

In **Space Settings**, click **"Pause this Space"** to stop. No usage = no resource costs.

### Delete the Space

In **Space Settings** → scroll to bottom → **"Delete this Space"**

⚠️ **Warning**: Irreversible! All code and history deleted.

---

## Support & Resources

| Resource | Link |
|----------|------|
| HF Spaces Documentation | https://huggingface.co/docs/hub/spaces |
| Spaces Troubleshooting | https://huggingface.co/docs/hub/spaces-troubleshoot |
| Gradio Guides | https://www.gradio.app/guides |
| Open-Meteo API | https://open-meteo.com/en/docs |
| MCP Specification | https://modelcontextprotocol.io/ |

---

**Need help?** Check the main deployment guide or the troubleshooting section in `PUBLISH_TO_HF_SPACES.md`.