flipper-mcp

خادم MCP (بروتوكول سياق النموذج) مكتوب بلغة Rust يعمل مباشرة على لوحة WiFi Dev Board v1 الخاصة بـ Flipper Zero (ESP32-S2)، مما يمكّن وكلاء الذكاء الاصطناعي من التحكم في Flipper Zero عبر الشبكة.

ما هذا؟

يضع هذا المشروع خادم MCP على Flipper نفسه. يمكن لأي عميل ذكاء اصطناعي متوافق مع MCP (Claude Desktop، Claude Code، إلخ) الاتصال واستخدام قدرات Flipper كأدوات — SubGHz، NFC، RFID، IR، GPIO، BadUSB، iButton، تخزين الملفات، والمزيد.

على عكس المشاريع الأخرى التي تتطلب جهاز كمبيوتر مضيفًا متصلًا عبر USB، يعمل flipper-mcp على وحدة ESP32-S2 WiFi المرفقة بـ Flipper. يصبح Flipper أداة مستقلة يمكن الوصول إليها عبر الشبكة.

البنية المعمارية

LOCAL (same network):
  MCP Client ──HTTP──► flipper-mcp.local:8080 (ESP32-S2) ──UART──► Flipper Zero

REMOTE (cross-network):
  MCP Client ──HTTP──► Relay Server ◄──WebSocket── ESP32-S2 ──UART──► Flipper Zero

يشغّل ESP32-S2 خادم HTTP يطبّق بروتوكول MCP. يترجم استدعاءات أدوات MCP إلى أوامر CLI الخاصة بـ Flipper Zero عبر UART بمعدل 115200 baud. يتيح خادم relay المرافق الوصول عن بُعد من أي شبكة.

الميزات

• ~30 أداة مدمجة تغطي جميع تطبيقات Flipper Zero الافتراضية
• اكتشاف الوحدات الديناميكي — اكتشاف تلقائي لتطبيقات FAP من بطاقة SD + أدوات مدفوعة بإعدادات TOML
• إعداد Flipper أولاً — تكوين WiFi من تطبيق Flipper FAP (لا حاجة لهاتف أو متصفح أو نصوص PC)
• نقل MCP المزدوج — Streamable HTTP (حديث) + Legacy SSE (متوافق مع الإصدارات السابقة)
• الاكتشاف المحلي — إعلان mDNS باسم flipper-mcp.local
• الوصول عن بُعد — نفق WebSocket عكسي عبر خادم relay (لا حاجة لإعادة توجيه المنافذ)
• بدون مصادقة — مصمم لسيناريوهات اختبار الاختراق والبحوث الأمنية
• خادم relay مرافق — ملف Rust ثنائي صغير للوصول عبر الشبكات، يدعم عدة أجهزة Flipper

الأجهزة المطلوبة

• Flipper Zero (أي إصدار firmware يدعم CLI)
• WiFi Dev Board v1 (وحدة ESP32-S2-WROVER)

بأي جهاز أتصل؟

المرحلة	الاتصال بـ	ملاحظات
فلاشة firmware	WiFi Dev Board USB-C	اللوحة لها منفذ USB خاص بها، منفصل عن Flipper
مراقبة Serial	WiFi Dev Board USB-C	نفس اتصال USB المستخدم في الفلاشة
ملفات إعدادات بطاقة SD	Flipper Zero بطاقة SD	أدخل بطاقة SD في Flipper، أو أخرجها وثبّتها على PC
أوامر التحكم بالخادم	Flipper Zero بطاقة SD	أنشئ ملف server.cmd في apps_data/flipper_mcp/
اتصال UART	تلقائي	يتصل WiFi Dev Board و Flipper عبر رأس GPIO
طلبات MCP HTTP	WiFi Dev Board IP:8080	اتصل عبر شبكة WiFi الخاصة بك

المتطلبات الأساسية

• Rust — ثبّته عبر rustup:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  

• سلسلة أدوات Xtensa — يتطلب ESP32-S2 سلسلة أدوات Rust مخصصة:

  cargo install espup
  espup install
  source ~/export-esp.sh  # Run this in every new terminal
  

• أداة الفلاشة و linker proxy:

  cargo install espflash
  cargo install ldproxy
  

• حزم النظام (Debian/Ubuntu/Kali):

  sudo apt install -y git curl gcc build-essential pkg-config libudev-dev libssl-dev python3 python3-venv cmake ninja-build
  

البدء السريع

تعليمات الإعداد الكاملة في docs/SETUP.md

1. بناء وفلاشة firmware

