دع وكيل البرمجة لديك يستخدم المتصفح الذي سجّلت الدخول إليه بالفعل.

ما الذي يبدأ أين

يشغّل عميل MCP لديك حزمة npm كعملية فرعية محلية عبر stdio. تستمع هذه العملية فقط على 127.0.0.1:17374. يتصل بها الامتداد ثم ينفّذ كل مهمة عبر حلقة الوكيل في WebBrain ضمن تبويب المتصفح المحدد.

الخادم ليس متصفحًا ثانيًا ولا ينسخ ملفات تعريف الارتباط. إنه نقطة تسليم محلية بين عميل MCP والامتداد. ملف تعريف المتصفح —وبالتالي الجلسة الموثَّقة— لا يتحرك أبدًا.

قبل الاتصال

سجّل الخادم لدى عميل MCP لديك

استخدم إحدى تهيئة العملاء المحددة أدناه، مرة واحدة فقط. هذه أوامر تثبيت، وليست الطريقة التي تطلب بها مهام المتصفح. بعد التسجيل يشغّل العميل الخادم نيابةً عنك وتواصل المحادثة كالمعتاد؛ لا تشغّل نسخة يدوية موازية على المنفذ نفسه.

تطبيق Codex أو CLI أو امتداد IDE

codex mcp add webbrain -- npx -y @webbrain/mcp-server

يخزّن Codex خوادم MCP في ~/.codex/config.toml؛ ويتشارك التطبيق وCLI وامتداد IDE على المضيف نفسه هذه التهيئة. للمهام الطويلة في المتصفح، افتح الملف ومنحِ الأداة وقتًا يتجاوز ميزانية Codex الافتراضية لكل استدعاء:

[mcp_servers.webbrain]
command = "npx"
args = ["-y", "@webbrain/mcp-server"]
tool_timeout_sec = 360

أعد تشغيل التطبيق أو امتداد IDE بعد تعديل الملف. في CLI، شغّل codex mcp list للتأكد من الإدخال واستخدم /mcp داخل جلسة Codex لفحص الخادم المتصل. راجع دليل Codex MCP الرسمي لمعرفة تهيئة المضيف المشترك وجميع الخيارات المدعومة.

Claude Code

claude mcp add --transport stdio webbrain -- npx -y @webbrain/mcp-server

تتطابق وسيلة النقل الصريحة مع تهيئة MCP الحالية في Claude Code. بعد الإضافة، شغّل claude mcp list للتحقق من صحة الخادم.

Cursor

أضف خادم stdio محليًا في إعدادات MCP في Cursor، أو ضع هذا المحتوى في ملف JSON الخاص بـ MCP الذي يستخدمه Cursor. يتبع التنسيق تنسيق خوادم MCP المحلية في Cursor:

{
  "mcpServers": {
    "webbrain": {
      "command": "npx",
      "args": ["-y", "@webbrain/mcp-server"]
    }
  }
}

OpenCode

أضف هذا الإدخال إلى ملف ~/.config/opencode/opencode.json باستخدام تنسيق خوادم MCP المحلية في OpenCode:

{
  "mcp": {
    "webbrain": {
      "type": "local",
      "command": ["npx", "-y", "@webbrain/mcp-server"]
    }
  }
}

OpenClaw

سجّل WebBrain في OpenClaw كخادم MCP صادر. لا تستخدم openclaw mcp serve لهذا التكامل: فهذا الأمر يجعل OpenClaw نفسه يعمل كخادم، أي باتجاه معاكس.

openclaw mcp add webbrain \
  --command npx \
  --arg -y \
  --arg @webbrain/mcp-server \
  --timeout 360

يستكشف mcp add خادم stdio قبل حفظه. شغّل openclaw mcp status --verbose لفحص التعريف المحفوظ. تتضمن ملفات الأدوات العادية coding وmessaging خوادم MCP المُهيَّأة؛ وقد يخفيها ملف minimal أو رفض صريح لـ bundle-mcp أو سياسة أدوات في بيئة معزولة. راجع دليل MCP في OpenClaw لمعرفة تفاصيل السجل والسياسات الحالية.

