@12-apps/mcp 3.10.0 → 3.12.0

package/src/en-US.ts

@@ -0,0 +1,204 @@
+import type {
+  AiCapability,
+  AiConnectPromptSpec,
+  AiHostConfigureStage,
+  AiHostGuide,
+  AiPermissionModel,
+} from "./guide";
+
+/**
+ * The en-US pack for the AI-integration surface — NAMED constants a host passes
+ * by hand, never defaults.
+ *
+ * The guides are DATA as much as copy: which assistants are offered, their
+ * stage ids, their brands and their LINKS. Both halves travel together because
+ * a step label and the stage it labels are useless apart — and the parts that
+ * are not words do not change between languages:
+ *
+ *  - `id` and `brand` are the package's own keys, matched on by the component;
+ *  - the URLs point at Anthropic's and OpenAI's own pages;
+ *  - the UI labels a reader must FIND in those products stay in the product's
+ *    own English (`Add custom connector`, `Settings › Security and login`,
+ *    `Sign in with …`), which is the same rule that keeps a vendor's field name
+ *    untranslated everywhere else here.
+ *
+ * The pt-BR pack quotes those same labels in English for exactly this reason;
+ * what differs between the two packs is the instruction around them.
+ */
+
+const CONNECTOR_TAIL: readonly string[] = [
+  "Leave OAuth Client ID and Client Secret blank — there are no credentials to generate: the store registers the connector automatically on first access.",
+  "Confirm and click Connect: the store's sign-in screen opens — sign in with YOUR own owner account and authorise the access.",
+  "Done: enable the connector in the chat so the assistant can query and operate your store.",
+];
+
+/**
+ * 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: "Open Security and login",
+      },
+      steps: [
+        "Turn on Developer mode under Settings › Security and login.",
+      ],
+    },
+    {
+      id: "configurar",
+      label: "configure",
+      link: {
+        url: "https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins",
+        label: "Create the connector",
+      },
+      steps: [
+        "That opens a popup to create a new plugin. Give it your store's name, and put the link you copied in the previous step in the MCP field.",
+        'Tick "I understand and want to continue" — OpenAI has not reviewed this MCP server; they warn that sites may try to steal your data or push the model into harmful actions, including destroying data.',
+        `Click "Sign in with ${platformName}" and sign in with your owner account to authorise access. That is it: the connection is registered automatically.`,
+      ],
+    },
+  ];
+}
+
+/**
+ * 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 EN_US_AI_HOST_GUIDES(platformName: string): readonly AiHostGuide[] {
+  const chatgptStages = chatgptConfigureStages(platformName);
+  return [
+    {
+      id: "claude",
+      label: "Claude.ai",
+      brand: "claude",
+      kind: "In the browser",
+      link: {
+        url: "https://claude.ai/new?modal=add-custom-connector#settings/customize-connectors",
+        label: "Open Claude's connectors",
+      },
+      docs: {
+        url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
+        label: "Anthropic's own documentation — custom connectors",
+      },
+      steps: [
+        "Click the button above (or go to Settings › Customize › Connectors) and choose Add custom connector.",
+        "Name the connector (your store's name works) and paste your store's MCP server URL (copy it above) into the URL field.",
+        ...CONNECTOR_TAIL,
+      ],
+    },
+    {
+      id: "claude-desktop",
+      label: "Claude Desktop",
+      brand: "claude",
+      kind: "App (Windows/Mac)",
+      docs: {
+        url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
+        label: "Anthropic's own documentation — custom connectors",
+      },
+      steps: [
+        "Open Claude Desktop and go to Settings (⚙️) › Connectors.",
+        "Click Add custom connector and paste your store's MCP server URL (copy it above).",
+        ...CONNECTOR_TAIL,
+      ],
+    },
+    {
+      id: "chatgpt",
+      label: "ChatGPT",
+      brand: "openai",
+      kind: "In the browser",
+      link: {
+        url: "https://chatgpt.com/plugins",
+        label: "Open ChatGPT's plugins",
+      },
+      docs: {
+        url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
+        label: "OpenAI's own documentation — connecting an MCP server to 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: "Developer app / CLI",
+      link: {
+        url: "https://developers.openai.com/codex",
+        label: "Codex documentation",
+      },
+      docs: {
+        url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
+        label: "OpenAI's own documentation — connecting an MCP server",
+      },
+      steps: [
+        "In Codex, open the MCP settings (Settings › MCP in the app, or the config file on the CLI).",
+        "Add an MCP server and paste your store's MCP server URL (copy it above) as a remote (HTTP) connector.",
+        ...CONNECTOR_TAIL,
+      ],
+    },
+  ];
+}
+
+export const EN_US_AI_CAPABILITIES: readonly AiCapability[] = [
+  // The `detail` of each is a QUESTION a reader could paste verbatim, so it is
+  // written as one rather than described.
+  {
+    id: "orders",
+    title: "Follow your orders",
+    detail: '"Which orders came in today?"',
+  },
+  {
+    id: "inventory",
+    title: "Keep on top of stock",
+    detail: '"How much of product X is left? Record 20 units received."',
+  },
+  {
+    id: "catalog",
+    title: "Manage the catalog",
+    detail: "Create and edit products and categories by chatting.",
+  },
+  {
+    id: "sales",
+    title: "Understand your sales",
+    detail: '"What was this week\'s revenue?"',
+  },
+];
+
+/**
+ * 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 EN_US_AI_PERMISSION_MODEL: AiPermissionModel =
+  "The assistant acts on your behalf with exactly your permissions: it can do what you can do in your store — and nothing beyond that. There is no key or extra credential to create; the authorisation uses your own login.";
+
+/** The en-US paste-in prompt, built from the host's own tool names. */
+export function EN_US_AI_CONNECT_PROMPT(spec: AiConnectPromptSpec): string {
+  // The TOOL NAMES are the host's own identifiers and are interpolated, never
+  // translated: the assistant has to call them by the name they are registered
+  // under, so a translated verb here is a prompt that does nothing.
+  return (
+    "You now have access to my store's MCP connector. Do the following, in order:\n" +
+    `1) Run the ${spec.announceTool} tool, saying which assistant you are (host: "chatgpt", "claude" or "codex"), to register the connection with my store.\n` +
+    `2) Run the ${spec.probeTool} tool to confirm access to ${spec.probeSubject}.\n` +
+    `If you need the store identifier, ask me for the ${spec.identifierName}.`
+  );
+}

