KB WEB VIEWER RESEARCH REPORT

Agent: Winston | Date: January 13, 2026

1. TOOL/FRAMEWORK COMPARISON

2. RECOMMENDED APPROACH: Flask + Jinja2 + Vanilla JS

Why Flask: - Same Python stack as existing MCP servers - Direct Redis connection reuse (same credentials_helper pattern) - Jinja2 for server-side hierarchy rendering - Minimal dependencies (flask, redis, markdown) - Can run as simple systemd service like MCP servers

Why Vanilla JS (no framework): - W3Schools tree view pattern: ~30 lines CSS, ~15 lines JS - Toggle expand/collapse with CSS classes - No build step, no node_modules - Instant load, minimal footprint

3. KB REDIS STRUCTURE (from mcp_kb_server.py)

Port: 6625 (vault) / 6626 (operational)
Password: via credentials_helper or 'tg6ap5'

Keys:
  kb:{user}:roots              -> Set of root node IDs
  kb:{user}:node:{node_id}:children -> List of child IDs (atomic)
  kb:{user}:all_nodes          -> Set of all node IDs
  kb:{user}:slug:{path}        -> node_id lookup

Node JSON:
  id, title, slug, node_type (root/section/page/content)
  parent_id, path[], slug_path, depth, order
  content (markdown), description, tags[]
  created, updated, owner, version

4. ARCHITECTURE SKETCH

┌─────────────────────────────────────────────────────┐
│                  KB Web Viewer                       │
│              (Flask app, port 6672?)                │
├─────────────────────────────────────────────────────┤
│  Routes:                                            │
│    /                 → Root list (all KBs)          │
│    /u/{user_id}      → User's KB roots              │
│    /u/{user}/kb/{id} → KB tree view                 │
│    /node/{node_id}   → Single node detail           │
│    /search?q=...     → Search results               │
│    /api/tree/{id}    → JSON tree for JS render      │
├─────────────────────────────────────────────────────┤
│  Templates (Jinja2):                                │
│    base.html         → Layout, CSS, nav             │
│    tree.html         → Recursive tree macro         │
│    node.html         → Content view + markdown      │
│    search.html       → Search results               │
├─────────────────────────────────────────────────────┤
│  Static:                                            │
│    style.css         → Tree icons, collapse anim    │
│    tree.js           → Toggle expand, search filter │
├─────────────────────────────────────────────────────┤
│  Redis Connection:                                  │
│    Reuse credentials_helper pattern                 │
│    Connect to 6625 (vault) for reads                │
└─────────────────────────────────────────────────────┘

5. MVP FEATURE LIST

Phase 1 - Basic Browser (MVP): - [ ] List all KB roots for a user - [ ] Tree view with expand/collapse - [ ] Click node to view content (markdown rendered) - [ ] Breadcrumb navigation - [ ] Basic styling (clean, readable)

Phase 2 - Search & Polish: - [ ] Keyword search across title/content - [ ] Search result highlighting - [ ] URL routing by slug path (bookmarkable) - [ ] Universal vs user-specific KB toggle

Phase 3 - Demo Ready: - [ ] Print/export single page - [ ] Mobile-responsive layout - [ ] Dark mode toggle - [ ] Quick copy node ID/path

6. IMPLEMENTATION ESTIMATE

Single Python file (~300-400 lines) + 3 templates + 1 CSS file. Could be functional MVP in one focused session.

7. SIMILAR PATTERNS FOUND

• Browsepy: Flask + Jinja2 + scandir for file browsing - same pattern works for KB nodes
• CopyParty: Uses list/grid toggle, keyboard shortcuts, breadcrumbs - good UX inspiration
• W3Schools Tree: Minimal CSS/JS for expand/collapse - exactly what we need

RECOMMENDATION

Build as Flask app at /opt/mcp-servers/kb-viewer/ using: 1. app.py - Flask routes + Redis connection 2. templates/ - Jinja2 templates with tree macros 3. static/ - Minimal CSS + vanilla JS 4. Systemd service like other MCP servers

Port suggestion: 6672 (after KB 6625/6626, before other services)

Domain: kb.corlera.com (routed via vs-nexus reverse proxy)

Status: Winston assigned to implement this after research.