Skip to content

Production-ready animations, transitions, backgrounds, and scenes for Remotion

17.9 KB
Raw Blame
import "server-only";

import { McpServer } from "@modelcontextprotocol/server";
import { z } from "zod";
import { VIBES } from "@/lib/docs-schema";
import { SITE_URL } from "@/lib/get-llm-text";
import { readAnatomy, readArchetypeRecipe } from "@/lib/mcp/archetype-files";
import {
  ARCHETYPES,
  type Archetype,
  extractQualityBar,
  type PlanBeat,
  parseRecipe,
  pickArchetype,
} from "@/lib/mcp/archetypes";
import { getCatalog, getComponentMarkdown } from "@/lib/mcp/catalog";
import {
  embedBaseUrl,
  embedUrl,
  MCP_APP_MIME_TYPE,
  PREVIEW_RESOURCE_URI,
} from "@/lib/mcp/config";
import { mcpRequestContext } from "@/lib/mcp/request-context";
import {
  type ComponentRecord,
  closestNames,
  installCommand,
  MAX_LIMIT,
  normalizeName,
} from "@/lib/mcp/search";
import { PREVIEW_WIDGET_HTML } from "@/lib/mcp/widget";
import { searchCatalog } from "@/lib/search/components";
import {
  trackAgentComponentFetch,
  trackAgentSearch,
} from "@/lib/server/analytics";
import { previewManifest } from "@/registry/__manifest__";

const SERVER_INFO = { name: "remocn", version: "1.0.0" };

const INSTRUCTIONS = `Remocn is a shadcn registry of Remotion video components. Find components with search_components: describe what the scene should show or say (in any language), or pass a name or keywords. Read one with get_component before writing code against it, and use plan_video to turn a brief into a beat-by-beat storyboard. Install with \`npx shadcn@latest add @remocn/<name>\`. Full index: ${SITE_URL}/llms-components.txt`;

const MAX_PROPS_JSON = 4000;
// The endpoint is public and unauthenticated; every text input is bounded so
// one request can't hold the event loop.
const MAX_NAME = 200;
const MAX_QUERY = 500;
const MAX_BRIEF = 2000;
const MAX_SUGGEST_INPUT = 64;

const READ_ONLY = {
  readOnlyHint: true,
  destructiveHint: false,
  idempotentHint: true,
  openWorldHint: false,
} as const;

// The title goes in the annotations too: the directory and clients on the
// 2025-03-26 spec read `annotations.title`, newer ones the tool's own `title`.
function readOnly(title: string) {
  return { ...READ_ONLY, title };
}

type TextResult = {
  content: { type: "text"; text: string }[];
  structuredContent?: Record<string, unknown>;
  isError?: boolean;
};

function text(body: string, structuredContent?: Record<string, unknown>) {
  const result: TextResult = { content: [{ type: "text", text: body }] };
  if (structuredContent) result.structuredContent = structuredContent;
  return result;
}

function errorText(body: string): TextResult {
  return { content: [{ type: "text", text: body }], isError: true };
}

function lengthLabel(length: ComponentRecord["length"]): string {
  if (length === undefined) return "—";
  return typeof length === "number" ? `${length}f` : length;
}

function htmlDocsUrl(record: ComponentRecord): string {
  return record.docs.replace(/\.md$/, "");
}

function callerUserAgent(): string {
  return mcpRequestContext.getStore()?.userAgent ?? "";
}

function trackFetch(
  tool: "get_component" | "preview_component",
  input: string,
  record: ComponentRecord | undefined,
): void {
  trackAgentComponentFetch({
    tool,
    userAgent: callerUserAgent(),
    component: record?.name ?? input,
    found: Boolean(record),
  });
}

/** Resolve user input (name, `@remocn/name`, docs path, or title) to a documented component. */
function resolveComponent(input: string): ComponentRecord | undefined {
  const { byName, records } = getCatalog();
  const exact = byName.get(input.trim());
  if (exact) return exact;
  const normalized = normalizeName(input);
  const byNormalized = byName.get(normalized);
  if (byNormalized) return byNormalized;
  const lowered = input.trim().toLowerCase();
  return records.find((r) => r.title.toLowerCase() === lowered);
}

