ربط وكيل برمجي (MCP)

يتضمن Getman خادم MCP محليًا. يتيح هذا الخادم لوكيل برمجي قراءة طلبات الفريق وعقوده، وتشغيلها، والعمل مع حزم التغيير. يعمل الخادم على جهازك، ويتواصل مع الوكيل عبر المدخلات والمخرجات القياسية. لا يحتاج إلى حساب ولا إلى مفتاح API لأي ذكاء اصطناعي.

الربط مع Claude Code

1. ثبّت أداة سطر الأوامر، كما هو موضح في مرجع سطر الأوامر.

2. أضف ملف .mcp.json إلى جذر المستودع وانقله إلى Git. لا يحتوي الملف على مسارات مطلقة، لذلك يعمل في كل نسخة مستنسخة:

   { "mcpServers": { "getman": { "command": "getman", "args": ["mcp", "--workspace", "getman"] } } }

3. صدّر الأسرار التي تحتاجها الطلبات، في الصدفة التي تشغّل الوكيل. لا تُكتب قيم الأسرار في أي ملف:

   export GETMAN_VAR_password=…

4. شغّل claude من جذر المستودع. وافق على خادم المشروع مرة واحدة، ثم شغّل /mcp. يجب أن يظهر getman بحالة متصل.

للتشغيل دون واجهة، ودون تغيير إعدادات Claude العامة لديك:

claude -p "What can you do with the getman MCP tools?" \
  --mcp-config .mcp.json --strict-mcp-config \
  --allowedTools "mcp__getman__list_projects,mcp__getman__list_environments"

الخيارات

الخيار	المعنى
--workspace DIR	مجلد مزامنة، مثل getman. يمكن تكراره. هذا هو الوضع الموصى به.
--project P	مشروع من قاعدة بيانات التطبيق، بالمعرّف أو بالاسم. يمكن تكراره.
--env NAME	البيئة الافتراضية للأدوات التي تشغّل الطلبات.
--read-only	يزيل أدوات الكتابة الأربع.
--allow-mutations	يتخطى موافقة كل طلب على الإنتاج. استخدمه في CI فقط.
--no-secrets	لا يقرأ قيم الأسرار.
--max-body-bytes N	يقص نصوص الاستجابات في مخرجات التشغيل عند N بايت. القيمة الافتراضية 8192.

مع --workspace ودون --project، لا يرى الخادم إلا ذلك المجلد. ومن دون أي من الخيارين، يرى كل المشاريع الموجودة في قاعدة بيانات التطبيق. لا تأخذ مدخلات الأدوات أبدًا مسارات ملفات. تُسمّى مساحة العمل باسم مجلدها، مثل workspace:getman.

الأسرار

• في وضع مساحة العمل، يقرأ الخادم كل سر من متغير بيئة اسمه GETMAN_VAR_<KEY>.
• في وضع قاعدة بيانات التطبيق، يقرأ الأسرار من سلسلة المفاتيح في النظام.
• لا يحتوي أي مخرج من الأدوات على قيمة سر. يعرض list_environments أسماء المفاتيح فقط، وما إذا كان المتغير سرًا، وما إذا كانت له قيمة.
• تظهر الترويسات وحقول المصادقة التي تبدو كبيانات اعتماد بالصيغة (hidden).

موافقة الإنتاج

لا يُرسل طلب POST أو PUT أو PATCH أو DELETE إلى بيئة إنتاج بناءً على كلام الوكيل. لكل طلب، يطلب الخادم من عميل MCP أن يعرض نموذج تأكيد. يذكر النموذج الطريقة والعنوان والطلب والبيئة. لا يرسل إلا الطلب المقبول وحده. يُرفض النموذج إذا رُفض أو أُلغي. ولا يستطيع الوكيل الإجابة عن النموذج بنفسه.

إذا كان العميل لا يدعم نموذج التأكيد، يُرفض الطلب. أما في CI، فيتخطى --allow-mutations السؤال لجلسة كاملة.

أدوات القراءة