التشغيل اليدوي

التشغيل اليدوي مفيد لتشخيص المستمع، لكنه غير ضروري في الاستخدام العادي لـ MCP:

npx -y @webbrain/mcp-server

اترك تلك الطرفية مفتوحة. إغلاقها يوقف مستمع الجسر. من نسخة الشيفرة المصدرية، شغّل npm install ثم npm run build ثم npm start داخل mcp-server/.

وجّه WebBrain إلى المستمع المحلي

1. شغّل عميل MCP لديك أو أعد تشغيله. يجب أن يعمل خادم WebBrain الخاص به قبل أن يتمكن الامتداد من الاتصال.
2. افتح إعدادات WebBrain. انتقل إلى الإعدادات ← Bridge.
3. حدّد الرابط بدقة. أدخل ws://127.0.0.1:17374/extension.
4. الصق مفتاح الاقتران. شغّل npx -y @webbrain/mcp-server pairing-key في طرفية (أو افتح ~/.webbrain/bridge-key) والصق المفتاح في حقل مفتاح الاقتران. لا يثق الخادم إلا بمتصفح يثبت أنه يحمل هذا المفتاح. إذا غاب الحقل، فحدّث WebBrain أولًا.
5. فعّل الجسر السحابي. يجب أن تتغير الحالة من «جارٍ الاتصال» إلى «متصل». التسمية لأسباب تاريخية: هذا الهدف محلي.
6. تحقق من الاتصال من طرف إلى طرف. اطلب من عميل MCP استدعاء webbrain_connection. كلمة «Connected» تثبت أن العميل والخادم المحلي ومستمع WebSocket ومصافحة الامتداد جاهزة.

صِف مهمة المتصفح بلغة طبيعية

اكتب الطلب في Codex أو Claude Code أو Cursor أو OpenClaw أو OpenCode كما لو كنت تكلّف زميلًا بمهمة. ذكر WebBrain يجعل قصتك واضحة لا لبس فيها؛ ضمّن الصفحة والنتيجة المتوقعة والنطاق وما إذا كانت التغييرات مسموحة.

قراءة دون تغيير الصفحة

استخدم WebBrain لقراءة لوحة معلومات Stripe المفتوحة بالفعل في متصفحي. ادرج المدفوعات الفاشلة خلال الأيام السبعة الماضية مع العميل والمبلغ والعملة والتاريخ وسبب الفشل. لا تغيّر أي شيء.

إرجاع JSON قابل للتنبؤ

استخدم WebBrain لاستخراج جميع الفواتير المتأخرة من لوحة المعلومات المفتوحة في متصفحي. أعد JSON يتضمن العميل والمبلغ والعملة وتاريخ الاستحقاق ورابط الفاتورة. لا تغيّر أي شيء.

التفاعل مع الصفحة

استخدم وضع Act في WebBrain لفتح سجل العميل المعروض بالفعل في متصفحي وحدّث اسم الشركة إلى Acme Europe. توقف قبل أي إرسال أو تأكيد نهائي.

يختار وكيل البرمجة webbrain_run للقراءة أو التفاعل العامين، ويختار webbrain_extract عند طلب بيانات مهيكلة. وهو يزوّد الوسائط ويراقب التشغيل ويعرض نتيجة WebBrain في المحادثة. يستطيع وضع Ask القراءة والاستخراج، لكنه لا يستطيع النقر أو الكتابة أو التنقل أو الإرسال. يستطيع وضع Act التفاعل، وفق أذونات WebBrain المعتادة في المتصفح.

webbrain_run(
  task: "read the open Stripe dashboard and list failed payments from the last 7 days with customer, amount, currency, date, and failure reason",
  mode: "ask"
)

للمهام التي تتطلب تفاعلًا، قل صراحةً «استخدم وضع Act في WebBrain» وأبقِ المتصفح مرئيًا. سيطبّق WebBrain رسائل الموافقة المعتادة لكل قدرة ولكل أصل.

