@12-apps/mcp 1.20.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/mcp",
-  "version": "1.20.0",
+  "version": "2.0.0",
   "type": "module",
   "description": "App-agnostic MCP server core: generate one MCP tool per OpenAPI operation and proxy each call carrying the caller's bearer token (permission passthrough). Also ships the OAuth 2.1 authorization server (./oauth, ./hono: register/authorize/token, JWKS and both .well-known documents), the package-owned Prisma partial + migration for its three tables, the mcp:generate/mcp:check (./generate) and mcp:coverage (./coverage) gates, and the reusable AI-connect onboarding UI (./react).",
   "exports": {
@@ -24,8 +24,8 @@
   },
   "dependencies": {
     "@12-apps/onboarding": "^1.20.0",
-    "@12-apps/rbac": "^1.20.0",
-    "@12-apps/ui": "^4.0.0",
+    "@12-apps/rbac": "^3.0.0",
+    "@12-apps/ui": "^4.1.0",
     "@mui/icons-material": "^6.5.0",
     "jose": "^6.1.3",
     "react": "^19.2.0"

package/src/guide.ts

@@ -99,104 +99,125 @@ const CONNECTOR_TAIL: readonly string[] = [
  * stage 2 creates the connector and signs in — which registers the connection on
  * the store side, so no prompt needs to be pasted afterwards.
  */
-const CHATGPT_CONFIGURE_STAGES: readonly AiHostConfigureStage[] = [
-  {
-    id: "enable-dev-mode",
-    label: "enable developer mode",
-    link: {
-      url: "https://chatgpt.com/plugins#settings/Security",
-      label: "Abrir Segurança e login",
+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).",
+      ],
     },
-    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",
+    {
+      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.`,
+      ],
     },
-    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 Future Drink" 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 const AI_HOST_GUIDES: readonly AiHostGuide[] = [
-  {
-    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",
+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,
+      ],
     },
-    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",
+    {
+      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,
+      ],
     },
-    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",
+    {
+      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),
     },
-    configureStages: CHATGPT_CONFIGURE_STAGES,
-    // Mirrors the flattened stage instructions so the MCP connect guide
-    // (`connectToChatGpt`) can never drift from what owners see in the wizard.
-    steps: CHATGPT_CONFIGURE_STAGES.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",
+    {
+      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,
+      ],
     },
-    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. */
@@ -217,7 +238,8 @@ export const AI_CAPABILITIES: readonly AiCapability[] = [
   {
     id: "inventory",
     title: "Controle o estoque",
-    detail: '"Quanto ainda tenho do produto X? Registre a entrada de 20 unidades."',
+    detail:
+      '"Quanto ainda tenho do produto X? Registre a entrada de 20 unidades."',
   },
   {
     id: "catalog",
@@ -239,15 +261,39 @@ export const AI_CAPABILITIES: readonly AiCapability[] = [
 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.";
 
+/** The two tools the paste-in prompt drives, and what to call the store id. */
+export interface AiConnectPromptSpec {
+  /**
+   * The tool that REGISTERS the connection server-side, so the store learns
+   * which assistant connected.
+   */
+  announceTool: string;
+  /** A real READ tool, called straight after, to prove the access works. */
+  probeTool: string;
+  /** What that read returns, in the owner's own words ("o estoque da loja"). */
+  probeSubject: string;
+  /** What the assistant should ask for if it needs to identify the store. */
+  identifierName: string;
+}
+
 /**
- * The message the owner pastes into the assistant's chat right after connecting.
- * It makes the assistant (1) call `announceAiConnection` reporting which host it
- * is (chatgpt / claude / codex) — the tool that registers the connection on the
- * server side so the store learns which assistant connected — and (2) call a
- * real read tool to confirm access. The owner types nothing.
+ * 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.
  */
-export const AI_CONNECT_PROMPT =
-  "Você agora tem acesso ao conector MCP da minha loja. Faça, nesta ordem:\n" +
-  '1) Execute a ferramenta announceAiConnection informando qual assistente você é (host: "chatgpt", "claude" ou "codex") para registrar a conexão com a minha loja.\n' +
-  "2) Execute a ferramenta listInventory para confirmar o acesso ao estoque da minha loja.\n" +
-  "Se precisar do identificador da loja, me pergunte o tenantSlug.";
+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}.`
+  );
+}

package/src/index.ts

@@ -13,10 +13,11 @@ 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 {
-  AI_HOST_GUIDES,
+  aiHostGuides,
   AI_CAPABILITIES,
   AI_PERMISSION_MODEL,
-  AI_CONNECT_PROMPT,
+  aiConnectPrompt,
+  type AiConnectPromptSpec,
   providerForHostId,
   type AiHostBrand,
   type AiHostLink,

package/src/react/ai-onboarding.tsx

@@ -10,8 +10,7 @@ import {
 
 import {
   AI_CAPABILITIES,
-  AI_CONNECT_PROMPT,
-  AI_HOST_GUIDES,
+  aiHostGuides,
   AI_PERMISSION_MODEL,
   type AiCapability,
   type AiHostGuide,
@@ -44,14 +43,33 @@ export interface AiIntegrationOnboardingProps {
   featureKey?: string;
   /** Show the dev-only "reset onboarding" button. @default false */
   devReset?: boolean;
-  /** Assistants offered in the flow. @default the shared AI_HOST_GUIDES */
+  /**
+   * The platform operating this MCP server, as its OAuth consent button names
+   * it. REQUIRED, and it is the reason `hosts` can have a default at all: one
+   * ChatGPT step tells the owner which "Sign in with …" button to click, and
+   * that button carries whoever runs the server. It used to be a hard-coded
+   * name — of a single STORE on one deployment, not even the product — so every
+   * other adopter pointed its owners at a button that does not exist.
+   */
+  platformName: string;
+  /** Assistants offered in the flow. @default aiHostGuides(platformName) */
   hosts?: readonly AiHostGuide[];
   /** Capability cards on the landing. @default the shared AI_CAPABILITIES */
   capabilities?: readonly AiCapability[];
   /** Permission reassurance copy on the landing. @default AI_PERMISSION_MODEL */
   permissionModel?: string;
-  /** Message pasted into the assistant on the Conectar step. @default AI_CONNECT_PROMPT */
-  connectPrompt?: string;
+  /**
+   * Message the owner pastes into the assistant on the Conectar step.
+   *
+   * REQUIRED, with no default, because the useful version of it names TOOLS —
+   * one to register the connection, one to read something real — and this
+   * package neither defines nor serves any. It shipped a constant naming two
+   * tools from one adopter's surface, so another host handed its owner a prompt
+   * that called two things that did not exist, and the confirm step then waited
+   * forever for a registration that could never happen. Build it with
+   * `aiConnectPrompt({ … })`.
+   */
+  connectPrompt: string;
   /**
    * Re-check the live connection on the verify step's "Testar conexão" button —
    * apps pass a router refresh (e.g. Next's `router.refresh`). @default a full
@@ -100,10 +118,19 @@ function AiOnboardingFlow(props: FlowProps): React.JSX.Element {
     devReset,
   } = props;
   const { state } = useOnboarding();
-  const selectedHost = hosts.find((h) => h.id === state.data.selectedHost) ?? hosts[0]!;
+  const selectedHost =
+    hosts.find((h) => h.id === state.data.selectedHost) ?? hosts[0]!;
 
-  const steps = buildFlowSteps({ host: selectedHost, hosts, endpointUrl, connectPrompt, connections, onRetest });
-  const connectedHostId = (state.data.connectedHost ?? state.data.selectedHost) as string | undefined;
+  const steps = buildFlowSteps({
+    host: selectedHost,
+    hosts,
+    endpointUrl,
+    connectPrompt,
+    connections,
+    onRetest,
+  });
+  const connectedHostId = (state.data.connectedHost ??
+    state.data.selectedHost) as string | undefined;
 
   return (
     <GuidedSection
@@ -111,13 +138,22 @@ function AiOnboardingFlow(props: FlowProps): React.JSX.Element {
       title="Conecte assistentes de IA à sua loja"
       startLabel="Ver como conectar"
       renderLanding={(start) => (
-        <AiLanding onStart={start} permissionModel={permissionModel} capabilities={capabilities} />
+        <AiLanding
+          onStart={start}
+          permissionModel={permissionModel}
+          capabilities={capabilities}
+        />
       )}
       configuredTitle={connectedTitle(connections, hosts, connectedHostId)}
       configuredSummary={connectedSummary(connections)}
       editLabel="Conectar IA"
       completedContent={(nav) => (
-        <StatusBoard nav={nav} connections={connections} hosts={hosts} onDisconnect={onDisconnect} />
+        <StatusBoard
+          nav={nav}
+          connections={connections}
+          hosts={hosts}
+          onDisconnect={onDisconnect}
+        />
       )}
       devReset={devReset}
       dataTestId="ai-onboarding"
@@ -143,17 +179,22 @@ export function AiIntegrationOnboarding({
   connections,
   featureKey = DEFAULT_FEATURE_KEY,
   devReset = false,
-  hosts = AI_HOST_GUIDES,
+  platformName,
+  hosts = aiHostGuides(platformName),
   capabilities = AI_CAPABILITIES,
   permissionModel = AI_PERMISSION_MODEL,
-  connectPrompt = AI_CONNECT_PROMPT,
+  connectPrompt,
   onRetest = () => {
     if (typeof window !== "undefined") window.location.reload();
   },
   onDisconnect,
 }: AiIntegrationOnboardingProps): React.JSX.Element {
   return (
-    <OnboardingProvider featureKey={featureKey} store={store} initialState={initialState}>
+    <OnboardingProvider
+      featureKey={featureKey}
+      store={store}
+      initialState={initialState}
+    >
       <AiOnboardingFlow
         endpointUrl={endpointUrl}
         connections={connections}

package/src/react/index.ts

@@ -29,10 +29,11 @@ export { McpEndpointUrl } from "./mcp-endpoint-url";
 export { HostBrandAvatar, CapabilityIcon } from "./ai-icons";
 export { FeatureBadge, type FeatureBadgeItem } from "./feature-badge";
 export {
-  AI_HOST_GUIDES,
+  aiHostGuides,
   AI_CAPABILITIES,
   AI_PERMISSION_MODEL,
-  AI_CONNECT_PROMPT,
+  aiConnectPrompt,
+  type AiConnectPromptSpec,
   providerForHostId,
   type AiHostBrand,
   type AiHostLink,