list_all_templates

Instructions

Implementation Reference

• src/tools/listTemplates.ts:37-94 (handler)

  The main handler function for the 'list_all_templates' tool. Fetches both built-in and custom templates from the API, optionally filters by category, groups them, and returns a formatted text output listing all available templates with their names, IDs, descriptions, and categories.

  export async function handleListAllTemplates(
    apiClient: MDMagicApiClient,
    args: any
  ): Promise<CallToolResult> {
    try {
      const input = listTemplatesSchema.parse(args);
      console.error(`[list_all_templates] Fetching all templates${input.category ? ` (category=${input.category})` : ''}...`);
  
      // Fetch both built-in and custom templates
      const [builtinResponse, customResponse] = await Promise.all([
        apiClient.getTemplates(),
        apiClient.getCustomTemplates()
      ]);
  
      let builtinTemplates = builtinResponse.templates || [];
      const customTemplates = customResponse.templates || [];
  
      if (input.category) {
        builtinTemplates = builtinTemplates.filter(
          t => (t.category || '').toLowerCase() === input.category!.toLowerCase()
        );
      }
  
      const allTemplates = [...builtinTemplates, ...customTemplates];
  
      if (allTemplates.length === 0) {
        const msg = input.category
          ? `📝 **No templates found in category "${input.category}"**\n\nTry calling \`list_all_templates\` without a category filter to see all available templates.`
          : "📝 **No templates available**\n\nNo templates found in the system.";
        return { content: [{ type: "text", text: msg }] };
      }
  
      let output = `📚 **Available Templates** (${allTemplates.length} total${input.category ? `, category=${input.category}` : ''})\n\n`;
  
      if (builtinTemplates.length > 0) {
        output += `## 🏢 Built-in Templates (${builtinTemplates.length})\n\n`;
        output += renderGroupedBuiltins(builtinTemplates);
      }
  
      if (customTemplates.length > 0) {
        output += `## 🎨 Your Custom Templates (${customTemplates.length})\n\n`;
        customTemplates.forEach(template => {
          output += `- **${template.name}** (\`${template.id}\`)`;
          if (template.description) output += ` — ${template.description}`;
          output += '\n';
        });
        output += '\n';
      }
  
      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_all_templates] Error:', error.message);
      throw error;
    }
  }

• src/utils/validation.ts:24-28 (schema)

  Zod validation schema (listTemplatesSchema) used by handleListAllTemplates. Defines two optional inputs: includeDetails (boolean, default false) and category (enum of Business/Creative/Professional/Technical).

  // Template listing schema
  export const listTemplatesSchema = z.object({
    includeDetails: z.boolean().default(false).describe("Include template details like page sizes and orientations"),
    category: z.enum(['Business', 'Creative', 'Professional', 'Technical']).optional().describe("Filter built-in templates by category. Custom templates are always included regardless.")
  });

• src/index.ts:104-137 (schema)

  Tool definition (inputSchema + outputSchema) for 'list_all_templates' in the tool definitions array returned by getToolDefinitions(). Describes input parameters (includeDetails, category) and output structure (builtinCount, customCount, templates array).

  {
    name: "list_all_templates",
    description: "List all 15 built-in MDMagic templates plus any custom templates the user has uploaded.\n\nCALL THIS PROACTIVELY when:\n- The user mentions a template by name (verify it exists before convert_document)\n- The user asks 'what templates are available' or similar\n- A previous convert_document call returned 'template not found'\n- The user describes the look they want without naming a template (so you can suggest a real one)\n\nReturns: name, description, type (built-in vs custom), and category. Categories are: Business (5 templates), Creative (6), Professional (2), Technical (2). Use the optional category filter to narrow recommendations (e.g. 'for legal documents' → category: 'Professional').",
    annotations: {
      title: "List all 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 built-in templates in this category. Custom templates are always included regardless. Categories: Business (executive/financial), Creative (designer/artistic/novelty), Professional (legal), Technical (code/data documentation)."
        }
      }
    },
    outputSchema: {
      type: "object" as const,
      properties: {
        builtinCount: { type: "integer", description: "Number of built-in templates returned" },
        customCount: { type: "integer", description: "Number of custom templates returned" },
        templates: { type: "array", items: TEMPLATE_OBJECT_SCHEMA, description: "All matching templates" }
      },
      required: ["templates"]
    }
  },

• src/tools/index.ts:33-34 (registration)

  Registration of 'list_all_templates' in the unified handler switch statement. Maps the tool name string to handleListAllTemplates function call.

  case 'list_all_templates':
    return await handleListAllTemplates(apiClient, request.params.arguments);

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

  Import of handleListAllTemplates from listTemplates module into the registration index.

  import { handleListAllTemplates, handleListBuiltinTemplates, handleListCustomTemplates } from './listTemplates.js';