strapi-plugin-mcp-chat 0.1.0 → 0.5.0

package/README.md

@@ -1,9 +1,16 @@
-# strapi-plugin-mcp-chat
+<p align="center">
+  <img src="./assets/logo.png" alt="MCP Chat" width="120" height="120" />
+</p>
+
+<h1 align="center">strapi-plugin-mcp-chat</h1>
 
 > AI chat inside the **Strapi 5** admin that actually **reads and edits your content** — including fields nested in **components and dynamic zones** — through **MCP**. Comes with **voice** (speech-to-text / text-to-speech) and a **side-by-side live preview** of your frontend.
 
 Ask in plain language ("change the homepage hero title to …") and the assistant finds the text across all content-types, edits it, and publishes — then reloads the preview on the very page you were looking at.
 
+[![npm](https://img.shields.io/npm/v/strapi-plugin-mcp-chat.svg)](https://www.npmjs.com/package/strapi-plugin-mcp-chat)
+[![license](https://img.shields.io/npm/l/strapi-plugin-mcp-chat.svg)](./LICENSE)
+
 https://github.com/raulbalestra/strapi-plugin-mcp-chat
 
 ---
@@ -12,12 +19,36 @@ https://github.com/raulbalestra/strapi-plugin-mcp-chat
 
 - 🤖 **AI chat in the admin** — a floating widget on every screen + a full-page view. Runs an agent loop on the OpenAI Chat Completions API.
 - ✏️ **Edits real content via MCP + Document Service** — `buscar_texto` finds a phrase across **all** content-types, single types, **components and dynamic zones** (recursive); `editar_campo` updates it (preserving the other components); `publicar` publishes.
+- 📝 **Draft-first by default** — the AI edits **drafts** and does **not** publish unless you ask (or flip the **Auto-publish** toggle). Pair it with the preview's **Draft / Live** switch to review unpublished changes before they go to production. See [Draft-first editing & previewing drafts](#draft-first-editing--previewing-drafts).
 - 🎙️ **Voice** — record a request (Whisper STT) and hear replies (OpenAI TTS).
 - 👁️ **Side-by-side preview panel** — the plugin's own docked iframe that shrinks the admin and shows your frontend; reloads after each edit and **stays on the same page + scroll position** (with the optional preview bridge below). This is a custom panel, *not* Strapi's official Live Preview (which is a Growth/Enterprise feature) — it works on any plan, including Community, and complements the official Preview if you have it configured.
 - 🖥️ **Optional browser control** — if a [Playwright MCP](https://github.com/microsoft/playwright-mcp) server is reachable, the agent can drive a real browser to verify changes.
 - 🧱 **Frontend provisioning** — upload your frontend (Next.js or TanStack Start) with a `strapi.manifest.json`; the plugin validates it, creates all content-types, seeds content and wires the preview. Never runs code from the upload — it acts only on the validated manifest.
 - 🌍 **Translate every page to any language** — create locales and translate all localized content via Strapi 5's native i18n, with **no length limits and no context blowups** (see below).
-- 🌐 Bilingual UI/prompts (PT / EN).
+- 🌐 **Fully bilingual (PT / EN)** — both the AI prompts/voice *and* the plugin's own admin pages, switchable with one click (the choice is shared across the chat and the menu pages).
+- 🎓 **Built-in onboarding tour** — a first-run mini-course (re-openable any time via **❓ Tour**) walks new users through chat, editing, live preview, provisioning and translation.
+
+## What makes MCP Chat unique
+
+MCP Chat is built on Strapi 5's **native MCP server** and focuses on letting an assistant
+**operate your content end-to-end** — find text anywhere (including fields nested in
+components and dynamic zones), edit it as a draft, publish it, and translate it — while you
+watch the result in a **live preview right next to the editor**.
+
+A few things that set it apart:
+
+- 👁️ **Docked, side-by-side live preview** that follows the exact page you're editing and
+  can show **drafts** before they're published — on any plan, including Community.
+- 🧱 **Frontend provisioning** from a `strapi.manifest.json` (Next.js / TanStack Start): the
+  plugin infers the content model, creates the content-types, seeds the data and wires the
+  preview for you.
+- 📝 **Draft-first & safe**: edits go to drafts and nothing is published until you say so.
+- ✏️ **Operates content in place**: finds and edits text nested in components and dynamic
+  zones, then publishes — not just generating text into a single field.
+- 🎙️ **Voice** (speech-to-text + text-to-speech) and a **bilingual** UI/prompts (PT / EN).
+
+It's a complement to the rest of Strapi's AI ecosystem, not a replacement — reach for it
+when you want the "chat that edits your content with a live preview" workflow.
 
 ## Requirements
 
@@ -27,8 +58,9 @@ https://github.com/raulbalestra/strapi-plugin-mcp-chat
 ## Install
 
 ```bash
-# Straight from GitHub (not on npm yet):
-npm install github:raulbalestra/strapi-plugin-mcp-chat
+npm install strapi-plugin-mcp-chat
+# or pull the latest unreleased code straight from GitHub:
+# npm install github:raulbalestra/strapi-plugin-mcp-chat
 ```
 
 > Or just try the ready-to-run [Launchpad demo](https://github.com/raulbalestra/launchpad-mcp-chat) (the plugin is vendored there).
@@ -161,6 +193,30 @@ export function PreviewBridge() {
 Then render `<PreviewBridge />` once in your root layout. The same idea works in any
 framework — just post `{ type: 'preview:location', href: location.href }` to `window.parent`.
 
+## Draft-first editing & previewing drafts
+
+Strapi's Draft & Publish lets editors stage changes before they go live. MCP Chat
+respects that:
+
+- **The AI edits drafts, never auto-publishes.** `editar_campo` always writes the
+  **draft** version. By default the agent stops there and tells you it saved a draft —
+  it only calls `publicar` when you explicitly ask ("publish this", "make it live") or
+  when you turn **Auto-publish ON** in the chat toolbar. The setting is remembered
+  (`localStorage` `mcp-chat-autopublish`, default off).
+- **Content-types without Draft & Publish are handled correctly.** Draft & Publish is per content-type and off by default; `publish()` only exists when it's enabled (calling it otherwise throws, per the Strapi 5 docs). When a type has no Draft & Publish, the edit *is* the live value — so the plugin skips publishing (no error) and the assistant tells you the change is already live.
+- **Preview the draft before publishing.** The preview panel has a **📝 Draft / 🌐 Live**
+  toggle. In **Draft** it reloads the frontend with `?preview=1`; provisioned frontends
+  read that flag and fetch `status=draft` from the Content API, so you see unpublished
+  changes exactly as they'll look — without publishing. Flip to **Live** to compare with
+  what's currently public.
+
+**Draft preview contract (for custom / non-provisioned frontends):** when the iframe URL
+carries `?preview=1` (or `?status=draft`), fetch Strapi with `status: 'draft'` and an API
+token that can read drafts (`STRAPI_API_TOKEN`). Provisioned frontends get this wired
+automatically via the generated `strapi-client` data module. Note: draft fetching keys off
+the URL on the **client**, so with SSR the first server render may show published content
+until hydration — fine for preview, but don't rely on it for production rendering.
+
 ## How it works
 
 ```
@@ -238,11 +294,16 @@ The plugin follows the documented Strapi 5 plugin APIs:
   (`register` / `bootstrap` / `destroy` / `config` / `controllers` / `services` / `routes`).
   Routes are declared with `type: 'admin'`, so the chat/STT/TTS endpoints require an
   authenticated admin session.
-- **MCP** — tools are registered with `strapi.ai.mcp.registerTool` during `register()`
-  (the documented extension point), using `z` from `@strapi/utils` for the schemas and
-  `auth.policies` (content-manager read/update/publish) for RBAC. They're organized in a
-  modular `server/src/mcp/` (one file per tool in `tools/`, aggregated and looped) following
-  the structure from [Paul Bratslavsky's MCP tool-extension example](https://github.com/PaulBratslavsky/strapi-mcp-demo-and-tool-extension).
+- **MCP** — tools are **defined** as pure objects with a local typed `defineTool` helper
+  (`server/src/mcp/define.ts`) and **registered from an array** via
+  `strapi.ai.mcp.registerTool` during `register()`, using `z` from `@strapi/utils` for the
+  schemas and `auth.policies` (content-manager read/update/publish) for RBAC. The
+  `defineTool`/`defineResource`/`definePrompt` identity functions infer each handler's
+  `args` from its input schema (no `any`) and keep the definitions side-effect-free —
+  mirroring the direction of Strapi's [PR #26603](https://github.com/strapi/strapi/pull/26603)
+  (`ai.mcp.defineTool` + the `import { ai } from "@strapi/strapi"` namespace). When that API
+  ships stable, migrating is a one-line import swap; until then the plugin stays on the
+  released `registerTool` so it runs on any Strapi ≥ 5.47 (no experimental build required).
 - **Admin** — `register()` uses only documented APIs (`app.addMenuLink`, `app.registerPlugin`).
 
 One intentional deviation: the **global floating chat** is mounted via its own React root
@@ -260,6 +321,27 @@ single spot.
   token's permissions — scope the token to only what those clients should change.
 - The agent can edit and publish content — give the plugin only to trusted editors.
 
+## Reliability — never degrades or breaks the host Strapi
+
+This plugin is built to be a good citizen: installing it must never slow down or take
+down the host app. Concrete guarantees:
+
+- **Can't crash boot.** `register()` degrades gracefully if the native MCP server / i18n /
+  OpenAI key are absent (logs a warning, disables the feature). MCP tools register inside a
+  per-tool `try/catch`, so a single bad tool can never abort the others or the boot.
+  `destroy()` is best-effort.
+- **Can't blank the admin.** The global overlay (floating chat + preview) mounts inside a
+  React **error boundary** in its own root, after an SSR/double-mount guard; any render
+  error just hides the overlay, leaving the Strapi admin fully intact. Lingering preview
+  layout styles are reset on load, and screen/mic capture is stopped on unmount.
+- **Provisioning is fail-safe.** Generated schemas are **validated before any file is
+  written** (kind/attributes/known types/relation targets) and writes are **all-or-nothing**
+  — a malformed manifest can never leave Strapi with a broken, unbootable schema. Generation
+  stays additive (never touches existing types), dev-only, with hardened zip-slip protection.
+- **Won't become a bottleneck.** Every outbound call (OpenAI, MCP) has a **timeout** so a
+  slow upstream can't hold a request open; recursive content search has depth caps and a
+  result cap; tool outputs are size-capped before going back to the model.
+
 ## License
 
 [MIT](./LICENSE) © Raul Balestra

package/admin/src/components/AdminOverlays.tsx

@@ -22,6 +22,7 @@ import { PreviewPanel } from './PreviewPanel';
 // edite na barra do painel — o valor fica salvo em localStorage.
 const FALLBACK_PREVIEW_URL = 'http://localhost:3000';
 const LS_KEY = 'mcp-chat-preview-url';
+const LS_DRAFT = 'mcp-chat-preview-draft';
 
 const initialPreviewUrl = (): string => {
   try {
@@ -31,6 +32,28 @@ const initialPreviewUrl = (): string => {
   }
 };
 
+const initialDraft = (): boolean => {
+  try {
+    return localStorage.getItem(LS_DRAFT) === '1';
+  } catch {
+    return false;
+  }
+};
+
+/** Aplica/remove o flag `?preview=1` na URL do iframe. Em modo rascunho, o
+ *  frontend provisionado (e qualquer frontend que respeite o contrato de
+ *  preview) busca `status=draft` no Strapi em vez do conteúdo publicado. */
+const withPreviewFlag = (url: string, draft: boolean): string => {
+  try {
+    const u = new URL(url);
+    if (draft) u.searchParams.set('preview', '1');
+    else u.searchParams.delete('preview');
+    return u.toString();
+  } catch {
+    return url;
+  }
+};
+
 const originOf = (u: string): string | null => {
   try {
     return new URL(u).origin;
@@ -48,6 +71,8 @@ export const AdminOverlays = () => {
   const liveRef = useRef(initialPreviewUrl());
   const srcRef = useRef(initialPreviewUrl());
   const [iframeKey, setIframeKey] = useState(0);
+  // Modo rascunho do preview (mostra conteúdo não publicado).
+  const [draftPreview, setDraftPreview] = useState(initialDraft);
 
   // Auto-run do frontend provisionado SEMPRE que o preview é ligado.
   const [runLoading, setRunLoading] = useState(false);
@@ -150,7 +175,7 @@ export const AdminOverlays = () => {
     <>
       <PreviewPanel
         open={previewOn}
-        src={previewSrc}
+        src={withPreviewFlag(previewSrc, draftPreview)}
         displayUrl={liveHref}
         onUrl={navigate}
         iframeKey={iframeKey}
@@ -159,6 +184,15 @@ export const AdminOverlays = () => {
         loading={runLoading}
         loadingText={runText}
         loadingError={runError}
+        draft={draftPreview}
+        onToggleDraft={() => {
+          setDraftPreview((v) => {
+            const next = !v;
+            try { localStorage.setItem(LS_DRAFT, next ? '1' : '0'); } catch { /* noop */ }
+            return next;
+          });
+          setIframeKey((k) => k + 1); // recarrega o iframe com/sem o flag
+        }}
       />
       <FloatingChat
         previewOn={previewOn}

package/admin/src/components/ErrorBoundary.tsx

@@ -0,0 +1,29 @@
+/**
+ * Error boundary que ISOLA as sobreposições do plugin (chat + preview) do resto
+ * do admin do Strapi. Se algo dentro renderizar com erro, capturamos aqui e
+ * renderizamos `null` — o overlay some, mas o admin do Strapi continua intacto.
+ * Sem isto, um erro de render num root React próprio poderia quebrar a página.
+ */
+import { Component, type ReactNode } from 'react';
+
+type Props = { children: ReactNode };
+type State = { failed: boolean };
+
+export class ErrorBoundary extends Component<Props, State> {
+  state: State = { failed: false };
+
+  static getDerivedStateFromError(): State {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: unknown) {
+    // Apenas loga; nunca propaga para o admin.
+    // eslint-disable-next-line no-console
+    console.error('[mcp-chat] overlay desativado após erro de render:', error);
+  }
+
+  render() {
+    if (this.state.failed) return null;
+    return this.props.children;
+  }
+}

package/admin/src/components/FloatingChat.tsx

@@ -28,6 +28,7 @@ const STR: Record<Lang, Record<string, string>> = {
     rec: '🎤 Enviar áudio', recStop: '⏹ Parar áudio', recTitle: 'Gravar áudio e enviar (transcreve e manda)',
     previewOn: '🖼 Preview: ON', previewOff: '🖼 Preview: OFF', previewTitle: 'Abrir/fechar o preview do site ao lado da Strapi',
     voiceOn: '🔊 Voz: ON', voiceOff: '🔈 Voz: OFF', voiceTitle: 'Ler as respostas em voz alta (TTS)',
+    pubOn: '🚀 Publicar: ON', pubOff: '📝 Rascunho', pubTitle: 'Auto-publicar OFF = a IA só salva rascunho (você revisa e publica). ON = publica direto no site.',
     shareOn: '🛑 Parar tela', shareOff: '🖥 Compart. tela', shareTitle: 'Compartilhar a tela com a IA',
     langTitle: 'Idioma do chat e da voz (PT-BR ↔ English)',
     seeingScreen: '• vendo sua tela ', voiceStatus: '• voz ON',
@@ -44,6 +45,7 @@ const STR: Record<Lang, Record<string, string>> = {
     rec: '🎤 Send audio', recStop: '⏹ Stop audio', recTitle: 'Record audio and send (transcribes and sends)',
     previewOn: '🖼 Preview: ON', previewOff: '🖼 Preview: OFF', previewTitle: 'Toggle the site preview next to Strapi',
     voiceOn: '🔊 Voice: ON', voiceOff: '🔈 Voice: OFF', voiceTitle: 'Read replies out loud (TTS)',
+    pubOn: '🚀 Publish: ON', pubOff: '📝 Draft', pubTitle: 'Auto-publish OFF = the AI only saves a draft (you review and publish). ON = publishes straight to the site.',
     shareOn: '🛑 Stop screen', shareOff: '🖥 Share screen', shareTitle: 'Share your screen with the AI',
     langTitle: 'Chat and voice language (PT-BR ↔ English)',
     seeingScreen: '• seeing your screen ', voiceStatus: '• voice ON',
@@ -66,6 +68,12 @@ export const FloatingChat = ({ previewOn, previewUrl, onTogglePreview, onReply }
   const [sharing, setSharing] = useState(false);
   const [voiceOn, setVoiceOn] = useState(false);
   const [recording, setRecording] = useState(false);
+  const [autoPublish, setAutoPublish] = useState<boolean>(() => {
+    try { return localStorage.getItem('mcp-chat-autopublish') === '1'; } catch { return false; }
+  });
+  useEffect(() => {
+    try { localStorage.setItem('mcp-chat-autopublish', autoPublish ? '1' : '0'); } catch { /* noop */ }
+  }, [autoPublish]);
   const [lang, setLang] = useState<Lang>(() => {
     try { return (localStorage.getItem('mcp-chat-lang') as Lang) || 'en'; } catch { return 'en'; }
   });
@@ -105,6 +113,14 @@ export const FloatingChat = ({ previewOn, previewUrl, onTogglePreview, onReply }
     if (bodyRef.current) bodyRef.current.scrollTop = bodyRef.current.scrollHeight;
   }, [messages, loading]);
 
+  // ── Cleanup ao desmontar: encerra captura de tela / microfone (sem vazar) ──
+  useEffect(() => {
+    return () => {
+      try { streamRef.current?.getTracks().forEach((t) => t.stop()); } catch { /* noop */ }
+      try { recorderRef.current?.stop(); } catch { /* noop */ }
+    };
+  }, []);
+
   // ── Screenshare ───────────────────────────────────────────────────────────
   const startShare = async () => {
     setError(null);
@@ -169,6 +185,8 @@ export const FloatingChat = ({ previewOn, previewUrl, onTogglePreview, onReply }
         // Página que o usuário está olhando no preview (se aberto). Dá à IA o
         // contexto do "isso aqui" sem precisar varrer o site inteiro.
         previewUrl: previewOn ? previewUrl : null,
+        // Draft-first: por padrão a IA só salva rascunho; só publica com isto ON.
+        autoPublish,
       });
       const reply = data?.reply || '(sem resposta)';
       setMessages((cur) => [...cur, { role: 'assistant', content: reply }]);
@@ -319,6 +337,10 @@ export const FloatingChat = ({ previewOn, previewUrl, onTogglePreview, onReply }
           title={t.voiceTitle}>
           {voiceOn ? t.voiceOn : t.voiceOff}
         </button>
+        <button style={btn(autoPublish)} onClick={() => setAutoPublish((v) => !v)}
+          title={t.pubTitle}>
+          {autoPublish ? t.pubOn : t.pubOff}
+        </button>
         <button style={btn(sharing)} onClick={sharing ? stopShare : startShare}
           title={t.shareTitle}>
           {sharing ? t.shareOn : t.shareOff}

package/admin/src/components/LangSwitcher.tsx

@@ -0,0 +1,24 @@
+/**
+ * Botão de idioma das páginas do plugin (PT-BR ↔ English).
+ * Alterna a mesma chave `mcp-chat-lang` usada pelo chat flutuante.
+ */
+import { useLang } from '../i18n';
+
+export const LangSwitcher = ({ size = 'M' as 'S' | 'M' }) => {
+  const [lang, setLang] = useLang();
+  const pad = size === 'S' ? '2px 8px' : '4px 10px';
+  return (
+    <button
+      type="button"
+      onClick={() => setLang(lang === 'pt' ? 'en' : 'pt')}
+      title="Idioma do plugin / Plugin language (PT-BR ↔ English)"
+      style={{
+        border: '1px solid #dcdce4', background: '#fff', color: '#32324d',
+        borderRadius: 6, padding: pad, cursor: 'pointer', fontSize: 12,
+        whiteSpace: 'nowrap', fontWeight: 600,
+      }}
+    >
+      {lang === 'pt' ? '🌐 PT-BR' : '🌐 English'}
+    </button>
+  );
+};

package/admin/src/components/Onboarding.tsx

@@ -0,0 +1,192 @@
+/**
+ * Mini-curso de onboarding: um carrossel de passos mostrado na PRIMEIRA vez que o
+ * usuário abre o plugin (flag em localStorage), e reabrível pelo botão "❓ Tour".
+ *
+ * Cada passo tem uma ilustração (SVG placeholder) + título + descrição, em PT/EN.
+ * Para usar screenshots reais, troque o componente `art` do passo por
+ * `<img src={...} />` (ou aponte para arquivos em admin/src/assets).
+ */
+import { useEffect, useState } from 'react';
+import type { Lang } from '../i18n';
+
+const LS_DONE = 'mcp-chat-tour-done';
+
+export const tourWasSeen = (): boolean => {
+  try { return localStorage.getItem(LS_DONE) === '1'; } catch { return false; }
+};
+const markSeen = () => { try { localStorage.setItem(LS_DONE, '1'); } catch { /* noop */ } };
+
+// ── Ilustrações (placeholders SVG; substitua por screenshots quando tiver) ──────
+const Frame = ({ children }: { children: React.ReactNode }) => (
+  <svg viewBox="0 0 320 180" width="100%" style={{ display: 'block' }} xmlns="http://www.w3.org/2000/svg">
+    <rect x="0" y="0" width="320" height="180" rx="12" fill="#f0f0ff" />
+    <rect x="0" y="0" width="320" height="26" rx="12" fill="#181826" />
+    <circle cx="14" cy="13" r="4" fill="#ff5f57" />
+    <circle cx="30" cy="13" r="4" fill="#febc2e" />
+    <circle cx="46" cy="13" r="4" fill="#28c840" />
+    {children}
+  </svg>
+);
+const artWelcome = (
+  <Frame>
+    <circle cx="160" cy="100" r="40" fill="#4945ff" />
+    <path d="M140 92h40a6 6 0 0 1 6 6v22a6 6 0 0 1-6 6h-22l-12 10v-10h-6a6 6 0 0 1-6-6V98a6 6 0 0 1 6-6Z" fill="#fff" />
+    <circle cx="150" cy="109" r="3" fill="#4945ff" /><circle cx="160" cy="109" r="3" fill="#4945ff" /><circle cx="170" cy="109" r="3" fill="#4945ff" />
+  </Frame>
+);
+const artChat = (
+  <Frame>
+    <rect x="30" y="44" width="180" height="18" rx="9" fill="#dcd9ff" />
+    <rect x="110" y="74" width="180" height="18" rx="9" fill="#4945ff" />
+    <rect x="30" y="104" width="140" height="18" rx="9" fill="#dcd9ff" />
+    <circle cx="270" cy="140" r="16" fill="#4945ff" /><text x="270" y="146" fontSize="16" textAnchor="middle" fill="#fff">🎤</text>
+  </Frame>
+);
+const artEdit = (
+  <Frame>
+    <rect x="30" y="50" width="120" height="80" rx="8" fill="#fff" stroke="#dcdce4" />
+    <rect x="42" y="64" width="80" height="10" rx="5" fill="#c0bfff" />
+    <rect x="42" y="84" width="96" height="8" rx="4" fill="#e6e6f0" />
+    <rect x="42" y="100" width="70" height="8" rx="4" fill="#e6e6f0" />
+    <path d="M170 90h70m0 0-14-12m14 12-14 12" stroke="#4945ff" strokeWidth="4" fill="none" strokeLinecap="round" />
+    <rect x="250" y="58" width="46" height="64" rx="6" fill="#28c840" opacity="0.18" />
+    <text x="273" y="96" fontSize="22" textAnchor="middle">✓</text>
+  </Frame>
+);
+const artPreview = (
+  <Frame>
+    <rect x="24" y="40" width="130" height="120" rx="8" fill="#fff" stroke="#dcdce4" />
+    <rect x="166" y="40" width="130" height="120" rx="8" fill="#fff" stroke="#dcdce4" />
+    <rect x="36" y="54" width="100" height="10" rx="5" fill="#c0bfff" />
+    <rect x="36" y="74" width="80" height="8" rx="4" fill="#e6e6f0" />
+    <rect x="178" y="54" width="106" height="40" rx="6" fill="#6bdaff" opacity="0.5" />
+    <rect x="178" y="104" width="80" height="8" rx="4" fill="#e6e6f0" />
+    <text x="158" y="120" fontSize="16" textAnchor="middle">👁️</text>
+  </Frame>
+);
+const artProvision = (
+  <Frame>
+    <rect x="40" y="60" width="60" height="60" rx="10" fill="#000" /><text x="70" y="98" fontSize="26" textAnchor="middle" fill="#fff">N</text>
+    <circle cx="160" cy="90" r="30" fill="#f9ffb5" stroke="#0b1722" strokeWidth="2" />
+    <path d="M110 90h20m100 0h-20" stroke="#4945ff" strokeWidth="4" strokeLinecap="round" />
+    <rect x="220" y="60" width="60" height="60" rx="10" fill="#4945ff" /><text x="250" y="98" fontSize="22" textAnchor="middle" fill="#fff">DB</text>
+  </Frame>
+);
+const artTranslate = (
+  <Frame>
+    <text x="80" y="105" fontSize="34" textAnchor="middle">🇧🇷</text>
+    <path d="M120 90h80m0 0-14-12m14 12-14 12" stroke="#4945ff" strokeWidth="4" fill="none" strokeLinecap="round" />
+    <text x="240" y="105" fontSize="34" textAnchor="middle">🌍</text>
+  </Frame>
+);
+
+type Step = { title: string; body: string; art: React.ReactNode };
+
+const STEPS: Record<Lang, Step[]> = {
+  en: [
+    { title: 'Welcome to MCP Chat', body: 'An AI assistant inside your Strapi admin that actually reads, edits and publishes your content via the native MCP server. This quick tour shows what it can do.', art: artWelcome },
+    { title: 'Just ask, in plain language', body: 'Type, talk (🎤 voice) or share your screen. Example: “Change the homepage hero title to Welcome”. No need to find the field yourself — the AI searches everything.', art: artChat },
+    { title: 'It edits & publishes for real', body: 'The assistant finds the text across content-types, components and dynamic zones, updates it and publishes — then confirms what changed.', art: artEdit },
+    { title: 'Side-by-side live preview', body: 'Toggle Live Preview to see your frontend next to the admin. After each edit it reloads on the same page you were viewing.', art: artPreview },
+    { title: 'Provision a frontend', body: 'Upload a Next.js or TanStack Start .zip — the AI infers the content model, you review it, and the plugin creates the content-types and seeds the data.', art: artProvision },
+    { title: 'Translate the whole site', body: 'Ask “translate the whole site to French” and it creates the locales and translates every localized field via Strapi’s native i18n.', art: artTranslate },
+  ],
+  pt: [
+    { title: 'Bem-vindo ao MCP Chat', body: 'Um assistente de IA dentro do admin do Strapi que realmente lê, edita e publica seu conteúdo via o MCP nativo. Este tour rápido mostra o que ele faz.', art: artWelcome },
+    { title: 'É só pedir, em linguagem natural', body: 'Escreva, fale (🎤 voz) ou compartilhe a tela. Ex.: “Troque o título do hero da home para Bem-vindo”. Não precisa achar o campo — a IA busca em tudo.', art: artChat },
+    { title: 'Ele edita e publica de verdade', body: 'O assistente acha o texto em content-types, componentes e dynamic zones, atualiza e publica — e confirma o que mudou.', art: artEdit },
+    { title: 'Preview ao vivo lado a lado', body: 'Ligue o Live Preview para ver seu frontend ao lado do admin. Após cada edição ele recarrega na mesma página que você estava vendo.', art: artPreview },
+    { title: 'Provisione um frontend', body: 'Suba um .zip Next.js ou TanStack Start — a IA infere o modelo de conteúdo, você revisa, e o plugin cria as content-types e semeia os dados.', art: artProvision },
+    { title: 'Traduza o site inteiro', body: 'Peça “traduza o site todo para francês” e ele cria os locales e traduz cada campo localizado via o i18n nativo do Strapi.', art: artTranslate },
+  ],
+};
+
+const L = {
+  en: { skip: 'Skip', back: 'Back', next: 'Next', done: 'Got it!', step: 'Step' },
+  pt: { skip: 'Pular', back: 'Voltar', next: 'Próximo', done: 'Entendi!', step: 'Passo' },
+};
+
+export const Onboarding = ({ lang, open, onClose }: { lang: Lang; open: boolean; onClose: () => void }) => {
+  const [i, setI] = useState(0);
+  const steps = STEPS[lang];
+  const t = L[lang];
+
+  useEffect(() => { if (open) setI(0); }, [open]);
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (!open) return;
+      if (e.key === 'Escape') finish();
+      if (e.key === 'ArrowRight') setI((v) => Math.min(steps.length - 1, v + 1));
+      if (e.key === 'ArrowLeft') setI((v) => Math.max(0, v - 1));
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [open, steps.length]);
+
+  if (!open) return null;
+  const finish = () => { markSeen(); onClose(); };
+  const last = i === steps.length - 1;
+  const s = steps[i];
+
+  return (
+    <div
+      onClick={finish}
+      style={{
+        position: 'fixed', inset: 0, zIndex: 2147483600,
+        background: 'rgba(10,10,25,0.55)', display: 'flex',
+        alignItems: 'center', justifyContent: 'center', padding: 16,
+      }}
+    >
+      <div
+        onClick={(e) => e.stopPropagation()}
+        style={{
+          width: 460, maxWidth: '100%', background: '#fff', borderRadius: 12,
+          boxShadow: '0 20px 60px rgba(0,0,0,0.35)', overflow: 'hidden',
+          fontFamily: 'inherit',
+        }}
+      >
+        <div style={{ padding: 16 }}>{s.art}</div>
+        <div style={{ padding: '0 20px 8px' }}>
+          <h2 style={{ margin: '4px 0 8px', fontSize: 18, color: '#181826' }}>{s.title}</h2>
+          <p style={{ margin: 0, fontSize: 14, lineHeight: 1.5, color: '#4a4a6a', minHeight: 64 }}>{s.body}</p>
+        </div>
+
+        {/* dots (hover para pular pra um passo) */}
+        <div style={{ display: 'flex', gap: 6, justifyContent: 'center', padding: '8px 0 4px' }}>
+          {steps.map((st, idx) => (
+            <button
+              key={idx}
+              onClick={() => setI(idx)}
+              title={`${t.step} ${idx + 1}: ${st.title}`}
+              style={{
+                width: idx === i ? 22 : 8, height: 8, borderRadius: 4, border: 'none',
+                background: idx === i ? '#4945ff' : '#d9d9e8', cursor: 'pointer',
+                transition: 'width .2s, background .2s',
+              }}
+            />
+          ))}
+        </div>
+
+        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', padding: 16, borderTop: '1px solid #eee' }}>
+          <button onClick={finish} style={{ background: 'none', border: 'none', color: '#8e8ea9', cursor: 'pointer', fontSize: 13 }}>
+            {t.skip}
+          </button>
+          <div style={{ display: 'flex', gap: 8 }}>
+            {i > 0 && (
+              <button onClick={() => setI((v) => v - 1)}
+                style={{ border: '1px solid #dcdce4', background: '#fff', color: '#32324d', borderRadius: 6, padding: '6px 14px', cursor: 'pointer', fontSize: 13 }}>
+                {t.back}
+              </button>
+            )}
+            <button
+              onClick={() => (last ? finish() : setI((v) => v + 1))}
+              style={{ border: 'none', background: '#4945ff', color: '#fff', borderRadius: 6, padding: '6px 16px', cursor: 'pointer', fontSize: 13, fontWeight: 600 }}
+            >
+              {last ? t.done : t.next}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+};

package/admin/src/components/PreviewPanel.tsx

@@ -27,12 +27,15 @@ type Props = {
   loading?: boolean;
   loadingText?: string;
   loadingError?: boolean;
+  /** modo rascunho: mostra conteúdo não publicado (draft) em vez do publicado. */
+  draft?: boolean;
+  onToggleDraft?: () => void;
 };
 
 const MIN_W = 320;
 const clampW = (w: number) => Math.max(MIN_W, Math.min(window.innerWidth - 360, w));
 
-export const PreviewPanel = ({ open, src, displayUrl, onUrl, iframeKey, onReload, onClose, loading, loadingText, loadingError }: Props) => {
+export const PreviewPanel = ({ open, src, displayUrl, onUrl, iframeKey, onReload, onClose, loading, loadingText, loadingError, draft, onToggleDraft }: Props) => {
   const [width, setWidth] = useState(() => Math.round(window.innerWidth * 0.42));
   const [draftUrl, setDraftUrl] = useState(displayUrl);
   const [resizing, setResizing] = useState(false);
@@ -132,6 +135,24 @@ export const PreviewPanel = ({ open, src, displayUrl, onUrl, iframeKey, onReload
             border: '1px solid #4a4a6a', background: '#0f0f1a', color: '#fff',
           }}
         />
+        {onToggleDraft && (
+          <button
+            onClick={onToggleDraft}
+            title={
+              draft
+                ? 'Mostrando RASCUNHO (conteúdo não publicado). Clique para ver o publicado (Live).'
+                : 'Mostrando publicado (Live). Clique para ver o RASCUNHO (draft).'
+            }
+            style={{
+              ...hdrBtn,
+              background: draft ? '#8c4bff' : '#2a2a45',
+              borderColor: draft ? '#8c4bff' : '#4a4a6a',
+              whiteSpace: 'nowrap',
+            }}
+          >
+            {draft ? '📝 Draft' : '🌐 Live'}
+          </button>
+        )}
         <button onClick={onReload} title="Recarregar" style={hdrBtn}>↻</button>
         <button onClick={onClose} title="Fechar" style={hdrBtn}>✕</button>
       </div>

package/admin/src/components/StackLogos.tsx

@@ -0,0 +1,60 @@
+/**
+ * Logos dos stacks de frontend suportados pela provisão (Next.js + TanStack Start).
+ * SVG inline (sem assets externos) para não depender do bundler/CSP.
+ */
+
+const NextLogo = ({ size = 28 }: { size?: number }) => (
+  <svg width={size} height={size} viewBox="0 0 180 180" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="Next.js">
+    <mask id="nextmask" style={{ maskType: 'alpha' }} maskUnits="userSpaceOnUse" x="0" y="0" width="180" height="180">
+      <circle cx="90" cy="90" r="90" fill="black" />
+    </mask>
+    <g mask="url(#nextmask)">
+      <circle cx="90" cy="90" r="90" fill="black" />
+      <path d="M149.508 157.52 69.142 54H54v71.97h12.114V69.384l73.885 95.461a90.304 90.304 0 0 0 9.509-7.325Z" fill="url(#nextfill0)" />
+      <rect x="115" y="54" width="12" height="72" fill="url(#nextfill1)" />
+    </g>
+    <defs>
+      <linearGradient id="nextfill0" x1="109" y1="116.5" x2="144.5" y2="160.5" gradientUnits="userSpaceOnUse">
+        <stop stopColor="white" />
+        <stop offset="1" stopColor="white" stopOpacity="0" />
+      </linearGradient>
+      <linearGradient id="nextfill1" x1="121" y1="54" x2="120.799" y2="106.875" gradientUnits="userSpaceOnUse">
+        <stop stopColor="white" />
+        <stop offset="1" stopColor="white" stopOpacity="0" />
+      </linearGradient>
+    </defs>
+  </svg>
+);
+
+const TanStackLogo = ({ size = 28 }: { size?: number }) => (
+  <svg width={size} height={size} viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="TanStack">
+    <defs>
+      <linearGradient id="tsgrad" x1="0" y1="0" x2="64" y2="64" gradientUnits="userSpaceOnUse">
+        <stop stopColor="#6BDAFF" />
+        <stop offset="0.5" stopColor="#F9FFB5" />
+        <stop offset="1" stopColor="#FFA770" />
+      </linearGradient>
+    </defs>
+    <circle cx="32" cy="32" r="30" fill="url(#tsgrad)" stroke="#0B1722" strokeWidth="3" />
+    <ellipse cx="24" cy="27" rx="6" ry="7" fill="#0B1722" />
+    <ellipse cx="40" cy="27" rx="6" ry="7" fill="#0B1722" />
+    <circle cx="26" cy="26" r="2" fill="#fff" />
+    <circle cx="42" cy="26" r="2" fill="#fff" />
+    <path d="M20 42c4 5 20 5 24 0" stroke="#0B1722" strokeWidth="3" strokeLinecap="round" fill="none" />
+  </svg>
+);
+
+const chip: React.CSSProperties = {
+  display: 'inline-flex', alignItems: 'center', gap: 8,
+  border: '1px solid #dcdce4', background: '#fff', borderRadius: 8,
+  padding: '6px 12px', fontSize: 13, fontWeight: 600, color: '#32324d',
+};
+
+export const StackLogos = () => (
+  <div style={{ display: 'flex', gap: 10, flexWrap: 'wrap', alignItems: 'center' }}>
+    <span style={chip}><NextLogo /> Next.js</span>
+    <span style={chip}><TanStackLogo /> TanStack Start</span>
+  </div>
+);
+
+export { NextLogo, TanStackLogo };