list_templates

Instructions

Implementation Reference

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

  Handler function for the list_templates tool. Calls client.listTemplates with args, formats the result as JSON text, and appends pagination info if hasMore is true.

  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, hasMore, nextCursor } = await client.listTemplates(args, options);
  
      if (templates.length === 0) {
        return { content: [{ type: 'text' as const, text: 'No templates found.' }] };
      }
  
      let text = JSON.stringify(templates, null, 2);
      if (hasMore && nextCursor) {
        text += `\n\nMore results available. Call list_templates again with cursor="${nextCursor}" to fetch the next page.`;
      }
  
      return { content: [{ type: 'text' as const, text }] };
    } catch (error) {
      return {
        isError: true,
        content: [{ type: 'text' as const, text: formatError(error) }],
      };
    }
  }

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

  Input schema (Zod) for the list_templates tool. Defines fields: 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:56-61 (registration)

  Registration of list_templates tool on the MCP server via server.registerTool(), mapping the name, description, schema, and handler.

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

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

  CarboneClient.listTemplates() - the underlying API call that constructs a GET /templates request with query parameters and returns a parsed TemplateListResponse.

  async listTemplates(params?: {
    id?:              string;
    versionId?:       string;
    category?:        string;
    origin?:          number;
    includeVersions?: boolean;
    search?:          string;
    limit?:           number;
    cursor?:          string;
  }, options?: CallOptions): Promise<TemplateListResponse> {
    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[], hasMore: boolean, nextCursor?: string };
    return { templates: json.data, hasMore: json.hasMore ?? false, nextCursor: json.nextCursor };
  }

• src/carbone/types.ts:32-36 (helper)

  Type definition for TemplateListResponse used by list_templates: templates array, hasMore flag, and optional nextCursor for pagination.

  export interface TemplateListResponse {
    templates:  TemplateListItem[];
    hasMore:    boolean;
    nextCursor?: string;
  }