package/src/index.ts

@@ -104,3 +104,15 @@ export {
   PT_BR_AI_HOST_GUIDES,
   PT_BR_AI_PERMISSION_MODEL,
 } from "./pt-BR";
+export {
+  EN_US_AI_CAPABILITIES,
+  EN_US_AI_CONNECT_PROMPT,
+  EN_US_AI_HOST_GUIDES,
+  EN_US_AI_PERMISSION_MODEL,
+} from "./en-US";
+export {
+  AI_CAPABILITIES,
+  AI_CONNECT_PROMPT,
+  AI_HOST_GUIDES,
+  AI_PERMISSION_MODEL,
+} from "./locales";

package/src/locales.ts

@@ -0,0 +1,58 @@
+import {
+  EN_US_AI_CAPABILITIES,
+  EN_US_AI_CONNECT_PROMPT,
+  EN_US_AI_HOST_GUIDES,
+  EN_US_AI_PERMISSION_MODEL,
+} from "./en-US";
+import type {
+  AiCapability,
+  AiConnectPromptSpec,
+  AiHostGuide,
+  AiPermissionModel,
+} from "./guide";
+import {
+  PT_BR_AI_CAPABILITIES,
+  PT_BR_AI_CONNECT_PROMPT,
+  PT_BR_AI_HOST_GUIDES,
+  PT_BR_AI_PERMISSION_MODEL,
+} from "./pt-BR";
+
+/**
+ * The AI-integration surface in both languages, keyed by tag — what a host
+ * hands to `@12-apps/i18n` when the reader's language is a property of the
+ * request rather than of the deployment.
+ *
+ * Two of these are FUNCTIONS rather than tables, and stay so:
+ *
+ *  - `AI_HOST_GUIDES` takes the platform's name, because the ChatGPT consent
+ *    screen shows an OAuth button labelled with whoever operates the server and
+ *    the owner is told which button to click. It once named one particular
+ *    tenant of one deployment, so every other adopter instructed its owners to
+ *    click a button that does not exist.
+ *  - `AI_CONNECT_PROMPT` takes the host's own tool names, which the assistant
+ *    must call by the name they are registered under.
+ *
+ * `LocalePack` is mirrored here rather than imported so the package stays
+ * liftable into a repo that has never heard of `@12-apps/i18n`.
+ */
+type LocalePack<T> = { readonly "pt-BR": T; readonly "en-US": T };
+
+export const AI_HOST_GUIDES = {
+  "pt-BR": PT_BR_AI_HOST_GUIDES,
+  "en-US": EN_US_AI_HOST_GUIDES,
+} as const satisfies LocalePack<(platformName: string) => readonly AiHostGuide[]>;
+
+export const AI_CONNECT_PROMPT = {
+  "pt-BR": PT_BR_AI_CONNECT_PROMPT,
+  "en-US": EN_US_AI_CONNECT_PROMPT,
+} as const satisfies LocalePack<(spec: AiConnectPromptSpec) => string>;
+
+export const AI_CAPABILITIES = {
+  "pt-BR": PT_BR_AI_CAPABILITIES,
+  "en-US": EN_US_AI_CAPABILITIES,
+} as const satisfies LocalePack<readonly AiCapability[]>;
+
+export const AI_PERMISSION_MODEL = {
+  "pt-BR": PT_BR_AI_PERMISSION_MODEL,
+  "en-US": EN_US_AI_PERMISSION_MODEL,
+} as const satisfies LocalePack<AiPermissionModel>;