الأدوات التي يستخدمها عميل MCP نيابةً عنك

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

اطلب JSON مهيكلًا

في الاستخدام العادي، قل ما الذي تريد استخراجه وسمِّ الحقول المطلوبة: «استخرج جميع الفواتير المتأخرة من لوحة المعلومات المفتوحة باستخدام WebBrain، وأعد JSON يتضمن العميل والمبلغ والعملة وتاريخ الاستحقاق ورابط الفاتورة». ويستطيع عميل MCP قادر ترجمة هذه الحقول إلى المخطط المطلوب واستدعاء webbrain_extract نيابةً عنك.

يوضح المثال بصيغة الدالة أدناه استدعاء الأداة المكافئ لمطوري العملاء ولأغراض التصحيح. صِف منطق الاختيار في task، واكتب شكل المخرجات في output_schema فقط.

webbrain_extract(
  task: "extract every overdue invoice visible in this account; preserve the displayed currency and use ISO dates where the page provides a full date",
  output_schema: {
    type: "object",
    properties: {
      invoices: {
        type: "array",
        items: {
          type: "object",
          properties: {
            customer: { type: "string" },
            amount: { type: "number" },
            currency: { type: "string" },
            due_date: { type: "string" },
            invoice_url: { type: "string" }
          },
          required: ["customer", "amount", "currency", "due_date"]
        }
      }
    },
    required: ["invoices"]
  }
)

• استخدم جذر كائن مع حقلَي properties وrequired صريحين.
• اطلب أضيق البيانات التي تحتاجها. لا يمنح المخطط صلاحية الوصول إلى بيانات لا تراها جلسة المتصفح.
• الأداة للقراءة فقط، لكن نص الصفحة والنتيجة يُرسلان مع ذلك إلى مزوّد نماذج اللغة الكبير المهيَّأ في WebBrain.
• إذا كانت النتيجة أكبر من اللقطة المخزَّنة للتشغيل، فقد يفيد الحالة بأن النتيجة المخزَّنة بُترت. قلّل الطلب وأعد المحاولة.

افهم دورة حياة التشغيل

يدير معظم عملاء MCP هذه الدورة نيابةً عنك: فهم ينتظرون النتيجة، ويعرضون سؤال التوضيح من WebBrain عند الحاجة إلى تدخل بشري، ثم يواصلون بإجابتك. الاستدعاءات الصريحة أدناه مفيدة لمطوري العملاء أو لاستكشاف الأخطاء أو عند الرغبة في تشغيل مهمة طويلة في الخلفية عمدًا.

تنتظر الاستدعاءات في المقدمة بشكل افتراضي. وللأعمال الطويلة يمكن للعميل ضبط wait: false والاستطلاع باستخدام webbrain_status.

# مرجع على مستوى الأداة
# البدء دون انتظار
webbrain_run(task: "compare the invoices across all visible pages", mode: "ask", wait: false)

# استطلاع المعرّف المُعاد
webbrain_status(run_id: "mcp_…")

يُعيد انتهاء مهلة تشغيل WebBrain التحكم إلى عميل MCP، لكنه لا يُجهض مهمة المتصفح عن قصد. استطلع المعرّف run_id المُعاد. وهذا يمنع أن ينهي انقضاء المهلة مهمةً قد تكون اتخذت إجراءً مهمًا بالفعل.

عندما يطرح WebBrain سؤالًا

تتضمن اللقطة المتوقفة سؤالًا مقروءًا للبشر ومعرف clarify_id. اعرض السؤال على المستخدم. وأرسل إجابته حرفيًا؛ لا تستنتجها.

webbrain_respond(
  run_id: "mcp_…",
  clarify_id: "clarify_…",
  answer: "Use the Acme EU account."
)

اختر أقل صلاحية كافية

