Add gateway-proxy/INTEGRATION_INSTRUCTIONS.md

gateway-proxy/INTEGRATION_INSTRUCTIONS.md

@@ -0,0 +1,164 @@
+# Dashboard Integration into gateway_proxy.py
+
+## Quick Integration Guide
+
+### Step 1: Add Imports at Top of gateway_proxy.py
+
+```python
+import asyncio
+from dashboard_routes import setup_dashboard_routes
+from fastapi.staticfiles import StaticFiles
+```
+
+### Step 2: Mount Static Files (After app creation)
+
+Find where the FastAPI app is created (likely `app = FastAPI(...)`) and add after it:
+
+```python
+# Setup static file serving for dashboard
+try:
+    app.mount("/", StaticFiles(directory="dashboard", html=True), name="static")
+except Exception as e:
+    print(f"Warning: Could not mount dashboard static files: {e}")
+```
+
+### Step 3: Register Dashboard Routes (In app startup/initialization)
+
+In the startup event or app initialization section, add:
+
+```python
+@app.on_event("startup")
+async def startup_event():
+    # ... existing startup code ...
+
+    # Setup dashboard routes
+    try:
+        dashboard_router = await setup_dashboard_routes(app)
+        app.include_router(dashboard_router)
+        print("✓ Dashboard routes registered")
+    except Exception as e:
+        print(f"Warning: Could not setup dashboard routes: {e}")
+```
+
+### Step 4: Update Dockerfile
+
+In `gateway-proxy/Dockerfile`, add a line to copy the dashboard:
+
+```dockerfile
+# ... existing COPY commands ...
+
+# Copy dashboard
+COPY dashboard/ /app/dashboard/
+```
+
+### Step 5: Verify dashboard_routes.py Dependencies
+
+Make sure `dashboard_routes.py` has these imports available in your environment.
+
+Required packages:
+- `aiohttp` (likely already installed for MCP communication)
+- `asyncio` (builtin)
+- `fastapi` (already in use)
+
+## Complete Example Integration
+
+Here's what a minimal integration looks like:
+
+```python
+# gateway_proxy.py
+
+import asyncio
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from dashboard_routes import setup_dashboard_routes
+
+# Create app
+app = FastAPI(title="MCP Gateway")
+
+# Mount dashboard
+app.mount("/", StaticFiles(directory="dashboard", html=True), name="dashboard")
+
+@app.on_event("startup")
+async def startup():
+    dashboard_router = await setup_dashboard_routes(app)
+    app.include_router(dashboard_router)
+    print("Dashboard ready at /dashboard")
+
+# ... rest of your routes ...
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=4444)
+```
+
+## Testing After Integration
+
+1. **Rebuild the gateway image:**
+   ```bash
+   docker compose build mcp-gateway
+   ```
+
+2. **Restart the gateway:**
+   ```bash
+   docker compose up mcp-gateway
+   ```
+
+3. **Access the dashboard:**
+   - Local: `http://localhost:4444/dashboard`
+   - Remote: `https://mcp.wilddragon.net/dashboard`
+
+4. **Test the API endpoint:**
+   ```bash
+   curl http://localhost:4444/mcp/status | jq
+   ```
+
+## Troubleshooting Integration
+
+### Module Not Found: dashboard_routes
+- Ensure `dashboard_routes.py` is in the same directory as `gateway_proxy.py`
+- Check Python path is correct
+
+### Dashboard Returns 404
+- Verify `dashboard/` folder exists in the gateway root
+- Check `dashboard.html` file exists
+- Review Dockerfile to ensure it copies the dashboard
+
+### Routes Not Registered
+- Check startup event is being called
+- Review application logs
+- Verify no errors in dashboard_routes.py
+
+### CSS/TailwindCSS Not Loading
+- This is expected since TailwindCSS is loaded via CDN in the HTML
+- Check browser console for any fetch errors
+- Verify network connectivity to cdn.tailwindcss.com
+
+## File Structure After Integration
+
+```
+mcp-gateway/
+├── gateway-proxy/
+│   ├── gateway_proxy.py          (MODIFIED - add imports & routes)
+│   ├── dashboard_routes.py       (NEW)
+│   ├── Dockerfile                (MODIFIED - add COPY dashboard)
+│   └── ...
+├── dashboard/
+│   └── dashboard.html            (NEW)
+├── docker-compose.yml
+└── ...
+```
+
+## Performance Considerations
+
+- Dashboard queries all services on each status check
+- Default refresh interval: 30 seconds
+- Each check times out after 5 seconds per service
+- Status queries run in parallel (async)
+- No caching of results (fresh data each time)
+
+To adjust refresh interval, edit `dashboard/dashboard.html` and find:
+```javascript
+const interval = setInterval(fetchServiceStatus, 30000);  // 30 seconds
+```
+
+Change `30000` to desired milliseconds (e.g., `15000` for 15 seconds).