package/src/manifest/index.ts

@@ -0,0 +1,89 @@
+/**
+ * `@12-apps/mcp/manifest` — the SHARED wiring manifest.
+ *
+ * Identity, the Prisma contribution (the three tables behind the
+ * authorization server) and the runtime inventory: `http` on the server.
+ *
+ * ON THE `db` DECLARATION — the reason this manifest exists at all.
+ *
+ * This package ships `prisma/mcp.prisma` and a migration beside it, and until
+ * now nothing said so in a form a host assembler could read. The origin
+ * host's assembler discovers partials in two steps: a package that carries
+ * `"wiring": { "db": ... }` in its package.json is taken at its word, and a
+ * package that carries nothing falls back to a STRUCTURAL scan — every
+ * `prisma/*.prisma` under the package root is treated as a partial. So three
+ * tables reach somebody's database because a `readdir` found them, not
+ * because this package said they should. `@12-apps/notifications`' manifest
+ * closed exactly this gap for its four models and the anti-pattern audit
+ * names it directly; declaring changes no assembler behaviour (the
+ * declaration is read where the scan used to run) and closes the one case
+ * where composition was happening by accident.
+ *
+ * The mirror is what makes the declaration reachable: host assemblers are
+ * plain Node reading `node_modules` and cannot execute this TypeScript, so
+ * the contribution is repeated under `package.json` `"wiring": { "db": … }`
+ * and `assertDbMirror` pins the two together in this package's own test run.
+ *
+ * `composed`, not `isolated`, and the choice is forced. An isolated stack
+ * needs models carrying no relation into host tables — true of the three
+ * here as SHIPPED (`user_id` and `user_email` are deliberately by-value
+ * scalars, see the partial's header) — but the host is invited to add the FK
+ * in its own migration, and the origin host's is `ON DELETE CASCADE`. A
+ * package cannot declare isolation for models whose adopters relate them
+ * into their own account tables.
+ *
+ * ## THE NARROWINGS, each deliberate
+ *
+ * - **No `mcp` capability.** This package IS the MCP runtime — the
+ *   OpenAPI→tools generator, the registry, the JSON-RPC transport, the
+ *   coverage gate. It advertises no tools of its own, and a manifest that
+ *   declared any would be the runtime describing itself to itself.
+ * - **No `permissions`.** Authorization here is the OAuth scope set
+ *   (`MCP_SUPPORTED_SCOPES`) plus whatever the host's own RBAC says about
+ *   the proxied endpoint — the point of bearer passthrough is that an agent
+ *   inherits the caller's permissions rather than holding its own. There is
+ *   no id for this package to contribute.
+ * - **No `web` inventory**, though `./react` ships the whole AI-connect
+ *   onboarding flow. A `surface` contribution is a `createWeb*` FACTORY —
+ *   one config object in, an object of component types out, memoised once by
+ *   the binder. `./react` has no such factory: it exports components a host
+ *   mounts with its own props (`AiIntegrationOnboarding` takes the store,
+ *   the endpoint URL and the live connection at the call site). Inventing a
+ *   factory here to have something to declare would freeze a props table
+ *   three hosts pass differently, which is the opposite of what a surface
+ *   contribution is for. When the flow grows a real bound surface, the
+ *   inventory grows with it.
+ * - **No `env`.** The signing-key variables (`DEFAULT_SIGNING_KEY_ENV`,
+ *   `DEFAULT_SIGNING_KEY_ID_ENV`) and `trustedOriginsFromEnv` are NAMES this
+ *   package exports for a host to read `process.env` with; the package reads
+ *   nothing itself, and the names are overridable per call. Declaring them
+ *   would oblige a host to answer for variables it may legitimately have
+ *   spelled differently.
+ * - **No `e2e`.** This package packages no journeys.
+ * - **No `jobs`.** Nothing here sweeps: authorization codes are stateless
+ *   signed blobs (the partial's header says so — there is no `oauth_codes`
+ *   table and nothing to expire), and refresh-token revocation happens on
+ *   the rotation path rather than on a clock.
+ *
+ * `@12-apps/wiring` is a TYPE-ONLY devDependency (the report-builder move):
+ * the manifest is a plain `satisfies`-checked value, and the producer
+ * factories' runtime assertions run in this package's own test suite.
+ */
+
+import type { PackageManifest } from "@12-apps/wiring";
+
+export const mcpManifest = {
+  name: "@12-apps/mcp",
+  contract: 1,
+  db: { partial: "prisma/mcp.prisma", migrations: "prisma/migrations" },
+  /**
+   * A refused token grant, an unresolvable signing key or a rejected
+   * redirect URI files under `mcp` rather than under whichever host mounted
+   * the authorization server. Mandatory for runtime manifests since wiring
+   * 1.3.0, and this is the surface that most needs it: every failure here is
+   * a caller who cannot connect, reported to them as an opaque OAuth error
+   * code by specification.
+   */
+  observability: { namespace: "mcp" },
+  server: ["http"],
+} as const satisfies PackageManifest;

