Skip to content

Connect wizard

Pick an AI assistant, copy its config, and see when the connection arrives.

441 lines · React · Tailwind 4

Install

$ bunx shadcn@latest add @blocco/connect-wizard

Code

blocks/free/connect-wizard.tsx441 lines
import { useEffect, useState, type ReactNode } from "react";
import { Button } from "@/registry/blocco/ui/button";
import { buttonClass } from "@/registry/blocco/ui/button-class";
import { CopyButton } from "@/registry/blocco/ui/copy-button";
import { ChartColumn, Check, Copy, Link2, Pencil, Search } from "@/registry/blocco/ui/icons";
import { LiveStatus } from "@/registry/blocco/ui/live-status";
import { cn } from "@/registry/blocco/ui/cn";
import { useToast } from "@/registry/blocco/ui/toast";

const MCP_URL = "https://mcp.acme.test/mcp";
const SERVER_NAME = "acme";

type AssistantId = "claude" | "chatgpt" | "cursor" | "vscode" | "claude-code" | "other";

const ASSISTANTS: readonly { id: AssistantId; label: string; mark: string }[] = [
  { id: "claude", label: "Claude", mark: "Cl" },
  { id: "chatgpt", label: "ChatGPT", mark: "Ch" },
  { id: "cursor", label: "Cursor", mark: "Cu" },
  { id: "vscode", label: "VS Code", mark: "VS" },
  { id: "claude-code", label: "Claude Code", mark: ">_" },
  { id: "other", label: "Other", mark: "MCP" },
];

/** Cursor and VS Code both open from a link; the config below is the fallback. */
const cursorLink = `cursor://anysphere.cursor-deeplink/mcp/install?name=${SERVER_NAME}&config=${encodeURIComponent(btoa(JSON.stringify({ url: MCP_URL })))}`;
const vscodeLink = `vscode:mcp/install?${encodeURIComponent(JSON.stringify({ name: SERVER_NAME, type: "http", url: MCP_URL }))}`;
const cursorConfig = JSON.stringify({ mcpServers: { [SERVER_NAME]: { url: MCP_URL } } }, null, 2);
const vscodeConfig = JSON.stringify(
  { servers: { [SERVER_NAME]: { type: "http", url: MCP_URL } } },
  null,
  2,
);
const claudeCodeCommand = `claude mcp add --transport http ${SERVER_NAME} ${MCP_URL}`;

/** For coding agents that can wire up a remote server themselves. */
const agentPrompt = `Connect the Acme MCP server to this tool.

Server URL: ${MCP_URL}

It is a remote MCP server over streamable HTTP that supports OAuth 2.1, so most MCP clients can add it with just the URL and handle sign-in themselves.

1. Find where this tool manages MCP (or "connector") servers.
2. If it supports a remote server with its own sign-in, add one with the URL above. In Claude Code: \`${claudeCodeCommand}\`.
3. If you cannot find the setting, tell me which menu or file to edit instead of guessing.

Confirm once it is connected.`;

async function copy(text: string, toast: ReturnType<typeof useToast>, message = "Copied") {
  try {
    await navigator.clipboard.writeText(text);
    toast(message);
  } catch (error) {
    toast("Could not copy to clipboard", "error");
    throw error;
  }
}

function AssistantTile({
  label,
  mark,
  selected,
  onSelect,
}: {
  label: string;
  mark: string;
  selected: boolean;
  onSelect: () => void;
}) {
  return (
    <button
      type="button"
      aria-pressed={selected}
      onClick={onSelect}
      className={cn(
        "flex cursor-pointer flex-col items-center gap-2 rounded-xl px-1 py-3 text-xs outline-none transition-[background-color,box-shadow,color] duration-150 focus-visible:shadow-[0_0_0_2px_var(--accent)]",
        selected
          ? "bg-surface-2 font-semibold text-text shadow-[0_0_0_2px_var(--accent)]"
          : "text-muted [@media(hover:hover)]:hover:bg-surface-2 [@media(hover:hover)]:hover:text-text",
      )}
    >
      <span
        aria-hidden
        className="flex size-10 items-center justify-center rounded-[10px] bg-surface font-mono text-xs font-semibold text-text smooth-shadow-ring-xs"
      >
        {mark}
      </span>
      <span className="max-w-full text-center leading-tight text-balance">{label}</span>
    </button>
  );
}

/** A value to copy, in its own field: the URL, a command or a JSON config. */
function CopyField({
  value,
  label,
  block,
  wrap,
}: {
  value: string;
  label: string;
  /** Several lines of code rather than one line. */
  block?: boolean;
  /** A command that may run over several lines on a phone, rather than scroll. */
  wrap?: boolean;
}) {
  const toast = useToast();
  return (
    <div className="flex items-start gap-1 rounded-lg bg-surface-2 py-1.5 pr-1.5 pl-3">
      {block ? (
        <pre className="min-w-0 flex-1 overflow-x-auto py-1 font-mono text-xs leading-relaxed">
          {value}
        </pre>
      ) : (
        <code
          className={cn(
            "min-w-0 flex-1 py-1.5 font-mono text-xs",
            wrap ? "break-words" : "overflow-x-auto whitespace-nowrap",
          )}
        >
          {value}
        </code>
      )}
      <CopyButton text={value} label={label} onCopy={(text) => copy(text, toast)} />
    </div>
  );
}

