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

1. مقدمة

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

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

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

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

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

المتطلبات

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

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

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

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

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

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

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

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

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

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

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

اختَر أحد الخيارات التالية: إعداد البيئة الذاتي إذا كنت تريد تنفيذ هذا

الدرس التطبيقي حول الترميز على جهازك، أو ابدأ Cloud Shell إذا أردت تنفيذ هذا الدرس التطبيقي حول الترميز بالكامل على السحابة الإلكترونية.

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

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 CLI، بما في ذلك كيفية تثبيته وإعداده لبيئتك.

ما هو Gemini CLI؟

‫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

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

ملاحظة: إذا كنت تستخدم Cloud Shell، سيتم توفير المصادقة لك تلقائيًا.

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

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

gcloud auth application-default login

4. ملف السياق (GEMINI.md)

تُستخدم ملفات السياق، التي تستخدم الاسم التلقائي GEMINI.md، لتوفير سياق تعليمي لنموذج Gemini. يمكنك استخدام هذه الملفات لتقديم تعليمات خاصة بالمشروع أو تحديد شخصية أو تقديم أدلة أسلوب الترميز لجعل ردود الذكاء الاصطناعي أكثر دقة وملاءمة لاحتياجاتك.

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

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

افتح بيئة التطوير المتكاملة لإنشاء ملف GEMINI.md يتضمّن المحتوى أدناه. إذا كنت تستخدم Cloud Shell، يمكنك فتح محرّر باستخدام الأمر أدناه:

cloudshell edit .

المهمة: أنشئ ملفًا باسم 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*.

## 6. Project structure
- cmd/ contains source code for target binaries (e.g. server, client)
- internal/ contains source code for packages not meant to be exported (e.g. internal/tools/hello)
- bin/ contains the compiled binaries
- At the root place README.md, go.mod and go.sum

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

5- الإصدار الأوّلي: خادم مستندات

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

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

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

gemini

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

عند تشغيل واجهة سطر الأوامر للمرة الأولى، سيُطلب منك اختيار وضع مصادقة ومظهر.

إذا كنت تنفّذ هذا الدرس العملي المبرمَج في Cloud Shell، اختَر الخيار استخدام بيانات اعتماد مستخدم Cloud Shell. إذا لم يكن لديك حساب، يمكنك استخدام ميزة تسجيل الدخول باستخدام 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 الذي نعمل على إنشائه أيضًا أداة متاحة لواجهة سطر الأوامر.

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

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

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

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

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

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

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

Create a Model Context Protocol (MCP) server that exposes a "hello_world" tool. This tool, when called, should return the message "Hello, MCP world!"

For the MCP implementation, you should use the official Go SDK for MCP (github.com/modelcontextprotocol/go-sdk/mcp) and use the stdio transport.

TODO:
- Download the dependency: `go get github.com/modelcontextprotocol/go-sdk/mcp`
- Inspect the documentation of the SDK: `go doc github.com/modelcontextprotocol/go-sdk/mcp`
- Build a `server` command that supports stdio transport only
- Build a `client` command that connects to the server over command transport to test the server

Acceptance Criteria:
- `./bin/client --list-tools` returns the list of server tools including "hello_world"
- `./bin/client --call-tool` "hello_world" returns the output "Hello, MCP world!"

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

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

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

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

تنفيذ أداة read_docs

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

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

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

TODO:
- create a package `./internal/tools/docs`
- register the tool with the MCP server
- update the client to support the "read_docs" tool by providing arguments to the tool call

Acceptance Criteria:
- `./bin/client --tools-list` show both hello_world and read_docs
- `./bin/client --tool-call read_docs fmt` returns the documentation for the `fmt` package
- `./bin/client --tool-call read_docs fmt.Println` returns the documentation for the `fmt.Println` function
- `./bin/client --tool-call read_docs github.com/modelcontextprotocol/go-sdk/mcp` returns documentation for the `mcp` package

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