package/src/manifest/server.ts

@@ -0,0 +1,94 @@
+/**
+ * `@12-apps/mcp/manifest/server` — the server capabilities.
+ *
+ * `http.create` wraps `createApiMcpOauth` in a WIRE VIEW, and the reason is
+ * the shape of an OAuth answer. `McpOauthRoute.handle` takes a Fetch
+ * `Request` and returns a Fetch `Response` — not a `{ status, body }` pair —
+ * because every endpoint here answers something the JSON pair cannot say: a
+ * 302 whose `Location` IS the payload, a form-encoded exchange answering
+ * RFC 6749 §5.1/§5.2 with its own cache headers, a JWKS with a
+ * `public, max-age=300`, an RFC 8414/9728 document. `create-api-mcp-oauth`'s
+ * own docstring says a wrapper would only break those. So the view answers
+ * the contract's RAW half (`{ response }`, wiring 1.9.0), which exists for
+ * exactly this, and the descriptors stay untouched.
+ *
+ * ## THE RAW REQUEST IS REQUIRED, and the view says so out loud
+ *
+ * The contract obliges an adapter to fill `params`/`query`/`body` and lets it
+ * fill `request`. Every handler here needs the whole request — the exact URL
+ * (redirect_uri echo, PKCE parameters, the `Host` an issuer is derived
+ * from), the form body byte-for-byte, the cookie header the session is read
+ * off. So a missing `request` is refused loudly at the first call rather
+ * than silently producing an authorization server that mints codes for the
+ * wrong origin. `@12-apps/storage`'s view takes the same posture for the
+ * same reason.
+ *
+ * ## THE MOUNT IS THE ORIGIN ROOT
+ *
+ * `McpOauthRoute.path` is absolute from the origin root — `.well-known/*`
+ * cannot live under a prefix (RFC 8615), and a connector reads those
+ * documents before it has ever spoken to us. The consumer joins
+ * `mountPath + path`, so the ONLY correct binding is `mountPath: "/"`; the
+ * paths themselves stay configurable per host through `config.paths`, which
+ * is where a host that serves `authorize` somewhere else says so. Binding
+ * this surface under a prefix would move the discovery documents off the
+ * two URLs the specification reserves, and the symptom is a connector that
+ * cannot find the authorization server at all.
+ *
+ * ## EVERY ROUTE IS `public`, and that is a decision
+ *
+ * Not "unguarded": these six ARE the authentication, so a host RBAC gate in
+ * front of them would demand a token from the endpoint that issues tokens.
+ * `authorize` reads the host's cookie session itself (`config.resolveSession`)
+ * and sends an anonymous caller through the host's sign-in flow; `token` and
+ * `register` authenticate the CLIENT per RFC; the three documents are public
+ * by specification. `public` is also the contract's only kind that forbids a
+ * `permission` while allowing the routes to be reached anonymously — which
+ * is precisely the property that has to hold here.
+ *
+ * `@12-apps/wiring` is a TYPE-ONLY devDependency — see `./index`.
+ */
+
+import type { AnyServerManifest, WireRequest, WireRouteAnswer } from "@12-apps/wiring";
+
+import {
+  createApiMcpOauth,
+  type ApiMcpOauth,
+  type McpOauthConfig,
+  type McpOauthRoute,
+} from "../oauth";
+
+/** One `McpOauthRoute` as the wiring contract reads it. */
+function asWireRoute(route: McpOauthRoute): {
+  method: McpOauthRoute["method"];
+  path: string;
+  kind: "public";
+  handle(request: WireRequest): Promise<WireRouteAnswer>;
+} {
+  return {
+    method: route.method,
+    path: route.path,
+    kind: "public",
+    handle: async (request) => {
+      if (!request.request) {
+        throw new Error(
+          "@12-apps/mcp/oauth needs the raw request — bind an adapter that forwards it.",
+        );
+      }
+      return { response: await route.handle(request.request) };
+    },
+  };
+}
+
+/** `createApiMcpOauth`, its routes re-shaped for the aggregate. */
+export function createWireApiMcpOauth(
+  config: McpOauthConfig,
+): Omit<ApiMcpOauth, "routes"> & { routes: ReturnType<typeof asWireRoute>[] } {
+  const api = createApiMcpOauth(config);
+  return { ...api, routes: api.routes.map(asWireRoute) };
+}
+
+export const mcpServerManifest = {
+  name: "@12-apps/mcp",
+  http: { create: createWireApiMcpOauth },
+} as const satisfies AnyServerManifest;

