كيفية إنشاء مساعد للبرمجة باستخدام Gemini CLI وMCP وGo

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعلّم كيفية إنشاء خادم Model Context Protocol (MCP) ونشره لتوسيع إمكانات Gemini CLI. ستنشئ godoctor، وهو خادم مستند إلى Go يوفّر أدوات مخصّصة لتطوير Go، ما يحوّل واجهة سطر الأوامر في Gemini من مساعد ترميز عام إلى خبير متخصص في تطوير Go.

يستخدم برنامج التدريب العملي هذا أسلوب "الاستناد إلى الطلبات". عليك أن تتولّى دور قائد الفريق التقني، وتقديم الطلبات إلى مساعدك المستنِد إلى الذكاء الاصطناعي (واجهة سطر الأوامر في Gemini نفسها). هدفك هو تعلُّم كيفية ترجمة متطلبات المشروع إلى طلبات فعّالة والسماح للذكاء الاصطناعي بمعالجة تفاصيل التنفيذ.

يستند هذا المشروع إلى بروتوكول سياق النموذج (MCP). بروتوكول MCP هو بروتوكول مفتوح المصدر يوحّد طريقة تواصل النماذج اللغوية الكبيرة (LLM)، مثل Gemini، مع الأدوات والخدمات الخارجية. وهي تعمل كجسر يتيح للذكاء الاصطناعي الوصول إلى المعلومات على أرض الواقع وتنفيذ إجراءات تتجاوز معرفته المضمّنة. من خلال إنشاء خادم MCP، يمكنك إنشاء إضافة مخصّصة يمكن أن يكتشفها Gemini CLI ويستخدمها، ما يتيح له اكتساب مهارات جديدة.

أهداف الدورة التعليمية

• كيفية تثبيت Gemini CLI وضبطه
• كيفية صياغة طلبات فعّالة لتوجيه مساعد يعمل بالذكاء الاصطناعي في عملية تطوير البرامج
• كيفية تقديم سياق وإرشادات لمساعد مستند إلى الذكاء الاصطناعي
• كيفية إنشاء خادم MCP وضبطه لتعزيز إمكانات واجهة سطر الأوامر في Gemini
• كيفية وضع تطبيق Go في حاوية ونشره على Google Cloud Run

المتطلبات

يمكن إجراء ورشة العمل هذه بالكامل في Google Cloud Shell، الذي يأتي مثبّتًا مسبقًا مع جميع التبعيات اللازمة (gcloud CLI وGo وDocker وGemini CLI).

بدلاً من ذلك، إذا كنت تفضّل العمل على جهازك الخاص، ستحتاج إلى ما يلي:

• ‫Node.js 20 أو إصدار أحدث
• مشروع Google Cloud تم تفعيل الفوترة فيه
• تثبيت حزمة تطوير البرامج (SDK) من Google Cloud (gcloud CLI) وإعدادها
• تثبيت الإصدار 1.24 أو إصدار أحدث على نظامك
• تثبيت Docker على نظامك

التقنيات الرئيسية

يمكنك هنا العثور على مزيد من المعلومات حول التكنولوجيات التي سنستخدمها:

• ‫Gemini CLI: واجهة سطر الأوامر المستندة إلى الذكاء الاصطناعي التي سنوسّعها
• بروتوكول Model Context Protocol (MCP): بروتوكول مفتوح المصدر يتيح لواجهة سطر الأوامر في Gemini التواصل مع أداتنا المخصّصة
• حزمة تطوير البرامج (SDK) للغة Go في "برنامج الشركاء في القياس": مكتبة Go التي سنستخدمها لتنفيذ خادم "برنامج الشركاء في القياس"

نصائح لإنشاء درس تطبيقي حول الترميز ناجح

العمل مع مساعد مستنِد إلى الذكاء الاصطناعي هو طريقة جديدة لتطوير البرامج. في ما يلي بعض النصائح لضمان تجربة سلسة وناجحة:

1. لا تتردد في الضغط على مفتاح ESC. في بعض الأحيان، سيقترح الذكاء الاصطناعي إجراءات أو رموزًا لا توافق عليها. استخدِم مفتاح ESC لإلغاء الإجراء المقترَح وتقديم طلب جديد لتوجيه الذكاء الاصطناعي في الاتجاه الصحيح. أنت الطيّار.
2. تشجيع استخدام الأدوات: إذا بدا أنّ الذكاء الاصطناعي غير متأكّد أو يقدّم معلومات غير صحيحة، شجِّعه على استخدام الأدوات المتاحة له. يمكن أن تكون الطلبات، مثل "هل يمكنك استخدام "بحث Google" للتحقّق من ذلك؟" أو "استخدِم أداة read_file لفهم الرمز الحالي قبل إجراء تغييرات"، فعّالة جدًا.
3. تجنُّب إجراء تغييرات يدوية: حاوِل أن يقوم الذكاء الاصطناعي بكل العمل. هذه هي المهارة الأساسية التي تتدرب عليها. ومع ذلك، إذا كان عليك إجراء تغيير يدوي، عليك إخبار الذكاء الاصطناعي بذلك بعد الانتهاء. ستظهر رسالة مثل "لقد عدّلت ملف README.md يدويًا. سيضمن لك تكرار قراءة المستندات أن تبقى تكنولوجيا الذكاء الاصطناعي على اطّلاع دائم على مشروعك.
4. هل حاولت إيقافه وتشغيله مرة أخرى؟ في الحالات النادرة التي تحاول فيها الذكاء الاصطناعي فرض مسار معيّن على الرغم من أمرك، قد يكون ذلك بسبب تدهور السياق (يُعرف أحيانًا باسم "تدهور السياق"). في هذه الحالة، يمكنك استخدام أمر Gemini CLI ‏ "/compress" لتقليل التشويش في السياق، أو يمكنك استخدام الأمر "/clear" لمحو سجلّ الجلسة بالكامل في الحالات القصوى.