function unknownComponent(input: string): TextResult {
  const { records, registry } = getCatalog();
  const normalized = normalizeName(input);
  const registryOnly = registry.get(normalized);
  if (registryOnly) {
    const hint =
      registryOnly.tier === "remocn-icons"
        ? `Icons are documented as a gallery: ${SITE_URL}/docs/icons/gallery.md`
        : "It is a shared library pulled in by other components, not used on its own.";
    return text(
      `\`${normalized}\` is a registry item without its own docs page. ${hint}\nInstall: \`${installCommand(normalized)}\``,
    );
  }
  // Edit distance against every name is quadratic in the input; a name this
  // long is no typo of a component, so skip the suggestions.
  const matches =
    input.length > MAX_SUGGEST_INPUT
      ? []
      : closestNames(
          records.map((r) => r.name),
          input,
        );
  const suggestion = matches.length
    ? `Did you mean: ${matches.map((m) => `\`${m}\``).join(", ")}?`
    : "Try search_components to find it by what it does.";
  return errorText(`No Remocn component named "${input}". ${suggestion}`);
}

function formatRow(r: ComponentRecord): string {
  const facts = [r.section, r.vibe, lengthLabel(r.length), r.tier]
    .filter(Boolean)
    .join(" · ");
  const lines = [`- \`${r.name}\` — ${r.title} (${facts})`];
  if (r.useWhen[0]) lines.push(`  Use: ${r.useWhen[0]}`);
  if (r.avoidWhen[0]) lines.push(`  Avoid: ${r.avoidWhen[0]}`);
  lines.push(`  Docs: ${r.docs} · Install: \`${r.install}\``);
  return lines.join("\n");
}

function compactRow(r: ComponentRecord) {
  return {
    name: r.name,
    title: r.title,
    section: r.section,
    docs: r.docs,
    vibe: r.vibe ?? null,
    length: r.length ?? null,
    tier: r.tier ?? null,
    useWhen: r.useWhen.slice(0, 2),
    avoidWhen: r.avoidWhen.slice(0, 2),
    install: r.install,
  };
}

function previewFor(name: string, props?: Record<string, unknown>) {
  const entry = previewManifest[name];
  if (!entry) return undefined;
  return {
    name,
    embedUrl: embedUrl(name, props),
    durationInFrames: entry.durationInFrames,
    fps: entry.fps,
    width: entry.compositionWidth,
    height: entry.compositionHeight,
  };
}

function beatOptions(beat: PlanBeat) {
  return beat.components.map((name) => ({
    name,
    embedUrl: previewManifest[name] ? embedUrl(name) : null,
    docs: getCatalog().byName.get(name)?.docs ?? null,
  }));
}

function formatFrames(beat: PlanBeat): string {
  return beat.startFrame !== undefined && beat.endFrame !== undefined
    ? ` (${beat.startFrame}–${beat.endFrame}f)`
    : "";
}

/**
 * `_meta.ui` for the view (McpUiResourceMeta in ext-apps). Hosts read it from
 * the `resources/read` content item, falling back to the `resources/list`
 * entry, so it is set on both. The view only nests iframes of the embed
 * origin; it loads no remote scripts and makes no network calls itself.
 */
function previewResourceMeta() {
  return {
    ui: {
      csp: {
        frameDomains: [embedBaseUrl()],
        resourceDomains: [],
        connectDomains: [],
      },
      permissions: { clipboardWrite: {} },
      prefersBorder: false,
    },
  };
}