نصائح مفيدة

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

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

1. إذا تخطّى النموذج قراءة المستندات في أي خطوة، اضغط على ESC وذكِّره بذلك. إذا لم تكن على دراية بلغة Go، سيؤدي تشغيل "go doc" بالإضافة إلى اسم الحزمة "go doc github.com/modelcontextprotocol/go-sdk/mcp" إلى عرض المستندات الصحيحة.
2. لا يتضمّن نموذج الوحدة الأعلى مستوى " github.com/modelcontextprotocol/go-sdk" أي مستندات (لأنّه لا يتضمّن أي رموز Go برمجية)، لذا عليك أن تطلب من النموذج البحث عن المسار الكامل.
3. في المقابل، إذا كان النموذج يقدّم معلومات غير صحيحة عن حزمة غير متوفّرة، مثلاً: "go doc github.com/modelcontextprotocol/go-sdk/mcp/server"، ما عليك سوى توجيهه إلى الحزمة ذات المستوى الأعلى.

6. ضبط godoctor كخادم MCP لـ Gemini CLI

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

retrieve the documentation for the package net/http

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

retrieve the documentation for the github.com/modelcontextprotocol/go-sdk/mcp 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.

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

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

update the GEMINI.md file to include instructions to always use the read_docs tool to retrieve documentation about Go packages or symbols. This should be done whenever seeing an import for the first time in a session or after a new dependency is installed to the project (e.g. via `go get`)

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

/chat save godoctor-workshop

3. اخرج من واجهة سطر الأوامر بالضغط على Ctrl+D مرتين أو كتابة الأمر /quit.
4. في الخطوات السابقة، من المفترض أنّ البرنامج قد جمع لك ملفًا ثنائيًا للخادم، ولكننا نجمع الخادم مرة أخرى باسم مختلف حتى لا يتأثر عند تعديل رمز المصدر:

mkdir -p bin && go build -o ./bin/godoctor ./cmd/server

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

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

6. الآن، أضِف المحتوى التالي إلى الملف الجديد باستخدام إما محرّر cloudshell أو بيئة التطوير المتكاملة المفضّلة لديك.

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

7. تشغيل Gemini CLI باستخدام الأمر gemini
8. من المفترض أن تتمكّن من معرفة أنّه تم تحميل الأداة من خلال كتابة الأمر /mcp. يمكنك أيضًا عرض الوصف الكامل للأدوات باستخدام /mcp desc:

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

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

ملاحظة: إذا حاول النموذج قراءة المستندات باستخدام run_shell_command، ألغِ الطلب وأعِد توجيهه لاستخدام الأداة التي طوّرناها للتو.

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

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

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

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

يمكنك الآن استعادة جلسة المحادثة السابقة باستخدام الأمر /chat resume godoctor-workshop. سيؤدي ذلك إلى تحميل سياق الجلسة حتى النقطة التي انتهينا فيها من تطوير read_docs، وبالتالي سيتوفّر لدى النموذج المعرفة المطلوبة لإنشاء الأداة الجديدة.

ستحتاج هذه الأداة إلى الوصول إلى Vertex AI، لذا علينا تفعيل واجهة برمجة التطبيقات أولاً. يمكنك تنفيذ أوامر shell بدون مغادرة Gemini CLI من خلال كتابة علامة تعجّب (!) في طلب فارغ. سيؤدي ذلك إلى تغيير Gemini CLI إلى وضع shell.

نفِّذ الأمر التالي في وضع shell لتفعيل Vertex AI API:

gcloud services enable aiplatform.googleapis.com

بعد الانتهاء من تنفيذ الأمر، يمكنك العودة إلى وضع الطلب عن طريق الضغط على مفتاح الخروج (Esc).

ملاحظة مهمة: ستستخدِم حزمة تطوير البرامج (SDK) الخاصة بـ go-genai متغيّرات البيئة التي حدّدناها في خطوة الإعداد في ورشة العمل هذه: GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION. إذا واجهتك أي مشاكل، تأكَّد من تحديد هذه المتغيّرات بشكلٍ صحيح في بيئتك.