2. إعداد البيئة

إعداد البيئة بالسرعة التي تناسبك

1. سجِّل الدخول إلى Google Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

• اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
• معرّف المشروع هو معرّف فريد في جميع مشاريع Google Cloud ولا يمكن تغييره (لا يمكن تغييره بعد ضبطه). تنشئ Cloud Console تلقائيًا سلسلة فريدة، ولا يهمّك عادةً ما هي. في معظم دروس البرمجة، عليك الرجوع إلى رقم تعريف مشروعك (يُشار إليه عادةً باسم PROJECT_ID). إذا لم يعجبك رقم التعريف الذي تم إنشاؤه، يمكنك إنشاء رقم تعريف عشوائي آخر. يمكنك بدلاً من ذلك تجربة اسم مستخدم من اختيارك ومعرفة ما إذا كان متاحًا. لا يمكن تغييرها بعد هذه الخطوة وتبقى سارية طوال مدة المشروع.
• للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات حول هذه القيم الثلاث في المستندات.

تنبيه: رقم تعريف المشروع فريد على مستوى العالم ولا يمكن لأي شخص آخر استخدامه بعد اختياره. أنت المستخدِم الوحيد لهذا المعرّف. حتى إذا تم حذف مشروع، لا يمكن استخدام المعرّف مرة أخرى.

ملاحظة: إذا كنت تستخدم حساب Gmail، يمكنك ترك الموقع الجغرافي التلقائي مضبوطًا على لا توجد مؤسسة. إذا كنت تستخدم حسابًا على Google Workspace، اختَر موقعًا جغرافيًا مناسبًا لمؤسستك.

2. بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تكلفك تجربة هذا الدرس البرمجي الكثير، إن وُجدت أي تكلفة على الإطلاق. لإيقاف الموارد وتجنُّب تحمّل تكاليف تتجاوز هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

بدء Cloud Shell

على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس العملي Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.

من Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات أعلى يسار الصفحة:

لن يستغرق توفير البيئة والاتصال بها سوى بضع لحظات. عند الانتهاء، من المفترض أن يظهر لك ما يلي:

يتم تحميل هذه الآلة الافتراضية مزوّدة بكل أدوات التطوير التي ستحتاج إليها. توفّر هذه الخدمة دليلًا منزليًا ثابتًا بسعة 5 غيغابايت، وتعمل على Google Cloud، ما يحسّن بشكل كبير أداء الشبكة والمصادقة. يمكن إكمال جميع المهام في هذا الدرس العملي ضمن المتصفّح. ليس عليك تثبيت أي تطبيق.

3- بدء استخدام واجهة سطر الأوامر في Gemini

في هذا القسم، سنتعرّف على واجهة سطر الأوامر (CLI) من Gemini، بما في ذلك كيفية تثبيتها وإعدادها لبيئتك.

ما هي "واجهة سطر الأوامر في Gemini"؟

‫Gemini CLI هي واجهة سطر أوامر مستنِدة إلى الذكاء الاصطناعي يمكنها مساعدتك في مجموعة كبيرة من مهام التطوير. يمكنه فهم سياق مشروعك والإجابة عن الأسئلة وإنشاء الرموز البرمجية واستخدام أدوات خارجية لتوسيع إمكاناته.

تثبيت

ملاحظة: إذا كنت تستخدم Google Cloud Shell، يكون Gemini CLI مثبّتًا مسبقًا، ويمكنك الانتقال إلى القسم التالي (الإعداد).

ثبِّت Gemini CLI على مستوى العالم باستخدام npm.

npm install -g @google/gemini-cli

يمكنك التأكّد من تثبيت واجهة سطر الأوامر من خلال تنفيذ الأمر التالي:

gemini --version

الإعداد

يتم التحكّم في سلوك واجهة سطر الأوامر في Gemini من خلال ملفات الإعداد ومتغيّرات البيئة. هناك ملفان رئيسيان:

• GEMINI.md: يقدّم هذا الملف إرشادات وسياقًا باللغة الطبيعية للذكاء الاصطناعي. يقرأ واجهة سطر الأوامر هذا الملف لفهم معايير وأساليب الترميز في مشروعك.
• ‫.gemini/settings.json: يتحكّم هذا الملف في إعدادات واجهة سطر الأوامر، بما في ذلك كيفية الاتصال بالأدوات الخارجية. سنستخدم هذا الملف لإعداد واجهة سطر الأوامر لاستخدام خادم MCP الذي سننشئه في هذا الدرس التطبيقي.

