Signal Lab لمساعد: `signallab mcp`

signallab mcp خادم Model Context Protocol. يشغّله المساعد في Claude Code أو Claude Desktop أو Cursor أو VS Code أو أي عميل MCP آخر، ثم يستطيع:

أن يتعرّف على مكونات التجربة، ويكتب واحدة، ويفحصها، ويشغّلها، ويقرأ خطوةً بخطوة سبب فشلها؛
وأن يرسل رسالة OSC واحدة، أو مخطط بيانات، أو طلب HTTP، أو رسالة WebSocket، أو نشرًا إلى MQTT، وأن يستمع على منفذ لما يرسله جهاز؛
وأن يرسل إشارة من مكتبتك؛
وأن يؤدي دور تبعية — واجهة HTTP API، أو جهاز OSC أو UDP أو TCP، أو وسيط MQTT — ويقرأ ما أرسله النظام إليها؛
وأن يقرأ تشغيلات سابقة ويقارن بين اثنين منها.

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

WARNING

تضع عمليات الإرسال والتشغيل والمحاكيات حركة مرور حقيقية على الشبكة. يلزم إخبار المساعد بالأجهزة التي يحق له مخاطبتها؛ فالقوالب المضمّنة تشير إلى عنوان الاسترجاع (127.0.0.1).

الإعداد

يأتي signallab مع التطبيق المكتبي، ويكون في PATH بعد تثبيته (انظر التثبيت). يشغّل العميل signallab mcp بنفسه ويتخاطب معه عبر stdin وstdout؛ فلا حاجة إلى تشغيله يدويًا.

طباعة الإعداد

يطبع --print-config ما يحتاجه العميل، مع المسار الكامل لهذا signallab:

الأمر	ما يطبعه
`signallab mcp --print-config claude-code`	سطر الأوامر `claude mcp add`.
`signallab mcp --print-config claude-desktop`	مدخل `mcpServers` لملف إعداد Claude Desktop.
`signallab mcp --print-config cursor`	مدخل `mcpServers` نفسه، لملف `mcp.json` في Cursor.
`signallab mcp --print-config vscode`	مدخل `servers` لملف `.vscode/mcp.json` في VS Code.

ولمساعد يعمل على خادم مختبر، يُضاف --server URL: فيحمله الإعداد المطبوع، مع عنصر نائب للرمز المميز.

Claude Code

يُشغَّل السطر الذي يطبعه --print-config claude-code، مثلًا:

bash

claude mcp add signallab -- "C:\Program Files\Signal Lab\signallab.exe" mcp

Claude Desktop وCursor

يوضع المدخل في إعداد العميل — claude_desktop_config.json في Claude Desktop، وmcp.json في Cursor — ثم يُعاد تشغيل العميل:

json

{
  "mcpServers": {
    "signallab": {
      "command": "C:\\Program Files\\Signal Lab\\signallab.exe",
      "args": ["mcp"],
      "env": {}
    }
  }
}

VS Code

json

{
  "servers": {
    "signallab": {
      "type": "stdio",
      "command": "/usr/bin/signallab",
      "args": ["mcp"],
      "env": {}
    }
  }
}

عملاء آخرون

يعمل أي عميل يشغّل خادم stdio بالطريقة نفسها: الأمر هو signallab (أو مساره الكامل)، والوسائط mcp وأيٌّ من الخيارات. وعلى Linux، يمكن لصورة الخادم أن تكون الأمر أيضًا:

bash

docker run -i --rm --network host --entrypoint signallab ghcr.io/proanima/signallab:1.0.0 mcp

الخيارات

الخيار	ما يفعله	الافتراضي
`--server URL`	تشغيل التجارب وعمليات الإرسال والمحاكيات على خادم Signal Lab هذا (انظر على خادم مختبر).	`SIGNALLAB_SERVER`
`--token-file PATH`	ملف يحتوي على الرمز المميز للخادم.	`SIGNALLAB_TOKEN_FILE`، وإلا `SIGNALLAB_TOKEN`
`--data-dir PATH`	مكان حفظ التشغيلات وتقاريرها. لا يُستخدم مع `--server`.	مجلد بيانات التطبيق (`Documents/SignalLab`)
`--library PATH`	مكتبة الإشارات لـ `list_signals` و`fire_signal`.	ملف `signals.json` الخاص بالتطبيق
`--emulators PATH`	مكتبة المحاكيات لـ `list_emulators` و`start_emulator`.	ملف `emulators.json` الخاص بالتطبيق
`--secrets files\|system`	مصدر قيم الأسرار للتشغيلات على هذا الجهاز، كما في `run`. لا يُستخدم مع `--server`.	`files`
`--secrets-dir PATH`	مجلد لملفات الأسرار، ملف لكل اسم. لا يُستخدم مع `--server`.	`/run/secrets/signallab` إن وُجد
`--lang <code>`	لغة النتائج والإخفاقات.	`SIGNALLAB_LANG`، وإلا لغة النظام، وإلا `en`
`--print-config CLIENT`	طباعة إعداد عميل ثم الخروج: `claude-code` أو `claude-desktop` أو `cursor` أو `vscode`.

