convert_document

Instructions

Implementation Reference

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

  The main handler function for the convert_document tool. It resolves the file input (URL/path/base64), calls client.convertDocument to perform the conversion, and formats the result as MCP content (text, image, or blob resource). Errors are caught and returned as structured error messages.

  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)

  The input schema for convert_document defining three parameters: file (string, accepts path/URL/base64), convertTo (string format name or object with formatName + formatOptions), and converter (optional enum 'L'|'C'|'O' for the engine choice).

  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/index.ts:63-67 (registration)

  Tool registration in the MCP server. The convert_document tool is registered using server.registerTool with its name, description, schema, and a handler callback that passes the client and auth token.

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

• src/carbone/client.ts:55-74 (helper)

  The CarboneClient.convertDocument method that makes the actual HTTP POST request to the Carbone API endpoint /render/template?download=true, sending the base64 template content and convertTo/converter parameters, and returns the binary buffer and filename.

  async convertDocument(params: {
    template: string;
    convertTo: OutputFormat;
    converter?: string;
  }, options?: CallOptions): Promise<{ buffer: Buffer; filename: string }> {
    const body: Record<string, unknown> = {
      data: {},
      template: params.template,
      convertTo: params.convertTo,
    };
    if (params.converter) body['converter'] = params.converter;
  
    const response = await this.request('/render/template?download=true', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    }, options);
  
    return this.handleBinaryResponse(response);
  }

• src/validation/schemas.ts:32-36 (schema)

  The validation schema (ConvertDocumentSchema) using Zod, used for runtime validation of convert_document inputs. Defines file (base64 string), convertTo (OutputFormatSchema), and converter (optional 'L'|'C'|'O'). Relies on shared OUTPUT_FORMATS and CONVERTERS constants.

  export const ConvertDocumentSchema = z.object({
    file: z.string().min(1, 'File content required'),
    convertTo: OutputFormatSchema,
    converter: z.enum(CONVERTERS).optional(),
  });