source ~/export-esp.sh
cd firmware
cargo build --release --target xtensa-esp32s2-espidf
espflash flash --monitor target/xtensa-esp32s2-espidf/release/flipper-mcp

3. تكوين WiFi

أنشئ config.txt على بطاقة SD الخاصة بـ Flipper في SD:/apps_data/flipper_mcp/config.txt:

wifi_ssid=YourNetworkName
wifi_password=YourPassword
device_name=flipper-mcp

أو كوّن مباشرة من Flipper باستخدام تطبيق FAP المرافق (انظر الخطوة 5): Apps → Tools → Flipper MCP → Configure WiFi

عند أول إقلاع بدون ملف إعدادات، ينتظر ESP32 ويكتب status=needs_config في ملف الحالة. سيعرض تطبيق Flipper FAP هذا على شاشة Status.

4. التحقق من عمل الخادم

قبل تكوين عميل ذكاء اصطناعي، تأكد من إمكانية الوصول إلى الخادم باستخدام curl:

# Quick health check
curl http://flipper-mcp.local:8080/health

# Full verification — initialize + list all available tools
./scripts/test-connection.sh

# If mDNS isn't resolving on your OS, pass the IP directly:
./scripts/test-connection.sh 192.168.x.xxx

اختبار أدوات MCP مباشرة باستخدام curl

احصل على عنوان IP الخاص بـ Flipper من قائمة Flipper MCP → Status، ثم اختبر:

بث BLE beacon (إرسال إعلان BLE منتحل):

curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ble_beacon","arguments":{"data":"020106"}}}'

لوحة مفاتيح BLE HID (محاكاة لوحة مفاتيح لاسلكية والكتابة):

# Start HID emulation
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ble_hid_start","arguments":{}}}'

# Type a message
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ble_hid_type","arguments":{"text":"Hello from Flipper!"}}}'

# Stop HID emulation
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ble_hid_stop","arguments":{}}}'

إرسال IR (إرسال أكواد التحكم عن بُعد بالأشعة تحت الحمراء):

# NEC protocol IR code (generic TV power button)
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ir_tx","arguments":{"protocol":"NEC","address":"00","command":"01","repeat":0}}}'

استقبال SubGHz (الاستماع للإشارات اللاسلكية على 433.92 MHz):

curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"subghz_rx","arguments":{"frequency":433920000,"duration":5000}}}'

استبدل 192.168.0.58 بعنوان IP الفعلي لـ Flipper.

ثم أضف إلى إعدادات Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "flipper": {
      "url": "http://flipper-mcp.local:8080/mcp"
    }
  }
}

5. إدارة لوحة WiFi من Flipper

ثبّت تطبيق Flipper MCP المرافق من flipper-app/ على Flipper Zero. ابنِ باستخدام ufbt وانسخ ملف .fap إلى SD:/apps/Tools/:

cd flipper-app && ufbt   # produces flipper_mcp.fap
# Copy flipper_mcp.fap to your Flipper SD card under apps/Tools/

يظهر التطبيق في Apps → Tools → Flipper MCP ويوفر:

الشاشة	ما تفعله
Status	تطلب تحديثًا جديدًا للحالة من ESP32، وتعرض IP و SSID وحالة الخادم والإصدار
Start / Stop / Restart	تتحكم في دورة حياة خادم MCP HTTP
Reboot Board	تعيد تشغيل لوحة ESP32 WiFi Dev Board
Configure WiFi	لوحة مفاتيح على الشاشة لإدخال SSID + كلمة المرور؛ تكتب config.txt إلى بطاقة SD
View Logs	سجل تشخيصي قابل للتمرير يكتبه ESP32 كل 30 ثانية
Tools List	قائمة قابلة للتمرير بجميع أدوات MCP المسجلة حاليًا على ESP32
Refresh Modules	تُشغّل إعادة فحص اكتشاف FAP + إعادة تحميل modules.toml على ESP32

يتواصل التطبيق عبر ملفات بطاقة SD (لا توصيلات إضافية تتجاوز رأس GPIO). Configure WiFi هو معالج أول إقلاع — لا حاجة لهاتف أو متصفح أو نصوص PC.

6. (اختياري) الوصول عن بُعد عبر relay

استضافة ذاتية (شغّل الملف الثنائي في أي مكان):

./scripts/build-relay.sh
./target/release/flipper-mcp-relay --listen 0.0.0.0:9090
# Then add relay_url to config.txt on the Flipper SD card:
# relay_url=ws://your-server:9090/tunnel