---
name: doctor
description: Diagnoses the widget-studio installation - MCP server health, PNG rendering, and generator API reachability - and fixes what it can. Use when widgets fail to render or generate, the PNG fallback errors, tools are missing, or after installing or updating the plugin.
---

# Widget Studio doctor

Run the checks in order; report each as pass/fail with the fix applied or needed.

## 1. MCP server

Are `generate_widget` / `display_widget` tools available in this session?

- Yes → call `display_widget` with a minimal card
  (`{"type":"Card","children":[{"type":"Text","value":"doctor ok"}]}`).
  A rendered result (inline or PNG) proves the server end-to-end
  (inline-only is normal in MCP Apps hosts — check 2 covers the PNG path).
- No → the MCP server isn't connected. The skills and CLI
  (`widget-generate` / `widget-render`) work without it — the server adds
  interactive inline widgets in MCP Apps hosts. To connect it: check the
  plugin is installed and enabled (`claude plugin list`, or the `mcpServers`
  entry if registered manually), then have the user restart the session —
  servers connect at session start.

## 2. PNG rendering (CLI path)

```bash
echo '{"type":"Card","children":[{"type":"Text","value":"doctor"}]}' | widget-render --in - --png widget-doctor.png
```

(Write the test PNG to any writable path.)

- If `widget-render` isn't on PATH, run the script directly from the install:
  `node "${CLAUDE_PLUGIN_ROOT:-<path-to-repo>}/scripts/render-widget.mjs"`.
- Rendering is fully self-contained (satori + resvg WASM + fonts bundled in
  dist/) — no browser or native dependencies. dist/ ships with the plugin, so
  a failure means the install is incomplete: reinstall or update the plugin.
  In a dev checkout, rebuild with `npm install && npm run build`.

## 3. Generator API reachability

Fast, non-LLM endpoint check (no 60s generation):

```bash
curl -sS -m 15 -X POST https://widgets.chatkit.studio/convert-widget-to-file \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://widgets.chatkit.studio' \
  -d '{"widgetJsx":"<Card><Text value=\"ping\" /></Card>"}'
```

A JSON response containing `"template"` means the hosted service is reachable.
Timeouts or 5xx → the generator is down or blocked; widgets can still be
tweaked/previewed locally, but generation (`generate_widget` /
`widget-generate`) will fail — say so.

## 4. Report

Summarize: what passed, what was fixed, what still needs the user (e.g. a
session restart, or network access). If everything passes but the user still
sees failures, the fault is likely session-scoped: have them restart the
session (MCP servers connect at startup) and show you the exact failing call.