Get renderable item details (#2)

* Add renderable item details tool

* Update types

* Tool description updates

* Add preview link for designs

* Check if layer has parametrization

* Review updates

* Add default value

Author: danixeee

src/sdk/api/getRenderableItemDetails.ts

@@ -0,0 +1,118 @@
+import { createAxiosInstance } from "../../axiosConfig";
+import {
+  DesignDetails,
+  DesignVariant,
+  Layer,
+  ProjectDetails,
+  RenderableItemDetails,
+  RenderableItemParameterType,
+} from "../types";
+
+const api = createAxiosInstance();
+
+export const getRenderableItemsDetails = async (
+  renderableItemId: string,
+  isDesign: boolean
+): Promise<RenderableItemDetails[]> => {
+  if (isDesign) {
+    return await getDesignVariants(renderableItemId);
+  } else {
+    return await getProjectTemplates(renderableItemId);
+  }
+};
+
+const getDesignVariants = async (
+  designId: string
+): Promise<RenderableItemDetails[]> => {
+  const response = await api.get<DesignDetails>(`/api/v2/designs/${designId}`);
+  const designDetails = response.data;
+
+  // flatten variants into renderable items with parameter details
+  return designDetails.variants.map((variant) => ({
+    isDesign: true,
+    projectDesignId: designDetails.id,
+    templateVariantId: variant.id,
+    exampleVideoUrl: getExampleVideoUrl(variant),
+    parameters: designDetails.parameters.map((param) => ({
+      key: param.key,
+      mandatory: !param.optional,
+      type: getDesignParameterType(param.type),
+      description: param.description,
+      label: null,
+      defaultValue: param.defaultValue || null,
+    })),
+  }));
+};
+
+const getProjectTemplates = async (
+  projectId: string
+): Promise<RenderableItemDetails[]> => {
+  const response = await api.get<ProjectDetails>(
+    `/api/v2/projects/${projectId}`
+  );
+  const projectDetails = response.data;
+
+  // flatten templates into renderable items with parameter details
+  return projectDetails.templates.map((template) => ({
+    isDesign: false,
+    projectDesignId: projectDetails.id,
+    templateVariantId: template.id,
+    parameters: template.layers.filter(isLayerParametrized).map((layer) => ({
+      key: layer.parametrization.value.replace("#", ""),
+      mandatory: layer.parametrization.mandatory,
+      type: getProjectParameterType(layer),
+      description: null,
+      label: layer.label || null,
+      defaultValue: layer.parametrization.defaultValue || null,
+    })),
+  }));
+};
+
+const isLayerParametrized = (
+  layer: Layer
+): layer is Layer & {
+  parametrization: { value: string; mandatory: boolean };
+} => {
+  return layer.parametrization != null;
+};
+
+const getExampleVideoUrl = (variant: DesignVariant): string | undefined => {
+  const allVariantExamples = Object.values(variant.examples || {});
+  if (allVariantExamples.length === 0) {
+    return undefined;
+  }
+
+  // Find the first example with a videoUrl
+  const videoExample = allVariantExamples.find((example) => example.videoUrl);
+  if (videoExample) {
+    return videoExample.videoUrl;
+  }
+
+  return undefined;
+};
+
+const getDesignParameterType = (type: string): RenderableItemParameterType => {
+  switch (type) {
+    case "STRING":
+      return "STRING";
+    case "MEDIA":
+      return "MEDIA"; // designs do not specify media type
+    case "COLOR":
+      return "COLOR";
+    default:
+      return "STRING"; // Fallback to STRING if unknown
+  }
+};
+
+const getProjectParameterType = (layer: Layer): RenderableItemParameterType => {
+  switch (layer.layerType) {
+    case "DATA":
+      return "STRING";
+    case "MEDIA":
+      return `MEDIA (${layer.mediaType})`; // specify media type
+    case "SOLID_COLOR":
+      return "COLOR";
+    default:
+      return "STRING"; // Fallback to STRING if unknown
+  }
+};

src/sdk/api/index.ts

@@ -0,0 +1,2 @@
+export * from "./listRenderableItems";
+export * from "./getRenderableItemDetails";

src/sdk/api.ts src/sdk/api/listRenderableItems.tssrc/sdk/api.ts renamed to src/sdk/api/listRenderableItems.ts

@@ -1,6 +1,6 @@
-import { createAxiosInstance } from "../axiosConfig";
-import { getAspectRatio } from "../utils/aspectRatio";
-import { Design, Project, RenderableItem } from "./types";
+import { createAxiosInstance } from "../../axiosConfig";
+import { getAspectRatio } from "../../utils/aspectRatio";
+import { Design, Project, RenderableItem } from "../types";
 
 const api = createAxiosInstance();
 

src/sdk/types.ts

@@ -5,6 +5,7 @@ export type DesignVariant = {
   name: string;
   aspectRatio: AspectRatio;
   duration: number;
+  examples: { [key: string]: { videoUrl: string } };
 };
 
 export type ProjectTemplate = {
@@ -17,16 +18,16 @@ export type ProjectTemplate = {
   };
 };
 
-export type Design = {
+export type Design<V extends DesignVariant = DesignVariant> = {
   id: string;
   name: string;
   description: string;
   category: string;
   renderUiDisabled: boolean;
-  variants: DesignVariant[];
+  variants: V[];
 };
 
-export type Project = {
+export type Project<T extends ProjectTemplate = ProjectTemplate> = {
   id: string;
   name: string;
   description: string | null;
@@ -35,7 +36,7 @@ export type Project = {
     tags?: string[];
     folder?: string;
   };
-  templates: ProjectTemplate[];
+  templates: T[];
 };
 
 export type RenderableTemplate = {
@@ -56,3 +57,86 @@ export type RenderableItem = {
   };
   templates: RenderableTemplate[];
 };
+
+export type ParameterType =
+  | "STRING"
+  | "MEDIA"
+  | "COLOR"
+  | "NUMBER"
+  | "BOOLEAN"
+  | "COMPLEX";
+
+export type DesignVariantDetails = DesignVariant & {};
+
+export type DesignDetails = Design<DesignVariantDetails> & {
+  parameters: {
+    key: string;
+    type: ParameterType;
+    name: string;
+    description: string;
+    optional: boolean;
+    defaultValue: any;
+    sampleValue: any;
+  }[];
+};
+
+enum LayerType {
+  DATA = "DATA",
+  MEDIA = "MEDIA",
+  SOLID_COLOR = "SOLID_COLOR",
+}
+
+type Parametrization = {
+  value: string;
+  defaultValue?: string;
+  expression: boolean;
+  mandatory: boolean;
+};
+
+type AbstractLayer<T extends LayerType> = {
+  layerType: T;
+  internalId: string;
+  label?: string;
+  layerName: string;
+  parametrization?: Parametrization;
+};
+
+type DataLayer = AbstractLayer<LayerType.DATA>;
+
+type MediaLayer = AbstractLayer<LayerType.MEDIA> & {
+  mediaType: "image" | "video" | "audio";
+};
+
+type SolidColorLayer = AbstractLayer<LayerType.SOLID_COLOR>;
+
+export type Layer = DataLayer | MediaLayer | SolidColorLayer;
+
+export type ProjectTemplateDetails = ProjectTemplate & {
+  layers: Layer[];
+};
+
+export type ProjectDetails = Project<ProjectTemplateDetails> & {};
+
+export type RenderableItemParameterType =
+  | "STRING"
+  | "MEDIA"
+  | "MEDIA (image)"
+  | "MEDIA (audio)"
+  | "MEDIA (video)"
+  | "COLOR";
+
+export type RenderableItemDetails = {
+  isDesign: boolean;
+  projectDesignId: string;
+  templateVariantId: string;
+  exampleVideoUrl?: string;
+  parameters: {
+    key: string;
+    mandatory: boolean;
+    // Used to understand what parameter changes in the video
+    type: RenderableItemParameterType;
+    description: string | null;
+    label: string | null;
+    defaultValue?: any | null;
+  }[];
+};

src/server.ts

@@ -1,6 +1,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { registerListRenderableItems } from "./tools/listRenderableItems";
+import {
+  registerListRenderableItems,
+  registerGetRenderableItemDetails,
+} from "./tools";
 
 export class PlainlyMcpServer {
   server: McpServer;
@@ -15,6 +18,7 @@ export class PlainlyMcpServer {
 
     // Register tools
     registerListRenderableItems(this.server);
+    registerGetRenderableItemDetails(this.server);
   }
 
   async start() {