mcp-servers/mcp-gateway/gateway-proxy/INTEGRATION_INSTRUCTIONS.md

# 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).