تصور کنید یک مدیر پروژه است که باید دهها گزارش PDF و لینک وبسایت را به هوش مصنوعی بدهد تا یک تحلیل جامع بنویسد، اما هر بار با مشکل بههمریختگی متن یا عدم شناسایی جداول مواجه میشود. ابزار markitdown-mcp دقیقاً برای حل این مشکل ساخته شده تا هر نوع دادهای را در لحظه به فرمت Markdown تبدیل کند. این قابلیت باعث میشود مدلها بتوانند اسناد پیچیده را مستقیماً از طریق یک رابط استاندارد دریافت کنند و دیگر نیازی به پاکسازی دستی دادهها نباشد.
این تحول در حالی رخ میدهد که پروتکل زمینهٔ مدل (Model Context Protocol یا MCP) — که شبیه به یک درگاه USB استاندارد برای اتصال مدلهای زبانی به ابزارهای خارجی است — در حال تبدیل شدن به استاندارد صنعت است. این استانداردسازی در مسیر تکاملی است که با حذف وضعیت نشستها، مقیاسپذیری بدون سرور را برای این پروتکل ممکن کرد. همانطور که در تحلیل قبلی ما دربارهی مدیریت محیطهای پیچیده توسط Claude Code اشاره کردیم، تمرکز اکنون از «نحوه اجرای دستورات» به «نحوه خواندن بهینه دادهها» تغییر کرده است. برای کاربر نهایی، این یعنی دستیار هوش مصنوعی دیگر یک فایل PDF یا صفحه وب را به صورت یک توده متنی خام نمیبیند، بلکه آن را به شکل Markdown ساختاریافته میبیند که در آن جداول و تیترها کاملاً حفظ شدهاند. در واقع، هوش مصنوعی از یک رابط چت غیرفعال به ابزاری تبدیل میشود که میتواند خودش منابع را پیدا، استخراج و قالببندی کند.
قرارداد فنی و سازوکار
به نقل از تحلیل فنی منتشر شده در وبسایت dev.to در ۲۹ سپتامبر ۲۰۲۶، این سرور دقیقاً یک ابزار به نام convert_to_markdown(uri) ارائه میدهد. این سیستم برای شناسایی منبع داده و تعیین مبدأ استخراج، بر چهار طرح URI خاص تکیه دارد:
file:برای خواندن اسناد از روی دستگاهی که سرور در حال اجراست.https:وhttp:که به مدل اجازه میدهد صفحات وب زنده را فراخوانی و تبدیل کند.data:برای پذیرش دادههای کدگذاری شده به صورت inline base64.
در یک تست عملی که در ۲۳ سپتامبر ۲۰۲۶ انجام شد، یک دستدادن (handshake) از نوع JSON-RPC فاش کرد که سرور خود را با نام {"name": "markitdown", "version": ""} معرفی میکند. نکته قابل توجه این است که رشتهی مربوط به نسخه (version) خالی است؛ این یک ویژگی واقعی سرور است و اشتباه برنامهنویسی نیست. همچنین فراخوانی tools/list تنها یک ابزار را برمیگرداند که دارای یک پارامتر رشتهای اجباری به نام uri است. این تغییرات در تعاریف ابزارها بخشی از یک روند گستردهتر است که سامانه HISTOR با رصد هزاران سرور MCP در حال ثبت و تحلیل آن است.
در همین تست، وقتی یک URI از نوع file:// به یک فایل PDF محلی مربوط به «نتایج سه ماهه سوم ۲۰۲۶ شرکت Northwind Tooling Co.» داده شد، سرور با موفقیت یک جدول Markdown قالببندی شده را در بخش content[0].text با وضعیت isError: false بازگرداند. خروجی شامل دادههای مالی دقیقی بود: درآمد ابزارهای دستی در سه ماهه سوم ۲۰۲۶ برابر ۴,۲۱۰ هزار دلار بود که در مقایسه با ۳,۹۵۵ هزار دلار در سه ماهه دوم ۲۰۲۶، نشاندهنده رشد ۶.۴ درصدی در مقایسه با سه ماهه قبل (QoQ) است.
نصب و انتقال داده
کاربران میتوانند این ابزار را با دستور pip install markitdown-mcp نصب کنند. نکته بسیار مهم این است که markitdown-mcp به کتابخانه markitdown[all] در نسخههای >=0.1.1 و <0.2.0 وابسته است. اگر از محیطی استفاده میکنید که به نسخههای پیشانتشار (pre-release) حساس است، ممکن است سیستم به طور خودکار نسخه قدیمیتر 0.1.x را جایگزین کند. برای جلوگیری از تداخل نسخهها، توصیه میشود برای هر سرور از یک محیط مجازی (Virtual Environment) مجزا استفاده کنید.
این سرور بسته به نیاز کلاینت، دو روش اصلی انتقال داده (Transport) را پشتیبانی میکند:
۱. STDIO: حالت پیشفرض برای اکثر کلاینتهای دسکتاپ است که در آن سرور مستقیماً از طریق ورودی/خروجی استاندارد (standard input/output) با پردازش ارتباط میگیرد.
۲. HTTP/SSE: یک حالت سرور دائمی است که با دستور markitdown-mcp --http --host 127.0.0.1 --port 3001 فعال میشود. در این حالت، Streamable HTTP در مسیر /mcp و انتقال قدیمیتر SSE در مسیر /sse در دسترس است.
پیکربندی کلاینتها
تنظیمات بسته به کلاینت متفاوت است اما منطق JSON-RPC در همه یکسان است.
Claude Desktop
برای Claude Desktop، کاربران باید فایل claude_desktop_config.json را ویرایش کنند. این فایل در macOS در مسیر ~/Library/Application Support/Claude/claude_desktop_config.json و در ویندوز در مسیر %APPDATA%\Claude\claude_desktop_config.json قرار دارد.
- تنظیمات Docker: مستندات رسمی توصیه میکنند سرور از طریق داکر اجرا شود:
{"mcpServers": {"markitdown": {"command": "docker", "args": ["run", "--rm", "-i", "markitdown-mcp:latest"]}}}. - دسترسی به فایلهای محلی: برای خواندن فایلهای محلی در داکر، باید یک Volume را mount کنید:
"args": ["run", "--rm", "-i", "-v", "/Users/me/Documents/contracts:/workdir", "markitdown-mcp:latest"]. سپس فایلها را به صورتfile:///workdir/contract-2026.pdfارجاع دهید. - تنظیمات Pip: اگر ابزار را از طریق pip نصب کردهاید، دستور/آرگومانها را با
"command": "markitdown-mcp"جایگزین کنید. توصیه میشود از مسیر مطلق (absolute path) استفاده کنید تا از خطاهای «عدم شروع سرور» که به دلیل تفاوتهای PATH رخ میدهد، جلوگیری شود.
Cursor و Cline
برای کسانی که از Cursor یا افزونه Cline در VS Code استفاده میکنند، پیکربندی متفاوت است:
- Cursor: تنظیمات را از فایل
~/.cursor/mcp.json(به صورت سراسری) یا.cursor/mcp.json(به صورت پروژه) میخواند. ساختار پیکربندی دقیقاً مشابهmcpServersدر Claude است. - Cline: مدیریت پیکربندی را از طریق پنل اختصاصی MCP Servers انجام میدهد. کاربران باید گزینه "Configure" را انتخاب کرده و JSON را جایگذاری کنند تا افزونه فیلدهای اضافی مانند سوئیچهای تایید (approval toggles) را مدیریت کند، به جای اینکه فایل را دستی ویرایش کنند.
عیبیابی و امنیت
برای ساخت دستی تصویر داکر، کاربران میتوانند مخزن را از github.com/microsoft/markitdown کلون کرده، به مسیر packages/markitdown-mcp بروند و دستور docker build -t markitdown-mcp:latest . را اجرا کنند.
برای عیبیابی، MCP Inspector سریعترین ابزار تشخیصی است. با اجرای دستور npx @modelcontextprotocol/inspector کاربران میتوانند از طریق STDIO یا HTTP (در آدرس http://127.0.0.1:3001/mcp یا /sse) متصل شوند تا پیش از اتصال به کلاینت، از صحت عملکرد ابزار convert_to_markdown مطمئن شوند.
هشدار امنیتی و پایداری: این سرور با تمام دسترسیهای کاربری که آن را اجرا میکند فعالیت میکند و هیچ سیستم احراز هویت داخلی ندارد. این بدان معناست که هر عاملی (Agent) که به این ابزار دسترسی داشته باشد، میتواند هر فایلی را که کاربر به آن دسترسی دارد بخواند یا هر URL-ی را که دستگاه قادر به دسترسی به آن است، فراخوانی کند. این فقدان لایههای امنیتی در سطح پروتکل، یادآور آسیبپذیریهای سیستماتیکی است که اخیراً در سرورهای MCP گوگل و مایکروسافت افشا شد و خطرات دسترسی غیرمجاز را برجسته میکند.
برای کاهش ریسکها، مستندات صراحتاً هشدار میدهند که سرور را فقط به 127.0.0.1 متصل کنید و هرگز آن را در معرض یک رابط عمومی قرار ندهید. برای ایزولاسیون بیشتر، اجرای سرور در یک کانتینر یا ماشین مجازی (VM) با Mountهای محدود به دایرکتوریهای خاص، مسیر توصیه شده است.
نقاط شکست رایج
- عدم نمایش ابزار: اگر ابزار هرگز ظاهر نشد، احتمالاً پردازش در لحظه شروع بسته شده است. دستور پیکربندی را در یک ترمینال اجرا کنید تا نبود باینریهای مورد نیاز را بررسی کنید.
- فایل یافت نشد: URIهای
file:روی دستگاه سرور Resolve میشوند. در داکر، این یعنی مسیر mount شده (مثلاً/workdir/...) و نه مسیر سیستم میزبان. - خطاهای پروتکل: چون انتقال STDIO از stdout برای JSON-RPC استفاده میکند، هر دستور
print()پراکنده در کد باعث شکست جریان داده میشود. لاگها باید به stderr ارسال شوند. - تایماوت: تبدیل دادهها به صورت همگام (Synchronous) است. فایلهای بسیار حجیم ممکن است باعث ایجاد تایماوت در کلاینت شوند.
تحلیل: تغییر به سمت دریافت استاندارد دادهها
این ابزار نشاندهنده تغییر رویکرد از «اسکریپتهای سفارشی» به «قابلیتهای استاندارد» است. پیش از این، اگر میخواستید یک عامل هوش مصنوعی PDF را بخواند، باید یک اسکریپت پایتون خاص برای آن عامل مینوشتید. اکنون با پیادهسازی استاندارد MCP، یک سرور به طور همزمان در Claude، Cursor و Cline کار میکند.
برای کاربر عملی، این امر مانع ساخت یک پایگاه دانش شخصی را کاهش میدهد. دیگر نیازی نیست آرشیوهای خود را دستی به Markdown تبدیل کنید؛ کافی است عامل خود را به یک پوشه ارجاع دهید و اجازه دهید سرور MCP ترجمه را در لحظه انجام دهد.
با این حال، نبود احراز هویت یک نقطه ضعف آشکار برای استفادههای سازمانی است. تا زمانی که سرورهای MCP مدیریت هویت قدرتمندی را ادغام نکنند، این ابزارها محدود به محیطهای محلی و مورد اعتماد باقی خواهند ماند و برای زیرساختهای مشترک شرکتی مناسب نیستند. به خاطر داشته باشید که این ابزار دادهها را تبدیل میکند اما آنها را بررسی نمیکند؛ اگر به یک URL داخلی ارجاع داده شود، مدل هر آنچه بازگردانده شود را خلاصه میکند.
اگر میخواهید منطق تبدیل را بدون راهاندازی محیط پایتون تست کنید، نسخه میزبانی شده در markitdown.tech همان قابلیتهای کتابخانه زیربنایی را از طریق یک رابط وب ارائه میدهد.
گام بعدی شما
- اگر از Cursor یا Claude Desktop استفاده میکنید، سرور را نصب کرده و یک پوشه حاوی PDFهای تخصصی را به آن معرفی کنید تا قدرت استخراج دادههای ساختاریافته را ببینید.
- برای محیطهای حساس، حتماً سرور را در یک کانتینر داکر با دسترسی محدود به دایرکتوریها (Restricted Mounts) اجرا کنید.
- اگر نمیخواهید محیط پایتون را نصب کنید، نسخه وب در markitdown.tech را برای تست منطق تبدیل امتحان کنید.
اما داستان سختافزاری این تحول حتی شگفتانگیزتر است — به تحلیل ما دربارهی تراشههای Blackwell مراجعه کنید.
گفتگو