function Steps({ children }: { children: ReactNode[] }) {
  return (
    <ol className="flex flex-col">
      {children.map((step, i) => (
        <li key={i} className="flex gap-3">
          <div className="flex flex-col items-center">
            <span className="tnum flex size-6 shrink-0 items-center justify-center rounded-full bg-surface-2 text-xs font-semibold smooth-shadow-ring-xs">
              {i + 1}
            </span>
            {i < children.length - 1 && <span aria-hidden className="my-1 w-px flex-1 bg-border" />}
          </div>
          <div
            className={cn(
              "flex min-w-0 flex-1 flex-col gap-2 pt-0.5 text-sm",
              i < children.length - 1 && "pb-5",
            )}
          >
            {step}
          </div>
        </li>
      ))}
    </ol>
  );
}

function CopyPromptButton() {
  const toast = useToast();
  return (
    <Button
      variant="outline"
      size="sm"
      onClick={() => void copy(agentPrompt, toast, "Prompt copied").catch(() => {})}
      className="shrink-0"
    >
      <Copy size={14} /> Copy prompt
    </Button>
  );
}

function StepsFor({ id }: { id: AssistantId }) {
  switch (id) {
    case "claude":
      return (
        <Steps>
          <p>In Claude, go to Settings → Connectors and select Add custom connector.</p>
          <p>Paste the URL above.</p>
          <p>Select Add. Claude opens a page to sign you in and ask for your approval.</p>
        </Steps>
      );
    case "chatgpt":
      return (
        <Steps>
          <p>
            In ChatGPT, go to Settings → Apps &amp; Connectors → Advanced settings and turn on
            Developer mode (paid plans only).
          </p>
          <p>
            Under Connectors, select Add custom connector, paste the URL above, and choose OAuth as
            the authentication method.
          </p>
          <p>
            Start a new chat, select + → More → Developer mode, and pick this connector to sign in.
          </p>
        </Steps>
      );
    case "cursor":
      return (
        <Steps>
          <>
            <p>Add the server. Cursor opens and asks you to confirm.</p>
            <div>
              <a href={cursorLink} className={buttonClass({ variant: "primary" })}>
                Add to Cursor
              </a>
            </div>
          </>
          <p>Select Connect next to Acme, then sign in and approve access.</p>
          <>
            <p>
              If the button does nothing, add this to{" "}
              <code className="font-mono text-xs">.cursor/mcp.json</code>.
            </p>
            <CopyField block value={cursorConfig} label="Copy Cursor config" />
          </>
        </Steps>
      );
    case "vscode":
      return (
        <Steps>
          <>
            <p>Add the server. VS Code opens and asks you to confirm.</p>
            <div>
              <a href={vscodeLink} className={buttonClass({ variant: "primary" })}>
                Add to VS Code
              </a>
            </div>
          </>
          <p>Select Start on the server when VS Code offers it, then sign in and approve access.</p>
          <>
            <p>
              If the button does nothing, add this to{" "}
              <code className="font-mono text-xs">.vscode/mcp.json</code>.
            </p>
            <CopyField block value={vscodeConfig} label="Copy VS Code config" />
          </>
        </Steps>
      );
    case "claude-code":
      return (
        <Steps>
          <>
            <p>Run this in your terminal.</p>
            <CopyField wrap value={claudeCodeCommand} label="Copy command" />
          </>
          <p>
            In Claude Code, run <code className="font-mono text-xs">/mcp</code> and select Acme to
            sign in.
          </p>
          <p>Approve access.</p>
        </Steps>
      );
    case "other":
      return (
        <Steps>
          <p>Find where your tool manages MCP or connector servers.</p>
          <p>Add a remote server over streamable HTTP with the URL above.</p>
          <>
            <p>Sign in when the tool asks. Acme supports OAuth, so there is no key to paste.</p>
            <div className="flex flex-wrap items-center gap-2">
              <CopyPromptButton />
              <span className="text-xs text-muted">Or have your agent set it up for you.</span>
            </div>
          </>
        </Steps>
      );
  }
}

const CAPABILITIES = [
  { icon: Link2, title: "Make links", hint: "Shorten a URL on any of your domains." },
  { icon: Search, title: "Find links", hint: "Search by slug, destination or title." },
  {
    icon: ChartColumn,
    title: "Read your clicks",
    hint: "Totals, top links, countries and referrers.",
  },
  { icon: Pencil, title: "Change where a link goes", hint: "Point it at a new destination." },
] as const;

