list_templates

Instructions

Implementation Reference

• src/tools/list-templates.ts:5-77 (handler)

  The core handler: registerListTemplatesTool registers the 'list_templates' tool on the McpServer. It accepts an optional 'tag' filter, calls client.listTemplates() to fetch all templates from the API, filters by tag if provided, and formats a text response listing each template (id, description, bestFor, needsPhoto, tags, required/optional slots).

  export function registerListTemplatesTool(
    server: McpServer,
    client: RendrKitClient,
  ): void {
    server.registerTool(
      "list_templates",
      {
        description:
          "List all available image templates with their slot definitions. Use this to discover which templates exist and what slots they accept for direct rendering with generate_image.",
        inputSchema: {
          tag: z
            .string()
            .optional()
            .describe(
              'Filter by tag (e.g. "photo", "gradient", "event", "food", "tech")',
            ),
        },
      },
      async ({ tag }) => {
        try {
          const result = await client.listTemplates();
          const templates = tag
            ? result.templates.filter((t) => t.tags?.includes(tag))
            : result.templates;
  
          const lines = [
            `${templates.length} templates${tag ? ` matching tag "${tag}"` : ""} available:`,
            "",
          ];
  
          for (const t of templates) {
            const requiredSlots = t.slots
              .filter((s) => s.required)
              .map((s) => s.name);
            const optionalSlots = t.slots
              .filter((s) => !s.required)
              .map((s) => s.name);
  
            lines.push(
              `**${t.id}** — ${t.description}`,
              `  Best for: ${t.bestFor}`,
              `  Needs photo: ${t.needsPhoto}`,
              `  Tags: ${t.tags?.join(", ") || "none"}`,
              `  Required: ${requiredSlots.join(", ") || "none"}`,
              `  Optional: ${optionalSlots.join(", ") || "none"}`,
              "",
            );
          }
  
          return {
            content: [
              {
                type: "text" as const,
                text: lines.join("\n"),
              },
            ],
          };
        } catch (error) {
          const message =
            error instanceof Error ? error.message : String(error);
          return {
            content: [
              {
                type: "text" as const,
                text: `Failed to list templates: ${message}`,
              },
            ],
            isError: true,
          };
        }
      },
    );
  }

• src/types.ts:95-125 (schema)

  Type definitions for TemplateSlot, Template, and TemplatesResponse used by the list_templates tool.

  export interface TemplateSlot {
    name: string;
    required: boolean;
    description: string;
  }
  
  /** A template definition */
  export interface Template {
    id: string;
    name: string;
    description: string;
    bestFor: string;
    needsPhoto: boolean;
    tags: string[];
    slots: TemplateSlot[];
    exampleSlots: Record<string, string>;
  }
  
  /** Response from the upload endpoint */
  export interface UploadResult {
    url: string;
    filename: string;
    size: number;
    mimeType: string;
  }
  
  /** Response from the templates endpoint */
  export interface TemplatesResponse {
    count: number;
    templates: Template[];
  }

• src/server.ts:7-28 (registration)

  Import and registration of registerListTemplatesTool in the main server setup (line 7 import, line 22 registration call).

  import { registerListTemplatesTool } from "./tools/list-templates.js";
  import { registerUploadImageTool } from "./tools/upload-image.js";
  import { registerBatchRenderTool } from "./tools/batch-render.js";
  import { registerCloneTemplateTool } from "./tools/clone-template.js";
  
  export function createServer(client: RendrKitClient): McpServer {
    const server = new McpServer({
      name: "rendrkit",
      version: "0.3.0",
    });
  
    registerGenerateImageTool(server, client);
    registerGetImageTool(server, client);
    registerListBrandKitsTool(server, client);
    registerGetUsageTool(server, client);
    registerListTemplatesTool(server, client);
    registerUploadImageTool(server, client);
    registerBatchRenderTool(server, client);
    registerCloneTemplateTool(server, client);
  
    return server;
  }

• src/api-client.ts:93-95 (helper)

  The API client method listTemplates() that sends a GET request to /api/v1/templates and returns a TemplatesResponse.

  async listTemplates(): Promise<TemplatesResponse> {
    return this.request<TemplatesResponse>("GET", "/api/v1/templates");
  }