feat: Add Hugging Face Spaces deployment

- app.py: Entry point for Hugging Face Spaces
- src/http_server.py: HTTP server wrapper with uvicorn
- Dockerfile: Container config for HF Spaces deployment
- requirements.txt: Python dependencies for deployment
- README_HF.md: Hugging Face Spaces metadata
- .dockerignore: Exclude unnecessary files from Docker build
- Updated README.md with deployment instructions

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

.dockerignore

@@ -0,0 +1,16 @@
+.git
+.gitignore
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+demo/
+tests/
+*.md
+!README_HF.md
+piv_quiver.png
+*.egg-info
+dist/
+build/

Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.14-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY src/ ./src/
+COPY app.py .
+
+# Expose the port Hugging Face expects
+EXPOSE 7860
+
+# Set environment variables
+ENV HOST=0.0.0.0
+ENV PORT=7860
+
+# Run the application
+CMD ["python", "app.py"]

README.md

@@ -139,6 +139,52 @@ Summary Statistics:
 | pandas | >=3.0.1 |
 | matplotlib | (auto-installed) |
 
+## Deployment
+
+### Hugging Face Spaces (Free)
+
+Deploy to Hugging Face Spaces for free HTTP access:
+
+1. **Create a new Space** at https://huggingface.co/spaces
+   - Click "Create new Space"
+   - Name: `openpiv-mcp`
+   - License: MIT
+   - Select **Docker** SDK
+
+2. **Connect your GitHub repo**
+   - In your Space settings, enable "Link to GitHub repository"
+   - Select `openpiv/openpiv-mcp`
+
+3. **Configure the Space**
+   - Copy `README_HF.md` content to your Space's README.md (HF metadata)
+   - The Dockerfile will build automatically
+
+4. **Connect MCP client**
+   - Once deployed, your endpoint will be: `https://<username>-openpiv-mcp.hf.space`
+   - Configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "openpiv": {
+      "url": "https://<username>-openpiv-mcp.hf.space/mcp"
+    }
+  }
+}
+```
+
+**Note:** Free Spaces sleep after 15 minutes of inactivity. First request after sleep has ~30s cold start.
+
+### Local HTTP Server
+
+Run the server with HTTP transport locally:
+
+```bash
+uv run python src/http_server.py
+```
+
+Connect to `http://localhost:8000/mcp`
+
 ## License
 
 MIT License - see LICENSE file for details.

README_HF.md

@@ -0,0 +1,14 @@
+title: OpenPIV MCP Server
+emoji: 🌊
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: mit
+
+# Hardware configuration
+hardware: cpu-basic
+
+# Scale to zero when idle (saves resources)
+# Note: First request after idle period will have cold start delay
+scale_to_zero_timeout: 15

app.py

@@ -0,0 +1,36 @@
+"""
+Hugging Face Spaces entry point for OpenPIV MCP Server.
+
+This app runs the MCP server with HTTP transport on Hugging Face Spaces.
+The server exposes PIV analysis tools via HTTP.
+
+API Endpoint:
+    /mcp - MCP HTTP endpoint (streamable HTTP)
+
+Usage with MCP client:
+    Configure your MCP client to connect to:
+    https://<your-space>.hf.space/mcp
+"""
+
+import os
+import logging
+import uvicorn
+from openpiv_mcp import mcp
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Get configuration from environment
+HOST = os.environ.get("HOST", "0.0.0.0")
+PORT = int(os.environ.get("PORT", 7860))
+
+# Create the ASGI app for HTTP transport
+app = mcp.streamable_http_app()
+
+if __name__ == "__main__":
+    logger.info(f"Starting OpenPIV MCP Server on {HOST}:{PORT}")
+    logger.info("MCP endpoint: /mcp")
+    
+    # Run with uvicorn
+    uvicorn.run(app, host=HOST, port=PORT)

requirements.txt

@@ -0,0 +1,7 @@
+mcp>=1.26.0
+openpiv>=0.25.1
+numpy>=2.4.3
+pandas>=3.0.1
+matplotlib>=3.9.0
+setuptools>=82.0.1
+uvicorn>=0.30.0

src/http_server.py

@@ -0,0 +1,29 @@
+"""
+HTTP Server wrapper for OpenPIV MCP Server.
+
+This module provides an HTTP endpoint for the OpenPIV MCP server,
+enabling remote clients to connect via HTTP instead of stdio.
+
+Usage:
+    uv run python src/http_server.py
+    
+Or on Hugging Face Spaces, it runs automatically via app.py
+"""
+
+import os
+import uvicorn
+from openpiv_mcp import mcp
+
+# Get host/port from environment (for Hugging Face Spaces)
+HOST = os.environ.get("HOST", "0.0.0.0")
+PORT = int(os.environ.get("PORT", 8000))
+
+# Create the ASGI app for HTTP transport
+app = mcp.streamable_http_app()
+
+if __name__ == "__main__":
+    print(f"Starting OpenPIV MCP Server on {HOST}:{PORT}")
+    print("Endpoint: http://{HOST}:{PORT}/mcp")
+    
+    # Run with uvicorn
+    uvicorn.run(app, host=HOST, port=PORT)