MCP Server

نظرة عامة

يُتيح خادم Web2MD MCP استخدام Web2MD كمجموعة أدوات يمكن لمساعدات AI استدعاءها مباشرة، باستخدام Model Context Protocol (MCP) — وهو معيار مفتوح لربط نماذج AI بالأدوات ومصادر البيانات الخارجية. بعد الإعداد، يمكنك أن تطلب من Claude أو Cursor أو Windsurf تحويل الصفحات، أو البحث في مكتبتك ومزامنتها، أو التحويل الجماعي عبر إضافة Chrome، أو سحب Skill محفوظة — دون مغادرة المحادثة.

يتطلب خادم MCP مفتاح API لـ Web2MD (خطة PRO). أنشئ واحدًا من لوحة التحكم، أو نفّذ npx web2md-cli login للمصادقة مرة واحدة ومشاركة المفتاح مع CLI تلقائيًا (راجع المصادقة أدناه).

الأدوات المتاحة

يوفر خادم MCP 11 أداة، مصنّفة حسب وظيفتها:

الأداة	الوصف
`convert_url`	تحويل أي رابط إلى Markdown نظيف عبر المحوّل على جانب الخادم
`bridge_convert_url`	تحويل رابط عبر إضافة Chrome الخاصة بك عبر HTTP — لـ Reddit، أو الصفحات المُصيَّرة بـ JS، أو الصفحات المحمية بتسجيل الدخول
`agent_convert`	تحويل رابط عبر إضافة Chrome باستخدام Native Messaging (نفس حالات استخدام `bridge_convert_url` لكن بنقل مختلف)
`agent_batch_convert`	تحويل جماعي لما يصل إلى 50 رابطًا عبر إضافة Chrome باستخدام Native Messaging
`search_library`	البحث في مكتبتك المحفوظة حسب الكلمة المفتاحية و/أو الوسم
`get_library_items`	جلب Markdown الكامل لعناصر المكتبة عبر المُعرِّف (id)
`sync_library`	مزامنة مكتبتك إلى مجلد محلي كملفات Markdown
`list_skills`	سرد الـ Skills المحفوظة في حساب Web2MD السحابي الخاص بك
`get_skill`	جلب المحتوى الكامل لـ Skill واحدة عبر المُعرِّف أو الاسم
`semantic_search`	مهملة (Deprecated) — استخدم `search_library` و`get_library_items` بدلاً منها
`get_conversion`	مهملة (Deprecated) — استخدم `search_library` و`get_library_items` بدلاً منها

convert_url

يجلب رابطًا على جانب الخادم ويُرجع محتوى الصفحة كـ Markdown، مع العنوان وعدد الكلمات ووقت القراءة. يدعم نفس خيارات التحويل المتوفرة في REST API (includeImages, includeLinks). مثال على طلب: “حوّل هذا الرابط إلى markdown: https://docs.example.com/getting-started”

bridge_convert_url

يحوّل رابطًا عن طريق جلب HTML الخاص به عبر إضافة Chrome العاملة لديك (عبر جسر HTTP محلي)، ثم يحوّل ذلك الـ HTML إلى Markdown على جانب الخادم. استخدم هذا للصفحات التي لا يمكن للخادم الوصول إليها مباشرة — Reddit، أو المواقع المحمية بتسجيل الدخول، أو الصفحات المُصيَّرة بكثافة عبر JS. يتطلب فتح Chrome مع تثبيت إضافة Web2MD؛ يتم اكتشاف معرّف الإضافة تلقائيًا من مفتاح API الخاص بك. مثال على طلب: “استخدم الجسر لتحويل موضوع Reddit هذا: https://reddit.com/r/…“

agent_convert

يحوّل رابطًا بنفس طريقة bridge_convert_url — عبر إضافة Chrome الخاصة بك — لكن عبر قناة Agent Bridge بواسطة Native Messaging بدلاً من HTTP. يقبل معامل skill اختياريًا: مرّر معرّف أو اسم Skill ليتم إلحاق محتواها بـ Markdown المُرجَع حتى يتمكن الوكيل من التصرف بناءً عليها فورًا. يتطلب تشغيل Chrome مع تثبيت الإضافة والمضيف الأصلي (native host). مثال على طلب: “حوّل هذه الصفحة مع تطبيق مهارة التلخيص: https://…“

agent_batch_convert

