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:

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 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:

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:

# 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:

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()):

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:

MAX_FORECAST_DAYS = 3  # Default is 7

Add More Weather Parameters

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

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):

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

Add a Custom Header/Logo

Add to the top of the Gradio app:

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:

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:

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:

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

Should return MCP server information.

Enable Debug Mode

In app.py:

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:

gradio>=4.2.0
httpx>=0.30.0
pydantic>=2.12.0
mcp[cli]>=1.12.0

2. Test locally:

uv sync  # or pip install -r requirements.txt
uv run gradio-weather

3. Commit and push:

git add requirements.txt
git commit -m "Update: dependencies"
git push origin main

---

Useful Gradio Settings

Disable the Mobile Theme

demo.launch(mcp_server=True, theme=gr.themes.Soft(), show_error=True)

Add Custom Footer

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

Enable Share Link

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

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.