MCP

mmd-mcp: التحكم في MikuMikuDance عبر MCP وإعدادات MME على Windows

mmd-mcp هو الأنسب للتحكم البرمجي في MikuMikuDance على Windows لإنتاج الرسوم المتحركة وإعدادات مؤثرات MME، لكن يشترط أن تشغّل بنفسك النسخة اليابانية MMD 9.32 x64 أولًا، وأن تُتم تثبيتًا بتجميع الكود المصدري يتطلب مكوّنات Visual Studio C++.

Official source · mmd-mcp

Install

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
cmd /c scripts\build_native.cmd

mmd-mcp هو خادم MCP يعمل عبر stdio وموجّه لـ Windows، يُستخدم للتحكم في عمليات MikuMikuDance (MMD) وإعدادات مؤثرات MME. شروط ملاءمته واضحة تمامًا: يجب أن تكون على Windows، وقد شغّلت بنفسك MMD 9.32 x64 (الإصدار الياباني، وسيرفض الخادم الإصدارات غير المدعومة)، وأن تكون مستعدًا لإتمام التثبيت بتجميع الكود المصدري (يتطلب Python x64 ومكوّن تطوير سطح المكتب C++ في Visual Studio 2022/Build Tools). لا يشغّل MMD تلقائيًا ولا يستمع على الشبكة. إذا لم تستوفِ بيئتك هذه الشروط، أو لم ترغب في التعامل مع سلسلة أدوات التجميع (compilation toolchain)، فليس هو الخيار الأول المناسب لك.

لمن هو مناسب

  • من يعمل على إنتاج رسوم MMD المتحركة على Windows ويحتاج إلى ضبط النماذج والكاميرا والإضاءة والفيزياء والخط الزمني برمجيًا، أو تعديل تخصيص مؤثرات EMM في MME، أو تصدير فيديو AVI.
  • بيئة التحقق هي MMD 9.32 x64 بالنسخة اليابانية، وWindows ياباني، وPython 3.10 x64؛ سيُرفض استخدام أي إصدار آخر من MMD، لذا يجب على مستخدمي الإصدارات الأخرى اعتبار أنفسهم غير مدعومين.
  • غير مناسب لـ: مستخدمي macOS/Linux، ومن لم يثبّت MMD بعد أو يستخدم إصدارًا غير مُتحقق منه، ومن لا يرغب في تثبيت مكوّنات Visual Studio C++. الأدلة الرسمية لا تذكر دعم macOS/Linux، وهذه نقطة مجهولة.

أول محاولة في 3 دقائق

ملاحظة: هذا المسار الرئيسي لا يمكن إتمامه فعليًا في 3 دقائق، إذ تستغرق عملية تجميع DLL من الكود المصدري وقتًا طويلًا؛ المقصود بـ"3 دقائق" هو قلة عدد الخطوات.

المتطلبات المسبقة:

  1. بيئة Windows مع Python x64 مثبّت (بيئة التحقق هي 3.10 x64).
  2. Visual Studio 2022 أو Build Tools مثبّت، مع تحديد مكوّن تطوير سطح المكتب C++ (لتجميع DLL الأصلي/native DLL).
  3. النسخة اليابانية MMD 9.32 x64 قيد التشغيل — الخادم لا يشغّل MMD تلقائيًا.

التثبيت (داخل مجلد المستودع، وبالأوامر الرسمية المقدَّمة لـ PowerShell):

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
cmd /c scripts\build_native.cmd

الأمر الثالث يجمّع DLL الأصلي، وهي خطوة إلزامية، وتُحفظ نتيجة التجميع محليًا.

التسجيل لدى عميل MCP (بطريقة stdio)، بحسب مثال الإعداد الرسمي:

"command": "C:/Tools/mmd-mcp/.venv/Scripts/python.exe",
"args": ["-m", "mmd_mcp.server"]

يجب استبدال المسار بموقع venv الخاص بك.

