`kazma mcp` — وكيلك يحتفظ بدماغه، وتنال أدواته حزام الأمان

kazma mcp — وكيلك يحتفظ بدماغه، وتنال أدواته حزام الأمان

كاظمه في معظمها عميل MCP: تستهلك أدوات الآخرين. هذا هو الاتجاه الآخر، وهو الأكثر نفعًا.

يوجد خادمان لـ MCP في هذا المستودع. ‏kazma_gateway.mcp_server (“kazma-ide”، ‏python -m kazma_gateway.mcp_server) هو الأقدم والأضيق: سبع أدوات IDE مكتوبة يدويًا خلف KAZMA_SECRET، مُبوَّبة عبر check_sync() — الذي لا يستطيع إلا حجب أداة خطر، ولا يضعها في طابور الموافقة أبدًا. هذه الصفحة عن kazma mcp، الخادم العام: سجلّ الأدوات كاملًا، موجَّهًا عبر البوابة الحقيقية. استخدم خادم IDE لسطح ملفات/اختبارات ثابت مُبوَّب بسر؛ واستخدم هذا الخادم لتسليم أدوات كاظمه إلى وكيل اعتباطي.

وجّه أي عميل MCP — Claude Desktop، أو محررًا، أو وكيلًا آخر — إلى kazma mcp، فيستطيع استدعاء أدوات كاظمه. لا يحدث شيء خطير دون المرور بنفس البوابة التي تستخدمها نافذة المحادثة — وحين لا تستطيع تلك البوابة الوصول إلى إنسان، لا تُعرض الأدوات الخطرة أصلًا.

هذا مهم لأن الوكيل الذي يسأل ليس عادةً ما تشك فيه. ما تشك فيه هو shell_exec يعمل بلا رقابة في الثانية فجرًا لأن نموذجًا أساء قراءة صفحة ويب. كاظمه لا تستبدل وكيلك؛ إنها تستبدل الجزء الذي لم يكن أحد يراقبه.

---

التهيئة

kazma mcp --help

‏Claude Desktop ‏(claude_desktop_config.json)، أو أي عميل يتحدث MCP عبر stdio:

{
  "mcpServers": {
    "kazma": {
      "command": "kazma",
      "args": ["mcp"]
    }
  }
}

أعد تشغيل العميل. تظهر أدوات كاظمه في قائمة أدواته. اطلب منه قراءة ملف فيعمل ذلك فحسب. ظهور أدوات الكتابة من عدمه يعتمد على إمكانية بلوغ مسار موافقة — انظر القسم التالي، وتحقق من لافتة الإقلاع.

---

ما يراه العميل

الأدوات من درجة القراءة — file_read، وweb_search، وsqlite_search — موسومة readOnlyHint وتعمل فورًا.

الأدوات من درجة الخطر — shell_exec، وfile_write، و file_apply_patch_set، وgit_push، وsend_message، وما يقارب الخمسين أخرى — موسومة destructiveHint، بحيث يعرضها العميل الذي يصيّر تعليقات MCP على أنها مدمِّرة في واجهته الخاصة دون قراءة هذه الوثائق. وأوصافها تقول أيضًا، بكلمات سيقرؤها النموذج:

[Kazma] Danger-tier: this call pauses for a human approval in Kazma before it runs.

انتظارُ استدعاء الخطر أو رفضُه يعتمد على إمكانية الوصول إلى إنسان. ‏kazma mcp عملية منفصلة، تنشئها عادةً عميلة MCP لديك، والناقل الذي يحمل بطاقات الموافقة يعيش في خادم كاظمه قيد التشغيل. لا تستطيع عملية ابنة رؤية ناقل في الذاكرة داخل عملية أخرى.

لذا يوجد مسار ثانٍ. سجلّ البوابات (hitl_gates في دليل بياناتك) جدول SQLite مشترك، ولوحة المعلومات تصيّر كل صف معلّق تجده هناك. تسجّل العملية بلا ناقل بوابةً وتنتظر تغيّر حالة الصف؛ تحصل على نفس البطاقة، في نفس المكان، وتنقر نفس الزر.

