strapi-plugin-mcp-chat 0.3.1 → 0.6.0

package/server/src/mcp/tools/traduzir.ts

@@ -1,36 +1,30 @@
 import { z } from '@strapi/utils';
-import type { StrapiMcpToolModule } from '../types';
+import { defineTool } from '../define';
 import { createContentTools } from '../../content-tools';
 
-const tool: StrapiMcpToolModule = {
-  register(registerTool) {
-    registerTool({
-      name: 'mcp_chat_traduzir',
-      title: 'Translate localized content',
-      description:
-        'Translate localized content into one or more languages. Creates missing locales, translates field by field (long text is split and reassembled, never overflows) and publishes. Without uid/documentId, translates ALL localized content-types. Handles many locales at once.',
-      resolveInputSchema: () =>
-        z.object({
-          target_locales: z.array(z.string()).min(1),
-          source_locale: z.string().optional(),
-          uid: z.string().optional(),
-          documentId: z.string().optional(),
-          publish: z.boolean().optional(),
-        }),
-      resolveOutputSchema: () =>
-        z.object({
-          ok: z.boolean().optional(),
-          source: z.string().optional(),
-          por_locale: z.array(z.any()).optional(),
-          erro: z.string().optional(),
-        }),
-      auth: { policies: [{ action: 'plugin::content-manager.explorer.update' }] },
-      createHandler: (strapi: any) => async ({ args }: any) => {
-        const r = await createContentTools(strapi).traduzir(args);
-        return { content: [{ type: 'text', text: JSON.stringify(r) }], structuredContent: r };
-      },
-    });
+export default defineTool({
+  name: 'mcp_chat_traduzir',
+  title: 'Translate localized content',
+  description:
+    'Translate localized content into one or more languages. Creates missing locales, translates field by field (long text is split and reassembled, never overflows) and publishes (only on content-types with Draft & Publish). Without uid/documentId, translates ALL localized content-types. Handles many locales at once.',
+  resolveInputSchema: () =>
+    z.object({
+      target_locales: z.array(z.string()).min(1),
+      source_locale: z.string().optional(),
+      uid: z.string().optional(),
+      documentId: z.string().optional(),
+      publish: z.boolean().optional(),
+    }),
+  resolveOutputSchema: () =>
+    z.object({
+      ok: z.boolean().optional(),
+      source: z.string().optional(),
+      por_locale: z.array(z.any()).optional(),
+      erro: z.string().optional(),
+    }),
+  auth: { policies: [{ action: 'plugin::content-manager.explorer.update' }] },
+  createHandler: (strapi: any) => async ({ args }) => {
+    const r = await createContentTools(strapi).traduzir(args);
+    return { content: [{ type: 'text', text: JSON.stringify(r) }], structuredContent: r };
   },
-};
-
-export default tool;
+});

package/server/src/mcp/types.ts

@@ -1,11 +1,14 @@
 /**
- * Tipos para os módulos de tool do MCP (padrão inspirado no exemplo do Paul
- * Bratslavsky: github.com/PaulBratslavsky/strapi-mcp-demo-and-tool-extension).
- * Cada tool é um módulo com um `register(registerTool, strapi)`.
+ * Tipos do MCP do plugin. As tools agora são DEFINIÇÕES puras criadas com
+ * `defineTool` (ver ./define.ts) e registradas a partir de um array — alinhado
+ * à direção do PR #26603 (`ai.mcp.defineTool`). Re-exportamos os tipos de
+ * `./define` aqui por conveniência/compatibilidade.
  */
-
-export type RegisterTool = (toolDef: Record<string, any>) => void;
-
-export type StrapiMcpToolModule = {
-  register: (registerTool: RegisterTool, strapi: any) => void;
-};
+export type {
+  McpToolDef,
+  McpResourceDef,
+  McpPromptDef,
+  McpToolResult,
+  McpAuth,
+  RegisterTool,
+} from './define';

package/server/src/mcp-client.ts

@@ -14,6 +14,18 @@ const baseHeaders = {
   Accept: 'application/json, text/event-stream',
 };
 
+/** fetch com timeout (AbortController) — nenhum endpoint MCP pode pendurar uma
+ *  request do Strapi indefinidamente. */
+const fetchT = async (url: string, opts: any, timeoutMs = 8000): Promise<Response> => {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...opts, signal: ctrl.signal });
+  } finally {
+    clearTimeout(t);
+  }
+};
+
 const parseSse = (text: string): any => {
   const dataLines = text
     .split('\n')
@@ -50,7 +62,7 @@ export class McpClient {
   }
 
   async init(): Promise<void> {
-    const res = await fetch(this.url, {
+    const res = await fetchT(this.url, {
       method: 'POST',
       headers: this.headers(),
       body: JSON.stringify({
@@ -67,7 +79,7 @@ export class McpClient {
     this.sessionId = res.headers.get('mcp-session-id') || undefined;
     await res.text();
     // Notifica que o handshake terminou (sem corpo de resposta relevante).
-    await fetch(this.url, {
+    await fetchT(this.url, {
       method: 'POST',
       headers: this.headers(),
       body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }),
@@ -75,7 +87,7 @@ export class McpClient {
   }
 
   private async rpc(method: string, params: any, id: number): Promise<any> {
-    const res = await fetch(this.url, {
+    const res = await fetchT(this.url, {
       method: 'POST',
       headers: this.headers(),
       body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),

package/server/src/provision/infer.ts

@@ -80,32 +80,53 @@ interface CollectResult {
   tree: string[];
 }
 
-/** Coleta os arquivos de código mais promissores (com conteúdo) + árvore. */
+/** Detecta um array de objetos declarado inline (ex.: `const services = [{...}]`),
+ *  inclusive DENTRO de componentes — é onde os frontends Lovable/Figma guardam
+ *  os dados (serviços, avaliações, etc.). */
+function hasInlineDataArray(content: string): boolean {
+  return /(?:export\s+)?const\s+\w+\s*(?::[^=\n]+)?=\s*\[\s*\{/.test(content);
+}
+
+/**
+ * Coleta os arquivos de código mais promissores (com conteúdo) + árvore.
+ *
+ * Ciente de conteúdo: além da pontuação por caminho, dá um bônus forte a QUALQUER
+ * arquivo que contenha um array de objetos inline — assim componentes (.tsx/.jsx)
+ * com `const X = [{...}]` entram na análise (antes eram excluídos por serem
+ * componentes, e os dados embutidos neles nunca eram modelados).
+ */
 function collectFiles(frontendDir: string): CollectResult {
   const all: string[] = [];
   walk(frontendDir, frontendDir, all);
-
   const tree = all.slice().sort();
-  // candidatos com conteúdo de array/objeto exportado, por pontuação
-  const ranked = all
-    .map((rel) => ({ rel, s: score(rel) }))
-    .filter((x) => x.s > 0)
-    .sort((a, b) => b.s - a.s);
 
-  const files: { rel: string; content: string }[] = [];
-  let total = 0;
-  for (const { rel } of ranked) {
-    if (files.length >= MAX_FILES || total >= MAX_TOTAL_CHARS) break;
+  // lê e pontua cada candidato (pontuação por caminho + bônus por dados inline).
+  const scored: { rel: string; content: string; s: number }[] = [];
+  for (const rel of all) {
+    let content: string;
     try {
-      let content = fs.readFileSync(path.join(frontendDir, rel), 'utf8');
-      // só interessa se houver dados estruturados ou tipos
-      if (!/export\s+(const|default|type|interface)/.test(content)) continue;
-      if (content.length > MAX_FILE_CHARS) content = content.slice(0, MAX_FILE_CHARS) + '\n/* …truncado… */';
-      files.push({ rel, content });
-      total += content.length;
+      content = fs.readFileSync(path.join(frontendDir, rel), 'utf8');
     } catch {
-      /* ignore */
+      continue;
     }
+    const dataArray = hasInlineDataArray(content);
+    const hasExport = /export\s+(const|default|type|interface)/.test(content);
+    if (!hasExport && !dataArray) continue; // sem dados nem exports → ignora
+    let s = score(rel);
+    if (dataArray) s += 8; // arrays de objetos inline valem muito (incl. componentes)
+    if (s <= 0) continue;
+    scored.push({ rel, content, s });
+  }
+  scored.sort((a, b) => b.s - a.s);
+
+  const files: { rel: string; content: string }[] = [];
+  let total = 0;
+  for (const it of scored) {
+    if (files.length >= MAX_FILES || total >= MAX_TOTAL_CHARS) break;
+    let content = it.content;
+    if (content.length > MAX_FILE_CHARS) content = content.slice(0, MAX_FILE_CHARS) + '\n/* …truncado… */';
+    files.push({ rel: it.rel, content });
+    total += content.length;
   }
   return { files, tree };
 }
@@ -341,13 +362,15 @@ Gere um JSON "strapi.manifest.json" com ESTE formato:
 
 REGRAS:
 - Crie uma content-type para cada COLEÇÃO de dados (arrays de objetos). Use os MESMOS nomes de campo do código.
+- IMPORTANTE: muitos frontends guardam os dados em arrays declarados INLINE dentro de componentes (.tsx/.jsx), ex.: \`const services = [{ name, price, desc }]\`, \`const reviews = [...]\`, \`const hours = [...]\`. TRATE esses arrays como coleções e modele cada um como um collectionType, mesmo que estejam dentro de um componente de UI.
+- Ao modelar um array desses, inclua SOMENTE os campos que são dados/texto (ex.: name, price, desc, label, href, value). IGNORE props que são código/apresentação: componentes de ícone (ex.: \`icon: Scissors\`), elementos React, funções, classes CSS, imports de imagem.
 - Dados de "configuração do site" (objeto único: nome, telefone, etc.) → singleType.
 - Campos string longos/descrições → "text" ou "richtext". Listas de strings → "json".
 - Use "date"/"datetime" SOMENTE para datas ISO completas (YYYY-MM-DD). Datas parciais como "2025-04" ou textos livres → use "string" (senão o seed falha).
 - Imagens (imports de assets ou caminhos) → "media" (NÃO coloque o valor da imagem no seed; omita o campo no seed).
-- Em "seed", extraia o conteúdo REAL hardcoded no código, omitindo campos de mídia e relações.
+- Em "seed", copie o conteúdo REAL hardcoded no código, VERBATIM (exatamente como está, sem reescrever, traduzir ou inventar), omitindo campos de mídia e relações. Todo valor de seed TEM que existir literalmente no código fornecido.
 - Foque APENAS em coleções/objetos de dados — NÃO precisa modelar textos soltos de UI (isso é tratado à parte).
-- NÃO invente. singularName kebab-case, sem repetir. Relações só apontam para types definidos por você.
+- NÃO invente NADA. Se não tiver certeza de um valor, omita-o. singularName kebab-case, sem repetir. Relações só apontam para types definidos por você.
 - Se não houver coleções de dados, devolva contentTypes: [] e seed: [].
 - Responda APENAS com o JSON, nada de markdown.
 
@@ -465,6 +488,55 @@ export async function inferManifest(
     result.warnings.push('Sem OPENAI_API_KEY: modelando os TEXTOS (determinístico); coleções de dados não inferidas.');
   }
 
+  // 3b) TRAVA ANTI-ALUCINAÇÃO (determinística): todo valor de seed gerado pela IA
+  //     TEM que existir literalmente no código analisado. Construímos um "haystack"
+  //     com o código-fonte real (não truncado) e descartamos entradas cujo conteúdo
+  //     não aparece nele. Assim a IA não consegue inventar dados — só transcrever.
+  if (dataCts.length && dataSeed.length) {
+    const parts: string[] = [];
+    for (const f of collected.files) {
+      try {
+        parts.push(fs.readFileSync(path.join(frontendDir, f.rel), 'utf8'));
+      } catch {
+        parts.push(f.content);
+      }
+    }
+    const norm = (x: any) => String(x).toLowerCase().replace(/[^a-z0-9]+/g, '');
+    const hay = norm(parts.join('\n'));
+    const present = (v: any) => {
+      if (typeof v !== 'string') return false;
+      const n = norm(v);
+      return n.length >= 4 && hay.includes(n); // valores curtos não são distintivos
+    };
+
+    const keep = new Set<string>();
+    const verifiedSeed: any[] = [];
+    let droppedEntries = 0;
+    for (const grp of dataSeed) {
+      const entries = (grp.entries ?? []).filter((e: any) => {
+        const ok = Object.values(e).some(present);
+        if (!ok) droppedEntries++;
+        return ok;
+      });
+      if (entries.length) {
+        verifiedSeed.push({ ...grp, entries });
+        keep.add(grp.singularName);
+      }
+    }
+    // coleções de dados sem NENHUMA entrada verificada são provável alucinação → fora.
+    const verifiedCts = dataCts.filter(
+      (ct: any) => ct.kind === 'singleType' || keep.has(ct.singularName)
+    );
+    const droppedCts = dataCts.length - verifiedCts.length;
+    if (droppedEntries || droppedCts) {
+      result.warnings.push(
+        `Anti-alucinação: descartei ${droppedEntries} entrada(s) e ${droppedCts} content-type(s) cujos valores não batiam com o código.`
+      );
+    }
+    dataCts = verifiedCts;
+    dataSeed = verifiedSeed;
+  }
+
   // 4) TEXTOS via extração DETERMINÍSTICA (garantido, sem IA, escala em qualquer tamanho)
   const budget = 60 - dataCts.length - 1; // teto de content-types do manifest
   const page = buildPageContentTypes(pageTexts, budget);

package/server/src/provision/link.ts

@@ -4,6 +4,7 @@ import type { Manifest } from './manifest';
 import { adapterForManifest, type LinkContext } from './adapters';
 import { generateTypes } from './types-gen';
 import { apiUid } from './generate';
+import { FRONTEND_BASE_PORT } from './runner';
 
 /**
  * Link: conecta o frontend já instalado à Strapi.
@@ -31,7 +32,11 @@ export interface LinkResult {
   envPreserved: string[];
   typesFile: string;
   previewFile: string;
-  previewAction: 'created' | 'sidecar' | 'skipped';
+  previewAction: 'created' | 'merged' | 'skipped';
+  /** vars adicionadas ao .env do BACKEND (CLIENT_URL/PREVIEW_SECRET). */
+  backendEnvAdded: string[];
+  /** ação no config/middlewares (CSP frame-src para o iframe do preview). */
+  cspAction: 'patched' | 'already' | 'manual' | 'skipped';
   errors: string[];
 }
 
@@ -79,44 +84,68 @@ function mergeEnv(
 // config de Preview da Strapi
 // ---------------------------------------------------------------------------
 
+// marca que o config/admin.ts já tem o preview do mcp-chat mesclado (idempotência).
+const PREVIEW_MARKER = 'mcp-chat:preview-merged';
+const PREVIEW_MODULE = 'mcp-chat-preview';
+
 /**
- * Gera o conteúdo de config/admin.ts com o Preview configurado: mapeia cada uid
- * para a rota de preview declarada no manifest e monta a URL com o slug do doc.
+ * Gera o MÓDULO de preview (config/mcp-chat-preview.ts): default-exporta o
+ * fragmento { preview: {...} } do config/admin, com o handler que mapeia uid ->
+ * rota do frontend. É 100% owned pelo gerador (sempre reescrito).
+ *
+ * Decisões importantes:
+ *  - Rota DEFAULT "/" para qualquer type sem rota declarada — assim o botão
+ *    Preview SEMPRE tem URL (singleTypes de uma landing page caem aqui).
+ *  - URL por framework: SPA (Vite/TanStack) abre a página direta com query;
+ *    Next usa a convenção /api/preview (draft mode).
  */
-export function buildPreviewConfig(manifest: Manifest): string {
+export function buildPreviewConfig(
+  manifest: Manifest,
+  framework: string = manifest.framework
+): string {
   const routes: Record<string, string> = {};
   for (const ct of manifest.contentTypes) {
-    if (ct.preview?.route) routes[apiUid(ct.singularName)] = ct.preview.route;
+    // rota declarada quando há página de detalhe; senão a raiz da app.
+    routes[apiUid(ct.singularName)] = ct.preview?.route ?? '/';
   }
   const routesJson = JSON.stringify(routes, null, 2);
+  const isNext = framework === 'next';
+
+  // ramo de montagem da URL final, por framework.
+  const urlBranch = isNext
+    ? `        // Next.js: rota de draft mode que seta o cookie e redireciona p/ \`path\`.
+        const qs = new URLSearchParams({ secret, status: status ?? 'draft', path: pathname });
+        return \`\${clientUrl}/api/preview?\${qs.toString()}\`;`
+    : `        // SPA (Vite/TanStack): abre a página direta; o front lê ?preview/status.
+        const qs = new URLSearchParams({ preview: '1', status: status ?? 'draft', secret });
+        return \`\${clientUrl}\${pathname}?\${qs.toString()}\`;`;
 
-  return `// Preview gerado pelo mcp-chat a partir do strapi.manifest.json.
+  return `// Preview gerado pelo mcp-chat a partir do strapi.manifest.json (framework: ${framework}).
 // Mapa uid -> rota do frontend (placeholders :campo são preenchidos pelo doc).
+// Este arquivo é mesclado em config/admin.ts — não precisa editá-lo à mão.
 const PREVIEW_ROUTES: Record<string, string> = ${routesJson};
 
-export default ({ env }) => ({
-  auth: {
-    secret: env('ADMIN_JWT_SECRET'),
-  },
-  apiToken: { salt: env('API_TOKEN_SALT') },
-  transfer: { token: { salt: env('TRANSFER_TOKEN_SALT') } },
+export default ({ env }: { env: any }) => ({
   preview: {
     enabled: true,
     config: {
       allowedOrigins: [env('CLIENT_URL', 'http://localhost:3000')],
       async handler(uid: string, { documentId, locale, status }: any) {
-        const route = PREVIEW_ROUTES[uid];
-        if (!route) return null;
-        const doc = await strapi.documents(uid as any).findOne({ documentId, locale });
-        if (!doc) return null;
-        // substitui :campo pelos valores do documento (ex.: :slug)
-        const pathname = route.replace(/:([a-zA-Z0-9_]+)/g, (_m, f) =>
-          encodeURIComponent(String((doc as any)[f] ?? ''))
-        );
+        const route = PREVIEW_ROUTES[uid] ?? '/';
         const clientUrl = env('CLIENT_URL', 'http://localhost:3000');
         const secret = env('PREVIEW_SECRET', '');
-        const qs = new URLSearchParams({ secret, status: status ?? 'draft', path: pathname });
-        return \`\${clientUrl}/api/preview?\${qs.toString()}\`;
+
+        // só busca o doc se a rota tiver placeholders (ex.: :slug) a preencher.
+        let pathname = route;
+        if (pathname.includes(':')) {
+          const doc = await strapi.documents(uid as any).findOne({ documentId, locale });
+          if (!doc) return null;
+          pathname = pathname.replace(/:([a-zA-Z0-9_]+)/g, (_m, f) =>
+            encodeURIComponent(String((doc as any)[f] ?? ''))
+          );
+        }
+
+${urlBranch}
       },
     },
   },
@@ -124,6 +153,112 @@ export default ({ env }) => ({
 `;
 }
 
+/** admin.ts auto-contido (quando o projeto ainda não tem um). */
+function buildStandaloneAdmin(): string {
+  return `// ${PREVIEW_MARKER} — admin.ts gerado pelo mcp-chat (preview incluído).
+import previewConfig from './${PREVIEW_MODULE}';
+
+export default ({ env }: { env: any }) => ({
+  auth: { secret: env('ADMIN_JWT_SECRET') },
+  apiToken: { salt: env('API_TOKEN_SALT') },
+  transfer: { token: { salt: env('TRANSFER_TOKEN_SALT') } },
+  secrets: { encryptionKey: env('ENCRYPTION_KEY') },
+  flags: {
+    nps: env.bool('FLAG_NPS', true),
+    promoteEE: env.bool('FLAG_PROMOTE_EE', true),
+  },
+  ...previewConfig({ env }),
+});
+`;
+}
+
+/**
+ * Wrapper que PRESERVA o admin existente (movido p/ admin.base.ts) e mescla o
+ * preview por cima. Como o admin é mesclado e não substituído, qualquer config
+ * do usuário (auth, flags, custom) continua valendo.
+ */
+function buildAdminWrapper(): string {
+  return `// ${PREVIEW_MARKER} — preview do mcp-chat mesclado sobre o admin original.
+// Sua config original está preservada em ./admin.base — edite lá, não aqui.
+import base from './admin.base';
+import previewConfig from './${PREVIEW_MODULE}';
+
+export default (ctx: any) => {
+  const b = typeof base === 'function' ? (base as any)(ctx) : (base ?? {});
+  return { ...b, ...previewConfig(ctx) };
+};
+`;
+}
+
+/** Lê a porta de dev do frontend (Vite) do config; null se não achar. */
+export function detectFrontendPort(frontendDir: string): number | null {
+  for (const f of ['vite.config.ts', 'vite.config.js', 'vite.config.mjs']) {
+    try {
+      const c = fs.readFileSync(path.join(frontendDir, f), 'utf8');
+      const m = c.match(/port\s*:\s*(\d{2,5})/);
+      if (m) return parseInt(m[1], 10);
+    } catch {
+      /* ignore */
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// CSP do admin: liberar frame-src para o iframe do preview
+// ---------------------------------------------------------------------------
+
+const CSP_MARKER = 'mcp-chat:csp-frame';
+
+/** Bloco strapi::security com frame-src liberado para o dev server do preview. */
+function securityBlock(): string {
+  return `  // ${CSP_MARKER} — libera o frame-src p/ o admin embutir o preview do frontend
+  // (dev server local em qualquer porta). Sem isto a CSP padrão (default-src 'self')
+  // bloqueia o iframe e o preview fica em branco.
+  {
+    name: 'strapi::security',
+    config: {
+      contentSecurityPolicy: {
+        useDefaults: true,
+        directives: {
+          'connect-src': ["'self'", 'https:', 'http:'],
+          'frame-src': ["'self'", 'http://localhost:*', 'http://127.0.0.1:*'],
+          'img-src': ["'self'", 'data:', 'blob:', 'market-assets.strapi.io'],
+          'media-src': ["'self'", 'data:', 'blob:'],
+          upgradeInsecureRequests: null,
+        },
+      },
+    },
+  },`;
+}
+
+/**
+ * Garante que o config/middlewares tenha frame-src liberado p/ o preview.
+ * Não-destrutivo e idempotente:
+ *  - já tem o marcador → 'already';
+ *  - tem o `'strapi::security'` string padrão → troca pelo bloco com frame-src → 'patched';
+ *  - já é um objeto custom de security → 'manual' (não mexe; reporta p/ o usuário ajustar).
+ */
+function patchSecurityMiddleware(strapiAppDir: string, dryRun?: boolean): LinkResult['cspAction'] {
+  const configDir = path.join(strapiAppDir, 'config');
+  const file = ['middlewares.ts', 'middlewares.js'].find((f) =>
+    fs.existsSync(path.join(configDir, f))
+  );
+  if (!file) return 'skipped';
+  const p = path.join(configDir, file);
+  const content = fs.readFileSync(p, 'utf8');
+
+  if (content.includes(CSP_MARKER) || content.includes("'frame-src'")) return 'already';
+
+  // troca a entrada string padrão pelo bloco objeto (cobre o starter do Strapi).
+  // O bloco já vem com indentação de 2 espaços, igual ao array do starter.
+  const m = content.match(/^[ \t]*['"]strapi::security['"]\s*,/m);
+  if (!m) return 'manual'; // já customizado de outra forma → não arrisca
+  const next = content.replace(m[0], securityBlock());
+  if (!dryRun) fs.writeFileSync(p, next, 'utf8');
+  return 'patched';
+}
+
 // ---------------------------------------------------------------------------
 // orquestração do link
 // ---------------------------------------------------------------------------
@@ -146,6 +281,8 @@ export function linkFrontend(
     typesFile: 'strapi-types.ts',
     previewFile: 'config/admin.ts',
     previewAction: 'skipped',
+    backendEnvAdded: [],
+    cspAction: 'skipped',
     errors: [],
   };
 
@@ -177,27 +314,87 @@ export function linkFrontend(
     result.errors.push(`types: ${e?.message ?? e}`);
   }
 
-  // 3) config de Preview (não-destrutivo)
+  // 3) config de Preview — merge REAL no config/admin.ts (não sidecar morto).
   try {
-    const adminPath = path.join(opts.strapiAppDir, 'config', 'admin.ts');
-    const content = buildPreviewConfig(manifest);
-    if (fs.existsSync(adminPath)) {
-      // não sobrescreve config existente: escreve sidecar e reporta
-      result.previewFile = 'config/admin.mcp-chat-preview.ts';
-      const sidecar = path.join(opts.strapiAppDir, 'config', 'admin.mcp-chat-preview.ts');
-      if (!opts.dryRun) fs.writeFileSync(sidecar, content, 'utf8');
-      result.previewAction = 'sidecar';
-    } else {
-      if (!opts.dryRun) {
-        fs.mkdirSync(path.dirname(adminPath), { recursive: true });
-        fs.writeFileSync(adminPath, content, 'utf8');
+    const configDir = path.join(opts.strapiAppDir, 'config');
+    if (!ensureInside(opts.strapiAppDir, configDir)) throw new Error('config fora do strapiAppDir');
+
+    const adminPath = path.join(configDir, 'admin.ts');
+    const adminBasePath = path.join(configDir, 'admin.base.ts');
+    const modulePath = path.join(configDir, `${PREVIEW_MODULE}.ts`);
+
+    if (!opts.dryRun) {
+      fs.mkdirSync(configDir, { recursive: true });
+      // 3a) módulo de preview — sempre (re)escrito (owned pelo gerador).
+      fs.writeFileSync(modulePath, buildPreviewConfig(manifest, adapter.framework), 'utf8');
+      // limpa o sidecar morto de versões antigas, se existir.
+      try {
+        fs.unlinkSync(path.join(configDir, 'admin.mcp-chat-preview.ts'));
+      } catch {
+        /* não existia */
       }
+    }
+    result.previewFile = `config/${PREVIEW_MODULE}.ts`;
+
+    if (!fs.existsSync(adminPath)) {
+      // 3b) sem admin.ts: cria um auto-contido já com o preview.
+      if (!opts.dryRun) fs.writeFileSync(adminPath, buildStandaloneAdmin(), 'utf8');
       result.previewAction = 'created';
+    } else {
+      const adminContent = fs.readFileSync(adminPath, 'utf8');
+      if (!adminContent.includes(PREVIEW_MARKER)) {
+        // 3c) admin.ts do usuário: preserva em admin.base.ts e troca por wrapper.
+        if (!opts.dryRun) {
+          if (!fs.existsSync(adminBasePath)) {
+            fs.writeFileSync(adminBasePath, adminContent, 'utf8');
+          }
+          fs.writeFileSync(adminPath, buildAdminWrapper(), 'utf8');
+        }
+      }
+      // se já tinha o marcador, só o módulo (3a) foi atualizado — idempotente.
+      result.previewAction = 'merged';
     }
   } catch (e: any) {
     result.errors.push(`preview: ${e?.message ?? e}`);
   }
 
+  // 4) .env do BACKEND: CLIENT_URL (origem do iframe + allowedOrigins) e, se houver,
+  //    PREVIEW_SECRET. Aditivo: nunca sobrescreve o que o usuário já definiu.
+  //
+  // CRÍTICO: o preview NATIVO do Strapi usa CLIENT_URL, e ele PRECISA bater com a
+  // porta onde o runner sobe o dev server. O runner ignora o vite.config e usa
+  // FRONTEND_BASE_PORT — então CLIENT_URL tem que apontar pra ESSA porta, não pra
+  // porta do vite.config (senão o preview nativo abre uma porta morta).
+  try {
+    const clientUrl =
+      opts.context.frontendUrl || `http://localhost:${FRONTEND_BASE_PORT}`;
+    const backendVars: Record<string, string> = { CLIENT_URL: clientUrl };
+    if (opts.context.previewSecret) backendVars.PREVIEW_SECRET = opts.context.previewSecret;
+
+    const backendEnvPath = path.join(opts.strapiAppDir, '.env');
+    if (ensureInside(opts.strapiAppDir, backendEnvPath)) {
+      const existing = fs.existsSync(backendEnvPath) ? fs.readFileSync(backendEnvPath, 'utf8') : '';
+      const { content, added } = mergeEnv(existing, backendVars);
+      result.backendEnvAdded = added;
+      if (!opts.dryRun && added.length) fs.writeFileSync(backendEnvPath, content, 'utf8');
+    }
+  } catch (e: any) {
+    result.errors.push(`backend env: ${e?.message ?? e}`);
+  }
+
+  // 5) CSP do admin: libera frame-src p/ o iframe do preview (senão fica em branco).
+  try {
+    result.cspAction = patchSecurityMiddleware(opts.strapiAppDir, opts.dryRun);
+    if (result.cspAction === 'manual') {
+      result.errors.push(
+        'CSP: config/middlewares já tem strapi::security customizado — adicione manualmente ' +
+          "frame-src 'self' http://localhost:* http://127.0.0.1:* para o preview embutir o frontend."
+      );
+    }
+  } catch (e: any) {
+    result.errors.push(`csp: ${e?.message ?? e}`);
+  }
+
   result.ok = result.errors.length === 0;
   return result;
 }

package/server/src/provision/orchestrate.ts

@@ -6,8 +6,9 @@ import { writeApis, requestReload, type WriteResult } from './write';
 export { requestReload };
 import { seedContent, type SeedResult } from './seed';
 import { linkFrontend, type LinkResult } from './link';
+import { FRONTEND_BASE_PORT } from './runner';
 import { grantPublicRead, type PermissionsResult } from './permissions';
-import { adapterForManifest, type LinkContext } from './adapters';
+import { type LinkContext } from './adapters';
 import { apiUid } from './generate';
 
 /**
@@ -206,9 +207,9 @@ export async function runPendingProvision(
 
   // grava o resumo de conclusão para a UI anunciar "preview pronto".
   try {
-    const adapter = adapterForManifest(marker.manifest);
+    // mesma porta do runner (onde o dev server realmente sobe), p/ o preview bater.
     const previewUrl =
-      marker.context.frontendUrl || `http://localhost:${adapter.defaultPort}`;
+      marker.context.frontendUrl || `http://localhost:${FRONTEND_BASE_PORT}`;
     const done: ProvisionDone = {
       name: marker.manifest.name,
       framework: marker.manifest.framework,