يُنصح بأن تكون أول استدعاء هو mmd_list_windows: فهو يعرض النوافذ فقط دون تغيير المشهد، وهو أقل الاستدعاءات خطورة كأول تجربة. إشارة النجاح هي إرجاع قائمة نوافذ MMD الحالية مع hwnd الخاص بها. إذا شغّلت أكثر من نسخة من MMD، فستحتاج في كل استدعاء لاحق إلى تمرير hwnd المُرجع من mmd_list_windows. لم تذكر الأدلة الرسمية ما إذا كان mmd_list_windows موسومًا كقراءة فقط (readOnlyHint)، فلا تعتبر أي أداة خالية من المخاطر تمامًا.

طرق تثبيت أخرى: الرسمي يقدّم مسار التثبيت من الكود المصدري أعلاه فقط، ولا توجد إرشادات لحزمة pip أو ثنائيات مُجمَّعة مسبقًا.

حالات الاستخدام

الحالة الأولى: التأكد من الاتصال وإدارة النسخ المتعددة. السيناريو: أنهيت للتو إعداد العميل وتريد التأكد من أنه يجد MMD. استدعِ mmd_list_windows وراقب قائمة النوافذ وhwnd المُرجعة. إذا كانت نسخة MMD واحدة مفتوحة، يمكنك لاحقًا استدعاء الأدوات الأخرى مباشرة؛ وإذا فُتحت عدة نسخ، فمرّر hwnd المناسب مع كل استدعاء لتحديد الهدف وفق الشرح الرسمي. ما يمكن تأكيده حتى هذه الخطوة: آلية تعداد النوافذ وتمرير hwnd، أما تفاصيل صيغة المخرجات فالقيمة المُرجعة فعليًا هي المرجع.

الحالة الثانية: كتابة إطارات مفتاحية للكاميرا دفعة واحدة وتصدير الفيديو. السيناريو: أنجزت حركة وتريد ضبط حركة الكاميرا برمجيًا وإخراج AVI. الإصدار الرسمي v0.3.0 يقدّم 50 أداة، منها mmd_batch_camera_keys لكتابة إطارات الكاميرا المفتاحية دفعة واحدة، وmmd_export_video لتصدير AVI. انتبه: كلتاهما عملية كتابة على مشروع MMD المفتوح حاليًا: كتابة الإطارات المفتاحية وتصدير الفيديو يغيّران/ينشئان محتوى المشروع، لذا تأكد قبل الاستدعاء من أن المشروع المفتوح قابل للتعديل أو لديك نسخة احتياطية منه. الأدلة الرسمية لا تذكر ما إذا كانت هذه الأدوات توفر مسار تراجع، ولا تفاصيل معاملات التصدير، فراجع تعريفات المعاملات في عميلك قبل الاستدعاء.

حدود الاستخدام

  • طبيعة القراءة/الكتابة: من بين الأدوات الخمسين توجد استدعاءات استعلام عن النوافذ/المشهد، وأخرى للكتابة مثل اختيار النماذج، وكتابة الإطارات المفتاحية للعظام/الكاميرا دفعة واحدة، وقراءة/كتابة تخصيص مؤثرات EMM (mmd_read_effect_assignments / mmd_write_effect_assignments)، وتصدير AVI. عمليات الكتابة تؤثر مباشرة على مشروع MMD المفتوح لديك.
  • ارتباط البيئة: بيئة التحقق محصورة في MMD 9.32 x64 (النسخة اليابانية، مع تحقق رسمي عبر بصمة SHA-256 محددة)، وسيُرفض أي بناء غير مدعوم.
  • المتطلبات المسبقة والآثار الجانبية: يجب تشغيل MMD يدويًا مسبقًا؛ الخادم لا يشغّل MMD تلقائيًا ولا يستمع على الشبكة؛ عند وجود نسخ متعددة يجب تمرير hwnd لتحديد الهدف، وإلا يكون الهدف غير محدد.
  • كتابات محلية: عملية التثبيت تنشئ venv محليًا وتجمّع DLL أصليًا، وهذه تعديلات محلية ضرورية.
  • بنود غير مؤكدة: الأدلة الرسمية لا تذكر ما إذا كانت الأدوات توفر آلية تراجع، ولا تفاصيل معاملات كل عملية كتابة، ولا التوافق مع Windows صيني/إنجليزي أو إصدارات Python أخرى. غياب هذه المعلومات لا يعني غياب المخاطر، فاحرص على نسخة احتياطية لمشروعك قبل أي عملية كتابة.