سنبدأ أولاً بإعداد البيئة ثم ننتقل إلى إنشاء ملف GEMINI.md. سيتم إعداد ملف settings.json في خطوة لاحقة.

1. أنشئ دليل مشروع وقم بتهيئته:

mkdir godoctor
cd godoctor
go mod init godoctor

1. المصادقة باستخدام بيانات الاعتماد التلقائية لتطبيق Google Cloud:

إذا كنت تستخدم Cloud Shell، تكون هذه الخطوة قد تمّت بالفعل. يمكنك الانتقال إلى القسم التالي (إرشادات التطوير).

يجب تسجيل الدخول إلى حساب لديه إذن الوصول إلى مشروع Google Cloud Platform الذي ستستخدمه في هذا الدرس العملي:

• تأكَّد من تثبيت حزمة تطوير البرامج (SDK) من Google Cloud وإعدادها.
• نفِّذ الأمر التالي لإعداد "بيانات الاعتماد التلقائية للتطبيق":

gcloud auth application-default login

4. إرشادات التطوير

لضمان أن ينشئ مساعد الذكاء الاصطناعي رمز Go عالي الجودة وبأسلوب لغوي سليم، من الضروري تزويده بإرشادات واضحة. يتم ذلك في ملف GEMINI.md.

ملاحظة: يمكن استخدام ملف GEMINI.md في العديد من الأغراض الأخرى، مثل إخبار واجهة سطر الأوامر ببنية المشروع وممارسات العمل والاختبار وغير ذلك.

الهدف: إنشاء ملف GEMINI.md يعمل كمجموعة من القواعد التي يلتزم بها المساعد المستنِد إلى الذكاء الاصطناعي أثناء هذا المشروع.

المهمة: أنشئ ملفًا باسم GEMINI.md في جذر دليل godoctor وألصِق المحتوى التالي فيه.

# Go Development Guidelines
All code contributed to this project must adhere to the following principles.

### 1. Formatting
All Go code **must** be formatted with `gofmt` before being submitted.

### 2. Naming Conventions
- **Packages:** Use short, concise, all-lowercase names.
- **Variables, Functions, and Methods:** Use `camelCase` for unexported identifiers and `PascalCase` for exported identifiers.
- **Interfaces:** Name interfaces for what they do (e.g., `io.Reader`), not with a prefix like `I`.

### 3. Error Handling
- Errors are values. Do not discard them.
- Handle errors explicitly using the `if err != nil` pattern.
- Provide context to errors using `fmt.Errorf("context: %w", err)`.

### 4. Simplicity and Clarity
- "Clear is better than clever." Write code that is easy to understand.
- Avoid unnecessary complexity and abstractions.
- Prefer returning concrete types, not interfaces.

### 5. Documentation
- All exported identifiers (`PascalCase`) **must** have a doc comment.
- Comments should explain the *why*, not the *what*.

# Agent Guidelines
- **Reading URLs:** ALWAYS read URLs provided by the user. They are not optional.

اكتملت الآن عملية إعداد بيئة التطوير بالكامل.

5- الإصدار الأوّلي: خادم godoc

هدفنا الأول هو إنشاء الإصدار الأولي من خادم godoctor. يجب أن يكون هذا الإصدار تطبيقًا بسيطًا جاهزًا للإنتاج يوفّر أداة واحدة باسم godoc تتيح البحث عن مستندات Go.

الهدف: إنشاء خادم MCP جاهز للإنتاج يعرض الأمر go doc، ما يسمح لنموذج لغوي كبير بالبحث في مستندات Go.

نفِّذ أمر Gemini CLI في واجهة المستخدم:

gemini

ملاحظة: إذا كنت بحاجة إلى تثبيت Gemini CLI أو تحديثه على Cloud Shell، يمكنك استخدام هذا الأمر: sudo env PATH=$PATH npm install -g @google/gemini-cli

عند تشغيل واجهة سطر الأوامر للمرة الأولى، سيُطلب منك اختيار وضع مصادقة ومظهر. بالنسبة إلى وضع المصادقة، اختَر "تسجيل الدخول باستخدام Google" لتسجيل الدخول باستخدام حساب Google شخصي حتى تتمكّن من الاستفادة من المستوى المجاني السخي في Gemini CLI. سيظهر لك خيار لتحديد وضع المصادقة على النحو التالي:

في حال أردت تغيير اختيارك، يمكنك كتابة /auth والضغط على مفتاح Enter لفتح هذه القائمة مرة أخرى.

سيُطلب منك بعد ذلك اختيار مظهر:

كما هو الحال مع /auth، يمكنك أيضًا تغيير المظهر لاحقًا باستخدام الأمر /theme.

بعد اختيار طريقة المصادقة والمظهر المفضّل، سيتم نقلك إلى موجه الأوامر. يمكنك هنا كتابة طلباتك، مثل:

