convert_document

Instructions

Implementation Reference

• src/tools/convert.ts:82-99 (handler)

  The handler function that executes the convert_document tool logic. It takes file, convertTo, and optional converter args, calls client.convertDocument(), and returns the converted document content.

  export async function handleConvertDocument(
    args: { file: string; convertTo: z.infer<typeof convertDocumentSchema.convertTo>; converter?: 'L' | 'C' | 'O' },
    client: CarboneClient,
    options?: CallOptions
  ) {
    try {
      const { file, ...rest } = args;
      const result = await client.convertDocument({ ...rest, template: await resolveFileInput(file) }, options);
  
      const content = toToolContent(result.buffer, result.filename, args.convertTo);
      return { content: [content] };
    } catch (error) {
      return {
        isError: true,
        content: [{ type: 'text' as const, text: formatError(error) }],
      };
    }
  }

• src/tools/convert.ts:25-80 (schema)

  Input schema for convert_document: defines 'file' (path/URL/base64), 'convertTo' (output format with optional advanced options), and 'converter' (engine: L/C/O).

  export const convertDocumentSchema = {
    file: z
      .string()
      .min(1)
      .describe(
        'The document to convert. Three input forms are accepted: ' +
        '(1) Local file path — absolute or relative, e.g. "/home/user/report.docx" or "./invoice.xlsx". ' +
        '(2) HTTPS URL — the file is downloaded automatically, e.g. "https://example.com/file.pptx". ' +
        '(3) Base64-encoded string — the raw file content encoded as base64. ' +
        'Supported input formats include: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, IDML, ' +
        'Markdown (MD), PDF, TXT, CSV, PNG, JPG, SVG, and more. ' +
        'Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type'
      ),
  
    convertTo: z
      .union([
        z.enum(OUTPUT_FORMATS),
        z.object({
          formatName: z.enum(OUTPUT_FORMATS).describe('Target format name.'),
          formatOptions: z
            .record(z.string(), z.unknown())
            .optional()
            .describe(
              'Advanced format options object. Examples by format: ' +
              'PDF — { "EncryptFile": true, "DocumentOpenPassword": "secret", "DocumentPermissionPassword": "owner" } password-protect; ' +
              'PDF — { "Watermarks": [{ "text": "DRAFT", "opacity": 0.2, "rotation": -45, "fontsize": 60 }] } up to 5 watermarks; ' +
              'PDF — { "SelectPdfVersion": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); ' +
              'PDF — { "PageRange": "1-3,5" } export specific pages only; ' +
              'PDF — { "ConvertSlideshow": true } convert each slide to a separate PDF page; ' +
              'Images (PNG/JPG/WEBP) — { "Quality": 90 } set compression quality 0-100; ' +
              'Images — { "density": 150 } set DPI for rasterisation (default 96); ' +
              'CSV — { "fieldSeparator": ";" } custom column separator.'
            ),
        }),
      ])
      .describe(
        'Target output format. ' +
        'Documents : "pdf", "docx", "xlsx", "pptx", "odt", "ods", "odp", "odg", "rtf", "epub". ' +
        'Web/text  : "html", "xhtml", "txt", "csv", "md", "xml", "idml". ' +
        'Images    : "png", "jpg", "jpeg", "webp", "svg", "tiff", "bmp", "gif". ' +
        'Archive   : "zip" (batch output). ' +
        'Simple usage: "pdf". ' +
        'Advanced usage: { "formatName": "pdf", "formatOptions": { "EncryptFile": true, "DocumentOpenPassword": "secret" } }.'
      ),
  
    converter: z
      .enum(CONVERTERS)
      .optional()
      .describe(
        'Converter engine. Only relevant when convertTo is "pdf" (or an image format rasterised from a document). ' +
        '"L" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. ' +
        '"O" — OnlyOffice: highest fidelity rendering for Microsoft Office formats (DOCX, XLSX, PPTX). ' +
        '"C" — Chromium: best for HTML, CSS, JavaScript — full browser rendering. ' +
        'If omitted, LibreOffice is used by default.'
      ),
  };

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

  Exported constants: convertDocumentToolName ('convert_document'), convertDocumentDescription (tool description string).

  export const convertDocumentToolName = 'convert_document';
  
  export const convertDocumentDescription =
    'Convert any document to another format without storing a template. ' +
    'Supports 100+ input/output format combinations: Office documents, PDFs, images, web pages, spreadsheets, and more. ' +
    'The source file can be a local path, a URL, or a base64 string. ' +
    'Use render_document instead when you need data injection ({d.field} tags), translations, or batch generation. ' +
    'Common conversions: ' +
    'DOCX → PDF (file: "report.docx", convertTo: "pdf"), ' +
    'XLSX → PDF (file: "data.xlsx", convertTo: "pdf"), ' +
    'PPTX → PDF (file: "slides.pptx", convertTo: "pdf", converter: "O" for best fidelity), ' +
    'HTML → PDF (file: "page.html", convertTo: "pdf", converter: "C" for full CSS/JS rendering), ' +
    'DOCX → HTML (file: "doc.docx", convertTo: "html"), ' +
    'XLSX → CSV (file: "sheet.xlsx", convertTo: "csv"), ' +
    'PDF → PNG (file: "doc.pdf", convertTo: "png"), ' +
    'PPTX → PNG (first slide as image), ' +
    'MD → PDF (file: "readme.md", convertTo: "pdf").';

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

  Imports convertDocumentToolName, convertDocumentDescription, convertDocumentSchema, and handleConvertDocument from convert.ts.

  import {
    convertDocumentToolName,
    convertDocumentDescription,
    convertDocumentSchema,
    handleConvertDocument,
  } from './convert.js';

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

  Registration of the convert_document MCP tool via server.registerTool() with its name, description, schema, and handler callback.

  server.registerTool(
    convertDocumentToolName,
    { description: convertDocumentDescription, inputSchema: convertDocumentSchema },
    (args, extra) => handleConvertDocument(args, client, { apiKey: extra.authInfo?.token })
  );