موافقة عميل MCP وموافقة WebBrain طبقتان مستقلتان. قد يسأل عميلك قبل استدعاء webbrain_run، وقد يسأل WebBrain قبل إجراء مهم على أصل معين. ولا تُغني موافقة عن الأخرى.

حدود الأمان التي يجب الحفاظ عليها

• أبقِ المستمع محليًا. إنه مرتبط بـ 127.0.0.1. لا تُحوّل المنفذ 17374 ولا تنشره عبر جسر حاويات ولا ترحّله إلى الشبكة.
• احفظ مفتاح الاقتران بعناية. حلقة الاسترجاع وحدها ليست مصادقة؛ فلا يثق الخادم بمقبس إلا بعد أن يجيب تحديًا لمرة واحدة بـ HMAC مفتاحُه هو مفتاح الاقتران، ولا يمر المفتاح نفسه عبر المقبس أبدًا. ويستطيع أي شخص يقرأ ~/.webbrain/bridge-key أن يقترن، لذا لا تلصق المفتاح في محادثة. ولا يوثّق الامتداد هوية الخادم، لذا ما زال ينبغي اعتبار الشيفرة المحلية وحزم MCP برمجيات موثوقة.
• استخدم وضع Ask أولًا. فالعمل للقراءة فقط أسهل للتحقق ونطاق تأثيره أصغر.
• أبقِ المتصفح مرئيًا في وضع Act. يمكنك إيقاف التشغيل من الشريط الجانبي، وأي تنقل أو كتابة غير متوقعين يُعدّان سببًا للإيقاف.
• تذكّر حدّ المزوّد. يبقى جسر MCP محليًا، لكن محتوى الصفحة يُرسل إلى مزوّد النموذج المهيَّأ في WebBrain. استخدم نموذجًا محليًا عندما يجب أن يبقى المحتوى على الجهاز.
• لا تخطئ فتظن أن انتهاء المهلة تراجع عن الإجراءات. الإيقاف يوقف الخطوات اللاحقة؛ ولا يستطيع التراجع عن بريد أُرسل أو نموذج أُرسل أو عملية شراء أو أي إجراء مكتمل آخر.

للتصميم الكامل، طالع نموذج الأمان والخصوصية وتدفق البيانات ودليل الأوضاع والأمان والخصوصية.

استكشاف الأخطاء حسب العَرَض

تهيئة البيئة

لعملاء stdio، اضبط متغيرات البيئة في تهيئة MCP لدى ذلك العميل. وإذا غيّرت المنفذ أو المسار، فحدّث رابط الجسر السحابي في إعدادات WebBrain ليطابقه تمامًا.

أتستخدم LM Studio؟

يستخدم LM Studio إضافة WebBrain Web Tools المنفصلة، لا حزمة MCP هذه. وتستطيع أداتا fetch_url وresearch_url فيها قراءة الصفحات العامة دون امتداد المتصفح؛ وتستطيع أدوات المتصفح فيها تفويض هدف إلى جلسة Chromium المسجَّل الدخول إليها عبر المنفذ 17375.

ما لا يفعله هذا الخادم عن قصد

• لا يشغّل متصفح بلا واجهة ولا ينشئ ملف تعريف متصفح جديدًا.
• لا يعمل عبر إصدار Firefox.
• لا يصدّر ملفات تعريف الارتباط أو بيانات الاعتماد أو تخزين الجلسات.
• لا يعرّي نحو خمسين بدائية نقر وكتابة وإطار والتقاط شبكة وDOM في WebBrain مباشرة لعميل MCP.
• لا يجعل الجسر آمنًا للتعريض البعيد.
• لا يلغي الحاجة إلى نموذج مهيَّأ داخل WebBrain.

إذا احتجت إلى أتمتة متصفح حتمية منخفضة المستوى في ملف تعريف معزول، فقد يناسبك خادم MCP بأسلوب Playwright أكثر. استخدم WebBrain MCP عندما يكون الشرط الحاسم هو جلسة متصفحك المسجَّل الدخول إليها القائمة إضافةً إلى نموذج الأمان داخل المتصفح لدى WebBrain.