لا يمكنك تغيير متغيرات البيئة من داخل وضع shell في Gemini CLI (لن يتم حفظ التغييرات)، لذا عليك الخروج من واجهة سطر الأوامر وتحديد المتغيرات ثم بدء واجهة سطر الأوامر مرة أخرى.

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

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

Add a new tool to my project called code_review. This tool should use the Gemini API on Vertex AI (with model id gemini-2.5-pro) to analyze Go code and provide a list of improvements 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".

The tool output should be text in Markdown format.

TODO:
- add the genai SDK dependency with `go get import google.golang.org/genai`
- create the tool code in ./internal/tools/code/review.go
- create a code review prompt to be used by the tool
- use go-genai with Vertex AI authentication to call gemini-2.5-pro
- register the tool with the server
- add a flag to the server to set the Google Cloud Project ID: --project
- add a flag to the server to set the Google Cloud Location: --location
- add support to the review tool in the client CLI

NOT TO DO:
- DO NOT use the package github.com/google/generative-ai-go/genai as it is DEPRECATED
- DO NOT use the package cloud.google.com/go/vertexai/genai as it has been superseded by google.golang.org/genai

Acceptance Criteria:
- `./bin/client --tools-list` show all tools including `code_review`
- `./bin/client --tool-call code_review internal/tools/code/review.go` returns the code review for the "review.go" file

نصائح مفيدة

1. بعد أن يبدأ النموذج في العمل على ذلك، قد تلاحظ تلقائيًا أنّه يطلب استدعاء أداة read_docs لتصفّح مستندات حزمة genai. إذا لم ينجح ذلك، يمكنك دائمًا إيقاف العملية باستخدام مفتاح الخروج وتذكيرها بأنّ أداة read_docs أصبحت متاحة لها.
2. إذا رأيت أنّه يحاول استخدام حزمة تطوير البرامج (SDK) الخاطئة للذكاء الاصطناعي التوليدي (على الرغم من وجود قائمة واضحة "غير مسموح بها" في الطلب)، أعِد توجيهه إلى الحزمة الصحيحة.

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

1. احفظ جلسة المحادثة باستخدام /chat save godoctor-workshop ثم اخرُج من واجهة سطر الأوامر بالضغط على Ctrl+D مرتين.
2. أعِد تجميع الخادم باستخدام تعريف الأداة الجديد:

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

3. باستخدام بيئة التطوير المتكاملة (IDE)، عدِّل ملف .gemini/settings.json ليشمل إعدادات البيئة في Vertex AI:

{
  "mcpServers": {
    "godoctor": {
      "command": "./bin/godoctor",
      "env": {
        "GOOGLE_CLOUD_USE_VERTEXAI": "true",
        "GOOGLE_CLOUD_PROJECT": "<your-project-id>",
        "GOOGLE_CLOUD_LOCATION": "<your-preferred-region>"
      }
    }
  }
}

4. أعِد تشغيل Gemini CLI. استعادة جلسة المحادثة مع /chat resume godoctor-workshop
5. تأكَّد من تفعيل الأداة عن طريق كتابة الأمر /mcp. ينبغي أن تظهر لك على النحو التالي:

6. لنختبر الآن أداة code_review من خلال مراجعة أحد ملفات المصدر الخاصة بها:

Use the code_review tool to review cmd/server/main.go

    You should see something like this:

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

لقد تأكّدت الآن من أنّ أداة code-review تعمل. في القسم التالي، ستعمل على نشرها على السحابة الإلكترونية. احفظ جلستك الحالية مع /chat save godoctor-workshop واخرج من واجهة سطر الأوامر.

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

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

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

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

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

The godoctor server is currently using the stdio transport. I want to prepare it to be deployed to Cloud Run, so we need to add support to use the Streamable HTTP transport.

