IDA Pro MCP

⚠️ مؤرشف — استُبدل بخادم IDA MCP الرسمي من Hex-Rays

لم يعد هذا المشروع قيد الصيانة. في 2026-09-27 أصدرت Hex-Rays SA خادم IDA MCP الرسمي و IDA Nexus. توقف التطوير في اليوم نفسه عند الإصدار 1.0.0a4.

للاستخدام الحالي، ثبّت نسختهم: uvx ida-hcli mcp install. يتطلب IDA 9.4+ مع idalib ويعمل بالكامل بدون واجهة رسومية؛ إضافة الواجهة الرسومية اختيارية.

يُحتفظ بهذا المستودع من أجل مجموعة الاختبارات والتوثيق والسجل المعماري الخاص به. راجع ARCHIVE.md للحساب الختامي الكامل: ما كان المشروع، ولماذا خسر، وأي الأجزاء كانت هيكلاً مؤقتاً، وأي الأجزاء لا تزال ذات قيمة. يصف باقي هذا الملف نظاماً لم يعد يُنصح باستخدامه.

IDA Pro MCP هو خادم محلي لبروتوكول سياق النموذج (Model Context Protocol) مخصص لـ IDA Pro. يتيح لعميل MCP فحص ملف IDB، وطلب نتائج تحليل حتمية من IDA، وعند السماح الصريح، كتابة تعليقات توضيحية أو تغييرات أخرى مرة أخرى إلى IDB. تعمل العملية المضيفة خارج IDA وتُشغّل عملية IDA منفصلة بدون واجهة رسومية لكل جلسة افتراضياً.

لماذا هذا التنفيذ

• سطح وكيل حتمي: 102 عملية ida_* بمخطط صارم مع اكتشاف حي عبر tools/list وida_help.
• بنية محلية أولاً: تتواصل العملية المضيفة وبيئة تشغيل IDA عبر جسر loopback محمي برمز مميز؛ لا توجد خدمة LLM خفية في مسار التحليل.
• أدلة، وليس مجرد محادثة: تحافظ النتائج الدائمة على المصدر، والثقة، وحالة دورة الحياة، والتعارضات، وسجل التدقيق خارج IDB.
• تعديلات محمية: تبقى العمليات التي تغيّر IDB خلف سياسة صريحة وعناصر تحكم في الإقرار بالمخاطر.
• دعم واسع للعملاء: يفهم المثبّت أكثر من 22 بيئة وكيل وأشكال إعداداتها من نوع JSON وJSON5 وTOML وYAML.

الإصدار الحالي هو 1.0.0a4. هذا برنامج ألفا. قد تتغير أسماء عمليات ida_* العامة والمخططات وصيغة مساحة العمل قبل إصدار 1.0.0 المستقر. يحتوي سطح العميل الافتراضي على 102 عملية بمخطط دقيق. استخدم الاكتشاف الحي للحصول على العقد الكامل: يُعدّد tools/list كل عملية مع مخططها، ويُرجع ida_help(topic="...") الوسائط الدقيقة ومثالاً لعملية واحدة.

قبل التثبيت

تحتاج إلى:

• IDA Pro أو IDA Home 9.2 أو أحدث، مع ملف تنفيذي صالح idat/idat64. تغطي أدلة الاختبار الحية في المستودع IDA 9.3 و9.4؛ و9.2 هو الحد الأدنى المعلن للتوافق.
• Python 3.11 أو أحدث للعملية المضيفة والمثبّت.
• إذن لتشغيل IDA على الملفات الثنائية التي تخطط لفحصها، ومساحة قرص كافية لبيئة Python مُدارة وملفات الجلسة ونسخ IDB.
• عميل MCP يدعم خادم stdio محلي، مثل Claude Code، Codex، OpenCode، Claude Desktop، Cursor، VS Code/Copilot، Windsurf، Cline، Roo Code، Gemini CLI، أو Antigravity.

لا يتطلب التحليل العادي مزوّد ذكاء. أوضاع الذكاء الصريحة هي jev وcustom وdisabled؛ يحافظ الوضع المعطّل على البحث المعجمي الحتمي المتاح ولا يوجد احتياطي محلي أو Gemini أو نموذج أصلي.

بيئة التشغيل الافتراضية هي idat: عملية IDA واحدة بدون واجهة رسومية لكل جلسة. خلفية idalib تجريبية، وتتطلب تثبيت IDA 9.3 أو أحدث مع تفعيل حزمة idapro، وليست ضرورية للتثبيت الأول.

التثبيت من نسخة المصدر

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

python3 install.py

لتركيب IDA معروف، مرّره صراحةً:

python3 install.py --ida-dir /path/to/ida-pro-9.3

للتشغيل غير التفاعلي:

python3 install.py --yes --no-ida-prompt --ida-dir /path/to/ida-pro-9.3

يمكن للمثبّت أيضًا العثور على IDA عبر IDADIR وIDA_DIR، وملفات IDA التنفيذية على PATH، ومجلدات التثبيت الشائعة. يختار --ida-version إصدارًا عندما يكون هناك أكثر من تثبيت واحد موجود. استخدم --dry-run لفحص التغييرات المخطط لها أولًا.

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