Write a hello world application in Go.

تستخدم واجهة سطر الأوامر مزيجًا من قدراتها الخاصة على الاستنتاج (من خلال نموذج Gemini، مثل Gemini Flash أو Gemini Pro) والأدوات لتنفيذ المهام. يستخدم هذا النظام الأدوات عندما يحتاج إلى التفاعل مع نظام الملفات أو الخدمات الخارجية، مثل واجهات برمجة التطبيقات وقواعد البيانات وما إلى ذلك. ومن الأمثلة على الأدوات الجاهزة للاستخدام، أو "الأدوات الداخلية"، read_file وwrite_file وweb_fetch وgoogle_search. سيصبح خادم MCP الذي نعمل على إنشائه أيضًا أداة متاحة لواجهة سطر الأوامر.

في المرة الأولى التي يتم فيها تشغيل أداة، سيُطلب منك منح الإذن. يمكنك منحها إذنًا لمرة واحدة أو موافقة شاملة لبقية الجلسة أو رفض طلبها. إذا كانت عملية تعديل ملف، سيظهر لك أيضًا خيار تعديل الملف باستخدام محرر خارجي، في حال أردت إجراء بعض التعديلات. على سبيل المثال، هذا هو ناتج الطلب أعلاه لإنشاء برنامج "Hello World":

بالإضافة إلى الطلبات، يمكنك أيضًا استخدام الأوامر التي تبدأ بشرطة مائلة. إذا كتبت "/"، ستعرض لك واجهة سطر الأوامر تلقائيًا خيارات الإكمال التلقائي. يمكنك مواصلة كتابة الأمر الكامل أو اختيار أحد الخيارات. الأمران /auth و/theme المذكوران أعلاه هما مثالان على هذه الأوامر.

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

إنشاء خادم MCP لتطبيق Hello World

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

للحصول على نهج أكثر اتساقًا، سنطلب من النموذج أولاً إنشاء خادم MCP "Hello World" قبل تنفيذ الوظيفة التي نريدها (قراءة مستندات Go).

في ما يلي مثال على طلب:

Your task is to create a Model Context Protocol (MCP) server to expose a "hello world" tool. For the MCP implementation, you should use the official Go SDK for MCP and use the stdio transport.

Read these references to gather information about the technology and project structure before writing any code:
- https://github.com/modelcontextprotocol/go-sdk/blob/main/README.md
- https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle
- https://go.dev/doc/modules/layout

To test the server, use shell commands like these:
(
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}';
  echo '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}';
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}';
) | ./bin/godoctor

يُرجى العِلم أنّ الطلب أعلاه يتألف من ثلاثة أقسام رئيسية:

1. مواصفات المشكلة، بما في ذلك ما نريد إنشاءه والقيود (مثل استخدام حزمة SDK الرسمية بدلاً من أي حزمة SDK)
2. مستند مرجعي للنموذج لمساعدته في إزالة الغموض عن الطلب
3. إجراء اختبار يعمل كمعايير قبول للمهمة

سيساعد توفّر هذه المكوّنات الثلاثة النموذج في تحقيق النتائج المطلوبة بطريقة أكثر اتساقًا.

ملاحظة: على الرغم من أنّنا نقدّم تعليمات دقيقة جدًا، قد ينحرف النموذج أحيانًا عن التعليمات التي طلبنا منه تنفيذها، لذا من المهم التحقّق من عمله ومتابعة أي أخطاء محتملة أو هلوسات. إذا تعذّر عليك إكمال النموذج، يُرجى الاطّلاع على قسم "المراجع المفيدة" في نهاية هذا الفصل.

تنفيذ أداة Go doc

بعد أن يصبح لديك تطبيق عملي، يمكننا الانتقال إلى تنفيذ أداة "مستند Go" الحقيقية:

Add a new tool to our MCP server called "godoc" that invokes the "go doc" shell command. The tool will take a mandatory "package" argument and an optional "symbol" argument.

Read the reference for the go doc command to understand its API: https://pkg.go.dev/golang.org/x/tools/cmd/godoc

Test it by executing the call with:
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name": "godoc", "arguments": {"package": "fmt"} } }'
 | ./bin/godoctor

Test it using both a standard library package and an external package like "github.com/modelcontextprotocol/go-sdk/mcp", both with and without symbols.

يمكنك تجربة هذا الطلب أو محاولة إنشاء طلب خاص بك.

ملاحظة: يشجّع الطلب أعلاه النموذج بشكل صريح على استخدام أمر shell go doc لأنّ الرمز البرمجي لاسترداد المستندات باستخدام المكتبة العادية ليس بسيطًا وقد يستغرق النموذج بعض الوقت لمعرفة كيفية استخدامه بنفسه. يوفّر استخدام أداة go doc المضمّنة في المترجم الكثير من الوقت ويساعدنا في التركيز على ما هو مهم، وهو تنفيذ MCP.

واجهة سطر أوامر مفيدة

