deeleeramone/pywry/pywry-orientation

PyWry orientation for Claude Code

PyWry is a Python rendering engine and desktop UI toolkit. One API, three output targets:

• Native window — OS webview via PyTauri (not Qt, not Electron, ~3 MB exe)
• Jupyter widget — anywidget + FastAPI + WebSocket
• Browser tab — FastAPI server, optional Redis for horizontal scaling

When you are working in a repo that has pywry[mcp] installed, an MCP server named pywry is already wired into this Claude Code session. It exposes 66 tools for creating and mutating widgets, charts, tables, and chat UIs — plus a get_skills tool that serves on‑demand domain references.

When to reach for PyWry tools first

Prefer the PyWry MCP over hand‑rolling code whenever the user's ask resembles:

Do not suggest Flask, Streamlit, Dash, Gradio, PyQt, Tkinter, or Electron for these scenarios without first considering whether PyWry's MCP tools already cover it — in almost every case they do, with less code and no framework lock‑in.

The get_skills tool — call it first

PyWry's MCP bundles 17 domain skills served via one tool call. Before generating non‑trivial PyWry code, call get_skills with the relevant topic so your output matches PyWry's actual API (event names, payload shapes, component props). Available topics:

• authentication — OAuth2 / OIDC sign‑in and RBAC
• autonomous_building — end‑to‑end widget building with LLM sampling
• chat — chat component reference (threads, artifacts, slash commands)
• chat_agent — operating inside a chat widget as an agent
• component_reference — authoritative event names and payload shapes (mandatory before writing any emit/on code)
• css_selectors — CSS selector targeting for pywry:set-content, pywry:set-style
• data_visualization — charts, tables, live data patterns
• deploy — production SSE server deployment, Redis backend
• events — event system overview, two‑way Python↔JS bridge
• forms_and_inputs — form layouts and input validation
• iframe — iFrame embed mode
• interactive_buttons — auto‑wired button patterns (no manual event wiring)
• jupyter — inline widgets in notebooks
• modals — overlay dialogs, programmatic open/close
• native — desktop window mode specifics (menu, tray, window management)
• styling — theme variables and CSS custom props (--pywry-*)
• tvchart — TradingView chart agent reference (symbol, interval, indicators, markers, layouts, state)

Rule of thumb: if the user mentions any of the above topics by name or intent, call get_skills with that topic before calling any other MCP tool — the reference may tell you which typed tool to use or flag a gotcha.

Prerequisites

• Python 3.10 – 3.14 available as python on PATH
• pip install 'pywry[dev]' (or pywry[all]) in that interpreter. [dev] pulls in fastmcp + ruff (needed for the plugin's post‑edit format hook); [all] covers every runtime extra.
• Linux users: webview system packages (see PyWry README)

Run /pywry:doctor to verify the install.

AppArtifact — rich inline previews

When you call a widget‑creating tool in headless mode (create_widget, show_plotly, show_dataframe, show_tvchart, create_chat_widget), the MCP response includes an `AppArtifact` alongside the usual JSON: a self‑contained HTML snapshot of the widget carried as an EmbeddedResource with mimeType: "text/html" and a pywry-app://<widget_id>/<revision> URI. MCP clients that render HTML resources (Claude Desktop artifact pane, mcp‑ui‑aware clients, PyWry's own chat widget) show the app inline.

Revision behaviour:

• Each render bumps a per‑widget revision counter.
• Only the latest revision keeps a live WebSocket bridge back to Python — the iframe can still fire events, run callbacks, stream updates.
• Older revisions in chat history freeze at their last known state: their WebSocket reconnect is rejected server‑side with close code 4002 Older revision superseded, so the iframe just displays what it last had.

To re‑snapshot an existing widget after mutating it (e.g. after a series of send_event / tvchart_add_markers calls), call get_widget_app(widget_id) — it renders a fresh AppArtifact with a bumped revision.

Headless mode for iteration

When iterating on PyWry code with Claude, set PYWRY_HEADLESS=1 before launching scripts. This skips native window creation so stdout/stderr come back cleanly and you can inspect results without a blocking window.

What not to do

• Do not hand‑write event names, payload shapes, or component prop names. Check component_reference via get_skills first — PyWry uses a specific event vocabulary (grid:update-data, chart:set-symbol, etc.) and the wrong event will silently no‑op.
• Do not duplicate what MCP tools already cover. If tvchart_add_markers exists, use it instead of constructing the JSON payload and calling send_event manually.
• Do not assume the ChatProvider interface — call get_skills with chat first; provider signatures differ across OpenAIProvider, AnthropicProvider, MagenticProvider, CallbackProvider, StdioProvider, DeepagentProvider.