export function createRemocnMcpServer(): McpServer {
  const server = new McpServer(SERVER_INFO, { instructions: INSTRUCTIONS });

  server.registerTool(
    "search_components",
    {
      title: "Search Remocn components",
      description:
        "Search Remocn Remotion components by what they do or by the need they serve; matches by meaning as well as by words. Returns name, docs .md URL, vibe, length (frames @30fps), use/avoid notes and install command.",
      inputSchema: z.object({
        query: z
          .string()
          .max(MAX_QUERY)
          .describe(
            "What the component should do or what the scene should say, in any language, e.g. 'typewriter headline' or 'show that setup takes five minutes'",
          ),
        vibe: z.enum(VIBES).optional().describe("Tonal tag to match the brand"),
        maxLength: z
          .number()
          .int()
          .positive()
          .optional()
          .describe("Max motion length in frames @30fps"),
        limit: z.number().int().min(1).max(MAX_LIMIT).optional(),
      }),
      annotations: readOnly("Search Remocn components"),
    },
    async ({ query, vibe, maxLength, limit }) => {
      const started = performance.now();
      const { results, mode } = await searchCatalog({
        query,
        vibe,
        maxLength,
        limit,
      });
      trackAgentSearch({
        surface: "mcp",
        userAgent: callerUserAgent(),
        query,
        results: results.map((r) => r.name),
        mode,
        latencyMs: performance.now() - started,
        vibe,
        maxLength,
      });
      const filters = [
        vibe && `vibe=${vibe}`,
        maxLength !== undefined && `maxLength=${maxLength}f`,
      ]
        .filter(Boolean)
        .join(", ");
      if (results.length === 0) {
        return text(
          `No components match "${query}"${filters ? ` (${filters})` : ""}. Try fewer words${filters ? " or drop the filters" : ""}. Vibes: ${VIBES.join(", ")}. Full index: ${SITE_URL}/llms-components.txt`,
          { results: [] },
        );
      }
      const header = `${results.length} Remocn components for "${query}"${filters ? ` (${filters})` : ""}. Lengths are frames of motion @30fps — a floor for the Sequence, add hold on top.`;
      return text(`${header}\n\n${results.map(formatRow).join("\n")}`, {
        results: results.map(compactRow),
      });
    },
  );

  server.registerTool(
    "get_component",
    {
      title: "Get a Remocn component's docs",
      description:
        "Full markdown docs for one Remocn component: props, usage example, use/avoid notes and install command.",
      inputSchema: z.object({
        name: z
          .string()
          .max(MAX_NAME)
          .describe("Component name, e.g. 'kinetic-center-build'"),
      }),
      annotations: readOnly("Get a Remocn component's docs"),
    },
    async ({ name }) => {
      const record = resolveComponent(name);
      trackFetch("get_component", name, record);
      if (!record) return unknownComponent(name);
      const markdown = await getComponentMarkdown(record.name);
      if (!markdown) return unknownComponent(name);
      const deps = getCatalog().registry.get(record.name)?.deps ?? [];
      const depsLine = deps.length
        ? `\n\nRegistry dependencies (installed automatically): ${deps.map((d) => `\`${d}\``).join(", ")}`
        : "";
      return text(`${markdown}${depsLine}`);
    },
  );

  server.registerTool(
    "plan_video",
    {
      title: "Plan a Remocn video",
      description:
        "Turn a video brief into a storyboard: picks an archetype, returns its recipe and a beat list with suggested Remocn components per beat.",
      inputSchema: z.object({
        brief: z
          .string()
          .min(1)
          .max(MAX_BRIEF)
          .describe("What the video is about, e.g. 'launch video for our CLI'"),
        archetype: z
          .enum(ARCHETYPES)
          .optional()
          .describe("Force an archetype instead of picking by keywords"),
        durationSeconds: z
          .number()
          .positive()
          .max(600)
          .optional()
          .describe("Target length; picks the closest recipe variant"),
      }),
      annotations: readOnly("Plan a Remocn video"),
      _meta: { ui: { resourceUri: PREVIEW_RESOURCE_URI } },
    },
    async ({ brief, archetype, durationSeconds }) => {
      const pick = archetype
        ? { archetype, matched: [] as string[], fallback: false }
        : pickArchetype(brief);
      const chosen: Archetype = pick.archetype;
      const recipe = readArchetypeRecipe(chosen);
      if (!recipe) {
        return errorText(
          `The ${chosen} recipe is not available on this server. Use search_components and the index at ${SITE_URL}/llms-components.txt instead.`,
        );
      }

      const catalog = getCatalog();
      const plan = parseRecipe(
        recipe,
        catalog.registry.keys(),
        durationSeconds,
      );
      const beats = plan.beats.map((beat) => {
        const primary = beat.components.find((n) => previewManifest[n]);
        return {
          ...beat,
          preview: primary ? previewFor(primary) : null,
          options: beatOptions(beat),
        };
      });
      const picked = [
        ...new Set([
          ...beats.flatMap((b) => (b.preview ? [b.preview.name] : [])),
          ...plan.transitions.slice(0, 1),
        ]),
      ];
      const install = picked.length
        ? `npx shadcn@latest add ${picked.map((n) => `@remocn/${n}`).join(" ")}`
        : "";
      const prompts = {
        claudeCode: `/remocn:video ${brief}`,
        generic: `Build a ${chosen} video in this Remotion project with Remocn components (${SITE_URL}/llms.txt): ${brief}`,
      };

      const why = archetype
        ? "requested"
        : pick.fallback
          ? "default — no archetype keywords matched; pass `archetype` to override"
          : `matched: ${pick.matched.join(", ")}`;
      const lines: string[] = [
        `# Video plan: ${chosen} (${why})`,
        "",
        `Brief: ${brief}`,
        `Recipe default duration: ${plan.meta.defaultduration ?? "see recipe"}${plan.variant ? ` · variant: ${plan.variant}` : ""}${plan.totalFrames ? ` · beats total ${plan.totalFrames}f` : ""}`,
        "",
        "## Beats",
        "The first component of each beat is the suggested pick; the rest are recipe alternatives.",
        "",
      ];
      beats.forEach((beat, i) => {
        lines.push(`${i + 1}. **${beat.name}**${formatFrames(beat)}`);
        if (beat.what) lines.push(`   ${beat.what}`);
        if (beat.components.length)
          lines.push(
            `   Components: ${beat.components.map((c) => `\`${c}\``).join(", ")}`,
          );
        if (beat.buildNew.length)
          lines.push(
            `   Build new (not in catalog): ${beat.buildNew.map((c) => `\`${c}\``).join(", ")}`,
          );
      });
      if (plan.transitions.length)
        lines.push(
          "",
          `Transitions: ${plan.transitions.map((c) => `\`${c}\``).join(", ")}`,
        );
      if (plan.extras.length) {
        lines.push("", "Optional:");
        for (const extra of plan.extras) {
          const parts = [
            ...extra.components.map((c) => `\`${c}\``),
            ...extra.buildNew.map((c) => `build \`${c}\``),
          ];
          lines.push(
            `- ${extra.label}${parts.length ? `: ${parts.join(", ")}` : ""}`,
          );
        }
      }
      for (const note of plan.notes) lines.push("", `Note: ${note}`);
      if (install) lines.push("", "## Install", "", `\`${install}\``);
      lines.push(
        "",
        "## Next step",
        "",
        `Claude Code with the Remocn plugin: \`${prompts.claudeCode}\``,
        `Other agents: ${prompts.generic}`,
        "Read each component's docs (get_component) before writing code against its props.",
        "",
        "---",
        "",
        `## Recipe: ${chosen} (authoritative — follow it over the summary above)`,
        "",
        recipe.trim(),
      );
      const anatomy = readAnatomy();
      const qualityBar = anatomy ? extractQualityBar(anatomy) : undefined;
      if (qualityBar)
        lines.push(
          "",
          "---",
          "",
          "## Quality bar (from anatomy.md)",
          "",
          qualityBar,
        );

      return text(lines.join("\n"), {
        kind: "plan",
        brief,
        archetype: chosen,
        archetypeReason: why,
        variant: plan.variant ?? null,
        defaultDuration: plan.meta.defaultduration ?? null,
        totalFrames: plan.totalFrames ?? null,
        beats,
        transitions: plan.transitions,
        extras: plan.extras,
        notes: plan.notes,
        install,
        prompts,
      });
    },
  );

  server.registerTool(
    "preview_component",
    {
      title: "Preview a Remocn component",
      description:
        "Live in-chat preview of a Remocn component with optional props. Also returns its docs URL and install command.",
      inputSchema: z.object({
        name: z
          .string()
          .max(MAX_NAME)
          .describe("Component name, e.g. 'kinetic-center-build'"),
        props: z
          .record(z.string(), z.unknown())
          .optional()
          .describe("Props merged over the component's demo defaults"),
      }),
      annotations: readOnly("Preview a Remocn component"),
      _meta: { ui: { resourceUri: PREVIEW_RESOURCE_URI } },
    },
    async ({ name, props }) => {
      const record = resolveComponent(name);
      trackFetch("preview_component", name, record);
      if (!record) return unknownComponent(name);
      if (props && JSON.stringify(props).length > MAX_PROPS_JSON) {
        return errorText(
          `props is too large to preview (max ${MAX_PROPS_JSON} chars of JSON).`,
        );
      }
      const preview = previewFor(record.name, props);
      const docsPage = htmlDocsUrl(record);
      if (!preview) {
        return text(
          `\`${record.name}\` has no live preview. Docs: ${record.docs}\nInstall: \`${record.install}\``,
        );
      }
      return text(
        [
          `Live preview of \`${record.name}\` (${record.title}): ${preview.embedUrl}`,
          `${preview.durationInFrames}f @ ${preview.fps}fps, ${preview.width}×${preview.height}${props ? ", custom props applied over demo defaults" : ""}.`,
          `Docs: ${record.docs}`,
          `Install: \`${record.install}\``,
        ].join("\n"),
        {
          kind: "preview",
          ...preview,
          title: record.title,
          docs: record.docs,
          docsPage,
          install: record.install,
          props: props ?? null,
        },
      );
    },
  );

  server.registerResource(
    "remocn-preview",
    PREVIEW_RESOURCE_URI,
    {
      title: "Remocn live preview",
      description: "Plays Remocn components and video plans in the chat.",
      mimeType: MCP_APP_MIME_TYPE,
      _meta: previewResourceMeta(),
    },
    async (uri) => ({
      contents: [
        {
          uri: uri.href,
          mimeType: MCP_APP_MIME_TYPE,
          text: PREVIEW_WIDGET_HTML,
          _meta: previewResourceMeta(),
        },
      ],
    }),
  );

  return server;
}