An AI agent should choose which file to convert and which format to convert it to, and a conversion engine should do the converting. With the GroupDocs.Conversion.Mcp server, Claude, Cursor or GitHub Copilot call that engine locally, on your machine, from one sentence:

Convert contract.docx to PDF

The step-by-step version with config and troubleshooting is in the documentation: How to convert documents with AI agents using MCP. This post explains why the split matters and where the agent should stay out of the way.

چه مشکلی پیش می‌آید وقتی یک عامل خود فایل را تبدیل می‌کند؟

یک مدل زبانی که «PDF را به Word تبدیل می‌کند» در واقع چیزی را تبدیل نمی‌کند. آن محتویاتی را که به آن داده شده می‌خواند و محتوای جدیدی را در قالب هدف می‌نویسد. هر چیزی که مدل ندیده باشد، نمی‌تواند بازتولید کند: فونت دقیق، هندسه ستون، شکست صفحه قبل از جدول، نام‌های سبک که یک قالب Word به آن‌ها وابسته است. خروجی به نظر تبدیل می‌رسد اما در واقع بازنویسی است.

این همان حالت شکست است که این پست درباره‌اش است. این شکست ساکت است: خروجی بدون خطا باز می‌شود، بنابراین تا زمانی که جدول جابجا شود یا عنوان سبک خود را از دست بدهد، کسی آن را بررسی نمی‌کند. دقت رندرینگ کار موتور تعیین‌پذیر است، نه کار تولید محتوا.

عامل باید چه تصمیمی بگیرد و موتور چه کاری انجام دهد؟

کار را بین قضاوت و اجرا تقسیم کنید.

سؤال عامل تصمیم می‌گیرد موتور انجام می‌دهد
کدام فایل‌ها در محدوده هستند؟ درخواست شما و پوشه ذخیره‌سازی را می‌خواند هیچ‌کاری
قالب هدف چیست؟ «قابل ویرایش کردن» را به DOCX، «آرشیو کردن» را به PDF تبدیل می‌کند هیچ‌کاری
آیا فایل حتی قابل تبدیل است؟ get_supported_formats را فراخوانی می‌کند و پاسخ را می‌خواند قالب‌های هدف معتبر را گزارش می‌دهد
اندازه فایل چقدر است؟ get_document_info را فراخوانی می‌کند و تعداد صفحات را می‌خواند نوع، تعداد صفحات، ویژگی‌ها را می‌خواند
خود تبدیل convert را فراخوانی می‌کند خروجی را با موتور GroupDocs.Conversion رندر می‌کند
در صورت شکست چه کاری انجام شود دوباره تلاش می‌کند، از شما می‌پرسد یا فایل را نادیده می‌گیرد دلیل را به صورت متن برمی‌گرداند

عامل هرگز بایت‌های سند شما را دست نمی‌زند. فقط نام فایل و قالب را می‌فرستد و موتور یک فایل برمی‌گرداند.

چگونه یک عامل را به‌صورت محلی به موتور متصل کنید؟

سرور را یک‌بار در کلاینت خود ثبت کنید. Claude Desktop از claude_desktop_config.json استفاده می‌کند، Claude Code از claude mcp add، VS Code با GitHub Copilot از mcp.json و Cursor از ~/.cursor/mcp.json. سرور همچنین از Visual Studio 2022، Windsurf، Cline، Codex CLI و JetBrains Rider پشتیبانی می‌کند. یک ورودی برای Claude Desktop به شکل زیر است:

{
  "mcpServers": {
    "groupdocs-conversion": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Conversion.Mcp", "--yes"],
      "env": { "GROUPDOCS_MCP_STORAGE_PATH": "/path/to/documents" }
    }
  }
}

dnx به .NET 10 SDK نیاز دارد. اگر Docker را ترجیح می‌دهید، تصویر خودکفا ghcr.io/groupdocs-conversion/conversion-net-mcp:latest است؛ با docker run --rm -i -v $(pwd)/documents:/data اجرا می‌شود. کلاینت از طریق stdio با سرور ارتباط برقرار می‌کند: مسیر = عامل → سرور محلی → فایل‌سیستم محلی. پس از ثبت، کلاینت را مجدداً راه‌اندازی کنید.

هر درخواست کدام ابزار را فعال می‌کند؟