بعد أن تستقر على عملية تنفيذ جيدة، يمكنك توجيه النموذج لإنشاء واجهة سطر أوامر godoctor باستخدام عميل MCP. سيساعد ذلك في تبسيط اختبار الميزات من خلال تجنُّب إنشاء طلبات JSON-RPC يدويًا كما كان يتم حتى الآن.

مثال على طلب:

Now create a godoctor-cli component that will call the MCP server using command transport. This CLI will expose all tools using subcommands and allow us to test the MCP server implementation without needing to build the JSON-RPC calls manually.

Use the reference implementation at https://github.com/modelcontextprotocol/go-sdk/blob/main/README.md to build the client.

Test it by calling from the command line:
- the hello_world tool 
- the godoc tool with a local package
- the godoc tool with a local package and symbol
- the godoc tool with an external package
- the godoc tool with an external package and symbol

بعد أن أصبح لديك مجموعة من البرامج تعمل على كل من العميل والخادم، ستنتقل في القسم التالي إلى إعداد Gemini CLI باستخدام خادم MCP الذي أنشأته للتوّ من أجل الاستفادة من مزاياه في مهمة الترميز التالية.

مراجع مفيدة

ملاحظة: إنّ تجربة البرمجة باستخدام النماذج اللغوية الكبيرة هي تجربة غير حتمية، لذا لا يمكنك دائمًا ضمان الحصول على النتائج نفسها بالضبط حتى إذا نفّذت طلبَين متطابقَين في البيئة نفسها. لهذا السبب، من المهم تعلُّم كيفية تحديد ما إذا كان النموذج اللغوي الكبير عالقًا في حلقة مفرغة أو إذا كان السياق قد تدهور. تذكَّر أنّ القرار يعود إليك ويمكنك إيقافها في أي وقت من خلال الضغط على مفتاح ESC.

بما أنّ MCP لا يزال مفهومًا جديدًا وأنّ حزمة تطوير البرامج (SDK) الخاصة بـ MCP في Go هي مكتبة جديدة، قد يستغرق Gemini وقتًا طويلاً في هذه الخطوة لاكتشاف التنفيذ الصحيح بمفرده. لمساعدة النموذج في التوصّل إلى الحلّ المناسب، يمكنك تزويده بالمراجع التالية:

1. يمكنك تقديم الطلب التالي للنموذج كي يتمكّن من العثور على واجهة برمجة التطبيقات لحزمة SDK بشكل أكثر اتساقًا: "use the go doc shell command to discover the api for the go-sdk library"
2. إذا حاول النموذج فحص الرمز المصدري لحزمة SDK باستخدام أداة read_file، ستتعذّر العملية لأنّ Gemini CLI لا يمكنه قراءة الملفات خارج نطاقه الحالي. يمكنك توجيهها لاستخدام الأمرين cat وls بدلاً من ذلك من خلال الأداة run_shell_command.
3. إذا واجه النموذج صعوبة في تصحيح أخطاء التطبيق، اطلب منه إضافة تسجيل دخول أكثر تفصيلاً وتحسين المعلومات السياقية في رسائل الخطأ.
4. إذا لم ينجح أيّ من الحلول السابقة، يمكنك تجربة هذا الحل: https://github.com/danicat/godoctor

6. ضبط godoctor كخادم MCP لأداة سطر الأوامر Gemini

بعد أن ينشئ مساعد الذكاء الاصطناعي الرمز البرمجي لكل من العميل والخادم، يمكنك توجيهه لتنفيذ بعض الاختبارات اليدوية. على سبيل المثال:

retrieve the documentation for the package net/http

تأكَّد أيضًا من اختباره باستخدام تبعية خارجية (ليست في المكتبة العادية):

retrieve the documentation for the go-sdk package

بعد أن تصبح راضيًا عن النتائج، اطلب منه كتابة ملف README.md يتضمّن تعليمات حول كيفية استخدام هذا المشروع وتطويره.

Now write a detailed README.md file explaining both from a user and a developer perspective how to use and to build this project.

سنضبط الآن الخادم لكي تتمكّن واجهة سطر الأوامر (CLI) في Gemini من استخدامه خلال المرحلة التالية من التطوير.

1. اطلب من واجهة سطر الأوامر تعديل ملف GEMINI.md لاستخدام godoc كطريقة مفضَّلة لقراءة المستندات:

update the GEMINI.md file to use the godoc tool to retrieve documentation about Go packages or symbols. Always prefer to use godoc over WebFetch and GoogleSearch, and only use those when godoc doesn't give a clear answer.

2. علينا الآن إعادة تشغيل Gemini CLI لضبطه. أولاً، لنحفظ جلسة المحادثة حتى تتمكّن من استئنافها من حيث توقّفت بعد إعادة تشغيلها.

/chat save workshop001

3. اخرُج من واجهة سطر الأوامر بالضغط على Ctrl+D مرّتين.
4. تجميع ملف الخادم الثنائي: أنشئ الدليل bin وجمِّع خادم godoctor فيه.

mkdir -p bin
go build -o ./bin/godoctor ./cmd/godoctor # adjust paths as needed

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