تحتفظ التشغيلات بتقاريرها في مجلد بيانات التطبيق، حيث يحتفظ التطبيق بتقاريره هو، فتبقى بعد انتهاء الجلسة.

الأدوات

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

الأداة	ما تفعله	تصل إلى العالم الخارجي
`describe_nodes`	مستند التجربة، وكل نوع من العقد مع حقوله ومخارجه ومثال عليه، ولغة `{{template}}`، وملفات تعريف الحمل، ومستند المحاكي.	لا
`list_templates`	التجارب المضمّنة، مع معاملاتها.	لا
`get_template`	تجربة مضمّنة واحدة بوصفها مستندًا.	لا
`validate_experiment`	يفحص تجربة كما يفعل المحرر قبل التشغيل؛ ولا يرسل شيئًا.	لا
`run_experiment`	يشغّل تجربة حتى نهايتها ويبلغ عن كل خطوة.	نعم
`send_osc`	رسالة OSC واحدة.	نعم
`send_udp`	مخطط بيانات UDP واحد.	نعم
`send_http`	طلب HTTP واحد.	نعم
`send_mqtt`	نشر MQTT 3.1.1 واحد.	نعم
`send_ws`	تبادل WebSocket واحد.	نعم
`listen`	ما يصل إلى منفذ UDP خلال مدة.	نعم
`list_signals`	إشارات مكتبتك.	لا
`fire_signal`	يرسل إشارة من المكتبة.	نعم
`list_emulators`	محاكيات مكتبتك.	لا
`start_emulator`	يبدأ محاكيًا.	نعم
`emulator_exchanges`	ما استقبله محاكٍ جارٍ وما أجاب به.	لا
`set_emulator_down`	يعطّل محاكيًا جاريًا، أو يعيده إلى العمل.	نعم
`list_runs`	تقارير التشغيلات السابقة.	لا
`compare_runs`	تشغيلان جنبًا إلى جنب.	لا
`list_jobs`	ما يعمل الآن.	لا
`stop_job`	يوقف مهمة جارية.	نعم

التجارب

describe_nodes هو ما يقرؤه المساعد قبل كتابة تجربة؛ وهو نفسه signallab nodes. ويقدّم list_templates وget_template أمثلة عاملة تُشغَّل أو تُعدَّل.

تأخذ validate_experiment وrun_experiment التجربة بإحدى ثلاث طرق — واحدة منها بالضبط:

الوسيطة	ما هي
`document`	مستند تجربة، كما يحفظه التطبيق.
`file`	مسار ملف تجربة على الجهاز الذي يعمل عليه `signallab`.
`template`	اسم قالب مضمّن.
`params`	قيم المعاملات لهذا التشغيل: `{"name": "value"}`؛ وتؤخذ الأرقام والقيم المنطقية نصوصًا.
`profile`	التشغيل بملف التعريف هذا من المستند؛ و`""` للقيم الافتراضية.
`seed`	في `run_experiment`: بذرة القيم العشوائية.
`timeout`	في `run_experiment`: عدد الثواني التي يجوز أن يستغرقها التشغيل، من 1 إلى 300 (الافتراضي 300).

يجيب run_experiment حين ينتهي التشغيل: ناجحًا أو فاشلًا أو موقوفًا، ومدته وبذرته، وكل خطوة مع ما فعلته أو سبب فشلها، وما سُئل عنه كل محاكٍ، وما فعله كل مرحّل إضعاف، ومسار التقرير. والتشغيل الذي يفشل جواب عادي — فالخطوات تبيّن السبب — لا استدعاء فاشل.

الرسائل المفردة