لا ينشط إلا حين يراقب شيءٌ ما فعلًا. ترسل نسخة كاظمه قيد التشغيل نبضات إلى تلك القاعدة من حلقة قراءة البوابات المعلقة، ويرفض kazma mcp وضع الاستدعاء في طابور الموافقة دون نبضة حديثة — لأن بطاقة لن يراها أحد أبدًا تكلّف المستدعي مهلة الموافقة كاملة ثم تنكره رغم ذلك. لذا هناك نتيجتان صادقتان، وتخبرك اللافتة أيهما:

[kazma mcp] 155 tools; no approval bus, but a live Kazma instance is watching
the gate registry (14s ago): danger tools queue for approval there

[kazma mcp] 100 tools; HITL is enabled, no approval bus is reachable from this
process, and no running Kazma instance is watching the gate registry, so
danger tools would be denied, not queued

في الحالة الثانية تُحجب أدوات الخطر بدل نشرها ثم رفضها: 55 أداة لا يمكنها إلا الفشل ليست سوى شيء يخطط حوله نموذج العميل ويخسر عليه أدواره.

شغّل كاظمه، فتحصل عميلة MCP على أدوات الكتابة. أوقفها، فتختفي عند إعادة الاتصال التالية.

المتغيّر	الأثر
KAZMA_BUS_BRIDGE=0	إطفاء الجسر. يعيد السلوك السابق تمامًا: لا ناقل، ولا موافقة، وأدوات الخطر محجوبة.
KAZMA_WATCHER_STALE_SECONDS	كم قد تبلغ قِدم النبضة وما زالت تُحتسب (الافتراضي 120 — أربع دقات فائتة للمراقب).

يرتكز الخادم على تثبيت كاظمه، لا على مجلد محررك. تنشئ عميلة MCP ‏kazma mcp بدليل العمل لأي مشروع مفتوح لديها، وكانت مسارات كاظمه تُحل سابقًا بالصعود للأعلى من هناك — فكانت تبحث عن kazma-data بجوار مشروع لا صلة له، ولا تجد نبضة، وتحجب كل أداة خطر وهي تُبلّغ أنه لا نسخة كاظمه تعمل. أما الآن فتُحل من موقع الحزمة نفسه. ما زال KAZMA_PROJECT_ROOT وKAZMA_DATA_DIR يتيحان التجاوز، لتثبيت منقول قصدًا.

تحقّق من أيٍّ من هذا دون محرر في الحلقة:

python scripts/mcp_probe.py /path/to/kazma

ينفّذ مصافحة initialize → tools/list الحقيقية ويطبع اللافتة، وقاعدة بيانات البوابات المستخدمة، وعدد الأدوات، وما إذا كانت أدوات الخطر منشورة. مطالبة وكيل بوصف سطح أدواته الخاص لا تنجح — فهو يعرض قائمة الدوال في موجّهه، وهو شيء مختلف.

ما ليس عليه الجسر. يحمل الجسر قرارًا؛ لا يتخذه. لا يوجد «موافقة للجلسة» ولا YOLO على هذا المسار: تلك خصائص خيط محادثة، والعملية المنفصلة لا خيط لها يمكن إعادة فحص استدعاءاتها اللاحقة مقابل المنحة. قرار واحد، استدعاء أداة واحد. وهو يُغلق عند الفشل في كل اتجاه — لا مراقب، أو مراقب متقادم، أو مهلة، أو صف اختفى، أو قاعدة بيانات غير قابلة للقراءة، كلها تُنكر.

---

أين البوابة فعلًا

لا مكان داخل خادم MCP — عمدًا.

يسلّم tools/call مباشرةً إلى LocalToolRegistry.execute()، نقطة الاختناق الوحيدة لتنفيذ الأدوات. تفويض الالتزام، وخطافات PreToolUse، وقائمة سماح kazma-permissions.yaml، وناقل HITL جميعها تعيش داخله سلفًا. لا يحوي خادم MCP صفرَ منطق أمان خاص به، ومن المقرر أن يبقى كذلك — بوابة ثانية بجانب تلك هي التصادم الذي تسمّيه ملاحظات البنية بالاسم (H-8)، وهو يُنتج بطاقات موافقة مزدوجة وطرقًا مسدودة بدل أمان أكبر.

النتيجة العملية: أي شيء تفعله لتشديد بوابة كاظمه ينطبق على عملاء MCP تلقائيًا، ولا شيء في MCP يستطيع فكّها.

---

الإغلاق عند الفشل حين لا يستطيع شيء الموافقة