سرور چهار ابزار را در اختیار می‌گذارد. نام‌های آن‌ها به‌صورت متنی هستند؛ عوامل هنگام بروز مشکل به دنبال این نام‌ها می‌گردند.

  • convert سند را به قالب دیگری تبدیل می‌کند و نتیجه را در پوشه ذخیره‌سازی یا خروجی شما ذخیره می‌نماید. پارامترهای آن file، format (مثلاً pdf، docx، xlsx، pptx، html، png، jpg، csv، txt، rtf، md) و یک password اختیاری است.
  • get_supported_formats قالب‌های هدفی که یک فایل منبع می‌تواند به آن‌ها تبدیل شود را فهرست می‌کند.
  • get_document_info بدون تبدیل، نوع فایل، تعداد صفحات و ویژگی‌های پایه را برمی‌گرداند.
  • get_license_status وضعیت لایسنس سرور را (ارزیابی، فایل لایسنس یا حالت متری) گزارش می‌دهد.

دستورات باز‑پاسخ کار می‌کنند چون عامل آن‌ها را زنجیره می‌کند:

چه قالب‌هایی می‌توانم این فایل Visio را به آن‌ها تبدیل کنم؟ سپس به PDF تبدیلش کن.

ابتدا تعداد صفحات whitepaper.pdf را بررسی کن، سپس به DOCX تبدیلش کن.

فایل‌های موجود هرگز بازنویسی نمی‌شوند. تبدیل دوم همان فایل نامی متمایز می‌گیرد، مثلاً report (1).pdf.

جلسه نمونه

این یک جلسه مختصر و نمونه است که از توصیف ابزارها در مستندات ساخته شده، نه یک اسکرین‌شات.

You:    Convert contract-draft.pdf to DOCX so I can edit it.
Agent:  [calls convert with file.filePath = "contract-draft.pdf", format = "docx"]
Agent:  Done. The converted file is saved as contract-draft.docx in your output folder.

برای مشاهده حلقه کامل، راهنمای n8n همان موتور را با یک ورک‌فلو به‌جای چت نشان می‌دهد و اعلامیه به‌طور کلی درباره سرور توضیح می‌دهد.

محدودیت‌ها چیست؟

  • حالت ارزیابی. بدون لایسنس، سرور یک واترمارک ارزیابی به خروجی تبدیل‌شده اضافه می‌کند و هر فرآیند سرور را به ۱۵ سند باز محدود می‌سازد؛ راه‌اندازی مجدد سرور شمارش را صفر می‌کند. ابتدا از عامل خود بپرسید «وضعیت لایسنس سرور تبدیل چیست؟»؛ get_license_status بدون پردازش سند پاسخ می‌دهد.
  • بدون OCR. سرور اسنادی را که لایه متنی دارند تبدیل می‌کند. اسکن‌های ذخیره‌شده به‌صورت PDF فقط‑تصویر به‌عنوان متن قابل ویرایش برنمی‌گردند.
  • تبدیل، نه استخراج. این سرور کل اسناد را تبدیل می‌کند. برای استخراج داده‌های سطح فیلد، سرور همراه GroupDocs.Parser.Mcp (فقط به‌صورت تصویر Docker) مناسب‌تر است و بسیاری از خطوط لوله از هر دو استفاده می‌کنند.

پرسش‌های متداول

آیا Claude می‌تواند یک docx را به pdf تبدیل کند؟
بله، به شرطی که سرور تبدیل متصل باشد. Claude convert را با format: "pdf" فراخوانی می‌کند و موتور GroupDocs فایل را روی ماشین شما تولید می‌کند.

آیا فایل‌های من هنگام تبدیل توسط عامل آپلود می‌شوند؟
نه. این سرور به‌صورت محلی از طریق stdio اجرا می‌شود و اسناد در پوشه ذخیره‌سازی شما می‌مانند. فایل لایسنس نیز از دیسک محلی خوانده می‌شود.

سرور چه قالب‌هایی را می‌تواند تبدیل کند؟
بیش از ۱۰۰ قالب سند، صفحه‑محاسبه، ارائه، تصویر، ایمیل، CAD و وب، همان مجموعه‌ای که کتابخانه .NET GroupDocs.Conversion دارد. برای دریافت فهرست دقیق برای یک فایل خاص، get_supported_formats را بپرسید.

عمیق‌تر بروید