الأداة	الوسائط
`send_osc`	`target` (`host:port`)، و`address`، و`args`: أرقام (صحيحة → int32، أو int64 إن تجاوزت نطاقه؛ وإلا float32)، ونصوص، وقيم منطقية، و`null`، أو `{"type": "int"\|"float"\|"str"\|"long"\|"double"\|"bool"\|"blob"\|"nil", "value": …}`.
`send_udp`	`target`، و`text` أو `hex` (`"de ad be ef"`).
`send_http`	`method`، و`url`، و`headers` (`{"Name": "value"}`)، و`body`، و`timeout_ms` (الافتراضي 10000)، و`auth`: `{"scheme": "basic"\|"digest", "username", "password"}` أو `{"scheme": "bearer", "token"}`. ويعيد الحالة والزمن والترويسات والمتن — أول 16 KiB منه.
`send_mqtt`	`broker` (`host:port`، والمنفذ 1883 إن لم يُذكر)، و`topic`، و`payload`، و`qos` (0 أو 1 أو 2)، و`retain`. والحمولة الفارغة مع `retain` تمسح قيمة محتفظًا بها.
`send_ws`	`url` (`ws://` أو `wss://`)، و`text` أو `hex`، و`headers`، و`protocols`، ولانتظار الرد `expect` (يحتوي على) أو `expect_regex` أو `wait` (أي رسالة)؛ و`timeout_ms` من 1 إلى 120000 (الافتراضي 2000). ويعيد المصافحة وما أُرسل والرد، مع تحليل JSON فيه إن كان JSON.

هذه هي الأوامر التي تستخدمها شاشات التطبيق؛ انظر signallab send.

الاستماع

تفتح listen منفذ UDP على الجهاز الذي يعمل عليه signallab mcp، لمدة، وتعيد ما وصل: رسائل OSC مفكوكة الترميز، ومخططات البيانات الأخرى نصًا وبايتات hex.

الوسيطة	ما هي	الافتراضي
`bind`	`IP:port`، مثل `0.0.0.0:9000`.	مطلوبة
`protocol`	`osc` أو `udp`.	`osc`
`seconds`	مدة الاستماع، من 0.1 إلى 60.	5
`max`	التوقف بعد هذا العدد من مخططات البيانات، من 1 إلى 1000.	100

وحين لا يصل شيء على 0.0.0.0، يذكّر الجواب المساعد بفحص جدار الحماية (signallab doctor). ومع --server تُرفض listen: فعلى الخادم، تستمع تجربة فيها عقدة انتظار هناك.

الإشارات والمحاكيات

تستخدم list_signals وfire_signal مكتبة إشاراتك — ملف signals.json الخاص بالتطبيق، أو --library، أو مسار library يُعطى للاستدعاء. وتُرسل الإشارة بمعرّفها أو اسمها، تمامًا كما يرسلها التطبيق.

تسمّي list_emulators محاكيات مكتبتك. وتبدأ start_emulator أحدها — مستندًا في emulator، أو معرّف مدخل في المكتبة أو اسمه في name — وتعيد معرّف مهمته وعنوانه؛ ويجيب وفق قواعده حتى stop_job. وتنقله bind إلى IP:port آخر، وتعطيه params قيمًا تقرؤها قوالبه، وتثبّت seed خياراته العشوائية. وتسرد emulator_exchanges (job_id، وafter للأحدث فقط) ما وصل وما أجابت به كل قاعدة. وتقطع set_emulator_down (job_id، وdown، وfault: unavailable أو reset أو timeout) الاتصال عن محاكٍ جارٍ حتى يُعاد تفعيله: فيواجه HTTP العطل (unavailable يجيب 503)، ويُسقط جهاز TCP ووسيط MQTT الاتصالات، ولا يجيب OSC وUDP بشيء. انظر المحاكيات.

التشغيلات والمهام

تقرأ list_runs تقارير التشغيلات السابقة، الأحدث أولًا — لتجربة واحدة حين يسمّيها experiment، وبحد أقصى limit (من 1 إلى 500، والافتراضي 50) — مع أرقام كل خطوة حمل. وتأخذ compare_runs اسمي تشغيلين، a (قبل) وb (بعد)، وتضع أزمنة الاستجابة ومعدل الأخطاء والمعدل المحقَّق والطلبات الفائتة لكل خطوة حمل جنبًا إلى جنب، وتصف تغيّرًا بنسبة 5% أو أكثر في الاتجاه الخاطئ بأنه تراجع. انظر التشغيلات والتقارير.