package/src/react/en-US.ts

@@ -0,0 +1,125 @@
+import { EN_US_CONFIRM_ACTION_COPY } from "@12-apps/ui/en-US";
+
+import type { McpAiCopy } from "./copy";
+
+/**
+ * The en-US pack for the AI-integration screens — a NAMED constant a host
+ * passes by hand, never a default.
+ *
+ * `statusBoard.confirmAction` composes `@12-apps/ui`'s own English pack rather
+ * than restating it, exactly as the pt-BR side composes the Portuguese one.
+ *
+ * The assistant NAMES (Claude, ChatGPT, Codex) are products, not words: they
+ * are spelled the same in every language, and `hostLabel` arrives as an
+ * argument so a sentence can place it where its own grammar wants.
+ */
+export const EN_US_MCP_AI_COPY: McpAiCopy = {
+  capabilities: {
+    heading: "What the assistant does for you",
+    subheading: "No spreadsheets, no clicking — just ask it in the chat.",
+  },
+  landing: {
+    eyebrow: "AI integration",
+    // Three fragments the heading renders around an emphasised middle, so the
+    // seam has to survive: "Connect / AI assistants / to your store".
+    titleLead: "Connect",
+    titleEmphasis: "AI assistants",
+    titleTail: "to your store",
+    lede:
+      "Let Claude, ChatGPT and other assistants answer questions about your menu, stock and " +
+      "orders — and take actions for you, right in the chat. Securely, with nothing to install.",
+    trust: [
+      // The `id`s are the package's own and are NOT words: the component keys
+      // its icons off them.
+      {
+        id: "login",
+        label: "Uses your own login",
+        caption: "No extra keys or credentials",
+      },
+      { id: "install", label: "Nothing to install", caption: "Connects in minutes" },
+      {
+        id: "permissions",
+        label: "Only what you can do",
+        caption: "Your permissions, nothing beyond them",
+      },
+      { id: "surface", label: "Browser or app", caption: "Claude, ChatGPT, Codex" },
+    ],
+    start: "Get started",
+  },
+  flow: {
+    steps: {
+      select: "Choose",
+      copyUrl: "Copy URL",
+      configure: "Configure",
+      connect: "Connect",
+      install: "Install",
+      confirm: "Confirm",
+    },
+    back: "Back",
+    next: "Next",
+    advance: "Continue",
+    finish: "Finish",
+    copyUrl: "Copy URL",
+    copied: "Copied",
+    copyMessage: "Copy message",
+    copyUrlTitle: "Copy your store's URL",
+    urlCaption:
+      "It is the only thing you paste into the assistant — copying it moves you to the next step.",
+    promptCaption:
+      "That is how it connects, identifies itself (Claude, ChatGPT…) and how we record the connection.",
+    askTitle: "Ask the assistant to connect",
+    installBody:
+      "Open your store's plugin, click Install and authorise access — no URL to copy, no credentials to generate.",
+    installAction: "Install the store plugin",
+    pasteTitle: "Paste this message into the assistant",
+    pasteInstallCaption:
+      "Paste it into the assistant so it connects, identifies itself and confirms access.",
+    connectedTo: (hostLabel) => `${hostLabel} is connected to your store.`,
+    waitingTitle: "Waiting for the connection",
+    waitingBody: (hostLabel) =>
+      `As soon as you authorise access in ${hostLabel}, it appears here automatically.`,
+    testNow: "Test it now",
+  },
+  statusBoard: {
+    instructions: "Instructions",
+    connected: "Connected",
+    notConnected: "Not connected yet",
+    connect: "Connect",
+    disconnect: "Disconnect",
+    disconnectTitle: "Disconnect this assistant?",
+    disconnectBody:
+      "It loses access to your store immediately. To use it again you will have to connect it afresh.",
+    disconnectConfirm: "Disconnect",
+    disconnectError: "Could not disconnect. Try again.",
+    boardTitle: "Connected assistants",
+    boardCaption:
+      "Green are the ones already working with your store; red are the ones still to connect.",
+    confirmAction: EN_US_CONFIRM_ACTION_COPY,
+  },
+  summary: {
+    activeNow: "active now",
+    activeMinutes: (minutes) => `active ${minutes} min ago`,
+    activeHours: (hours) => `active ${hours} h ago`,
+    activeDays: (days) => `active ${days} days ago`,
+    configured: "Integration configured",
+    connectedSuffix: "Connected",
+    connectedSeveral: (names) => `${names} connected`,
+    connectedGeneric: "AI connected",
+  },
+  hostSelect: {
+    heading: "Choose your assistant",
+    caption: "Pick where you use AI — the walkthrough is tailored to it.",
+  },
+  connectGuide: {
+    urlLabel: "Your store's server URL",
+    urlHint: "Copy this URL and paste it into your assistant to connect it to the store.",
+    // Ends mid-sentence: the screen renders a documentation link straight after.
+    moreInfo: "For more, see the",
+    connectOn: (hostLabel) => `Connect in ${hostLabel}`,
+  },
+  onboarding: {
+    title: "Connect AI assistants to your store",
+    editLabel: "Connect AI",
+    collapseLabel: "Hide",
+  },
+};