function Capabilities() {
  return (
    <div>
      <p className="text-sm font-semibold">What it can do</p>
      <ul className="mt-3 flex flex-col gap-3.5">
        {CAPABILITIES.map(({ icon: Icon, title, hint }) => (
          <li key={title} className="flex gap-3">
            <span
              aria-hidden
              className="flex size-8 shrink-0 items-center justify-center rounded-lg bg-surface-2 text-muted"
            >
              <Icon size={16} />
            </span>
            <div className="min-w-0">
              <p className="text-sm font-medium">{title}</p>
              <p className="text-xs text-pretty text-muted">{hint}</p>
            </div>
          </li>
        ))}
      </ul>
    </div>
  );
}

type Phase = "idle" | "waiting" | "connected";

function ConnectRow({
  phase,
  assistant,
  onStart,
  onCancel,
  onReset,
}: {
  phase: Phase;
  assistant: string;
  onStart: () => void;
  onCancel: () => void;
  onReset: () => void;
}) {
  if (phase === "idle")
    return (
      <div>
        <Button variant="outline" onClick={onStart}>
          I&rsquo;ve added the server
        </Button>
      </div>
    );
  if (phase === "connected")
    return (
      <div
        role="status"
        className="flex flex-wrap items-center gap-x-3 gap-y-1 rounded-lg bg-surface-2 px-3 py-2.5"
      >
        <span
          aria-hidden
          className="grid size-6 shrink-0 place-items-center rounded-full bg-accent-2 text-bg"
        >
          <Check size={14} stroke={2.6} className="welcome-check" />
        </span>
        <div className="min-w-0 flex-1">
          <p className="text-sm font-semibold">{assistant} is connected</p>
          <p className="text-xs text-pretty text-muted">
            Ask it to list your newest links. You can disconnect it any time.
          </p>
        </div>
        <Button variant="ghost" size="sm" onClick={onReset}>
          Connect another
        </Button>
      </div>
    );
  return (
    <div
      role="status"
      className="flex flex-wrap items-center gap-x-3 gap-y-1 rounded-lg bg-surface-2 px-3 py-2.5"
    >
      <div className="min-w-0 flex-1">
        <LiveStatus
          done={false}
          announce={false}
          label="Waiting for the connection"
          className="text-sm font-semibold"
        />
        <p className="text-xs text-pretty text-muted">
          Finish signing in and approving access in {assistant}. This page notices on its own.
        </p>
      </div>
      <Button variant="ghost" size="sm" onClick={onCancel}>
        Cancel
      </Button>
    </div>
  );
}

/** Pick an assistant, follow its steps, copy what it needs, and see when it is connected. */
export default function ConnectWizard() {
  const [id, setId] = useState<AssistantId>("claude");
  const [phase, setPhase] = useState<Phase>("idle");
  const current = ASSISTANTS.find((a) => a.id === id) ?? ASSISTANTS[0];

  // Stands in for the app noticing the new grant: it arrives a few seconds
  // after "I've added the server".
  useEffect(() => {
    if (phase !== "waiting") return;
    const timer = setTimeout(() => setPhase("connected"), 3500);
    return () => clearTimeout(timer);
  }, [phase]);

  return (
    <section className="mx-auto max-w-4xl px-4 py-10 sm:px-6 sm:py-12">
      <div className="mb-6">
        <h1 className="text-xl font-semibold tracking-tight text-balance">Connect an assistant</h1>
        <p className="mt-1 text-sm text-pretty text-muted">
          Let an AI assistant make links and read your clicks, with your approval.
        </p>
      </div>

      <div
        role="group"
        aria-label="Connect an assistant"
        className="grid gap-6 rounded-2xl bg-surface p-4 smooth-shadow-ring-xs sm:p-6 lg:grid-cols-[minmax(0,1fr)_17rem] lg:gap-8"
      >
        <div className="flex min-w-0 flex-col gap-5">
          <div
            role="group"
            aria-label="AI assistant"
            className="grid grid-cols-3 gap-1.5 sm:grid-cols-6"
          >
            {ASSISTANTS.map((a) => (
              <AssistantTile
                key={a.id}
                label={a.label}
                mark={a.mark}
                selected={a.id === id}
                onSelect={() => {
                  setId(a.id);
                  setPhase("idle");
                }}
              />
            ))}
          </div>

          <div className="flex flex-col gap-1.5">
            <p className="text-xs text-muted">MCP server URL</p>
            <CopyField value={MCP_URL} label="Copy URL" />
          </div>

          <StepsFor id={id} />

          <ConnectRow
            phase={phase}
            assistant={current.label}
            onStart={() => setPhase("waiting")}
            onCancel={() => setPhase("idle")}
            onReset={() => setPhase("idle")}
          />
        </div>

        <div className="border-t border-border pt-6 lg:border-t-0 lg:border-l lg:pt-0 lg:pl-8">
          <Capabilities />
        </div>
      </div>
    </section>
  );
}