5. إعداد Gemini CLI للأداة المحلية: أنشئ ملف .gemini/settings.json في جذر مشروعك وأضِف قسم mcpServers لإخبار Gemini CLI بكيفية تشغيل الخادم المجمَّع.

mkdir -p .gemini
touch .gemini/settings.json

6. الآن، أضِف المحتوى التالي إلى الملف الجديد باستخدام أداة تعديل سطر الأوامر، مثل vim أو nano:

{
  "mcpServers": {
    "godoctor": {
      "command": "./bin/godoctor"
    }
  }
}

7. الآن، شغِّل Gemini CLI واستعِد جلسة المحادثة:

/chat resume workshop001

8. يجب أن تتمكّن من رؤية الأداة التي تم تحميلها من خلال الضغط على Ctrl+T:

9. اختبِر عملية الدمج من خلال الطلب من Gemini CLI استخدام أداتك مع طلب مثل "Get the documentation for net/http"

ينبغي أن تظهر لك على النحو التالي:

ملاحظة: قد يحاول النموذج استدعاء الأداة من خلال أمر shell. في حال حدوث ذلك، حاوِل بدء جلسة بدون سياق الجلسة السابقة (على سبيل المثال، عدم طلب /chat resume).

إذا كانت الأداة تعمل بشكل صحيح، من المفترض أن تظهر لك المستندات التي تم استرجاعها من خلال طلب الأداة:

تهانينا، لقد أنشأت أداة MCP. لكنّ هذا ليس كلّ ما في الأمر، فما زال بإمكاننا جعله أكثر فائدة.

7. إضافة أداة مراجعة للرموز البرمجية مستندة إلى الذكاء الاصطناعي

ملاحظة مهمة: لإجراء طلبات إلى واجهة برمجة التطبيقات باستخدام Gemini، يجب أن يكون لديك مشروع على Google Cloud Platform مرتبط بحساب فوترة. من جهة العميل، يتطلّب ذلك ضبط متغيّر بيئة باسم GEMINI_API_KEY.

توفّر Gemini CLI مستوى مجانيًا سخيًا لطلبات نماذج Gemini، ولكن إذا عثر على GEMINI_API_KEY، سيتوفّر في واجهة سطر الأوامر خيار استخدام هذا المفتاح للمصادقة بدلاً من ذلك، ما سيؤدي إلى تجاوز حصص المستوى المجاني.

تأكَّد من استخدام وضع المصادقة الصحيح لتجنُّب إيقاف الطبقة المجانية. يمكنك اختيار وضع المصادقة باستخدام الأمر /auth.

لنضِف ميزة أكثر تطورًا تستند إلى الذكاء الاصطناعي، وهي ميزة مراجعة الرموز البرمجية التي تستخدم Gemini API.

الهدف: إضافة أداة جديدة باسم code_review إلى المشروع الحالي ستستخدم هذه الأداة Gemini API لتحليل رموز Go البرمجية وتقديم الملاحظات.

مثال على الطلب:

I want to add a new tool to my project called code_review. This tool should use the Gemini API to analyze Go code and provide a list of improvements in json format according to the best practices accepted by the Go community. The tool should take the Go code content and an optional hint as input. The hint will be used to provide additional guidance for the AI reviewer, like "focus on security" or "help me simplify this code". Please update the server to include this new tool and modify the CLI client to add a review command to use it.

Use this SDK to call Gemini: https://github.com/googleapis/go-genai

نصائح مفيدة

بعد أن يبدأ النموذج في العمل على ذلك، قد تلاحظ تلقائيًا أنّه يطلب استخدام أداة godoc لتصفّح مستندات حزمة genai. إذا لم ينجح ذلك، يمكنك دائمًا إيقاف العملية باستخدام مفتاح الخروج وتذكيرها بأنّ لديها الآن أداة godoc تحت تصرّفها.

تجربة ميزة "مراجعة الرموز البرمجية"

1. علينا إعادة تشغيل Gemini CLI لإنشاء خادم MCP وإعادة تحميله. احفظ جلسة المحادثة باستخدام /chat save workshop002 ثم اخرُج من واجهة سطر الأوامر بالضغط على Ctrl+D مرّتين.
2. تحتاج أداة code_review إلى مفتاح واجهة برمجة تطبيقات لأنّنا نطلب من أحد نماذج Gemini إجراء المراجعات نيابةً عنّا. يمكنك إنشاء مفتاح واجهة برمجة تطبيقات باستخدام Google AI Studio.
3. اضبط متغيّر البيئة GEMINI_API_KEY باستخدام مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه في الخطوة أعلاه:

export GEMINI_API_KEY="YOUR_API_KEY"

4. إعادة تجميع الخادم: بعد إضافة الأداة الجديدة، يجب إعادة تجميع رمز الخادم الثنائي لتضمين التغييرات.

go build -o ./bin/godoctor ./cmd/godoctor

5. شغِّل واجهة سطر الأوامر (CLI) الخاصة بـ Gemini مرة أخرى. استعادة جلسة المحادثة مع /chat resume workshop002
6. ملاحظة مهمة: تأكَّد من إثبات ملكية حسابك الشخصي على Gmail حتى لا تستخدم أداة Gemini CLI حساب الفوترة الخاص بك. يمكنك إجراء ذلك باستخدام الأمر /auth:

7. تأكَّد من تفعيل الأداة بالضغط على Ctrl+T. ينبغي أن تظهر لك على النحو التالي:

8. لنختبر الآن أداة code-review من خلال مراجعة أحد ملفات المصدر الخاصة بها:

"استخدِم أداة godoctor لمراجعة الملف cmd/godoctor/main.go".

    You should see something like this:

بعد أن أصبحت أداة مراجعة الرموز البرمجية تعمل، يمكنك الآن اقتراح تطبيق بعض التحسينات التي عثر عليها النموذج، وذلك للحصول على سير عمل كامل "يحسّن نفسه بنفسه".

لقد تأكّدت الآن من أنّ أداة code-review تعمل. في القسم التالي، ستعمل على نشرها على السحابة الإلكترونية.

تحذير: إذا كنت تستخدم المستوى المجاني من Gemini CLI، ننصحك بإلغاء ضبط GEMINI_API_KEY قبل الانتقال إلى القسم التالي لتجنُّب تفعيل الفوترة عن طريق الخطأ. يمكنك دائمًا التأكّد من أنّك تستخدم طريقة المصادقة الصحيحة من خلال الأمر /auth.

لمحو GEMINI_API_KEY، اتّبِع الخطوات التالية:

1. حفظ الجلسة الحالية باستخدام /chat save workshop003 والخروج من واجهة سطر الأوامر
2. احتفِظ بنسخة احتياطية من مفتاح واجهة برمجة التطبيقات في مكان آمن:

export | grep GEMINI_API_KEY > env.bkp

3. إلغاء ضبط GEMINI_API_KEY:

export GEMINI_API_KEY=

4. أعِد تشغيل واجهة سطر الأوامر وحمِّل الجلسة باستخدام /chat resume workshop003
5. اطلب من النموذج تطبيق التحسينات التي تمّت على مراجعة الرمز البرمجي.

8. إعداد الخادم للسحابة الإلكترونية

لا يعمل خادم MCP الذي طوّرناه حتى الآن إلا على الجهاز المحلي، وهو أمر جيد إذا كنت تطوّر أدوات لاستخدامك الخاص، ولكن غالبًا ما نحتاج في بيئات المؤسسات إلى نشر أدوات لاستخدامها على نطاق أوسع من قِبل مئات أو حتى آلاف المطوّرين.

من أجل توسيع نطاق خادم MCP، علينا تحويله من خادم يتوافق مع الإدخال/الإخراج العادي فقط إلى خادم يمكنه استخدام HTTP، ونشره في مكان يمكن للمطوّرين المختلفين الوصول إليه. لتحقيق هذا الهدف، سنستخدم وضع نقل محدّدًا في مواصفات MCP باسم HTTP القابل للبث، وسنستخدم Cloud Run كهدف نشر.

الهدف: إعادة هيكلة خادم godoctor لاستخدام نقل HTTP القابل للبث

مثال على الطلب:

The godoctor server is currently using the stdio transport. I want to deploy it to Cloud Run, so I need to refactor it to use the streamable HTTP transport instead. Please modify the server to comply with the streamable HTTP specification.

مراجع مفيدة

1. إذا واجه النموذج صعوبة في تنفيذ نقل HTTP القابل للبث، يمكنك تقديم هذا المرجع إليه: https://github.com/modelcontextprotocol/go-sdk/blob/main/design/design.md
2. قد يحاول النموذج استخدام HTTP+SSE بدلاً من ذلك، ولكن تم إيقاف هذا البروتوكول نهائيًا. إذا لاحظت أنّها تسلك هذا المسار، أعِد توجيهها إلى HTTP القابل للبث.

اختبار الخادم باستخدام HTTP

اطلب من النموذج تعديل عميل godoctor لاستخدام HTTP القابل للبث أيضًا حتى تتمكّن من اختبار ما إذا كان لا يزال يعمل.

Now update the client to use streamable HTTP and run a test by retrieving documentation from one package

اختياري: إذا أردت ضبط Gemini CLI لاستخدام الخادم عبر HTTP، اتّبِع الخطوات التالية:

1. حفظ جلستك والخروج من واجهة سطر الأوامر
2. عدِّل ملف .gemini/settings.json وغيِّر الإعدادات للإشارة إلى الخادم الذي يتم تشغيله محليًا.

"mcpServers": {
  "godoctor": {
    "httpUrl": "http://localhost:8080"
  }
}

3. شغِّل الخادم الذي تمّت إعادة تصميمه محليًا:

go run ./cmd/godoctor/main.go

4. في نافذة طرفية جديدة (بما أنّ العملية أعلاه تحظر الوصول)، ابدأ واجهة سطر الأوامر Gemini CLI وقدِّم لها طلبًا لاختبار الاتصال، مثلاً: "استخدِم أداة godoctor للحصول على مستندات حول fmt.Println".
5. أوقِف الخادم بالضغط على Ctrl+C عند الانتهاء من الاختبار.