package/src/react/index.ts

@@ -47,6 +47,22 @@ export {
   PT_BR_AI_PERMISSION_MODEL,
 } from "../pt-BR";
 
+// The English twins and the tag-keyed records, re-exported beside them so a
+// screen reaching for the AI surface finds all of it on one subpath — which is
+// how the pt-BR names have always been reachable from here.
+export {
+  EN_US_AI_CAPABILITIES,
+  EN_US_AI_CONNECT_PROMPT,
+  EN_US_AI_HOST_GUIDES,
+  EN_US_AI_PERMISSION_MODEL,
+} from "../en-US";
+export {
+  AI_CAPABILITIES,
+  AI_CONNECT_PROMPT,
+  AI_HOST_GUIDES,
+  AI_PERMISSION_MODEL,
+} from "../locales";
+
 export type {
   AiCapabilitiesCopy,
   AiConnectGuideCopy,
@@ -60,3 +76,5 @@ export type {
   McpAiCopy,
 } from "./copy";
 export { PT_BR_MCP_AI_COPY } from "./pt-BR";
+export { EN_US_MCP_AI_COPY } from "./en-US";
+export { MCP_AI_COPY } from "./locales";

package/src/react/locales.ts

@@ -0,0 +1,17 @@
+import type { McpAiCopy } from "./copy";
+import { EN_US_MCP_AI_COPY } from "./en-US";
+import { PT_BR_MCP_AI_COPY } from "./pt-BR";
+
+/**
+ * The AI-integration screens in both languages, keyed by tag.
+ *
+ * `LocalePack` is mirrored here rather than imported so the package stays
+ * liftable into a repo that has never heard of `@12-apps/i18n`. The named
+ * single-language packs stay exported and unchanged.
+ */
+type LocalePack<T> = { readonly "pt-BR": T; readonly "en-US": T };
+
+export const MCP_AI_COPY = {
+  "pt-BR": PT_BR_MCP_AI_COPY,
+  "en-US": EN_US_MCP_AI_COPY,
+} as const satisfies LocalePack<McpAiCopy>;