عن المشروع

fumasignal-mcp هو خادم بروتوكول سياق النموذج (MCP) من الطرف الثالث وغير رسمي، وهدفه تمكين مساعدي الذكاء الاصطناعي من البحث في مواقع التوثيق المبنية بـ Fumadocs وقراءتها. يُوجّه إما إلى عنوان URL لنشر Fumadocs أو إلى مجلد مشروع محلي، ويعرض مجموعة من الأدوات المقروءة فقط لأي عميل يدعم MCP. الاسم مستوحى من اسم المستخدم fuma-nama وفكرة إشارات الدخان في نقل الرسائل بين عميل الذكاء الاصطناعي والأداة الخارجية. يؤكد المؤلف أنه غير تابع لمشروع Fumadocs. أوضاع التشغيل يعمل الخادم بطريقتين: الوضع البعيد حيث تُزوّد برأس موقع منشور (المخطط والاستضافة فقط) دون إعداد محلي، والوضع المحلي حيث تُشير إلى جذر مشروع Fumadocs على القرص. يُوزَّع كثنائي npx واحد، والتشغيل النموذجي يكون: npx -y fumasignal-mcp --url https://your-docs.com. الوصول مقروء فقط ولا يُعدِّل التوثيق. الأدوات المعروضة سبع أدوات متاحة: search_docs يبحث في النصوص الكاملة عبر API بحث Orama ويحتاج استعلاماً؛ يمكن أيضاً تمرير علامة للمواقع متعددة المستندات. list_pages يدرج صفحات التوثيق المعروفة مع إمكانية التصفية حسب بادئة URL. get_page يجلب محتوى Markdown الكامل للصفحة. get_section يسترد قسماً محدداً بواسطة مرساة العنوان. get_toc يدرج عناوين الصفحة مع مراسيها. get_meta يعيد البيانات الوصفية أو بيانات frontmatter كـ JSON. get_llms_txt يجلب llms.txt، أو llms-full.txt عند تفعيل الخيار الكامل. يمكن إعطاء مراجعات الصفحات كمسار URL أو عنوان URL مطلق أو slug تحت بادئة docs. تكوين العميل يُوثِّق دليل README أمثلة تكوين لكل من Claude Desktop وClaude Code وCursor وVS Code مع GitHub Copilot Chat وContinue.dev، باستخدام نقل stdio ونفس أمر npx. يمكن تقديم مواقع توثيق متعددة بتسجيل عدة مثيلات تحت مفاتيح مختلفة. بالنسبة لـ Continue.dev، تُعرض صيغة JSON القابلة لإعادة الاستخدام والصيغة الأصلية YAML. عبارات CLI ومتغيرات البيئة تشمل العبارات: --url للنص الأصلي للموقع، --local لجذر المشروع المحلي، --search-path لمسار API بحث غير افتراضي (الافتراضي /api/search)، --docs-prefix لبادئة URL التوثيق (الافتراضي /docs)، --content-dir لمجلد المحتوى المحلي (الافتراضي content/docs)، --auth-header للمواقع التي تتطلب مصادقة، --cache-ttl لتخزين الاستجابات البعيدة مؤقتاً (الافتراضي 300000 مللي ثانية)، بالإضافة إلى --version و--help. كل عبارة لها متغير بيئة مطابق FUMASIGNAL_*، مع أولوية العبارات الصريحة، وهناك FUMASIGNAL_LOG_LEVEL بدون مكافئ بالعبارة. يُوصى بتمرير الأسرار عبر متغير البيئة لتجنب بقائها في سجل الshell أو قوائم العمليات. آلية الاسترجاع في الوضع البعيد، تستدعي عملية البحث API الموقع على Orama وتتعامل مع أشكال المصفوفة المسطحة وhits/document؛ ويجلب فهرسة الصفحات sitemap.xml مع التصفية حسب بادئة docs؛ ويحصل جلب الصفحة أولاً على متغيرات .md و.mdx و/raw، وإلا يعود إلى استخراج HTML والمصادقة إلى Markdown عبر Turndown؛ ويُجلب llms.txt مباشرة. يتم تخزين الاستجابات البعيدة في الذاكرة بفترة TTL افتراضية خمس دقائق. في الوضع المحلي، يتصفح الخادم ملفات Markdown وMDX في دليل المحتوى، ويحلل البيانات الوصفية عبر gray-matter، ويربط الملفات الفهرسية بجذر docs، ويقيّم نتائج البحث بمطابقة الرموز المميزة الموزونة بالعناوين. التوافق والاختبار يتطلب Node.js 20 أو أحدث، واختُبر مع واجهة Orama search API الافتراضية وترتيب sitemap القياسي، ويعمل مع أي عميل STDIO MCP، بما في ذلك Claude Desktop وClaude Code وCursor وVS Code وZed وCline. يتضمن المشروع أكثر من 280 اختبار وحدة مع عينات تغطي مسارات البحث وsitemap وHTML. استكشاف الأخطاء وإصلاحها والتطوير يغطي الدليل المشكلات الشائعة: غياب sitemap يؤثر فقط على list_pages، وخطأ 404 في البحث يعني عادة مسار بحث غير افتراضي أو URL يحتوي على مسار، وقد ينتج عن استخراج HTML ضوضاء في المواقع بلا نقاط نهاية Markdown. يتوفر نص MCP Inspector للتحقق من تسجيل الأدوات بشكل صحيح. تعليمات التطوير تشمل الاستنساخ والتثبيت والتحقق النوعي عبر tsc والتنقيح عبر eslint والاختبار عبر vitest والبناء عبر tsup، مع نص متكامل للتحقق. تُقبل المساهمات بعد فتح issue للتغييرات غير البسيطة. المشروع مرخص تحت رخصة MIT.