convert_document
Convert documents between formats like PDF, DOCX, HTML, and Markdown while preserving original formatting and styles.
Instructions
Convert documents between formats with enhanced style preservation. Output directory is controlled by OUTPUT_DIR environment variable. All output files will be automatically saved to the directory specified by OUTPUT_DIR with auto-generated names. ⚠️ IMPORTANT: For Markdown to HTML conversion with style preservation, use 'convert_markdown_to_html' tool instead for better results with themes and styling. For creating Word documents from content, use 'create_word_document' tool to avoid conversion loops.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| inputPath | Yes | Input file path | |
| targetFormat | No | Target format: pdf, html, docx, markdown, md, txt (optional, auto-detected from input if not specified) | |
| preserveFormatting | No | Preserve formatting | |
| useInternalPlaywright | No | Use built-in Playwright for PDF conversion |
Implementation Reference
- src/tools/documentConverter.ts:79-126 (handler)The core handler function for the 'convert_document' tool. It takes document content and conversion options, applies default styling and watermark for PDF, and dispatches to specific format converters (md, html, pdf, docx).async convertDocument( content: DocumentContent, options: ConversionOptions ): Promise<DocumentConversionResult> { try { const styling = { ...this.defaultStyling, ...options.styling }; const outputPath = options.outputPath ?? this.generateOutputPath(content.title ?? 'document', options.format); // 为PDF格式设置默认水印配置 - 企业微信风格（最下层） if (options.format === 'pdf' && !options.watermark) { options.watermark = { enabled: true, text: 'doc-ops-mcp', opacity: 0.015, // 极低透明度（1.5%） fontSize: 8, // 超小字体（8px） rotation: -20, // 轻微旋转 spacing: { x: 600, // 合适的水平间距 y: 500 // 合适的垂直间距 } }; } switch (options.format) { case 'md': return await this.convertToMarkdown(content, outputPath); case 'html': return await this.convertToHTML(content, outputPath, styling); case 'pdf': return await this.convertToPDF(content, outputPath, styling, options.watermark); case 'docx': return await this.convertToDocx(content, outputPath, styling); default: return { success: false, error: `不支持的格式: ${options.format}`, format: options.format, }; } } catch (error: any) { return { success: false, error: `转换失败: ${error.message}`, format: options.format, }; } }
- src/tools/documentConverter.ts:6-56 (schema)TypeScript interfaces defining the input (DocumentContent, ConversionOptions) and output (DocumentConversionResult) schemas for the convertDocument function.interface DocumentContent { title?: string; content: string; author?: string; description?: string; metadata?: { [key: string]: string; }; } interface ConversionOptions { outputPath?: string; format: 'md' | 'pdf' | 'docx' | 'html'; styling?: { fontSize?: number; fontFamily?: string; lineHeight?: number; margins?: { top?: number; bottom?: number; left?: number; right?: number; }; colors?: { primary?: string; secondary?: string; text?: string; }; }; // PDF水印配置 watermark?: { enabled?: boolean; // 是否启用水印，PDF格式默认为true text?: string; // 水印文字，默认为'doc-ops-mcp' imagePath?: string; // 水印图片路径，如果提供则优先使用图片 opacity?: number; // 透明度，0-1之间，默认0.1 fontSize?: number; // 文字水印字体大小，默认48 rotation?: number; // 旋转角度，默认-45度 spacing?: { x?: number; // 水印间距X，默认200 y?: number; // 水印间距Y，默认150 }; }; } interface DocumentConversionResult { success: boolean; outputPath?: string; error?: string; fileSize?: number; format: string; }
- Helper method in ConversionPlanner that determines which tool to use for conversions, frequently returning 'convert_document' as the default or mapped tool.private getToolForConversion(fromFormat: string, toFormat: string): string { // 特殊转换工具映射 const specialMappings: Record<string, Record<string, string>> = { docx: { pdf: 'convert_docx_to_pdf', html: 'convert_document', }, markdown: { html: 'convert_markdown_to_html', docx: 'convert_markdown_to_docx', }, html: { markdown: 'convert_html_to_markdown', }, }; if (specialMappings[fromFormat]?.[toFormat]) { return specialMappings[fromFormat][toFormat]; } // 默认使用通用转换工具 return 'convert_document'; }
- Helper method providing detailed descriptions for the 'convert_document' tool based on input/output formats, used in planning.private getConvertDocumentDescription(fromFormat: string, toFormat: string): string { if (fromFormat === 'html' && toFormat === 'docx') { return '将HTML文档转换为DOCX格式，保留样式、结构和格式，生成完整的Word文档'; } if (fromFormat === 'html' && toFormat === 'markdown') { return '将HTML文档转换为Markdown格式，保留文档结构和基本格式'; } if (fromFormat === 'docx' && toFormat === 'markdown') { return '将DOCX文档转换为Markdown格式，使用优化转换器提取文本内容和结构，保留标题、段落、列表等格式'; } if (fromFormat === 'docx' && toFormat === 'html') { return '将DOCX文档转换为HTML格式，使用OOXML解析器保留样式、格式和结构，生成完整的HTML文档'; } return `将${fromFormat.toUpperCase()}格式转换为${toFormat.toUpperCase()}格式，保持文档内容和基本结构`; }