إن كان HITL معطلًا، يمرّر execute() أدوات الخطر بلا رقابة. هذا افتراضي معقول لمطوّر يكتب في نافذة محادثته الخاصة. وهو ليس معقولًا لعميل MCP يستدعي ولا أحد يراقب.

لذا حين تكتشف كاظمه غياب مسار موافقة، تُحجب أدوات الخطر كليًا — لا تُدرَج ولا يمكن استدعاؤها. الأداة التي يراها العميل أداة سيخطط حولها نموذجه، لذا لا تُعلن ثم تُرفض. لافتة الإقلاع (على stderr) تخبرك في أي وضع أنت:

[kazma mcp] 155 tools; HITL enabled: danger tools require approval
[kazma mcp] 155 tools; no approval bus, but a live Kazma instance is watching the gate registry (14s ago): danger tools queue for approval there
[kazma mcp] 100 tools; HITL is enabled, no approval bus is reachable from this process, and no running Kazma instance is watching the gate registry, so danger tools would be denied, not queued
[kazma mcp] 100 tools; HITL is disabled (safety.hitl.enabled), so execute() would run danger tools unattended

استدعاء أداة محجوبة يعيد خطأ يشرح كيف تصلح ذلك بدلًا من رفض مجرد.

---

الإعداد

المتغيّر	الأثر
KAZMA_MCP_TOOLS	قائمة سماح مفصولة بفواصل. عدم الضبط ينشر كل شيء. تُفرَض على tools/call كما على tools/list، لأن العميل يستطيع استدعاء اسم لم يُعرَض عليه قط.
KAZMA_MCP_ALLOW_UNGATED	نشر أدوات الخطر حتى بلا مسار موافقة متحقَّق منه. لجهاز مختبر حيث هذا فعلًا ما تريده. تقوله اللافتة بصوت عالٍ.

تضييق السطح أمر يستحق الفعل. خادم مركّز أسهل في الاستدلال من 155 أداة:

{
  "mcpServers": {
    "kazma": {
      "command": "kazma",
      "args": ["mcp"],
      "env": { "KAZMA_MCP_TOOLS": "file_read,file_write,shell_exec,web_search" }
    }
  }
}

---

ملاحظات البروتوكول

• ‏JSON-RPC 2.0، محدَّد بأسطر جديدة، عبر stdio. مكتوب يدويًا مثل kazma acp وعميل MCP؛ ‏SDK الخاص بـ MCP ليس اعتمادية ولا يضيفه هذا.
• تُتفاوَض إصدارات البروتوكول 2025-06-18 و2025-03-26 و2024-11-05؛ والإصدار المجهول يتراجع إلى أحدث ما ننفذه.
• ‏stdout يحمل إطارات البروتوكول ولا شيء غيرها. يعيد الخادم توجيه sys.stdout إلى stderr طوال المدة، فلا يستطيع print شارد من أي مكتبة أن يهبط بين إطارين ويكسر الجلسة.
• تُكتَب الإطارات بـ ensure_ascii=True. الهروب \uXXXX صالح JSON، وكل عميل يفك ترميزه، ولا ترميز تدفق يستطيع رفضه. بدونه، يقتل توصيفُ أداة واحد يحوي شرطة طويلة (en-dash) الخادمَ على طرفية Windows — وهكذا اكتُشف هذا.
• يُعاد ضبط stdin وstdout على UTF-8، فتنجو الوسائط غير ASCII ‏(المسارات العربية، مثلًا) عبر الرحلة.

---

ما هذا ليس

• ليس خادمًا بعيدًا. stdio فقط، على جهازك، كعملية ابنة لعميلك. لا مستمع شبكة ولا طبقة مصادقة، لأنه لا يوجد ما يُصادَق عليه. لا تعرّضه بغلاف مقبس وتفترض أن البوابة نظام تحكم وصول — إنها تبوّب الأفعال لإنسان حاضر، لا الهويات.
• ليس بيئة حماية. الموافقة قبول، لا احتواء. يعمل python_exec في Docker عند KAZMA_CODE_EXEC_DOCKER=force؛ ‏shell_exec بعد الموافقة هو سلطة كاملة على المضيف. انظر SECURITY.md.
• ليس دماغًا ثانيًا. نموذج العميل يقوم بالتفكير. كاظمه تزوّد الأدوات والبوابة أمامها.