@12-apps/mcp 1.0.0 → 1.3.0

package/src/react/host-connect-guide.tsx

@@ -0,0 +1,225 @@
+"use client";
+
+import CheckIcon from "@mui/icons-material/Check";
+import ContentCopyOutlinedIcon from "@mui/icons-material/ContentCopyOutlined";
+import OpenInNewIcon from "@mui/icons-material/OpenInNew";
+import { useState } from "react";
+
+import { Button } from "@12-apps/ui/form/Button";
+import { Box } from "@12-apps/ui/mui/Box";
+import { Stack } from "@12-apps/ui/mui/Stack";
+import { Text } from "@12-apps/ui/typography/Text";
+
+import type { AiHostGuide } from "../guide";
+import { HostBrandAvatar } from "./ai-icons";
+import { McpEndpointUrl } from "./mcp-endpoint-url";
+
+/**
+ * The store's MCP endpoint URL with a blue "Copiar" button (the display-only
+ * field defers the copy to this button). Controlled: `copied` flips the label to
+ * "Copiado" and `onCopy` fires after the clipboard write — the wizard uses it to
+ * unlock the "Próximo" button on the Copiar-URL step.
+ */
+export function EndpointCopyBlock({
+  endpointUrl,
+  copied,
+  onCopy,
+}: {
+  endpointUrl: string;
+  copied: boolean;
+  onCopy: () => void;
+}): React.JSX.Element {
+  const handleClick = (): void => {
+    if (typeof navigator !== "undefined" && navigator.clipboard) {
+      void navigator.clipboard.writeText(endpointUrl).catch(() => undefined);
+    }
+    onCopy();
+  };
+
+  return (
+    <Box
+      sx={{
+        p: 2,
+        borderRadius: 2,
+        border: 1,
+        borderColor: "primary.main",
+        bgcolor: "action.hover",
+      }}
+    >
+      <Text variant="caption" as="p" weight="bold">
+        URL do servidor da sua loja
+      </Text>
+      <Text variant="caption" as="p" color="secondary">
+        Copie esta URL e cole no seu assistente para conectá-lo à loja.
+      </Text>
+      <Box sx={{ mt: 1 }}>
+        <McpEndpointUrl url={endpointUrl} copyable={false} />
+      </Box>
+      <Box sx={{ mt: 1.5 }}>
+        <Button onClick={handleClick} data-testid="ai-copy-endpoint">
+          {copied ? (
+            <CheckIcon sx={{ fontSize: 18, mr: 0.5 }} />
+          ) : (
+            <ContentCopyOutlinedIcon sx={{ fontSize: 18, mr: 0.5 }} />
+          )}
+          {copied ? "Copiado" : "Copiar URL"}
+        </Button>
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * A copyable multi-line message block (preserves line breaks). Used on the
+ * Conectar step for the prompt the owner pastes into the assistant so it
+ * identifies itself and calls a tool (which registers the connection).
+ */
+export function PromptCopyBlock({
+  title,
+  caption,
+  message,
+}: {
+  title: string;
+  caption: string;
+  message: string;
+}): React.JSX.Element {
+  const [copied, setCopied] = useState(false);
+
+  const handleClick = (): void => {
+    if (typeof navigator !== "undefined" && navigator.clipboard) {
+      void navigator.clipboard.writeText(message).catch(() => undefined);
+    }
+    setCopied(true);
+  };
+
+  return (
+    <Box
+      sx={{
+        p: 2,
+        borderRadius: 2,
+        border: 1,
+        borderColor: "primary.main",
+        bgcolor: "action.hover",
+      }}
+    >
+      <Text variant="caption" as="p" weight="bold">
+        {title}
+      </Text>
+      <Text variant="caption" as="p" color="secondary">
+        {caption}
+      </Text>
+      <Box
+        sx={{
+          mt: 1,
+          p: 1.5,
+          borderRadius: 1,
+          border: 1,
+          borderColor: "divider",
+          bgcolor: "background.paper",
+          whiteSpace: "pre-line",
+        }}
+      >
+        <Text variant="body" size="sm" as="p">
+          {message}
+        </Text>
+      </Box>
+      <Box sx={{ mt: 1.5 }}>
+        <Button onClick={handleClick} data-testid="ai-copy-prompt">
+          {copied ? (
+            <CheckIcon sx={{ fontSize: 18, mr: 0.5 }} />
+          ) : (
+            <ContentCopyOutlinedIcon sx={{ fontSize: 18, mr: 0.5 }} />
+          )}
+          {copied ? "Copiado" : "Copiar mensagem"}
+        </Button>
+      </Box>
+    </Box>
+  );
+}
+
+/** The brand mark + "Conectar no <host>" header shared by the connect sub-steps. */
+export function HostConnectHeader({ host }: { host: AiHostGuide }): React.JSX.Element {
+  return (
+    <Stack direction="row" spacing={1.5} alignItems="center">
+      <HostBrandAvatar brand={host.brand} size={36} />
+      <Text variant="heading" size="sm" as="h3">
+        Conectar no {host.label}
+      </Text>
+    </Stack>
+  );
+}
+
+/**
+ * The primary direct-link button to a host's connector settings (nothing when it
+ * has none). `onOpen` fires after the link opens so the Configurar step can
+ * unlock its "Próximo" only once the owner has actually gone to the connectors.
+ */
+export function HostOpenButton({
+  host,
+  onOpen,
+}: {
+  host: AiHostGuide;
+  onOpen?: () => void;
+}): React.JSX.Element | null {
+  if (!host.link) return null;
+  return (
+    <Box>
+      <Button
+        onClick={() => {
+          window.open(host.link!.url, "_blank", "noopener,noreferrer");
+          onOpen?.();
+        }}
+        data-testid={`ai-host-link-${host.id}`}
+      >
+        {host.link.label}
+        <OpenInNewIcon sx={{ fontSize: 16, ml: 0.5 }} />
+      </Button>
+    </Box>
+  );
+}
+
+/** A "Para mais informações" reference to the host's official connector docs. */
+export function HostDocsLink({ host }: { host: AiHostGuide }): React.JSX.Element | null {
+  if (!host.docs) return null;
+  return (
+    <Text variant="caption" as="p" color="secondary">
+      Para mais informações, consulte a{" "}
+      <Box
+        component="a"
+        href={host.docs.url}
+        target="_blank"
+        rel="noopener noreferrer"
+        data-testid={`ai-host-docs-${host.id}`}
+        sx={{ color: "primary.main", textDecoration: "underline" }}
+      >
+        {host.docs.label}
+      </Box>
+      .
+    </Text>
+  );
+}
+
+/**
+ * A numbered slice of a host's connect steps. `start` keeps the numbering
+ * continuous when the steps are split across wizard stages (e.g. the Conectar
+ * stage continues at 4 after Configurar showed 1–3).
+ */
+export function HostStepList({
+  steps,
+  start = 1,
+}: {
+  steps: readonly string[];
+  start?: number;
+}): React.JSX.Element {
+  return (
+    <Box component="ol" start={start} sx={{ m: 0, pl: 3 }}>
+      {steps.map((step, index) => (
+        <Box component="li" key={index} sx={{ mb: 1 }}>
+          <Text variant="body" as="span">
+            {step}
+          </Text>
+        </Box>
+      ))}
+    </Box>
+  );
+}

package/src/react/host-select-step.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import CheckCircleIcon from "@mui/icons-material/CheckCircle";
+
+import { Box } from "@12-apps/ui/mui/Box";
+import { Stack } from "@12-apps/ui/mui/Stack";
+import { Text } from "@12-apps/ui/typography/Text";
+
+import type { AiHostGuide } from "../guide";
+import { HostBrandAvatar } from "./ai-icons";
+
+/** One selectable assistant card (brand mark + name + kind, checked when active). */
+function HostCard({
+  host,
+  active,
+  onSelect,
+}: {
+  host: AiHostGuide;
+  active: boolean;
+  onSelect: () => void;
+}): React.JSX.Element {
+  return (
+    <Box
+      component="button"
+      type="button"
+      onClick={onSelect}
+      aria-pressed={active}
+      data-testid={`ai-host-card-${host.id}`}
+      sx={{
+        position: "relative",
+        display: "flex",
+        alignItems: "center",
+        gap: 1.5,
+        p: 2,
+        borderRadius: 3,
+        cursor: "pointer",
+        textAlign: "left",
+        width: "100%",
+        border: 2,
+        borderColor: active ? "primary.main" : "divider",
+        bgcolor: active ? "action.selected" : "background.paper",
+        transition: (theme) => theme.transitions.create(["border-color", "background-color"]),
+        "&:hover": { borderColor: "primary.main" },
+      }}
+    >
+      <HostBrandAvatar brand={host.brand} size={40} />
+      <Box sx={{ minWidth: 0 }}>
+        <Text variant="body" weight="bold" as="span">
+          {host.label}
+        </Text>
+        <Text variant="caption" as="p" color="secondary">
+          {host.kind}
+        </Text>
+      </Box>
+      {active && (
+        <CheckCircleIcon
+          sx={{ position: "absolute", top: 10, right: 10, fontSize: 20, color: "primary.main" }}
+        />
+      )}
+    </Box>
+  );
+}
+
+/**
+ * Step 1 of the guided AI connect flow: the owner picks a single assistant
+ * (Claude.ai, Claude Desktop, ChatGPT, Codex) from a card grid. Picking a card
+ * advances straight to the next step — no separate "Próximo" button. Selection
+ * is controlled (persisted by the onboarding flow) so a refresh resumes with the
+ * same assistant highlighted.
+ */
+export function HostSelectStep({
+  hosts,
+  selectedId,
+  onSelect,
+}: {
+  hosts: readonly AiHostGuide[];
+  selectedId: string | null;
+  onSelect: (hostId: string) => void;
+}): React.JSX.Element {
+  return (
+    <Stack spacing={3} data-testid="ai-host-select">
+      <Box>
+        <Text variant="heading" size="sm" as="h2">
+          Escolha o seu assistente
+        </Text>
+        <Text variant="caption" as="p" color="secondary">
+          Selecione onde você usa a IA — o passo a passo é feito sob medida para ele.
+        </Text>
+      </Box>
+
+      <Box
+        sx={{
+          display: "grid",
+          gap: 2,
+          gridTemplateColumns: { xs: "1fr", sm: "1fr 1fr" },
+        }}
+      >
+        {hosts.map((host) => (
+          <HostCard
+            key={host.id}
+            host={host}
+            active={host.id === selectedId}
+            onSelect={() => onSelect(host.id)}
+          />
+        ))}
+      </Box>
+    </Stack>
+  );
+}

package/src/react/index.ts

@@ -0,0 +1,43 @@
+/**
+ * `@12-apps/mcp/react` — the reusable, app-agnostic AI/MCP connect onboarding UI.
+ *
+ * The app supplies the persistence `store`, the `endpointUrl`, and the live
+ * `connection`; the flow's content (hosts, capabilities, copy) defaults to the
+ * shared guide and can be overridden per app. React + MUI + `@12-apps/ui` +
+ * `@12-apps/onboarding`; server-side MCP core stays on the package root export.
+ */
+
+export {
+  AiIntegrationOnboarding,
+  type AiIntegrationOnboardingProps,
+  type AiConnection,
+} from "./ai-onboarding";
+
+// Building blocks + content, exported so apps can compose or override.
+export { AiLanding } from "./ai-landing";
+export { AiCapabilities } from "./ai-capabilities";
+export { AiStatusBoard, type HostStatus } from "./ai-status-board";
+export { HostSelectStep } from "./host-select-step";
+export {
+  EndpointCopyBlock,
+  PromptCopyBlock,
+  HostConnectHeader,
+  HostOpenButton,
+  HostStepList,
+} from "./host-connect-guide";
+export { McpEndpointUrl } from "./mcp-endpoint-url";
+export { HostBrandAvatar, CapabilityIcon } from "./ai-icons";
+export { FeatureBadge, type FeatureBadgeItem } from "./feature-badge";
+export {
+  AI_HOST_GUIDES,
+  AI_CAPABILITIES,
+  AI_PERMISSION_MODEL,
+  AI_CONNECT_PROMPT,
+  providerForHostId,
+  type AiHostBrand,
+  type AiHostLink,
+  type AiHostConfigureStage,
+  type AiHostGuide,
+  type AiProvider,
+  type AiCapability,
+} from "../guide";

package/src/react/mcp-endpoint-url.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+import { Code } from "@12-apps/ui/typography/Code";
+
+/**
+ * The store's MCP endpoint URL. Client component because the copy interaction
+ * needs the browser clipboard — the `@12-apps/ui` Code component provides the copy
+ * affordance (`copyable`). Pass `copyable={false}` for a display-only field when
+ * an external control owns the copy action (e.g. the connect flow's blue Copiar
+ * button, which also gates the following steps on the copy).
+ */
+export function McpEndpointUrl({
+  url,
+  copyable = true,
+}: {
+  url: string;
+  copyable?: boolean;
+}): React.JSX.Element {
+  return (
+    <Code variant="block" copyable={copyable} data-testid="mcp-endpoint-url">
+      {url}
+    </Code>
+  );
+}

package/src/server/manifest.test.ts

@@ -10,6 +10,11 @@ function tool(name: string): GeneratedTool {
     method: "GET",
     path: `/${name}`,
     inputSchema: { type: "object", properties: {} },
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: false,
+      destructiveHint: false,
+    },
     parameters: [],
     bodyProps: [],
     bodyIsWhole: false,
@@ -20,11 +25,18 @@ function tool(name: string): GeneratedTool {
 
 describe("buildManifest", () => {
   it("sorts tools by name regardless of input order", () => {
-    const manifest = buildManifest([tool("charlie"), tool("alpha"), tool("bravo")], {
-      version: 1,
-      source: "test",
-    });
-    expect(manifest.tools.map((t) => t.name)).toEqual(["alpha", "bravo", "charlie"]);
+    const manifest = buildManifest(
+      [tool("charlie"), tool("alpha"), tool("bravo")],
+      {
+        version: 1,
+        source: "test",
+      },
+    );
+    expect(manifest.tools.map((t) => t.name)).toEqual([
+      "alpha",
+      "bravo",
+      "charlie",
+    ]);
     expect(manifest.version).toBe(1);
     expect(manifest.source).toBe("test");
   });
@@ -32,8 +44,12 @@ describe("buildManifest", () => {
 
 describe("serializeManifest", () => {
   it("is deterministic and ends with a trailing newline", () => {
-    const a = serializeManifest(buildManifest([tool("b"), tool("a")], { version: 1, source: "s" }));
-    const b = serializeManifest(buildManifest([tool("a"), tool("b")], { version: 1, source: "s" }));
+    const a = serializeManifest(
+      buildManifest([tool("b"), tool("a")], { version: 1, source: "s" }),
+    );
+    const b = serializeManifest(
+      buildManifest([tool("a"), tool("b")], { version: 1, source: "s" }),
+    );
     expect(a).toBe(b);
     expect(a.endsWith("\n")).toBe(true);
   });
@@ -44,8 +60,12 @@ describe("serializeManifest", () => {
     // Same data, different key insertion order in inputSchema.
     t1.inputSchema = { type: "object", properties: { b: {}, a: {} } };
     t2.inputSchema = { properties: { a: {}, b: {} }, type: "object" };
-    const s1 = serializeManifest(buildManifest([t1], { version: 1, source: "s" }));
-    const s2 = serializeManifest(buildManifest([t2], { version: 1, source: "s" }));
+    const s1 = serializeManifest(
+      buildManifest([t1], { version: 1, source: "s" }),
+    );
+    const s2 = serializeManifest(
+      buildManifest([t2], { version: 1, source: "s" }),
+    );
     expect(s1).toBe(s2);
   });
 });

package/src/server/redact.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import { redactResponseBody } from "./redact";
+
+describe("redactResponseBody", () => {
+  it("returns the body unchanged when nothing is redacted", () => {
+    const body = { data: { id: "s1", taxId: "123" } };
+    expect(redactResponseBody(body, undefined)).toBe(body);
+    expect(redactResponseBody(body, [])).toBe(body);
+  });
+
+  it("strips a nested path without touching its siblings", () => {
+    const body = { data: { id: "s1", name: "ACME", taxId: "123" } };
+    expect(redactResponseBody(body, ["data.taxId"])).toEqual({
+      data: { id: "s1", name: "ACME" },
+    });
+  });
+
+  it("applies a path to every element when it lands on an array", () => {
+    const body = {
+      data: [
+        { id: "s1", taxId: "1", postalCode: "01000-000" },
+        { id: "s2", taxId: "2", postalCode: "02000-000" },
+      ],
+      pagination: { total: 2 },
+    };
+    expect(
+      redactResponseBody(body, ["data.taxId", "data.postalCode"]),
+    ).toEqual({ data: [{ id: "s1" }, { id: "s2" }], pagination: { total: 2 } });
+  });
+
+  it("does not mutate the caller's object", () => {
+    const body = { data: { id: "s1", taxId: "123" } };
+    redactResponseBody(body, ["data.taxId"]);
+    expect(body.data.taxId).toBe("123");
+  });
+
+  it("ignores a path that does not exist in the body", () => {
+    const body = { data: { id: "s1" } };
+    expect(redactResponseBody(body, ["data.location.latitude"])).toEqual(body);
+  });
+
+  it("leaves non-object bodies alone", () => {
+    expect(redactResponseBody(null, ["data.taxId"])).toBeNull();
+    expect(redactResponseBody("plain", ["data.taxId"])).toBe("plain");
+  });
+});

package/src/server/redact.ts

@@ -0,0 +1,47 @@
+/**
+ * Strip audited-sensitive fields out of a tool result before it reaches the
+ * agent.
+ *
+ * The dispatcher forwards the wrapped endpoint's response body verbatim, so a
+ * narrowed `outputSchema` alone would only change what the manifest CLAIMS is
+ * returned. This module is what actually removes the value, keeping the served
+ * payload and the advertised schema in agreement.
+ */
+
+/** Walk one dotted path, mapping over arrays, and delete the leaf. */
+function stripPath(value: unknown, segments: readonly string[]): void {
+  if (value === null || typeof value !== "object") return;
+
+  if (Array.isArray(value)) {
+    value.forEach((entry) => stripPath(entry, segments));
+    return;
+  }
+
+  const [head, ...rest] = segments;
+  if (!head) return;
+
+  const record = value as Record<string, unknown>;
+  if (rest.length === 0) {
+    delete record[head];
+    return;
+  }
+  if (head in record) stripPath(record[head], rest);
+}
+
+/**
+ * Return `body` without the listed dotted paths.
+ *
+ * The input is deep-cloned first: dispatch results are handed straight to the
+ * JSON-RPC encoder AND reused as `structuredContent`, so mutating in place
+ * could leak a half-redacted object into one of the two surfaces.
+ */
+export function redactResponseBody(
+  body: unknown,
+  paths: readonly string[] | undefined,
+): unknown {
+  if (!paths?.length || body === null || typeof body !== "object") return body;
+
+  const clone = structuredClone(body);
+  paths.forEach((path) => stripPath(clone, path.split(".")));
+  return clone;
+}