خادم OmniWeb للتحكم في Android MCP

خادم MCP الذي يحيط بـ "الوسيط Android" الخاص بـ OmniWeb (خدمة Flask omniweb-android، /api/android/*) بحيث يمكن لعميل MCP - مثل Claude Code، أو Claude Desktop، أو عميل مخصص - التحكم في هواتف Android والمودمات USB في المختبر.

إنه عميل HTTP رقيق فوق واجهة برمجة التطبيقات REST الحالية (لا يستورد أي مكونات داخلية من Flask)، لذا فهو يعمل ضد أي مثيل omniweb-android يمكن الوصول إليه.

الأدوات المعروضة

الأداة	التوقيع	ماذا تفعل
`list_devices`	`()`	جميع الأجهزة المعروفة (هواتف + مودمات)، متصلة وغير متصلة.
`device_info`	`(serial)`	تفاصيل كاملة لجهاز واحد.
`screenshot`	`(serial)` → صورة PNG	الشاشة الحالية (عالمي: هواتف scrcpy وأجهزة screencap القديمة).
`tap`	`(serial, x, y)`	نقر عند إحداثيات البكسل.
`swipe`	`(serial, x1, y1, x2, y2, ms=200)`	سحب/جر/إلقاء.
`input_text`	`(serial, text)`	الكتابة في الحقل المحدد.
`key`	`(serial, name)`	الضغط على زر العودة/الرئيسية/الأخيرة/إدخال/حذف/طاقة/قائمة/رفع الصوت/خفض الصوت.
`adb_shell`	`(serial, command, timeout=30)` → `{stdout, stderr, return_code}`	أمر `adb shell` عشوائي (أداة قوية).
`list_scripts`	`()`	مكتبة نصوص اختبار الجهاز.
`run_script`	`(serials, file, params={})`	تشغيل نص عبر الأجهزة؛ يعيد مقبض التشغيل.
`get_run`	`(run_id)`	نتيجة تشغيل نص (الحالة/stdout/return_code).
`at_command`	`(serial, command, read_ms=0, timeout_ms=0)`	أمر AT خام لمودم USB.
`send_sms`	`(serial, number, text)`	إرسال رسالة نصية من مودم.

التكوين (متغيرات البيئة)

هدف الخلفية:

OMNIWEB_API_BASE — عنوان URL الأساسي لخدمة Android. الافتراضي http://127.0.0.1:5002. يتم إضافة بادئة /api/android تلقائيًا.

مصادقة الخلفية (اختر واحدة):

OMNIWEB_JWT — رمز وصول م��بق الصنع للخلفية (Bearer)، أو
OMNIWEB_JWT_SECRET — JWT_SECRET_KEY الخاص بالخلفية. يقوم الخادم بعد ذلك بصنع JWT إداري قصير العمر بنفسه وتجديده تلقائيًا. يتحكم OMNIWEB_JWT_TTL (بالثواني، الافتراضي 3600) في مدة حياته.

الباب الأمامي الخاص بهذا الخادم MCP:

MCP_TRANSPORT — http (افتراضي، HTTP قابل للبث للعملاء عن بُعد) أو stdio (محلي claude mcp add).
MCP_HOST / MCP_PORT — عنوان الربط لنقل http. الافتراضي 127.0.0.1:5005.
MCP_AUTH_TOKEN — رمز حامل يجب على عميل MCP عن بُعد تقديمه. مطلوب للربط بأي شيء غير localhost — يرفض الخادم الربط غير المتكرر بدونه (يفشل مغلقًا). في /mcp يتم التحقق من الرمز بواسطة الوسيط؛ / و/health مفتوحة لفحوصات الصحة.

تشغيله

venv (محتوى ذاتي)

cd /opt/omniweb-mcp           # أو في أي مكان وضعت فيه server.py + requirements.txt
python3 -m venv venv
venv/bin/pip install -r requirements.txt

export OMNIWEB_API_BASE=http://127.0.0.1:5002
export OMNIWEB_JWT_SECRET=<the backend JWT_SECRET_KEY>
export MCP_TRANSPORT=http
export MCP_HOST=0.0.0.0
export MCP_PORT=5005
export MCP_AUTH_TOKEN=<a long random token>
venv/bin/python server.py

systemd (إنتاج)

وحدة متوفرة في packaging/omniweb-android-mcp.service. تقرأ /etc/omniweb/omniweb.env (لـ JWT_SECRET_KEY → يتم إعادة تصديره كـ OMNIWEB_JWT_SECRET، انظر أدناه) بالإضافة إلى /etc/omniweb/android-mcp.env للأسرار الخاصة بـ MCP. أنشئ تلك الإضافة (chmod 600):

# /etc/omniweb/android-mcp.env
OMNIWEB_JWT_SECRET=<same value as JWT_SECRET_KEY in omniweb.env>
MCP_AUTH_TOKEN=<a long random token>

ثم:

sudo cp packaging/omniweb-android-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now omniweb-android-mcp

ملف البيئة الخلفية يسمي سر JWT JWT_SECRET_KEY؛ هذا الخادم يقرأ OMNIWEB_JWT_SECRET. قم بتعيين OMNIWEB_JWT_SECRET بشكل صريح في android-mcp.env (انسخ القيمة) بحيث تتماشى الأسماء.

الاتصال من Claude Code

عن بُعد (HTTP قابل للبث)، مع مصادقة:

claude mcp add --transport http android-control http://<host>:5005/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

محلي (stdio)، توجيه الخادم إلى خلفية وصنع JWT الخاص به:

claude mcp add android-control \
  -e OMNIWEB_API_BASE=http://127.0.0.1:5002 \
  -e OMNIWEB_JWT_SECRET=<backend JWT_SECRET_KEY> \
  -e MCP_TRANSPORT=stdio \
  -- /opt/omniweb-mcp/venv/bin/python /opt/omniweb-mcp/server.py

ثم في Claude Code: /mcp لتأكيد الاتصال، وجرب list_devices.

الاتصال من Claude Desktop

claude_desktop_config.json — إطلاق stdio:

{
  "mcpServers": {
    "android-control": {
      "command": "/opt/omniweb-mcp/venv/bin/python",
      "args": ["/opt/omniweb-mcp/server.py"],
      "env": {
        "OMNIWEB_API_BASE": "http://127.0.0.1:5002",
        "OMNIWEB_JWT_SECRET": "<backend JWT_SECRET_KEY>",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

لخادم HTTP قابل للبث عن بُعد من Claude Desktop، استخدم جسر mcp-remote أو تكوين خادم HTTP المدعوم من إصدار Desktop الخاص بك، مع توجيه إلى http://<host>:5005/mcp مع رأس Authorization: Bearer <MCP_AUTH_TOKEN>.

ملاحظات أمنية

يتطلب التحكم في الجهاز MCP_AUTH_TOKEN المكون على نقل HTTP. بدون رمز، يسمح الخادم فقط بربط الحلقة ويطبع تحذيرًا؛ يتم رفض الربط غير المتكرر بدون رمز.
يقوم الخادم بالمصادقة على الخلفية كإداري (JWT مُصنع أو رمز مُقدم)، لذا أي شخص يمكنه الوصول إلى /mcp مع رمز الحامل لديه تحكم كامل في الجهاز. تعامل مع MCP_AUTH_TOKEN مثل كلمة مرور وواجهه بـ TLS (على سبيل المثال عبر nginx) للوصول من خارج المضيف.

الأدوات المعروضة​

التكوين (متغيرات البيئة)​

تشغيله​

venv (محتوى ذاتي)​

systemd (إنتاج)​

الاتصال من Claude Code​

الاتصال من Claude Desktop​

ملاحظات أمنية​