@12-apps/mcp 3.5.0 → 3.6.0

package/src/guide.ts

@@ -87,138 +87,6 @@ export interface AiHostGuide {
   pluginUrl?: string;
 }
 
-const CONNECTOR_TAIL: readonly string[] = [
-  "Deixe OAuth Client ID e Client Secret em branco — não é preciso gerar credenciais: a loja registra o conector automaticamente no primeiro acesso.",
-  "Confirme e clique em Connect: abre a tela de login da loja — entre com a SUA conta de lojista e autorize o acesso.",
-  "Pronto: ative o conector na conversa para o assistente consultar e operar a sua loja.",
-];
-
-/**
- * ChatGPT's two-stage configuration (Developer mode is now required before a
- * connector can be created). Stage 1 enables Developer mode in Security & login;
- * stage 2 creates the connector and signs in — which registers the connection on
- * the store side, so no prompt needs to be pasted afterwards.
- */
-function chatgptConfigureStages(
-  platformName: string,
-): readonly AiHostConfigureStage[] {
-  return [
-    {
-      id: "enable-dev-mode",
-      label: "enable developer mode",
-      link: {
-        url: "https://chatgpt.com/plugins#settings/Security",
-        label: "Abrir Segurança e login",
-      },
-      steps: [
-        "Ative o Modo desenvolvedor em Settings › Security and login (Segurança e login).",
-      ],
-    },
-    {
-      id: "configurar",
-      label: "configurar",
-      link: {
-        url: "https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins",
-        label: "Criar o conector",
-      },
-      steps: [
-        "Isso vai abrir um popup para você criar um plugin novo. Coloque como nome o nome da sua loja e, no campo MCP, o link copiado no passo anterior.",
-        'Marque a caixa "I understand and want to continue" — a OpenAI não revisou este servidor MCP; ela avisa que sites podem tentar roubar seus dados ou induzir o modelo a ações indevidas, incluindo destruir dados.',
-        `Clique em "Sign in with ${platformName}" e entre com a sua conta de lojista para autorizar o acesso. Pronto: a conexão é registrada automaticamente.`,
-      ],
-    },
-  ];
-}
-
-/**
- * The AI hosts a store owner can connect, in recommended order. Same OAuth flow
- * everywhere (the host drives it) — only the menu path differs per app.
- *
- * A FUNCTION of the platform's name, because one step is not generic: the
- * ChatGPT connector's consent screen shows an OAuth button labelled with
- * whoever operates the server, and the owner is told which button to click. It
- * used to name one particular STORE on one particular deployment — not even the
- * product, a tenant of it — so every other adopter instructed its owners to
- * click a button that does not exist.
- */
-export function aiHostGuides(platformName: string): readonly AiHostGuide[] {
-  const chatgptStages = chatgptConfigureStages(platformName);
-  return [
-    {
-      id: "claude",
-      label: "Claude.ai",
-      brand: "claude",
-      kind: "No navegador",
-      link: {
-        url: "https://claude.ai/new?modal=add-custom-connector#settings/customize-connectors",
-        label: "Abrir os conectores do Claude",
-      },
-      docs: {
-        url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
-        label: "documentação oficial da Anthropic — conectores personalizados",
-      },
-      steps: [
-        "Clique no botão acima (ou vá em Settings › Customize › Connectors) e escolha Add custom connector.",
-        "Dê um nome ao conector (ex.: o nome da sua loja) e cole a URL do servidor MCP da sua loja (copie acima) no campo de URL.",
-        ...CONNECTOR_TAIL,
-      ],
-    },
-    {
-      id: "claude-desktop",
-      label: "Claude Desktop",
-      brand: "claude",
-      kind: "Aplicativo (Windows/Mac)",
-      docs: {
-        url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
-        label: "documentação oficial da Anthropic — conectores personalizados",
-      },
-      steps: [
-        "Abra o Claude Desktop e vá em Settings (⚙️) › Connectors.",
-        "Clique em Add custom connector e cole a URL do servidor MCP da sua loja (copie acima).",
-        ...CONNECTOR_TAIL,
-      ],
-    },
-    {
-      id: "chatgpt",
-      label: "ChatGPT",
-      brand: "openai",
-      kind: "No navegador",
-      link: {
-        url: "https://chatgpt.com/plugins",
-        label: "Abrir os plugins do ChatGPT",
-      },
-      docs: {
-        url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
-        label:
-          "documentação oficial da OpenAI — conectar um servidor MCP ao ChatGPT",
-      },
-      configureStages: chatgptStages,
-      // Mirrors the flattened stage instructions so the MCP connect guide
-      // (`connectToChatGpt`) can never drift from what owners see in the wizard.
-      steps: chatgptStages.flatMap((stage) => stage.steps),
-    },
-    {
-      id: "codex",
-      label: "Codex",
-      brand: "openai",
-      kind: "App / CLI de desenvolvedor",
-      link: {
-        url: "https://developers.openai.com/codex",
-        label: "Documentação do Codex",
-      },
-      docs: {
-        url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
-        label: "documentação oficial da OpenAI — conectar um servidor MCP",
-      },
-      steps: [
-        "No Codex, abra as configurações de MCP (Settings › MCP no app, ou o arquivo de configuração na CLI).",
-        "Adicione um servidor MCP e cole a URL do servidor MCP da sua loja (copie acima) como um conector remoto (HTTP).",
-        ...CONNECTOR_TAIL,
-      ],
-    },
-  ];
-}
-
 export interface AiCapability {
   /** Stable id — maps to an icon in the component. */
   id: string;
@@ -228,38 +96,16 @@ export interface AiCapability {
   detail: string;
 }
 
-/** What a connected assistant does for the owner — one marketing card each. */
-export const AI_CAPABILITIES: readonly AiCapability[] = [
-  {
-    id: "orders",
-    title: "Acompanhe seus pedidos",
-    detail: '"Quais pedidos entraram hoje?"',
-  },
-  {
-    id: "inventory",
-    title: "Controle o estoque",
-    detail:
-      '"Quanto ainda tenho do produto X? Registre a entrada de 20 unidades."',
-  },
-  {
-    id: "catalog",
-    title: "Gerencie o catálogo",
-    detail: "Crie e edite produtos e categorias conversando.",
-  },
-  {
-    id: "sales",
-    title: "Entenda suas vendas",
-    detail: '"Qual foi o faturamento da semana?"',
-  },
-];
 
 /**
  * The permission model in one line, shown prominently: the assistant acts AS
  * the signed-in owner (auth-passthrough) — it can do exactly what the owner
  * can, nothing more, and no extra credential/API key is ever created.
+ *
+ * A TYPE now, not a constant. The sentence is copy, and a package that shipped
+ * it made one product's Portuguese every adopter's silent default.
  */
-export const AI_PERMISSION_MODEL =
-  "O assistente age em seu nome, com exatamente as suas permissões: ele pode fazer o que você pode fazer na sua loja — nada além disso. Não é preciso criar nenhuma chave ou credencial extra; a autorização usa o seu próprio login.";
+export type AiPermissionModel = string;
 
 /** The two tools the paste-in prompt drives, and what to call the store id. */
 export interface AiConnectPromptSpec {
@@ -288,12 +134,34 @@ export interface AiConnectPromptSpec {
  * two tools that do not exist, and because nothing registered the connection,
  * the wizard's confirm step then waited forever for a state that could never
  * arrive.
+
+/**
+ * The sentences the paste-in prompt is written in.
+ *
+ * A template rather than a string, because the prompt INTERPOLATES the host's
+ * own tool names and its word order is language-specific. The package supplies
+ * the spec; the host supplies the way it is said.
+ */
+export interface AiConnectPromptCopy {
+  (spec: AiConnectPromptSpec): string;
+}
+
+/**
+ * The message the owner pastes into the assistant's chat right after
+ * connecting: announce the connection, then read something real to prove it
+ * works. The owner types nothing.
+ *
+ * BUILT from the host's tool names rather than shipped with them. This was a
+ * constant naming two tools — `announceAiConnection` and `listInventory` — that
+ * THIS PACKAGE does not define or serve; they belong to one adopter's surface.
+ * Any other host handed its owner a prompt instructing the assistant to call
+ * two tools that do not exist, and because nothing registered the connection,
+ * the wizard's confirm step then waited forever for a state that could never
+ * arrive.
+ *
+ * The WORDS around those names are the host's too, since FUT-760: this is a
+ * thin seam that hands the spec to the host's own template.
  */
-export function aiConnectPrompt(spec: AiConnectPromptSpec): string {
-  return (
-    "Você agora tem acesso ao conector MCP da minha loja. Faça, nesta ordem:\n" +
-    `1) Execute a ferramenta ${spec.announceTool} informando qual assistente você é (host: "chatgpt", "claude" ou "codex") para registrar a conexão com a minha loja.\n` +
-    `2) Execute a ferramenta ${spec.probeTool} para confirmar o acesso a ${spec.probeSubject}.\n` +
-    `Se precisar do identificador da loja, me pergunte o ${spec.identifierName}.`
-  );
+export function aiConnectPrompt(spec: AiConnectPromptSpec, copy: AiConnectPromptCopy): string {
+  return copy(spec);
 }

package/src/index.ts

@@ -13,9 +13,6 @@ export * from "./types";
 // truth for BOTH the `@12-apps/mcp/react` onboarding UI and the server-side connect
 // tools, so what an agent reads via MCP cannot drift from what owners see.
 export {
-  aiHostGuides,
-  AI_CAPABILITIES,
-  AI_PERMISSION_MODEL,
   aiConnectPrompt,
   type AiConnectPromptSpec,
   providerForHostId,
@@ -99,3 +96,11 @@ export {
   type AuthorizationServerMetadataInput,
   type AuthorizationServerPaths,
 } from "./auth/authorization-server-metadata";
+
+export type { AiConnectPromptCopy } from "./guide";
+export {
+  PT_BR_AI_CAPABILITIES,
+  PT_BR_AI_CONNECT_PROMPT,
+  PT_BR_AI_HOST_GUIDES,
+  PT_BR_AI_PERMISSION_MODEL,
+} from "./pt-BR";

package/src/pt-BR.ts

@@ -0,0 +1,195 @@
+import type {
+  AiCapability,
+  AiConnectPromptSpec,
+  AiHostConfigureStage,
+  AiHostGuide,
+  AiPermissionModel,
+} from "./guide";
+
+/**
+ * The pt-BR pack for the AI-integration surface — NAMED constants a host passes
+ * by hand, never defaults (FUT-760).
+ *
+ * The filename is what exempts this file from the copy-portability gate:
+ * Portuguese may ship, it may not be silent. Every sentence here is VERBATIM
+ * what `guide.ts` used to compile in, so a host adopting it sees no change on
+ * screen — what changes is that the walkthrough is chosen in a diff.
+ *
+ * The guides are DATA as much as copy: which assistants are offered, their
+ * stage ids and brands. Both halves travel together because a step label and
+ * the stage it labels are useless apart.
+ */
+
+const CONNECTOR_TAIL: readonly string[] = [
+  "Deixe OAuth Client ID e Client Secret em branco — não é preciso gerar credenciais: a loja registra o conector automaticamente no primeiro acesso.",
+  "Confirme e clique em Connect: abre a tela de login da loja — entre com a SUA conta de lojista e autorize o acesso.",
+  "Pronto: ative o conector na conversa para o assistente consultar e operar a sua loja.",
+];
+
+/**
+ * ChatGPT's two-stage configuration (Developer mode is now required before a
+ * connector can be created). Stage 1 enables Developer mode in Security & login;
+ * stage 2 creates the connector and signs in — which registers the connection on
+ * the store side, so no prompt needs to be pasted afterwards.
+ */
+function chatgptConfigureStages(
+  platformName: string,
+): readonly AiHostConfigureStage[] {
+  return [
+    {
+      id: "enable-dev-mode",
+      label: "enable developer mode",
+      link: {
+        url: "https://chatgpt.com/plugins#settings/Security",
+        label: "Abrir Segurança e login",
+      },
+      steps: [
+        "Ative o Modo desenvolvedor em Settings › Security and login (Segurança e login).",
+      ],
+    },
+    {
+      id: "configurar",
+      label: "configurar",
+      link: {
+        url: "https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins",
+        label: "Criar o conector",
+      },
+      steps: [
+        "Isso vai abrir um popup para você criar um plugin novo. Coloque como nome o nome da sua loja e, no campo MCP, o link copiado no passo anterior.",
+        'Marque a caixa "I understand and want to continue" — a OpenAI não revisou este servidor MCP; ela avisa que sites podem tentar roubar seus dados ou induzir o modelo a ações indevidas, incluindo destruir dados.',
+        `Clique em "Sign in with ${platformName}" e entre com a sua conta de lojista para autorizar o acesso. Pronto: a conexão é registrada automaticamente.`,
+      ],
+    },
+  ];
+}
+
+/**
+ * The AI hosts a store owner can connect, in recommended order. Same OAuth flow
+ * everywhere (the host drives it) — only the menu path differs per app.
+ *
+ * A FUNCTION of the platform's name, because one step is not generic: the
+ * ChatGPT connector's consent screen shows an OAuth button labelled with
+ * whoever operates the server, and the owner is told which button to click. It
+ * used to name one particular STORE on one particular deployment — not even the
+ * product, a tenant of it — so every other adopter instructed its owners to
+ * click a button that does not exist.
+ */
+export function PT_BR_AI_HOST_GUIDES(platformName: string): readonly AiHostGuide[] {
+  const chatgptStages = chatgptConfigureStages(platformName);
+  return [
+    {
+      id: "claude",
+      label: "Claude.ai",
+      brand: "claude",
+      kind: "No navegador",
+      link: {
+        url: "https://claude.ai/new?modal=add-custom-connector#settings/customize-connectors",
+        label: "Abrir os conectores do Claude",
+      },
+      docs: {
+        url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
+        label: "documentação oficial da Anthropic — conectores personalizados",
+      },
+      steps: [
+        "Clique no botão acima (ou vá em Settings › Customize › Connectors) e escolha Add custom connector.",
+        "Dê um nome ao conector (ex.: o nome da sua loja) e cole a URL do servidor MCP da sua loja (copie acima) no campo de URL.",
+        ...CONNECTOR_TAIL,
+      ],
+    },
+    {
+      id: "claude-desktop",
+      label: "Claude Desktop",
+      brand: "claude",
+      kind: "Aplicativo (Windows/Mac)",
+      docs: {
+        url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
+        label: "documentação oficial da Anthropic — conectores personalizados",
+      },
+      steps: [
+        "Abra o Claude Desktop e vá em Settings (⚙️) › Connectors.",
+        "Clique em Add custom connector e cole a URL do servidor MCP da sua loja (copie acima).",
+        ...CONNECTOR_TAIL,
+      ],
+    },
+    {
+      id: "chatgpt",
+      label: "ChatGPT",
+      brand: "openai",
+      kind: "No navegador",
+      link: {
+        url: "https://chatgpt.com/plugins",
+        label: "Abrir os plugins do ChatGPT",
+      },
+      docs: {
+        url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
+        label:
+          "documentação oficial da OpenAI — conectar um servidor MCP ao ChatGPT",
+      },
+      configureStages: chatgptStages,
+      // Mirrors the flattened stage instructions so the MCP connect guide
+      // (`connectToChatGpt`) can never drift from what owners see in the wizard.
+      steps: chatgptStages.flatMap((stage) => stage.steps),
+    },
+    {
+      id: "codex",
+      label: "Codex",
+      brand: "openai",
+      kind: "App / CLI de desenvolvedor",
+      link: {
+        url: "https://developers.openai.com/codex",
+        label: "Documentação do Codex",
+      },
+      docs: {
+        url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
+        label: "documentação oficial da OpenAI — conectar um servidor MCP",
+      },
+      steps: [
+        "No Codex, abra as configurações de MCP (Settings › MCP no app, ou o arquivo de configuração na CLI).",
+        "Adicione um servidor MCP e cole a URL do servidor MCP da sua loja (copie acima) como um conector remoto (HTTP).",
+        ...CONNECTOR_TAIL,
+      ],
+    },
+  ];
+}
+
+export const PT_BR_AI_CAPABILITIES: readonly AiCapability[] = [
+  {
+    id: "orders",
+    title: "Acompanhe seus pedidos",
+    detail: '"Quais pedidos entraram hoje?"',
+  },
+  {
+    id: "inventory",
+    title: "Controle o estoque",
+    detail:
+      '"Quanto ainda tenho do produto X? Registre a entrada de 20 unidades."',
+  },
+  {
+    id: "catalog",
+    title: "Gerencie o catálogo",
+    detail: "Crie e edite produtos e categorias conversando.",
+  },
+  {
+    id: "sales",
+    title: "Entenda suas vendas",
+    detail: '"Qual foi o faturamento da semana?"',
+  },
+];
+
+/**
+ * The permission model in one line, shown prominently: the assistant acts AS
+ * the signed-in owner (auth-passthrough) — it can do exactly what the owner
+ * can, nothing more, and no extra credential/API key is ever created.
+ */
+export const PT_BR_AI_PERMISSION_MODEL: AiPermissionModel =
+  "O assistente age em seu nome, com exatamente as suas permissões: ele pode fazer o que você pode fazer na sua loja — nada além disso. Não é preciso criar nenhuma chave ou credencial extra; a autorização usa o seu próprio login.";
+
+/** The pt-BR paste-in prompt, built from the host's own tool names. */
+export function PT_BR_AI_CONNECT_PROMPT(spec: AiConnectPromptSpec): string {
+  return (
+    "Você agora tem acesso ao conector MCP da minha loja. Faça, nesta ordem:\n" +
+    `1) Execute a ferramenta ${spec.announceTool} informando qual assistente você é (host: "chatgpt", "claude" ou "codex") para registrar a conexão com a minha loja.\n` +
+    `2) Execute a ferramenta ${spec.probeTool} para confirmar o acesso a ${spec.probeSubject}.\n` +
+    `Se precisar do identificador da loja, me pergunte o ${spec.identifierName}.`
+  );
+}

package/src/react/ai-capabilities.tsx

@@ -1,7 +1,8 @@
 import { Box } from "@12-apps/ui/mui/Box";
 import { Text } from "@12-apps/ui/typography/Text";
 
-import { AI_CAPABILITIES, type AiCapability } from "../guide";
+import type { AiCapability } from "../guide";
+import type { AiCapabilitiesCopy } from "./copy";
 import { CapabilityIcon } from "./ai-icons";
 
 /** One marketing card: an icon, a headline and an example prompt (as a bubble). */
@@ -64,22 +65,25 @@ function CapabilityCard({ capability }: { capability: AiCapability }): React.JSX
  * Marketing block for the AI integration: a headline + a responsive grid of
  * capability cards. Shown on the onboarding landing (before the owner starts) to
  * sell the feature — "here's what the assistant does for you". `capabilities`
- * defaults to the shared set; apps can pass their own.
+ * and `copy` are REQUIRED host copy — the package ships no default sentence
+ * (FUT-760).
  */
 export function AiCapabilities({
-  capabilities = AI_CAPABILITIES,
+  capabilities,
+  copy,
 }: {
-  capabilities?: readonly AiCapability[];
+  capabilities: readonly AiCapability[];
+  copy: AiCapabilitiesCopy;
 }): React.JSX.Element {
   return (
     <Box data-testid="ai-capability-examples" sx={{ width: "100%" }}>
       <Box sx={{ mb: 3 }}>
         <Text variant="heading" size="sm" as="h2">
-          O que o assistente faz por você
+          {copy.heading}
         </Text>
         <Box sx={{ mt: 0.5 }}>
           <Text variant="body" size="sm" as="p" color="secondary">
-            Sem planilhas, sem cliques — é só perguntar na conversa.
+            {copy.subheading}
           </Text>
         </Box>
       </Box>

package/src/react/ai-connection-utils.ts

@@ -1,3 +1,4 @@
+import type { AiConnectionSummaryCopy } from "./copy";
 import { providerForHostId, type AiHostGuide, type AiProvider } from "../guide";
 
 /**
@@ -54,14 +55,14 @@ export function connectionForHost(
   );
 }
 
-/** Short pt-BR "ativo há X" from a timestamp (agora / min / h / dias). */
-export function activeAgo(date: Date): string {
+/** The recency line from a timestamp, in the host's own words. */
+export function activeAgo(date: Date, copy: AiConnectionSummaryCopy): string {
   const minutes = Math.max(0, Math.floor((Date.now() - date.getTime()) / 60_000));
-  if (minutes < 1) return "ativo agora";
-  if (minutes < 60) return `ativo há ${minutes} min`;
+  if (minutes < 1) return copy.activeNow;
+  if (minutes < 60) return copy.activeMinutes(minutes);
   const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `ativo há ${hours} h`;
-  return `ativo há ${Math.floor(hours / 24)} dias`;
+  if (hours < 24) return copy.activeHours(hours);
+  return copy.activeDays(Math.floor(hours / 24));
 }
 
 /** The most-recently-active connection across all providers (null when none). */
@@ -77,20 +78,24 @@ export function connectedTitle(
   connections: readonly AiConnection[],
   hosts: readonly AiHostGuide[],
   connectedHostId: string | undefined,
+  copy: AiConnectionSummaryCopy,
 ): string {
   const providers = [...new Set(connections.map((c) => c.host).filter((h): h is AiProvider => h !== null))];
-  if (providers.length === 1) return `${PROVIDER_LABEL[providers[0]!]} Conectado`;
+  if (providers.length === 1) return `${PROVIDER_LABEL[providers[0]!]} ${copy.connectedSuffix}`;
   if (providers.length > 1) {
-    return `${providers.map((p) => PROVIDER_LABEL[p]).join(", ")} conectados`;
+    return copy.connectedSeveral(providers.map((p) => PROVIDER_LABEL[p]).join(", "));
   }
   // Legacy connection with no attributed provider — name the completed host.
-  if (connections.length > 0) return `${hostLabel(hosts, connectedHostId)} Conectado`;
-  return "IA conectada";
+  if (connections.length > 0) return `${hostLabel(hosts, connectedHostId)} ${copy.connectedSuffix}`;
+  return copy.connectedGeneric;
 }
 
 /** The completed summary line (second line) for the configured-state header. */
-export function connectedSummary(connections: readonly AiConnection[]): string {
+export function connectedSummary(
+  connections: readonly AiConnection[],
+  copy: AiConnectionSummaryCopy,
+): string {
   const recent = mostRecent(connections);
-  if (!recent) return "Integração configurada";
-  return activeAgo(recent.lastActiveAt);
+  if (!recent) return copy.configured;
+  return activeAgo(recent.lastActiveAt, copy);
 }