أعد تشغيل عميل MCP بعد التثبيت حتى يعيد تحميل تكوينه.

تكتشف أُطُر تشغيل الوكلاء سطح الأدوات مباشرةً: يُعدّد tools/list كل عملية مع مخططها، ويُرجع ida_help(topic="...") الوسائط الدقيقة ومثالًا. لا يتم تثبيت أي ملفات مهارات ثابتة.

جذر التثبيت الافتراضي هو:

• Linux وmacOS: ~/.local/share/ida-pro-mcp
• Windows: %LOCALAPPDATA%/ida-pro-mcp

عيّن IDA_PRO_MCP_HOME أو مرّر --install-root لاختيار موقع آخر.

التثبيت من حزمة إصدار

تُبنى إصدارات Alpha بواسطة GitHub Actions وتُنشر يدويًا كإصدارات أولية. عند توفر إصدار، نزّل أصل bundle.zip أو bundle.tar.gz وملف SHA256SUMS الخاص به من صفحة الإصدارات. تحقق من المجموع الاختباري، واستخرج الحزمة، وشغّل المثبّت من دليلها الأعلى:

python3 install.py --yes --no-ida-prompt --ida-dir /path/to/ida-pro-9.3

يحتوي الإصدار أيضًا على wheel وتوزيع مصدري لعمليات تثبيت Python النصية. الحزمة هي المسار الأبسط لأنها تتضمن المثبّت وجميع ملفات المشروع اللازمة لتهيئة عميل MCP. الإصدارات ذات جودة ألفا؛ احتفظ بالملف الثنائي الأصلي وIDB واقرأ ملاحظات الإصدار قبل الترقية.

ربط عميل MCP

يكتب المثبّت إدخال الخادم لمسارات تهيئة العميل التي يعرفها. وهو يدعم Gemini CLI وAntigravity وAntigravity IDE وAntigravity CLI وClaude Code وCodex وCopilot CLI وOpenCode وClaude Desktop وCursor وVS Code وWindsurf وCline وRoo Code. تستخدم OpenCode وعملاء عائلة Copilot أشكال تهيئة مختلفة؛ دع المثبّت يكتب تلك الملفات أو اتبع دليل إعداد OpenCode.

بالنسبة لعميل يستخدم تنسيق JSON الشائع، فإن الإدخال يعادل:

{
  "mcpServers": {
    "ida-pro-mcp": {
      "command": "/path/to/ida-pro-mcp/.venv/bin/python",
      "args": ["-u", "-m", "ida_pro_mcp.host.server"],
      "env": {
        "IDA_PRO_MCP_HOME": "/path/to/ida-pro-mcp",
        "IDADIR": "/path/to/ida-pro-9.3",
        "IDA_MCP_TOOL_SURFACE": "agent"
      }
    }
  }
}

على Windows، استخدم المفسّر المُدار في <install-root>/.venv/Scripts/python.exe. التفاصيل المهمة هي المفسّر المُدار، و-u -m ida_pro_mcp.host.server، ومجلد IDA المحدد، وIDA_MCP_TOOL_SURFACE=agent. لا توجّه العميل إلى install.py؛ فذلك الملف هو المثبّت، وليس خادم MCP.

بعد تغيير إعدادات العميل، أعد تشغيل العميل بالكامل وتحقق من ظهور ida_help ضمن العمليات المتاحة لديه. إذا أظهر العميل فقط واجهة قديمة عريضة tool(action=...)، فتحقق من أن البيئة تختار سطح agent الافتراضي بدلاً من IDA_MCP_TOOL_SURFACE=legacy.

جلسة أولى مفيدة

استخدم مسارًا مطلقًا لملف ثنائي اختباري أولاً. فتح ملف ثنائي ينتظر عادةً انتهاء التحليل الأولي في IDA؛ وقد يستغرق الملف الثنائي الكبير وقتًا.

ida_open_binary(binary_path="/absolute/path/to/sample")
ida_session_status()
ida_overview()
ida_list_imports(limit=30)
ida_list_strings(query="http", limit=30)
ida_find(query="main", limit=20)
ida_decompile(address="<address returned by IDA>")
ida_xrefs_to(address="<same address>")

استخدم ida_help(topic="ida_decompile") كلما احتجت إلى مخطط الوسائط الدقيق. مخططات العمليات العامة صارمة: يتم رفض الوسائط غير المعروفة. قد تُقبل العناوين كأعداد صحيحة أو سلاسل نصية وفقًا لعقد كل عملية على حدة؛ استخدم الشكل الذي يعرضه ida_help للعملية في عميلك.

لسجل تحقيق صغير، تكون عمليات النتائج في مساحة العمل كالتالي:

ida_write_finding(title="Input reaches parser", address="<address returned by IDA>", kind="finding", status="confirmed", confidence=0.8, evidence=[{"type":"call", "value":"recv", "address":"<evidence address>"}])
ida_analysis_brief()
ida_next_target()
ida_export_findings(format="markdown")