TODO:
- Update server to enable Streamable HTTP via the -http flag.
- An optional -listen flag can be specified to set the port to listen
- If no -http flag is specified, the server defaults to stdio transport and -listen is ignored
- Update client to use Streamable HTTP via the -addr flag
- If no flag is specified, the client defaults to command transport
- Create a shell script test_server.sh to support testing

NOT TO DO:
- DO NOT use the HTTP+SSE protocol as it has been deprecated by the MCP specification

Acceptance Criteria
- Create a shell script that:
  - Runs the server in the background;
  - Runs the client connecting over HTTP and call list tools
  - Kills the background process
- The shell script should run without failures

نصائح مفيدة

1. قد يحاول النموذج استخدام HTTP+SSE بدلاً من ذلك، ولكن تم إيقاف هذا البروتوكول نهائيًا. إذا لاحظت أنّها تسلك هذا المسار، أعِد توجيهها إلى HTTP القابل للبث.
2. لا يتيح الإصدار الحالي من Gemini CLI (الإصدار 0.26.0) تنفيذ العمليات في الخلفية (يتم إيقاف أي عملية يتم تشغيلها باستخدام run_shell_command بمجرد أن تعرض نتيجة استدعاء الأداة)، لذا نطلب من Gemini تنفيذ عملية الاختبار تلقائيًا باستخدام نص برمجي. تم التخطيط لهذه الميزة وسيتم إضافتها في المستقبل القريب، ما قد يسهّل عملية الاختبار.

اختياري: اختبار خادم MCP باستخدام HTTP

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

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

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

3. في وحدة طرفية ثانية، شغِّل الخادم المتوافق مع HTTP محليًا:

go build -o ./bin/godoctor ./cmd/server && ./bin/godoctor -listen=:8080

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.25.6-alpine. The image should support the following environment variables:
- GOOGLE_CLOUD_USE_VERTEXAI
- GOOGLE_CLOUD_PROJECT
- GOOGLE_CLOUD_LOCATION

Acceptance Criteria:
- The image builds successfully
- Create a script test_docker.sh to launch the docker image in background and test the connectivity with the client:
    - Call list_tools on the client pointing to the server running on Docker
    - Call read_docs for fmt.Println
    - Stop the server
- The script should run without failures

اختياري: اختبار صورة Docker يدويًا

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

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

docker build -t godoctor:latest .

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

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

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

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

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

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

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

Now please deploy this image to Cloud Run and return me an URL I can use to call the MCP tool. Configure Cloud Run to use the following environment variables:
- GOOGLE_CLOUD_USE_VERTEXAI: true,
- GOOGLE_CLOUD_PROJECT: <your-project-id>
- GOOGLE_CLOUD_LOCATION: <your-preferred-region>

TODO:
- Run `docker build -t gcr.io/daniela-genai-sandbox/godoctor .`
- Run `gcloud run deploy godoctor --image` with the image created above

Acceptance Criteria:
- Call list-tools with the client pointing to the CloudRun endpoint

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

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

عدِّل ملف .gemini/settings.json لتغيير إعدادات أداة MCP للإشارة إلى الخدمة التي تم نشرها، أو اطلب من Gemini CLI إجراء ذلك نيابةً عنك:

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 البعيد. جرِّب طلب مستندات لأي حِزم.

يمكنك أيضًا تجربة أداة مراجعة الرموز البرمجية:

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

تنظيف

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

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

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 باستخدام أداة MCP مخصّصة، ما يجعلها مساعدًا أكثر فعالية وتخصّصًا لتطوير تطبيقات Go.

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

• مدونة إعلان Gemini CLI
• الصفحة الرئيسية لـ Gemini CLI
• مستندات Gemini CLI
• مواصفات بروتوكول سياق النموذج
• حزمة تطوير البرامج (SDK) للغة Go في "برنامج الشركاء المتعدّدين القنوات"
• ‫Google Gen AI Go SDK