9- تغليف التطبيق في حاوية باستخدام Docker

بعد أن أصبح الخادم يستخدم بروتوكول النقل الصحيح، يمكننا تحويله إلى حاوية لنشره.

الهدف: إنشاء ملف Dockerfile لتعبئة خادم godoctor في صورة حاوية محمولة وجاهزة للإنتاج

مثال على الطلب:

Please create a multi-stage Dockerfile that compiles the Go binary and copies it into a minimal golang image like golang:1.24-alpine.

اختبار صورة Docker

بعد إنشاء Dockerfile، أنشئ الصورة وشغِّلها للتأكّد من أنّها تعمل بشكل صحيح. يمكنك أن تطلب من Gemini تنفيذ المهمة نيابةً عنك:

build the image and test the connectivity to the server using the godoctor client

اختياري: إذا أردت إجراء الاختبار يدويًا، اتّبِع الخطوات التالية:

1. إنشاء الحاوية:

docker build -t godoctor:latest .

2. تشغيل الحاوية محليًا:

docker run -p 8080:8080 -e PORT=8080 godoctor:latest

3. اختبِر الحاوية قيد التشغيل: في نافذة طرفية أخرى، شغِّل واجهة سطر الأوامر Gemini واطلب منها استرداد المستندات.
4. أوقِف الخادم بالضغط على Ctrl+C عند الانتهاء من الاختبار.

10. النشر على Cloud Run

حان الوقت الآن لنشر الحاوية على السحابة الإلكترونية.

الهدف: نشر خادم godoctor المحفوظ في حاوية على Google Cloud Run

إرشادات الطلب: اطلب من مساعدك المستنِد إلى الذكاء الاصطناعي تقديم أوامر gcloud لنشر الحاوية.

مثال على الطلب:

Now please deploy this image to Cloud Run and return me an URL I can use to call the MCP tool. Deploy it to us-central1 and use the project currently configured in the environment.

ملاحظة: إذا كان هذا مشروعًا جديدًا أو كانت هذه هي المرة الأولى التي تستخدم فيها Cloud Run في هذا المشروع، سيُطلب منك تفعيل واجهات برمجة التطبيقات Artifact Registry وCloud Run.

بعد انتهاء عملية النشر، سنضبط واجهة سطر الأوامر Gemini CLI لاستخدام الأداة التي نشرتها للتو.

اطلب من Gemini تعديل ملف .gemini/settings.json لتغيير إعدادات أداة MCP للإشارة إلى الخدمة التي تم نشرها.

now update the .gemini/settings.json file to use this URL for the godoctor server

يجب أن يبدو القسم الأخير mcpServers على النحو التالي (تذكَّر استبدال العنصر النائب بعنوان URL الفعلي لتطبيق Cloud Run):

"mcpServers": {
  "godoctor": {
    "httpUrl": "https://<your-cloud-run-id>.us-central1.run.app"
  }
}

اختبار عملية النشر في Cloud Run

أنت الآن جاهز للاختبار النهائي والشامل.

أعِد تشغيل Gemini CLI لآخر مرة (باستخدام /chat save و/chat resume للحفاظ على السياق). من المفترض أن يتمكّن واجهة سطر الأوامر الآن من استدعاء خادم MCP البعيد. جرِّب طلب مستندات لأي حِزم.

يُرجى العِلم أنّه لاستخدام أداة مراجعة الرموز البرمجية، تحتاج الخدمة إلى GEMINI_API_KEY. يمكنك أن تطلب من Gemini CLI إعادة نشرها باستخدام البيئة المناسبة:

update the cloud run environment to add a GEMINI_API_KEY and use the value in @env.bkp. Then update the .gemini/settings.json file with the correct service URL

أعِد تشغيل واجهة سطر الأوامر واختبِرها باستخدام طلب:

Use the godoctor tool to review the cmd/godoctor/main.go file

سيتصل Gemini CLI الآن بخدمة Cloud Run التي تم نشرها وينفّذ مراجعة الرمز.

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

مثال على طلب:

I'm done with my tests on the CloudRun server, please delete this deployment for me and revert my .gemini/settings.json to use the local version.

11. تهانينا!

لقد نجحت في توجيه مساعد مستنِد إلى الذكاء الاصطناعي لإنشاء أداة متطورة مستنِدة إلى الذكاء الاصطناعي وتعبئتها في حاوية ونشرها. والأهم من ذلك، أنّك تدربت على المهارة الأساسية لتطوير البرامج الحديثة، وهي تحويل المتطلبات إلى طلبات فعّالة. لقد نجحت في توسيع نطاق Gemini CLI باستخدام أداة مخصّصة، ما يجعله مساعدًا أكثر فعالية وتخصّصًا في تطوير Go.

مستندات المرجع

• مواصفات بروتوكول سياق النموذج
• Go SDK for MCP
• ‫Google Gen AI Go SDK
• إعلان عن Gemini CLI
• صفحة Gemini CLI الرئيسية للمشروع على GitHub
• مستندات Gemini CLI