نفس نقل agent_convert، لكنه يأخذ مصفوفة تصل إلى 50 رابطًا ويحوّلها بالتتابع في استدعاء واحد. الأفضل لسحب العديد من مواضيع Reddit أو الصفحات المُصيَّرة بـ JS دفعة واحدة. مثال على طلب: “حوّل هذه الروابط الـ 12 إلى Markdown دفعة واحدة: […]“

search_library

يبحث في مكتبة Web2MD الخاصة بك — كل صفحة قمت بحفظها — حسب الكلمة المفتاحية (يطابق العنوان والمحتوى الكامل للصفحة) و/أو الوسم، من الأحدث إلى الأقدم. يُرجع بيانات وصفية مختصرة (id، العنوان، الرابط، التاريخ، الوسوم)، وليس Markdown الكامل. حسابات الخطة المجانية ترى فقط أحدث العناصر في النتائج؛ تخبرك الأداة عندما يتم اقتطاع النتائج. مثال على طلب: “ابحث في مكتبتي عن أي شيء متعلق بالمصادقة”

get_library_items

يجلب محتوى Markdown الكامل لعناصر المكتبة عبر المُعرِّف (حتى 20 عنصرًا لكل استدعاء — استخدم search_library أولاً للعثور على المعرّفات). قد تكون الاستجابات كبيرة؛ للصفحات الطويلة، اجمع 5 معرّفات أو أقل لكل استدعاء. مثال على طلب: “احصل على المحتوى الكامل لعنصري المكتبة abc123 وdef456”

sync_library

يزامن مكتبتك بأكملها إلى مجلد محلي كملفات Markdown، منظّمة حسب الوسم مع بيانات وصفية أمامية (frontmatter). تزايدية افتراضيًا (تتبع مؤشرًا في <dir>/.web2md-sync.json)؛ مرّر full: true لإعادة مسح كل شيء. هذه هي نفس المزامنة التي ينفذها web2md sync من CLI — استخدم أي واجهة تناسب سير عملك. مثال على طلب: “زامن مكتبتي إلى ~/notes/web2md، بوسم ‘research’ فقط”

list_skills

يسرد الـ Skills المحفوظة في حساب Web2MD السحابي الخاص بك كمصفوفة مختصرة (id، الاسم، الوصف). استخدم get_skill لجلب واحدة كاملة. مثال على طلب: “ما هي المهارات المحفوظة لدي؟“

get_skill

يجلب المحتوى الكامل بأسلوب SKILL.md لـ Skill واحدة عبر المُعرِّف أو الاسم — تعليماتها ووصفها ومحتواها بالكامل. استخدم list_skills أولاً إذا كنت لا تعرف المعرّف. مثال على طلب: “احصل على مهارة ‘summarize’ الخاصة بي”

semantic_search / get_conversion (مهملة)

هاتان الأداتان تسبقان المكتبة. لا تزالان تعملان لكنهما تريان فقط التحويلات المحفوظة عبر واجهة السجل القديمة، وليس المكتبة الكاملة — يجب أن تستخدم عمليات الدمج الجديدة search_library وget_library_items بدلاً من ذلك.

المصادقة

يحسم الخادم مفتاح API بهذا الترتيب:

متغير البيئة WEB2MD_API_KEY، إن وُجد.
وإلا، ~/.web2md/config.json — نفس الملف الذي يكتبه npx web2md-cli login (تدفق تسجيل الدخول عبر الجهاز في CLI). نفّذ login مرة واحدة وسيلتقط كل من CLI وخادم MCP المفتاح تلقائيًا، دون الحاجة لكتلة env.

إذا لم يتم العثور على أي منهما، يبدأ الخادم لكن كل استدعاء أداة يُرجع خطأ مصادقة مع تلميح لضبط المفتاح أو تنفيذ login.

الإعداد

Claude Desktop
Cursor
Windsurf

افتح ملف إعدادات Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

أضف إدخال web2md ضمن mcpServers:

{
  "mcpServers": {
    "web2md": {
      "command": "npx",
      "args": ["-y", "web2md-mcp-server"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

إذا سبق لك تنفيذ npx web2md-cli login، يمكنك حذف كتلة env بالكامل — يقرأ الخادم المفتاح من ~/.web2md/config.json.أعد تشغيل Claude Desktop. يجب أن تظهر أدوات Web2MD في منتقي الأدوات.

افتح ملف إعدادات Cursor MCP في ~/.cursor/mcp.json وأضف:

{
  "mcpServers": {
    "web2md": {
      "command": "npx",
      "args": ["-y", "web2md-mcp-server"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

أعد تشغيل Cursor لتحميل الخادم الجديد.

افتح ملف إعدادات Windsurf MCP في ~/.windsurf/mcp.json وأضف:

{
  "mcpServers": {
    "web2md": {
      "command": "npx",
      "args": ["-y", "web2md-mcp-server"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

أعد تشغيل Windsurf لتحميل الخادم الجديد.

أمثلة الاستخدام

بمجرد تشغيل خادم MCP، يمكنك استخدام اللغة الطبيعية في مساعد AI الخاص بك:

تحويل صفحة إلى Markdown

أنت: حوّل هذا الرابط إلى markdown: https://react.dev/learn/thinking-in-reactالمساعد: (يستدعي convert_url) إليك Markdown المحوَّل لصفحة “Thinking in React”…

البحث والسحب من مكتبتك

أنت: ابحث في مكتبتي عن أي شيء متعلق بالمصادقة، ثم احصل على المحتوى الكامل للأحدثالمساعد: (يستدعي search_library ثم get_library_items) وجدت 3 عناصر متعلقة بالمصادقة. إليك المحتوى الكامل للأحدث، “OAuth 2.0 Guide”…

مزامنة مكتبتك محليًا

أنت: زامن مكتبتي إلى ~/notes/web2mdالمساعد: (يستدعي sync_library) تمت مزامنة 42 عنصرًا جديدًا، و118 محدّثًا مسبقًا، و0 فشل.

التحويل الجماعي عبر الإضافة

أنت: حوّل هذه المواضيع الـ 8 من Reddit دفعة واحدة: […]المساعد: (يستدعي agent_batch_convert) تم تحويل 8/8 روابط بنجاح.

تطبيق Skill محفوظة

أنت: ما هي المهارات المتوفرة لدي، وهل يمكنك تطبيق “summarize” على هذه الصفحة: https://…المساعد: (يستدعي list_skills ثم agent_convert مع skill: "summarize") إليك الصفحة محوَّلة إلى Markdown، مع تطبيق مهارة التلخيص أسفلها…

اجمع بين الأدوات في محادثة واحدة. على سبيل المثال: “ابحث في مكتبتي عن وثائق React، ثم احصل على المحتوى الكامل للأحدث.”

استكشاف الأخطاء وإصلاحها

الأدوات لا تظهر بعد الإعداد

تأكد من أنك أعدت تشغيل التطبيق بعد تعديل ملف الإعدادات. تحقق من أن npx -y web2md-mcp-server يعمل بنجاح في الطرفية لديك.

أخطاء المصادقة

تحقق من أن WEB2MD_API_KEY مفتاح w2m_ صالح، أو أن ~/.web2md/config.json يحتوي على واحد (أعد تنفيذ npx web2md-cli login إن لم تكن متأكدًا). يمكنك التحقق من مفتاحك على صفحة مفاتيح API.

فشل agent_convert / agent_batch_convert / bridge_convert_url

تتطلب هذه الأدوات فتح Chrome مع تثبيت إضافة Web2MD، وبالنسبة لأدوات agent_* — تثبيت المضيف الأصلي (native host) أيضًا. راجع Agent Bridge للإعداد.

فشل npx في حل الحزمة

جرّب تثبيت الحزمة عالميًا أولاً: npm install -g web2md-mcp-server، ثم غيّر command إلى web2md-mcp-server واحذف حقل args.

البدء

الميزات الأساسية

متقدم

الخطط

نظرة عامة

الأدوات المتاحة

convert_url

bridge_convert_url

agent_convert

agent_batch_convert

search_library

get_library_items

sync_library

list_skills

get_skill

semantic_search / get_conversion (مهملة)

المصادقة

الإعداد

أمثلة الاستخدام

استكشاف الأخطاء وإصلاحها

​نظرة عامة

​الأدوات المتاحة

​convert_url

​bridge_convert_url

​agent_convert

​agent_batch_convert

​search_library

​get_library_items

​sync_library

​list_skills

​get_skill

​semantic_search / get_conversion (مهملة)

​المصادقة

​الإعداد

​أمثلة الاستخدام

​استكشاف الأخطاء وإصلاحها

نظرة عامة

الأدوات المتاحة

convert_url

bridge_convert_url

agent_convert

agent_batch_convert

search_library

get_library_items

sync_library

list_skills

get_skill

semantic_search / get_conversion (مهملة)

المصادقة

الإعداد

أمثلة الاستخدام

استكشاف الأخطاء وإصلاحها