وتسرد list_jobs ما يعمل — مراقبات ومولّدات ومحاكيات وتشغيلات — وتوقف stop_job واحدة بمعرّفها.

النتائج والأخطاء

كل جواب نص للنموذج وهو نفسه بيانات مهيكلة. والفشل موسوم بأنه خطأ ويحمل خطأ المحرك — code ثابتًا وقيمه والعقدة والحقل المعنيين به — مصوغًا باللغة المختارة بـ --lang. أما الوسائط التي أخطأ فيها المساعد فتعود بكلمات يستطيع تصحيحها.

التقدم والإلغاء

حين يطلب العميل التقدم في run_experiment، تُعلَن كل خطوة فور حدوثها (العقدة وحالتها)، فيرى المساعد — وأنت — التشغيل يتقدم. وإلغاء الاستدعاء يوقفه؛ وإلغاء run_experiment يوقف التشغيل نفسه، كما يفعل إيقاف في التطبيق.

وحين يغلق العميل الاتصال، تنتهي الاستدعاءات الجارية، ثم يخرج signallab mcp.

على خادم مختبر

مع --server http://192.0.2.10:1430 تجري التجارب وعمليات الإرسال والإشارات والمحاكيات على ذلك الخادم، عبر واجهته — بشبكته وأسراره ومجلد بياناته — فيصل المساعد إلى معدات لا يصل إليها إلا المختبر. ويُعطى الرمز المميز في بيئة العميل:

json

{
  "mcpServers": {
    "signallab": {
      "command": "signallab",
      "args": ["mcp", "--server", "http://192.0.2.10:1430"],
      "env": { "SIGNALLAB_TOKEN": "<the server's token>" }
    }
  }
}

وما يبقى على هذا الجهاز: مكتبتا الإشارات والمحاكيات (الخاصتان بالتطبيق، أو --library و--emulators) والملفات التي يسمّيها الاستدعاء (file وlibrary) تُقرأ هنا، ويُرسل ما فيها إلى الخادم؛ وتُرفض listen. انظر تشغيل Signal Lab خادمًا.

الأمان

لا يستطيع المساعد إلا ما تفعله الأدوات، وكل أداة أمر من أوامر التطبيق نفسه: فلا يصل إلى شيء لا يصل إليه التطبيق.
الأدوات التي ترسل أو تستمع أو تبدأ شيئًا موسومة بأنها تصل إلى العالم الخارجي؛ ويقرر عميلك هل يسألك قبل كل استدعاء.
لا تصل قيم الأسرار إلى المساعد أبدًا: فالتجربة تسمّيها {{secret.NAME}}، وتعرض كل نتيجة •••• مكانها.
يفتح المحاكي أو المستمع منفذًا على الجهاز الذي يعمل عليه؛ وlist_jobs وstop_job يعرضان ما لا يزال يعمل وينهيانه.

البروتوكول

لمؤلفي العملاء: JSON-RPC 2.0 عبر stdio، رسالة واحدة في كل سطر؛ ولا يحمل stdout إلا رسائل البروتوكول، وما هو موجّه إلى شخص يذهب إلى stderr. إصدارات البروتوكول 2025-06-18 و2025-03-26 و2024-11-05 (الأحدث حين يطلب العميل غيرها)، والدفعات، وping، وtools/list، وtools/call؛ والتقدم بوصفه notifications/progress للاستدعاء الذي أرسل progressToken، والإلغاء بـ notifications/cancelled. وتبيّن instructions الخاصة بالخادم للنموذج كيف تتكامل الأدوات.

Signal Lab لمساعد: signallab mcp ​

الإعداد ​

طباعة الإعداد ​

Claude Code ​

Claude Desktop وCursor ​

VS Code ​

عملاء آخرون ​

الخيارات ​

الأدوات ​

التجارب ​

الرسائل المفردة ​

الاستماع ​

الإشارات والمحاكيات ​

التشغيلات والمهام ​

النتائج والأخطاء ​

التقدم والإلغاء ​

على خادم مختبر ​

الأمان ​

البروتوكول ​

Signal Lab لمساعد: `signallab mcp`

الإعداد

طباعة الإعداد

Claude Code

Claude Desktop وCursor

VS Code

عملاء آخرون

الخيارات

الأدوات

التجارب

الرسائل المفردة

الاستماع

الإشارات والمحاكيات

التشغيلات والمهام

النتائج والأخطاء

التقدم والإلغاء

على خادم مختبر

الأمان

البروتوكول