# Chat UI

> White-label AI chat interface built on HuggingFace Chat UI with OIDC auth, MCP tool integration, and branded assets

- Skill: `jrennie99-glitch/chat-ui` (Agent Skill)
- Install (CLI): `npx skillmds add jrennie99-glitch/chat-ui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jrennie99-glitch/chat-ui/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jrennie99-glitch (https://skillmd.com/u/jrennie99-glitch)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/jrennie99-glitch/chat-ui

---


# Chat UI — White-Label AI Chat Interface

Containerized AI chat interface based on HuggingFace Chat UI, configured for white-label deployment with OIDC authentication, MCP tool integration, and custom branding. Runs as a Docker container with pre-baked environment configuration.

## Purpose

Provides a production-ready conversational AI frontend that connects to multiple LLM providers via OpenRouter/OpenAI-compatible APIs. Includes MCP tool support through a companion MCP bridge service, enabling the AI to execute tools during conversations.

## Source Location

`/tmp/ruflo/ruflo/src/chat-ui/`

## Architecture

```
Docker Container (ghcr.io/huggingface/chat-ui-db:latest)
  |
  +-- .env.local           (model config, too large for env vars)
  +-- patch-mcp-url-safety.sh  (security patch for private network MCP)
  +-- static/chatui/       (branded assets: welcome GIF, PWA icon)
```

## Container Build

The Dockerfile layers customizations on top of the upstream HF Chat UI image:

1. **Bake .env.local** -- Copies model configuration (MODELS JSON) into the container since it exceeds Cloud Run environment variable size limits
2. **Security Patch** -- Applies `patch-mcp-url-safety.sh` to allow HTTP MCP connections over private Docker networks
3. **Branded Assets** -- Copies welcome GIF and PWA icon into both SvelteKit build output and static directories
4. **Non-root Execution** -- Switches back to UID 1000 after setup

## Security Patch Details

HF Chat UI enforces HTTPS-only for MCP server URLs as SSRF protection. In containerized deployments, MCP servers run on a private Docker network and are not exposed to the internet. The patch:

- Allows `http:` protocol in addition to `https:` for MCP URLs in `urlSafety-*.js`
- Permits localhost connections for container-internal MCP servers
- Only relaxes protocol check, not IP safety checks
- Admin-configured MCP_SERVERS (via env var / .env.local) are trusted

```bash
# Patches the urlSafety compiled JS to allow http protocol
sed -i 's/if (url\.protocol !== "https:")/if (url.protocol !== "https:" \&\& url.protocol !== "http:")/' "$URLSAFETY_FILE"
```

## Configuration

Models and providers are configured via `.env.local` (baked into the container):

```bash
MODELS='[{"name":"...","endpoints":[{"type":"openai","baseURL":"..."}]}]'
PUBLIC_APP_NAME="Brand Name"
PUBLIC_ORIGIN=https://chat.example.com
```

## MCP Integration

The chat UI connects to MCP tools via a companion MCP bridge service. Tool calls flow through the SvelteKit server to the bridge over the private Docker network:

```
Chat UI (SvelteKit) --HTTP--> MCP Bridge (Express) --stdio--> MCP Backends
```

MCP tools appear as interactive cards in the chat interface, allowing the AI to search, research, manage agents, and execute code during conversations.

## Deployment

Designed for Google Cloud Run or any Docker-compatible platform:

- Container image includes all dependencies (no external MongoDB required when using RuVocal fork)
- Static assets served from `/app/build/client/` and `/app/static/`
- PWA support with 144x144 icon
- Custom welcome screen with branded GIF animation

## Commands

```bash
# Build the container
docker build -t chat-ui -f Dockerfile .

# Run locally
docker run -p 5173:5173 --env-file .env.local chat-ui

# Deploy to Cloud Run
gcloud run deploy chat-ui --image gcr.io/project/chat-ui --port 5173
```

## Key Files

| File | Purpose |
|------|---------|
| `Dockerfile` | Container build with patches and branding |
| `patch-mcp-url-safety.sh` | HTTP protocol patch for private network MCP |
| `static/chatui/omni-welcome.gif` | Branded welcome animation |
| `static/chatui/icon-144x144.png` | PWA app icon |