الأداة	ما تعيده
list_projects	مراجع المشاريع وأسماؤها ومجلداتها ومفاتيح التغيير والبيئات. استدعها أولًا.
list_requests	شجرة المجموعات والمجلدات والطلبات، مع معرّفاتها.
get_request	الطريقة والعنوان والمعاملات والترويسات والمصادقة الفعلية وشكل النص والسكربتات والأمثلة لطلب واحد.
list_environments	أسماء البيئات وأنواعها، ومفاتيح المتغيرات، وما إذا كان لكل سر قيمة. دون قيم.
get_contract	مستند OpenAPI، أو عملية واحدة، مثل GET /orders/{id}.
diff_contract	التغييرات المنظمة بين عقدين، مع درجات الخطورة.
list_changes	ملخصات التغييرات. ومع consumer تعيد صندوق وارد ذلك المستهلك.
get_change	حزمة التغيير كاملة، مع الفرق والأمثلة وملاحظات الترحيل والأدلة والتكاملات.
get_evidence	إدخالات الدليل لتغيير واحد.
validate_workspace	علامات التعارض والملفات غير الصالحة والمعرّفات المكررة، مع تلميح لكل منها.
run_requests	يشغّل طلبًا أو مجلدًا أو مجموعة. يعيد حالة كل خطوة واختباراتها ونصوصًا مقصوصة.

أدوات الكتابة

تعمل هذه الأدوات على مجلدات مساحة العمل فقط، وتُزال مع --read-only.

الأداة	ما تفعله
create_change	تكتب ملف تغيير جديدًا والعقد. ترفض الأداة إذا لم يتغير شيء.
update_change	تعدّل عنوان التغيير وملخصه وترحيله وحالته ومعرّفاته المرتبطة. لا تعدّل الأدلة ولا التكاملات أبدًا.
verify_change	تشغّل طلبات التغيير وتسجّل التشغيل كدليل. تُسجَّل التشغيلات الفاشلة أيضًا.
report_integration	تسجّل حالة مستهلك. مع verified تشغّل الطلبات المتأثرة أولًا.

مثال على التسليم

1. يستدعي وكيل الخادم، في نسخته المحلية، الأداة create_change، ثم verify_change في local، ويعيد المرجع، مثل GT-SHOP-001.
2. ينفّذ الخادم commit ويدفع ملفات changes/ وcontracts/ عبر Git.
3. يسحب وكيل الويب التغييرات في نسخته، ثم يستدعي list_changes مع consumer: web، ثم get_change، ثم run_requests، ثم report_integration مع status: verified.
4. بعد أن يدفع فريق الويب تغييراته، يستدعي وكيل الخادم get_change ويرى Integration verified.

النسخة البشرية الكاملة من هذا المثال موجودة في سير العمل في الفريق.

الأمان

• لا يصل الخادم إلا إلى المجلدات والمشاريع التي أُعطيها. تُرفض المراجع المجهولة.
• لا تقرأ أي أداة ملفًا تعسفيًا أو تكتبه. لا توجد أداة صدفة.
• يرسل run_requests طلبات GET وHEAD وOPTIONS فقط عندما يكون الخادم للقراءة فقط.
• لا تستطيع متغيرات وقت التشغيل التي تُمرَّر إلى run_requests أن تتجاوز متغيرًا يكوّن عنوان الطلب، فلا تُرسل بيانات الاعتماد المحفوظة إلى مضيف آخر.
• تأتي استجابات الواجهة وملاحظات الترحيل والأمثلة من أشخاص وأنظمة أخرى. يجب على الوكلاء التعامل معها كبيانات، لا كتعليمات.
• أسماء المؤلفين للعرض فقط. لا يتحقق شيء من هوية من كتب التغيير أو من أبلغ عن التكامل.

القيود

• يفتح كل استدعاء أداة جلسته الخاصة، لذلك تكون الاستدعاءات أبطأ من عميل يعمل طويلًا.
• معرّفات التغيير خاصة بكل نسخة محلية. قد تنتج نسختان الرقم نفسه، ويبلّغ validate_workspace عن ذلك.
• لا يعرض الخادم موارد MCP. استخدم الأدوات بدلًا منها.
• اختُبر نموذج التأكيد مع عميل MCP SDK. ولم يُختبر عرض النموذج في Claude Code خلال جلسة تفاعلية.