list_builtin_templates

Instructions

Implementation Reference

• src/tools/listTemplates.ts:96-130 (handler)

  Main handler function `handleListBuiltinTemplates` that executes the tool logic. Fetches built-in templates via `apiClient.getTemplates()`, optionally filters by category, and formats the output using `renderGroupedBuiltins`.

  export async function handleListBuiltinTemplates(
    apiClient: MDMagicApiClient,
    args: any
  ): Promise<CallToolResult> {
    try {
      const input = listBuiltinTemplatesSchema.parse(args);
      console.error(`[list_builtin_templates] Fetching built-in templates${input.category ? ` (category=${input.category})` : ''}...`);
  
      const response = await apiClient.getTemplates();
      let templates = response.templates || [];
  
      if (input.category) {
        templates = templates.filter(
          t => (t.category || '').toLowerCase() === input.category!.toLowerCase()
        );
      }
  
      if (templates.length === 0) {
        const msg = input.category
          ? `📝 **No built-in templates in category "${input.category}"**\n\nValid categories: Business, Creative, Professional, Technical.`
          : "📝 **No built-in templates available**\n\nNo built-in templates found in the system.";
        return { content: [{ type: "text", text: msg }] };
      }
  
      let output = `🏢 **Built-in Templates** (${templates.length} available${input.category ? `, category=${input.category}` : ''})\n\n`;
      output += renderGroupedBuiltins(templates);
      output += '💡 **Usage:** Pass the template ID (in backticks) as `templateName` to `convert_document`.';
  
      return { content: [{ type: "text", text: output }] };
  
    } catch (error: any) {
      console.error('[list_builtin_templates] Error:', error.message);
      throw error;
    }
  }

• src/utils/validation.ts:31-34 (schema)

  Zod schema `listBuiltinTemplatesSchema` defining input validation: optional `includeDetails` (boolean, default false) and optional `category` filter (enum: Business, Creative, Professional, Technical).

  export const listBuiltinTemplatesSchema = z.object({
    includeDetails: z.boolean().default(false).describe("Include template details"),
    category: z.enum(['Business', 'Creative', 'Professional', 'Technical']).optional().describe("Filter by category: Business (5 templates), Creative (6), Professional (2), Technical (2).")
  });

• src/index.ts:138-170 (registration)

  Tool definition registered via `getToolDefinitions()` – sets name, description, annotations, inputSchema (includeDetails + category), and outputSchema (count + templates array).

  {
    name: "list_builtin_templates",
    description: "List the 15 built-in MDMagic templates, grouped by category. Same as list_all_templates but excludes the user's custom uploads. Use this when the user asks specifically about MDMagic's bundled templates rather than their personal ones.\n\nCategories available: Business (5), Creative (6), Professional (2), Technical (2).",
    annotations: {
      title: "List built-in MDMagic templates",
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    },
    inputSchema: {
      type: "object" as const,
      properties: {
        includeDetails: {
          type: "boolean",
          description: "Include template details like available page sizes and orientations (default: false)"
        },
        category: {
          type: "string",
          enum: CATEGORY_ENUM,
          description: "Optional filter — return only templates in this category."
        }
      }
    },
    outputSchema: {
      type: "object" as const,
      properties: {
        count: { type: "integer", description: "Number of templates returned" },
        templates: { type: "array", items: TEMPLATE_OBJECT_SCHEMA, description: "Matching built-in templates" }
      },
      required: ["templates"]
    }
  },

• src/tools/index.ts:36-37 (registration)

  Route in the unified handler that dispatches 'list_builtin_templates' to `handleListBuiltinTemplates(apiClient, request.params.arguments)`.

  case 'list_builtin_templates':
    return await handleListBuiltinTemplates(apiClient, request.params.arguments);

• src/tools/listTemplates.ts:8-16 (helper)

  Helper function `groupByCategory` used to group templates by their category field.

  function groupByCategory(templates: any[]): Record<string, any[]> {
    const grouped: Record<string, any[]> = {};
    templates.forEach(t => {
      const cat = t.category || 'Uncategorized';
      if (!grouped[cat]) grouped[cat] = [];
      grouped[cat].push(t);
    });
    return grouped;
  }