pm-template/openwebui/SETUP.md

# Open WebUI Integration

The PM Factory uses Open WebUI as the browser-based frontend for non-technical PMs. It connects to Kiro Gateway for LLM intelligence and mcpo for tool access (Jira, Aha!, Gainsight).

## Architecture

```
Browser (PM)
    ↕
Open WebUI (:3000)
    ├── LLM → Kiro Gateway (:8000/v1) → Claude/GPT/etc
    └── Tools → mcpo (:3001) → MCP Servers
                                ├── atlassian (Jira)
                                ├── aha (Aha! roadmaps)
                                └── context7 (docs lookup)
```

## Quick Start

```bash
cp env.example .env    # Fill in your API keys
docker compose up -d
```

Open http://localhost:3000. Log in with the admin email/password from your `.env`.

## How It Works

1. **Kiro Gateway** provides an OpenAI-compatible `/v1/chat/completions` endpoint. Open WebUI talks to it like any OpenAI provider.

2. **mcpo** reads `config/mcporter.json` and exposes each MCP server as an OpenAPI endpoint. Open WebUI discovers tools automatically via `TOOL_SERVER_CONNECTIONS`.

3. **No pipelines needed.** The old `pipelines/` directory contained custom Python shims that shelled out to mcporter. With mcpo, Open WebUI calls MCP tools natively through OpenAPI. The pipelines are deprecated.

## First-Time Setup

### 1. Jira OAuth

Atlassian uses OAuth, not API keys. After `docker compose up`:

```bash
docker exec -it pm-mcpo mcporter auth atlassian
```

Follow the browser prompt to authorize. This is a one-time step per machine.

### 2. Aha! + Gainsight

These use API keys set in `.env`. No extra auth step needed.

### 3. Verify Tools

Open http://localhost:3001/docs to see all available MCP tools exposed by mcpo. Each server has its own route:

- http://localhost:3001/atlassian/docs — Jira tools
- http://localhost:3001/aha/docs — Aha! tools  
- http://localhost:3001/context7/docs — Documentation lookup

In Open WebUI, go to Settings → Tools to confirm all three servers are connected.

## Model Preset

Import `preset.json` via Workspace → Models → Import. This loads the PM Factory system prompt with Transparent Factory tenets baked in.

## Knowledge Base

Upload these files as a Knowledge collection in Open WebUI:

- `skills/epics-standards/references/` — Epic templates and checklists
- `skills/gainsight-px/SKILL.md` — Analytics reference
- `docs/reltio-forge.md` — Reltio Forge velocity standard

Then attach the collection to the PM Factory model preset.

## Customization

- **Add MCP servers:** Edit `config/mcporter.json`, restart mcpo
- **Change LLM:** Update `OPENAI_API_KEY` and gateway config in `.env`
- **Custom CSS:** Edit `openwebui/custom.css` (mounted into the container)