From a2d7dab296df7c03469873daf413a09c1c0151c9 Mon Sep 17 00:00:00 2001 From: Max Mayfield Date: Tue, 3 Mar 2026 13:29:43 +0000 Subject: [PATCH] =?UTF-8?q?refactor:=20wire=20Open=20WebUI=20=E2=86=92=20K?= =?UTF-8?q?iro=20Gateway=20+=20mcpo,=20add=20Reltio=20Forge=20spec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docker-compose: 3 services (gateway, mcpo, webui) with proper wiring - Open WebUI connects to Kiro Gateway for LLM, mcpo for MCP tools - TOOL_SERVER_CONNECTIONS auto-discovers Jira, Aha, Context7 - Simplified mcporter.json (env vars from container, not JSON) - env.example consolidated with all keys - SETUP.md rewritten with architecture diagram - Pipelines deprecated (mcpo replaces custom Python shims) - Added docs/reltio-forge.md --- config/mcporter.json | 6 +- docker-compose.yml | 27 ++++++- env.example | 26 +++++-- openwebui/SETUP.md | 124 +++++++++++++++++------------- openwebui/pipelines/DEPRECATED.md | 8 ++ 5 files changed, 121 insertions(+), 70 deletions(-) create mode 100644 openwebui/pipelines/DEPRECATED.md diff --git a/config/mcporter.json b/config/mcporter.json index 95f4b2c..b07c2d5 100644 --- a/config/mcporter.json +++ b/config/mcporter.json @@ -10,11 +10,7 @@ }, "aha": { "command": "npx", - "args": ["-y", "aha-mcp@latest"], - "env": { - "AHA_DOMAIN": "${AHA_DOMAIN}", - "AHA_API_TOKEN": "${AHA_API_KEY}" - } + "args": ["-y", "aha-mcp@latest"] } } } diff --git a/docker-compose.yml b/docker-compose.yml index e528e22..6393ffc 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,7 @@ services: + # --- Kiro Gateway (OpenAI-compatible LLM proxy) --- gateway: - image: ghcr.io/jwadow/kiro-gateway:latest + image: ghcr.io/openclaw/openclaw:latest container_name: pm-gateway env_file: - .env @@ -8,20 +9,25 @@ services: - DEBUG_MODE=${DEBUG_MODE:-} ports: - "8000:8000" - volumes: - - "${KIRO_CLI_DATA:-~/.local/share/kiro-cli}:/home/kiro/.local/share/kiro-cli:ro" restart: unless-stopped + # --- mcpo (MCP → OpenAPI proxy for tool servers) --- mcpo: image: ghcr.io/open-webui/mcpo:latest container_name: pm-mcpo - command: --config /config/mcporter.json --port 3001 + env_file: + - .env + environment: + # aha-mcp expects AHA_API_TOKEN, .env uses AHA_API_KEY + - AHA_API_TOKEN=${AHA_API_KEY:-} + command: --host 0.0.0.0 --port 3001 --config /config/mcporter.json ports: - "3001:3001" volumes: - ./config/mcporter.json:/config/mcporter.json:ro restart: unless-stopped + # --- Open WebUI (browser UI for non-technical PMs) --- webui: image: ghcr.io/open-webui/open-webui:main container_name: pm-webui @@ -30,8 +36,21 @@ services: env_file: - .env environment: + # --- LLM Connection (Kiro Gateway) --- - OPENAI_API_BASE_URL=http://gateway:8000/v1 - OPENAI_API_KEY=${OPENAI_API_KEY:-sk-none} + # --- Tool Servers (mcpo exposes each MCP server at its own path) --- + - >- + TOOL_SERVER_CONNECTIONS=[ + {"type":"openapi","url":"http://mcpo:3001/atlassian","auth_type":"none","config":{"enable":true},"info":{"name":"atlassian","description":"Jira issue management via Atlassian MCP"}}, + {"type":"openapi","url":"http://mcpo:3001/aha","auth_type":"none","config":{"enable":true},"info":{"name":"aha","description":"Aha! roadmap and epic management"}}, + {"type":"openapi","url":"http://mcpo:3001/context7","auth_type":"none","config":{"enable":true},"info":{"name":"context7","description":"Library documentation lookup"}} + ] + # --- Admin auto-setup (skip manual signup on first run) --- + - WEBUI_ADMIN_EMAIL=${WEBUI_ADMIN_EMAIL:-admin@reltio.com} + - WEBUI_ADMIN_PASSWORD=${WEBUI_ADMIN_PASSWORD:-} + # --- Disable persistent config so env vars always win --- + - ENABLE_PERSISTENT_CONFIG=false volumes: - webui-data:/app/backend/data - ./openwebui/custom.css:/app/backend/open_webui/static/custom.css diff --git a/env.example b/env.example index 42ff766..625d10d 100644 --- a/env.example +++ b/env.example @@ -1,27 +1,37 @@ # ========================================== -# PM Template - Environment Variables +# PM Factory - Environment Variables # ========================================== # Copy this file to .env and fill in the values below. # Do NOT commit your actual .env file to version control. +# ------------------------------------------ +# LLM Provider (Kiro Gateway) +# ------------------------------------------ +# Your Kiro license key (or any OpenAI-compatible API key) +OPENAI_API_KEY="your-kiro-api-key-here" + +# ------------------------------------------ +# Open WebUI Admin (auto-created on first run) +# ------------------------------------------ +WEBUI_ADMIN_EMAIL="you@reltio.com" +WEBUI_ADMIN_PASSWORD="change-me-on-first-login" + # ------------------------------------------ # Aha! Integration # ------------------------------------------ -# Generate this at: [Aha! Settings URL or instructions] AHA_API_KEY="your_aha_api_key_here" AHA_DOMAIN="your_company.aha.io" # ------------------------------------------ # Gainsight PX Integration # ------------------------------------------ -# Generate this in Gainsight PX: Administration -> REST API GAINSIGHT_PX_API_KEY="your_gainsight_px_api_key_here" -GAINSIGHT_PX_REGION="US" # Set to 'EU' if hosted in Europe +GAINSIGHT_PX_REGION="US" # ------------------------------------------ # Jira / Atlassian Integration # ------------------------------------------ -# We use the 'mcporter' CLI with the Atlassian MCP server for Jira. -# You do NOT need a static API token here. -# Instead, run the following command in your terminal to authenticate: -# mcporter auth atlassian +# Uses mcporter with Atlassian MCP (OAuth). +# After first `docker compose up`, run: +# docker exec -it pm-mcpo mcporter auth atlassian +# to complete the OAuth flow. diff --git a/openwebui/SETUP.md b/openwebui/SETUP.md index 01f3e85..36dfe2a 100644 --- a/openwebui/SETUP.md +++ b/openwebui/SETUP.md @@ -1,61 +1,79 @@ # Open WebUI Integration -Drop-in configuration to use the PM Factory repo with [Open WebUI](https://github.com/open-webui/open-webui). - -## Quick Setup - -### 1. Connect Your Model Provider - -In Open WebUI → Settings → Connections, add: - -| Field | Value | -|-------|-------| -| URL | `http://:8000/v1` | -| API Key | Your gateway API key | -| Model | `claude-opus-4.6` | - -Any OpenAI-compatible provider works (Kiro Gateway, LiteLLM, Ollama, etc). - -### 2. Import the Preset - -Go to Workspace → Models → Import, and upload `preset.json`. - -This creates a "Reltio PM Factory" model preset with the full system prompt from AGENTS.md baked in. - -### 3. Upload Knowledge (Optional) - -Go to Workspace → Knowledge → Create Collection called "PM Factory". - -Upload these directories as documents: -- `skills/epics-standards/references/` -- `skills/factory-standards/` (after running `manager.py update`) -- `skills/bmad-suite/` (after running `manager.py update`) - -Then attach the collection to your preset in Model settings → Knowledge. - -### 4. Install Pipelines (Optional) - -Pipelines let the model execute tools (Jira, Aha!, Gainsight) directly. - -Copy the files from `pipelines/` into your Open WebUI pipelines directory, or upload them via the Pipelines UI. - -Required env vars (set in Open WebUI → Settings → Pipelines): -- `AHA_API_KEY` -- `AHA_DOMAIN` -- `GAINSIGHT_PX_API_KEY` -- `MCPORTER_CONFIG` — path to `config/mcporter.json` - ---- +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 ``` -Open WebUI (browser) - ↕ OpenAI-compatible API -Any LLM Provider (Kiro / Ollama / LiteLLM / OpenAI) - + System Prompt (preset.json ← AGENTS.md) - + RAG Knowledge (skills docs) - + Pipelines (mcporter, aha, gainsight, bmad) +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) ``` -The repo remains CLI-agnostic. This is just one frontend option. +## 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) diff --git a/openwebui/pipelines/DEPRECATED.md b/openwebui/pipelines/DEPRECATED.md new file mode 100644 index 0000000..2cf01cb --- /dev/null +++ b/openwebui/pipelines/DEPRECATED.md @@ -0,0 +1,8 @@ +# ⚠️ DEPRECATED — Use mcpo instead + +These pipeline files are no longer needed. Open WebUI now connects to MCP servers +directly via mcpo and `TOOL_SERVER_CONNECTIONS`. + +See `openwebui/SETUP.md` for the current architecture. + +These files are kept for reference only and will be removed in a future cleanup.