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)

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

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

• Rust — ثبّته عبر rustup:
  root@kitploit:~

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

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

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

• أداة الفلاشة و linker proxy:
  root@kitploit:~

  cargo install espflash
  cargo install ldproxy
  

• حزم النظام (Debian/Ubuntu/Kali):
  root@kitploit:~

  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 ويوفر:

يتواصل التطبيق عبر ملفات بطاقة 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

النشر السحابي (AWS أو GCP، مع TLS + DNS):

# Bootstrap state storage, then deploy
./infra/bootstrap/aws.sh   # or ./infra/bootstrap/gcp.sh
cd infra/aws && cp terraform.tfvars.example terraform.tfvars
tofu init && tofu apply
# Outputs the relay URL and a ready-to-paste wifi-config.sh command

انظر RELAY.md للحصول على التعليمات الكاملة.

الأدوات المتاحة

يمكن إضافة أدوات مخصصة عبر ملفات إعدادات TOML أو بتثبيت تطبيقات FAP على بطاقة SD. انظر OPERATIONS.md للحصول على أوامر curl الجاهزة للنسخ واللصق لكل أداة.

بديل مجاني: Open WebUI + Ollama

لا تحتاج إلى اشتراك Claude لاستخدام flipper-mcp. Open WebUI هي واجهة مجانية مستضافة ذاتيًا بأسلوب ChatGPT تدعم أصلاً MCP Streamable HTTP (v0.6.31+). اقرنها مع Ollama للتحكم الكامل المحلي وغير المتصل بالإنترنت في Flipper بالذكاء الاصطناعي.

1. تثبيت Ollama وسحب نموذج قادر على استخدام الأدوات

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model with tool-calling support
ollama pull llama3.1        # 8B — good balance of speed and capability
# or: ollama pull qwen2.5   # strong tool-calling, good at structured output
# or: ollama pull mistral    # lightweight, fast tool use

2. تشغيل Open WebUI

# Docker (recommended) — connects to Ollama on localhost automatically
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -e WEBUI_AUTH=False \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

# Or without Docker:
pip install open-webui
open-webui serve

افتح http://localhost:3000 في متصفحك.

3. توصيل خادم Flipper MCP

1. انتقل إلى Admin Settings (أيقونة الترس) → External Tools
2. انقر على + Add Server
3. اضبط Type على MCP (Streamable HTTP)
4. أدخل عنوان URL للخادم:
   • محلي: http://flipper-mcp.local:8080/mcp (أو http://192.168.x.x:8080/mcp)
   • عبر relay: https://relay.example.com/mcp
   • من Docker: استخدم http://host.docker.internal:8080/mcp إذا كان Flipper على شبكة مضيف Docker
5. اضبط Authentication على None (لا يوجد مصادقة في flipper-mcp)
6. Save

نصيحة: ضمن Workspace → Models → (نموذجك) → Advanced Parameters، اضبط Function Calling على Default للنماذج الأصغر. لا تنتقل إلى Native إلا للنماذج ذات الدعم القوي المدمج للأدوات (Llama 3.1 8B+، Qwen 2.5، Mistral).

4. أمثلة على الأوامر

بمجرد الاتصال، جرّب هذه في محادثة Open WebUI:

المهام الوكيلية متعددة الخطوات تعمل بشكل أفضل مع النماذج الأكبر (Llama 3.1 70B، Qwen 2.5 72B، أو النماذج السحابية عبر واجهات برمجة متوافقة مع OpenAI). تتعامل النماذج الأصغر مع استدعاءات الأداة الواحدة بشكل موثوق.

هيكل المشروع

flipper-mcp/
├── firmware/          # ESP32-S2 firmware (Rust, esp-idf-svc)
├── relay/             # Companion relay server (Rust, tokio/axum)
├── flipper-app/       # Flipper Zero FAP — in-device management UI (C, ufbt)
├── infra/             # OpenTofu IaC — cloud relay deployment (AWS + GCP)
├── config/            # Example module configurations
├── scripts/           # Build, flash, and setup helper scripts
└── docs/              # Architecture, setup, API, troubleshooting

التوثيق

• SETUP.md — الإعداد الكامل من الصفر
• ARCHITECTURE.md — تعمق في تصميم النظام
• API.md — مرجع أدوات MCP الكامل
• OPERATIONS.md — دليل العمليات مع أوامر curl لكل أداة
• MODULE_DEVELOPMENT.md — إنشاء وحدات مخصصة
• RELAY.md — إعداد الوصول عن بُعد
• HARDWARE.md — تفاصيل التوصيلات والأجهزة
• TROUBLESHOOTING.md — المشكلات الشائعة والحلول
• DESIGN.md — التصميم التقني والبنية المعمارية للنظام

لوكلاء الذكاء الاصطناعي

انظر AGENTS.md للحصول على سياق المشروع الكامل والمواصفات التقنية والبنية المعمارية للنظام وكل ما يلزم لمواصلة التطوير على هذا المشروع.

الترخيص

MIT