list_templates

Instructions

Implementation Reference

• src/tools/templates.ts:56-86 (handler)

  The main handler function for the list_templates tool. Calls client.listTemplates() with the provided args and returns formatted JSON results or an error.

  export async function handleListTemplates(
    args: {
      id?: string;
      versionId?: string;
      category?: string;
      origin?: number;
      includeVersions?: boolean;
      search?: string;
      limit?: number;
      cursor?: string;
    },
    client: CarboneClient,
    options?: CallOptions
  ) {
    try {
      const templates = await client.listTemplates(args, options);
  
      if (templates.length === 0) {
        return { content: [{ type: 'text' as const, text: 'No templates found.' }] };
      }
  
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(templates, null, 2) }],
      };
    } catch (error) {
      return {
        isError: true,
        content: [{ type: 'text' as const, text: formatError(error) }],
      };
    }
  }

• src/tools/templates.ts:18-54 (schema)

  Input schema for the list_templates tool using Zod. Defines optional filtering parameters: id, versionId, category, origin, includeVersions, search, limit, cursor.

  export const listTemplatesSchema = {
    id: z
      .string()
      .optional()
      .describe('Filter by Template ID (64-bit format). Cannot be a Version ID.'),
    versionId: z
      .string()
      .optional()
      .describe('Filter by Version ID (SHA-256 format).'),
    category: z
      .string()
      .optional()
      .describe('Filter by category (e.g. "invoices", "legal").'),
    origin: z
      .number()
      .int()
      .optional()
      .describe('Filter by upload origin. 0 = uploaded via API, 1 = uploaded via Carbone Studio.'),
    includeVersions: z
      .boolean()
      .optional()
      .describe('If true, returns all versions for each template. Default: false (only deployed version).'),
    search: z
      .string()
      .optional()
      .describe('Fuzzy search in template names, or exact match on Template ID / Version ID.'),
    limit: z
      .number()
      .int()
      .positive()
      .optional()
      .describe('Maximum number of results to return (default: 100).'),
    cursor: z
      .string()
      .optional()
      .describe('Pagination cursor from the previous response nextCursor field. Use to fetch the next page.'),
  };

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

  Registration of the list_templates tool in the MCP server via server.registerTool(). Links the tool name, schema, and handler together.

  server.registerTool(
    listTemplatesToolName,
    { description: listTemplatesDescription, inputSchema: listTemplatesSchema },
    (args, extra) => handleListTemplates(args, client, { apiKey: extra.authInfo?.token })
  );

• src/carbone/client.ts:249-274 (helper)

  The CarboneClient.listTemplates() method that makes the actual HTTP GET request to /templates with query parameters, returning TemplateListItem[].

  async listTemplates(params?: {
    id?:              string;
    versionId?:       string;
    category?:        string;
    origin?:          number;
    includeVersions?: boolean;
    search?:          string;
    limit?:           number;
    cursor?:          string;
  }, options?: CallOptions): Promise<TemplateListItem[]> {
    const query = new URLSearchParams();
    if (params?.id)                            query.set('id',              params.id);
    if (params?.versionId)                     query.set('versionId',       params.versionId);
    if (params?.category)                      query.set('category',        params.category);
    if (params?.origin !== undefined)          query.set('origin',          String(params.origin));
    if (params?.includeVersions !== undefined) query.set('includeVersions', String(params.includeVersions));
    if (params?.search)                        query.set('search',          params.search);
    if (params?.limit)                         query.set('limit',           String(params.limit));
    if (params?.cursor)                        query.set('cursor',          params.cursor);
  
    const url = `/templates${query.size ? `?${query}` : ''}`;
    const response = await this.request(url, { method: 'GET' }, options);
  
    const json = await response.json() as { data: TemplateListItem[] };
    return json.data;
  }

• src/carbone/types.ts:17-30 (helper)

  Type definition for TemplateListItem, which is the return type of the list_templates tool (and the Carbone API response shape).

  export interface TemplateListItem {
    id: string;
    versionId: string;
    deployedAt?: number;
    createdAt?: number;
    expireAt?: number;
    size?: number;
    type?: string;
    name?: string;
    category?: string;
    comment?: string;
    tags?: string[];
    origin?: number;
  }