To batch convert a folder with an AI agent, point the GroupDocs.Conversion.Mcp server at the folder and describe the job in one sentence. The agent works through the files, calls the conversion engine once per document, and reports what it produced, all locally in Claude, Cursor or GitHub Copilot. It is batch processing driven by a sentence:

تمام فایل‌های DOCX موجود در پوشه «اسناد» را به PDF تبدیل کن و نسخه‌های اصلی را نگه دار

The step‑by‑step version with config and troubleshooting is in the documentation: How to batch-convert a folder of documents with an AI agent. This post walks through the same job as a short session, from the first prompt to handling failures.

از کجا شروع می‌کنید: پوشه ذخیره‌سازی یا پرسش؟

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

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

GROUPDOCS_MCP_STORAGE_PATH پوشه‌ای است که عامل می‌تواند بخواند. GROUPDOCS_MCP_OUTPUT_PATH جایی است که فایل‌های تبدیل‌شده در آن ذخیره می‌شوند. با تنظیم هر دو، پوشهٔ منبع دست نخورده می‌ماند و تمام نتایج به پوشهٔ converted می‌روند. این تمیزترین چیدمان برای یک کار دسته‌ای است. دستور dnx به .NET 10 SDK نیاز دارد؛ تصویر Docker ghcr.io/groupdocs-conversion/conversion-net-mcp:latest پوشه را به عنوان /data سوار می‌کند. پس از ثبت سرور، Claude Desktop، Claude Code، VS Code یا Cursor را مجدداً راه‌اندازی کنید.

اولین پرسش چه کاری انجام می‌دهد؟

در ابتدا مورد ساده را به عامل بدهید:

همهٔ موارد موجود در این پوشه را از DOCX به PDF تبدیل کن.

عامل پوشه را فهرست می‌کند و برای هر فایل ابزار convert را با format: "pdf" فراخوانی می‌کند. هر فراخوانی نام فایلی را از ذخیره‌سازی می‌گیرد و نام فایلی که ذخیره شده را برمی‌گرداند. اگر این کار را دو بار اجرا کنید، اجرای دوم فایل‌های جدیدی با نام‌های متمایز در کنار اولین‌ها ایجاد می‌کند.

چگونه فیلتر یا قاعده‌ای اضافه می‌کنید؟

پرسش لایهٔ ارکستراسیون است. فیلتر کردن، ترتیب‌بندی و سیاست خطا به زبان ساده بیان می‌شوند:

تمام PDFها را به Markdown تبدیل کن؛ فایل‌هایی که قبلاً تبدیل شده‌اند را نادیده بگیر.

فاکتورها را به PDF/A برای بایگانی تبدیل کن و هر فایلی که شکست خورد را فهرست کن.

پیش‌نمایش‌های PNG برای هر ارائه بساز.

برای ترتیب‌بندی، عامل می‌تواند ابتدا get_document_info را فراخوانی کند؛ این فراخوانی نوع فایل، تعداد صفحات و ویژگی‌های پایه را بدون تبدیل برمی‌گرداند:

ابتدا تعداد صفحات هر PDF را بررسی کن و فقط آن‌هایی را که بیش از ۱۰ صفحه دارند تبدیل کن.

تصمیم «بیش از ۱۰ صفحه» به عهدهٔ عامل است. تبدیل همچنان به عهدهٔ موتور است.

وقتی یک فایل شکست می‌خورد چه می‌شود؟

زمانی که موتور نمی‌تواند فایلی را تبدیل کند، مثلاً چون قالب منبع پشتیبانی نمی‌شود یا رمز عبور اشتباه است، متن پاسخ برای آن فایل با عملیات و دلیل شروع می‌شود. نام فایلی که وجود ندارد، فهرست فایل‌هایی که سرور می‌تواند ببیند را برمی‌گرداند تا عامل بتواند خود را اصلاح کند. برای فایل‌های محافظت‌شده، convert پارامتر اختیاری password را می‌پذیرد.

به همین دلیل سیاست شکست باید در پرسش گنجانده شود: «هر فایلی که شکست خورد را فهرست کن» از عامل می‌خواهد در پایان اجرا گزارشی ارائه دهد، بنابراین شکست‌ها نادیده گرفته نمی‌شوند. گزارش را بخوانید و فقط فایل‌های شکست‌خورده را دوباره اجرا کنید.

جلسهٔ نمونه

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

You:    فاکتورها را به PDF/A برای بایگانی تبدیل کن و هر فایلی که شکست خورد را فهرست کن.
Agent:  [فایل‌های فاکتور را فهرست می‌کند]
Agent:  [برای هر فایل، یک‌به‌یک، convert را فراخوانی می‌کند]
Agent:  ۱۱ فایل به پوشهٔ خروجی تبدیل شد.
        شکست: invoice-0412.docx (محافظت‌شده با رمز عبور، رمز عبور داده نشد).

چگونه پیشرفت را در یک پوشهٔ بزرگ دنبال می‌کنید؟

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

اگر کار دسته‌ای باید بدون نظارت اجرا شود چه می‌کنید؟

یک جلسهٔ عامل نیاز به شخصی دارد که آن را آغاز کند. برای خطوط لولهٔ زمان‌بندی‌شده، راهنمای n8n walkthrough نشان می‌دهد چگونه یک ابزار گردش کار همان سرور را هدایت می‌کند و موتور نیز از طریق کتابخانهٔ .NET GroupDocs.Conversion قابل اسکریپت‌نویسی است. از چت برای دسته‌های اد‑هاک استفاده کنید که می‌خواهید گزارش را بخوانید.

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

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

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

چگونه تمام فایل‌های DOCX موجود در یک پوشه را به PDF با هوش مصنوعی تبدیل کنم؟
پوشهٔ ذخیره‌سازی را تنظیم کنید، سپس از عامل خود دقیقاً این کار را در یک جمله بخواهید. عامل فایل‌ها را یکی‌به‌یکی از طریق سرور محلی تبدیل می‌کند و هیچ‌چیزی بارگذاری نمی‌شود.

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

بهترین روش برای خودکارسازی یک خط لولهٔ تبدیل سند چیست؟
از چت برای دسته‌های اد‑هاک که می‌خواهید مرور کنید استفاده کنید. برای خط لوله‌ای که به‌صورت زمان‌بندی شده اجرا می‌شود، همان سرور را از ابزار گردش کاری مانند n8n هدایت کنید یا کتابخانهٔ .NET را اسکریپت‌نویسی کنید.

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