نحوه ساخت سرور MCP با Gemini CLI و Go

۱. مقدمه

در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه یک سرور Model Context Protocol (MCP) بسازید و مستقر کنید تا قابلیت‌های Gemini CLI را گسترش دهید. شما در حال ساخت godoctor ، یک سرور مبتنی بر Go هستید که ابزارهای سفارشی برای توسعه Go ارائه می‌دهد و Gemini CLI را از یک دستیار کدنویسی عمومی به یک متخصص توسعه Go تخصصی تبدیل می‌کند.

این آزمایشگاه کد از رویکرد «هدایت‌محور» استفاده می‌کند. شما به عنوان یک سرپرست فنی، دستورالعمل‌هایی را برای دستیار هوش مصنوعی خود (Gemini CLI) ارائه خواهید داد. هدف شما یادگیری نحوه تبدیل الزامات پروژه به دستورالعمل‌های مؤثر و سپردن جزئیات پیاده‌سازی به هوش مصنوعی است.

در قلب این پروژه، پروتکل زمینه مدل (MCP) قرار دارد. MCP یک پروتکل متن‌باز است که نحوه ارتباط مدل‌های زبانی بزرگ (LLM) مانند Gemini با ابزارها و سرویس‌های خارجی را استاندارد می‌کند. این پروتکل به عنوان یک پل عمل می‌کند و به هوش مصنوعی اجازه می‌دهد تا به اطلاعات دنیای واقعی دسترسی پیدا کند و اقداماتی فراتر از دانش داخلی خود انجام دهد. با ساخت یک سرور MCP، شما در حال ایجاد یک افزونه سفارشی هستید که Gemini CLI می‌تواند آن را کشف و استفاده کند و به طور مؤثر مهارت‌های جدید را به آن آموزش دهد.

آنچه یاد خواهید گرفت

• نحوه نصب و پیکربندی رابط خط فرمان Gemini
• چگونه دستورالعمل‌های مؤثری برای راهنمایی یک دستیار هوش مصنوعی در توسعه نرم‌افزار تدوین کنیم؟
• نحوه ارائه زمینه و دستورالعمل‌ها به یک دستیار هوش مصنوعی
• نحوه ایجاد و پیکربندی یک سرور MCP برای افزایش قابلیت‌های Gemini CLI
• نحوه کانتینرایز کردن و استقرار یک برنامه Go در Google Cloud Run

آنچه نیاز دارید

این کارگاه آموزشی را می‌توان به‌طور کامل در Google Cloud Shell انجام داد، که شامل تمام وابستگی‌های لازم (gcloud CLI، Go، Docker، Gemini CLI) از پیش نصب‌شده است .

از طرف دیگر ، اگر ترجیح می‌دهید روی دستگاه خودتان کار کنید، به موارد زیر نیاز خواهید داشت:

• Node.js نسخه ۲۰ یا بالاتر
• نصب و راه‌اندازی Google Cloud SDK (gcloud CLI)
• نسخه ۱.۲۴ یا بالاتر را روی سیستم خود نصب کنید.
• داکر روی سیستم شما نصب شده باشد

فناوری‌های کلیدی

در اینجا می‌توانید اطلاعات بیشتری در مورد فناوری‌هایی که ما استفاده خواهیم کرد، بیابید:

• رابط خط فرمان Gemini : رابط خط فرمان مبتنی بر هوش مصنوعی که ما آن را گسترش خواهیم داد
• پروتکل زمینه مدل (MCP) : پروتکل متن‌بازی که به Gemini CLI اجازه می‌دهد تا با ابزار سفارشی ما ارتباط برقرار کند.
• کیت توسعه نرم‌افزار Go برای MCP : کتابخانه Go که برای پیاده‌سازی سرور MCP خود استفاده خواهیم کرد.

نکاتی برای یک آزمایشگاه کد موفق

کار با یک دستیار هوش مصنوعی روشی جدید برای توسعه نرم‌افزار است. در اینجا چند نکته برای ایجاد یک تجربه روان و موفق ارائه شده است:

1. از زدن دکمه ESC نترسید. هوش مصنوعی گاهی اوقات اقدامات یا کدهایی را پیشنهاد می‌دهد که شما با آنها موافق نیستید. از کلید ESC برای لغو اقدام پیشنهادی آن استفاده کنید و یک پیام جدید برای هدایت آن در مسیر درست ارائه دهید. شما خلبان هستید.
2. استفاده از ابزار را تشویق کنید. اگر به نظر می‌رسد هوش مصنوعی اطلاعات را گم کرده یا در حال ساخت اطلاعات است، آن را تشویق کنید که از ابزارهای موجود خود استفاده کند. عباراتی مانند «آیا می‌توانید از جستجوی گوگل برای تأیید آن استفاده کنید؟» یا «قبل از ایجاد تغییرات، از ابزار read_file برای درک کد فعلی استفاده کنید» می‌توانند بسیار مؤثر باشند.
3. در برابر تغییرات دستی مقاومت کنید. سعی کنید تمام کارها را هوش مصنوعی انجام دهد. این مهارت اصلی است که شما در حال تمرین آن هستید. با این حال، اگر مجبور به ایجاد تغییر دستی هستید، بعداً به هوش مصنوعی در مورد آن بگویید. عبارتی مانند «من فایل README.md را به صورت دستی به‌روزرسانی کرده‌ام. لطفاً دوباره آن را بخوانید تا دانش خود را به‌روز کنید» تضمین می‌کند که هوش مصنوعی با پروژه شما همگام می‌ماند.
4. آیا سعی کرده‌اید آن را خاموش و روشن کنید؟ در موارد نادری که هوش مصنوعی سعی می‌کند مسیر مشخصی را در برابر دستور شما اعمال کند، ممکن است به دلیل تخریب زمینه (که گاهی اوقات "پوسیدگی زمینه" نیز نامیده می‌شود) باشد. در این حالت می‌توانید از دستور "/compress" در Gemini CLI برای کاهش نویز زمینه استفاده کنید یا در موارد شدید، می‌توانید از دستور "/clear" برای پاک کردن کل تاریخچه جلسه استفاده کنید.

۲. تنظیمات محیطی

برای اعتبارهای Google Cloud: برای کمک به شروع کار، اعتبارهای رایگان Google Cloud خود را با استفاده از این لینک فعال کنید. می‌توانید دستورالعمل‌های اینجا را برای فعال کردن اعتبار و ایجاد یک پروژه جدید دنبال کنید.

یکی از گزینه‌های زیر را انتخاب کنید: اگر می‌خواهید این را اجرا کنید، تنظیم محیط خودتنظیم

codelab را روی دستگاه خودتان اجرا کنید، یا اگر می‌خواهید این codelab را کاملاً در فضای ابری اجرا کنید ، Cloud Shell را شروع کنید .

تنظیم محیط خودتنظیم

1. وارد کنسول گوگل کلود شوید و یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید. اگر از قبل حساب جیمیل یا گوگل ورک اسپیس ندارید، باید یکی ایجاد کنید .

• نام پروژه، نام نمایشی برای شرکت‌کنندگان این پروژه است. این یک رشته کاراکتری است که توسط APIهای گوگل استفاده نمی‌شود. شما همیشه می‌توانید آن را به‌روزرسانی کنید.
• شناسه پروژه در تمام پروژه‌های گوگل کلود منحصر به فرد است و تغییرناپذیر است (پس از تنظیم، قابل تغییر نیست). کنسول کلود به طور خودکار یک رشته منحصر به فرد تولید می‌کند؛ معمولاً برای شما مهم نیست که چه باشد. در اکثر آزمایشگاه‌های کد، باید شناسه پروژه خود را (که معمولاً با عنوان PROJECT_ID شناخته می‌شود) ارجاع دهید. اگر شناسه تولید شده را دوست ندارید، می‌توانید یک شناسه تصادفی دیگر ایجاد کنید. به عنوان یک جایگزین، می‌توانید شناسه خودتان را امتحان کنید و ببینید که آیا در دسترس است یا خیر. پس از این مرحله قابل تغییر نیست و در طول پروژه باقی می‌ماند.
• برای اطلاع شما، یک مقدار سوم، شماره پروژه ، وجود دارد که برخی از APIها از آن استفاده می‌کنند. برای کسب اطلاعات بیشتر در مورد هر سه این مقادیر، به مستندات مراجعه کنید.

احتیاط: شناسه پروژه به صورت سراسری منحصر به فرد است و پس از انتخاب آن توسط شما، شخص دیگری نمی‌تواند از آن استفاده کند. شما تنها کاربر آن شناسه هستید. حتی اگر پروژه‌ای حذف شود، شناسه دیگر قابل استفاده نخواهد بود.

توجه: اگر از حساب Gmail استفاده می‌کنید، می‌توانید مکان پیش‌فرض را روی «بدون سازمان» تنظیم کنید. اگر از حساب Google Workspace استفاده می‌کنید، مکانی را انتخاب کنید که برای سازمان شما منطقی باشد.

2. در مرحله بعد، برای استفاده از منابع/API های ابری، باید پرداخت صورتحساب را در کنسول ابری فعال کنید . اجرای این آزمایشگاه کد هزینه زیادی نخواهد داشت، اگر اصلاً هزینه‌ای داشته باشد. برای خاموش کردن منابع به منظور جلوگیری از پرداخت صورتحساب پس از این آموزش، می‌توانید منابعی را که ایجاد کرده‌اید یا پروژه را حذف کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان ۳۰۰ دلاری هستند.

شروع پوسته ابری

اگرچه می‌توان از راه دور و از طریق لپ‌تاپ، گوگل کلود را مدیریت کرد، اما در این آزمایشگاه کد، از گوگل کلود شل ، یک محیط خط فرمان که در فضای ابری اجرا می‌شود، استفاده خواهید کرد.

از کنسول گوگل کلود ، روی آیکون Cloud Shell در نوار ابزار بالا سمت راست کلیک کنید:

آماده‌سازی و اتصال به محیط فقط چند لحظه طول می‌کشد. وقتی تمام شد، باید چیزی شبیه به این را ببینید:

این ماشین مجازی با تمام ابزارهای توسعه‌ای که نیاز دارید، مجهز شده است. این ماشین مجازی یک دایرکتوری خانگی پایدار ۵ گیگابایتی ارائه می‌دهد و روی فضای ابری گوگل اجرا می‌شود که عملکرد شبکه و احراز هویت را تا حد زیادی بهبود می‌بخشد. تمام کارهای شما در این آزمایشگاه کد را می‌توان در یک مرورگر انجام داد. نیازی به نصب چیزی ندارید.

۳. شروع کار با رابط خط فرمان Gemini

در این بخش با رابط خط فرمان Gemini، از جمله نحوه نصب و پیکربندی آن برای محیط خود، آشنا خواهید شد.

رابط خط فرمان جمینی چیست؟

رابط خط فرمان Gemini یک رابط خط فرمان مبتنی بر هوش مصنوعی است که می‌تواند در طیف گسترده‌ای از وظایف توسعه به شما کمک کند. این رابط می‌تواند زمینه پروژه شما را درک کند، به سوالات پاسخ دهد، کد تولید کند و از ابزارهای خارجی برای گسترش قابلیت‌های خود استفاده کند.

نصب

توجه: اگر از Google Cloud Shell استفاده می‌کنید، رابط خط فرمان Gemini از قبل نصب شده است و می‌توانید به بخش بعدی (پیکربندی) بروید.

Gemini CLI را با استفاده از npm به صورت سراسری نصب کنید.

npm install -g @google/gemini-cli

می‌توانید با اجرای دستور زیر از نصب CLI اطمینان حاصل کنید:

gemini --version

پیکربندی

رفتار رابط خط فرمان Gemini توسط فایل‌های پیکربندی و متغیرهای محیطی کنترل می‌شود. دو فایل کلیدی وجود دارد:

• GEMINI.md : این فایل دستورالعمل‌ها و زمینه را برای هوش مصنوعی فراهم می‌کند. رابط خط فرمان (CLI) این فایل را می‌خواند تا استانداردها و قراردادهای کدنویسی پروژه شما را درک کند.
• .gemini/settings.json : این فایل پیکربندی CLI، از جمله نحوه اتصال به ابزارهای خارجی را کنترل می‌کند. ما قصد داریم بعداً از این فایل برای پیکربندی CLI برای استفاده از سرور MCP که در این آزمایشگاه می‌سازیم، استفاده کنیم.

ابتدا محیط را راه‌اندازی می‌کنیم و سپس به ایجاد فایل GEMINI.md می‌پردازیم. فایل settings.json در مرحله بعدی پیکربندی خواهد شد.

1. ایجاد و مقداردهی اولیه یک دایرکتوری پروژه:

mkdir godoctor && cd godoctor
go mod init godoctor

2. با استفاده از اعتبارنامه‌های پیش‌فرض برنامه Google Cloud، احراز هویت کنید:

توجه: اگر از Cloud Shell استفاده می‌کنید، احراز هویت از قبل برای شما انجام شده است.

ما باید به حسابی وارد شویم که به پروژه GCP که قرار است برای این آزمایشگاه کد استفاده کنید، دسترسی داشته باشد:

• مطمئن شوید که Google Cloud SDK را نصب و راه‌اندازی کرده‌اید .
• برای تنظیم اعتبارنامه‌های پیش‌فرض برنامه، دستور زیر را اجرا کنید:

gcloud auth application-default login

۴. فایل متنی (GEMINI.md)

فایل‌های زمینه‌ای که از نام پیش‌فرض GEMINI.md استفاده می‌کنند، برای ارائه زمینه آموزشی به مدل Gemini استفاده می‌شوند. می‌توانید از این فایل‌ها برای ارائه دستورالعمل‌های خاص پروژه، تعریف یک پرسونا یا ارائه راهنماهای سبک کدنویسی برای دقیق‌تر و متناسب‌تر کردن پاسخ‌های هوش مصنوعی با نیازهای خود استفاده کنید.

برای اطمینان از اینکه دستیار هوش مصنوعی، کد Go با کیفیت بالا و اصطلاحی تولید می‌کند، قصد داریم یک GEMINI.md با برخی از بهترین شیوه‌های رایج برای توسعه‌دهندگان Go بنویسیم.

هدف: یک فایل GEMINI.md ایجاد کنید که به عنوان مجموعه‌ای از قوانین برای دستیار هوش مصنوعی در طول این پروژه عمل کند.

IDE خود را باز کنید تا فایل 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

اکنون محیط توسعه شما کاملاً راه‌اندازی شده است.

۵. ساخت اولیه: یک سرور مستندات

هدف اول شما ایجاد نسخه اولیه سرور godoctor است. این نسخه باید یک برنامه مینیمال باشد که ابزاری به نام read_docs را ارائه می‌دهد که امکان جستجوی مستندات Go را فراهم می‌کند.

هدف: ایجاد یک سرور MCP آماده برای تولید که دستور go doc را در معرض نمایش قرار دهد و به یک LLM اجازه دهد تا مستندات Go را جستجو کند.

دستور Gemini CLI را روی shell اجرا کنید:

gemini

نکته مهم: اگر نیاز به نصب یا به‌روزرسانی رابط خط فرمان Gemini روی Cloud Shell دارید، می‌توانید از این دستور استفاده کنید: sudo env PATH=$PATH npm install -g @google/gemini-cli

وقتی برای اولین بار CLI را اجرا می‌کنید، از شما می‌خواهد که یک حالت احراز هویت و یک قالب انتخاب کنید.

اگر این codelab را در Cloud Shell اجرا می‌کنید، گزینه Use Cloud Shell user credentials را انتخاب کنید. در غیر این صورت، می‌توانید از login with Google برای ورود با حساب کاربری شخصی گوگل استفاده کنید تا بتوانید از امکانات رایگان و سخاوتمندانه Gemini CLI بهره‌مند شوید. صفحه انتخاب احراز هویت شبیه به این خواهد بود:

در صورتی که نیاز به تغییر انتخاب خود داشتید، می‌توانید عبارت /auth را تایپ کرده و اینتر را بزنید تا دوباره این منو باز شود.

در مرحله بعد از شما خواسته می‌شود که یک تم انتخاب کنید:

مشابه /auth ، می‌توانید بعداً با دستور /theme تم را تغییر دهید.

پس از انتخاب روش احراز هویت و قالب مورد نظر خود، به خط فرمان (command prompt) هدایت خواهید شد. در اینجا می‌توانید دستورات خود را تایپ کنید، به عنوان مثال:

Write a hello world application in Go

رابط خط فرمان (CLI) از ترکیبی از منطق خود (از طریق مدل Gemini مانند Gemini Flash یا Gemini Pro) و ابزارها برای انجام وظایف استفاده می‌کند. هر زمان که نیاز به تعامل با سیستم فایل یا سرویس‌های خارجی مانند APIها، پایگاه‌های داده و غیره داشته باشد، از ابزارها استفاده می‌کند. نمونه‌هایی از ابزارهایی که به صورت پیش‌فرض یا "ابزارهای داخلی" ارائه می‌شوند، read_file ، write_file ، web_fetch و google_search هستند. سرور MCP که ما در حال ساخت آن هستیم نیز به ابزاری در دسترس CLI تبدیل خواهد شد.

اولین باری که ابزاری را اجرا می‌کند، از شما اجازه می‌خواهد. می‌توانید به آن یک مجوز یک‌باره (اجازه یک‌باره)، یک مجوز کلی برای بقیه جلسه (اجازه همیشه) یا درخواست آن را رد کنید. اگر عملیات ویرایش فایل باشد، گزینه ویرایش فایل با استفاده از یک ویرایشگر خارجی را نیز خواهید یافت، فقط در صورتی که بخواهید تنظیماتی انجام دهید. به عنوان مثال، این خروجی دستور بالا برای ایجاد یک برنامه hello world است:

علاوه بر اعلان‌ها، می‌توانید از دستورات اسلش نیز استفاده کنید. اگر "/" را تایپ کنید، CLI به طور خودکار گزینه‌های تکمیل خودکار را به شما نشان می‌دهد. می‌توانید به تایپ دستور کامل ادامه دهید یا یکی از گزینه‌ها را انتخاب کنید. دستورات /auth و /theme که در بالا ذکر شد، چند نمونه از این دستورات هستند.

وقتی با رابط کاربری آشنا شدید، می‌توانید کار اصلی این بخش را شروع کنید، یعنی از CLI بخواهید سرور MCP را برای ما بنویسد.

ایجاد یک سرور Hello World MCP

یکی از بهترین راه‌ها برای اطمینان از اینکه مدل، کارها را به طور مداوم انجام می‌دهد، تقسیم وظایف پیچیده به مراحل افزایشی است. در حالی که مدل ممکن است بتواند یک کار پیچیده را به تنهایی تشخیص دهد، بدون تنظیمات مناسب، کشف پیاده‌سازی مناسب زمان زیادی خواهد برد.

برای یک رویکرد منسجم‌تر، ابتدا قصد داریم قبل از پیاده‌سازی عملکرد مورد نظرمان (با مطالعه مستندات go)، به آن دستور دهیم که یک سرور MCP با پسوند "Hello World" بسازد.

یک نمونه اعلان در زیر نشان داده شده است:

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 transport به جای http)
2. تقسیم وظایف برای انجام (TODO)
3. معیارهای پذیرش برای وظیفه، که به عنوان یک رویه آزمایشی عمل می‌کند تا عامل بداند چه زمانی کار انجام شده است

داشتن این سه جزء به مدل کمک می‌کند تا به نتایج مطلوب به شیوه‌ای سازگارتر دست یابد.

توجه: اگرچه ما در دستورالعمل‌های خود بسیار دقیق هستیم، اما گاهی اوقات مدل می‌تواند از آنچه به آن گفته‌ایم منحرف شود، بنابراین مهم است که عملکرد آن را تأیید کنید و مراقب حلقه‌های خطای احتمالی و توهمات باشید. اگر مدل گیر کرد، لطفاً بخش نکات مفید را در انتهای این فصل بررسی کنید.

پیاده‌سازی ابزار read_docs

نکته: دستور زیر صریحاً مدل را تشویق می‌کند که از دستور go doc shell استفاده کند، زیرا کد بازیابی اسناد با استفاده از کتابخانه استاندارد، بدیهی نیست و ممکن است مدتی طول بکشد تا مدل خودش آن را بفهمد. استفاده از ابزار 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

توجه: می‌توانید این دستورالعمل را امتحان کنید یا سعی کنید دستورالعمل خودتان را ابداع کنید.

نکات مفید

توجه: کدنویسی با LLMها یک تجربه غیرقطعی است، بنابراین حتی اگر دو دستور یکسان را با محیط یکسان اجرا کنید، همیشه تضمین نمی‌شود که نتایج دقیقاً یکسانی داشته باشید. به همین دلیل یادگیری نحوه تشخیص اینکه چه زمانی LLM در یک حلقه گیر کرده یا متن آن تخریب شده است، مهم است. به یاد داشته باشید که شما کنترل را در دست دارید و می‌توانید هر زمان با فشار دادن ESC آن را متوقف کنید.

با توجه به اینکه MCP هنوز یک مفهوم جدید است و Go SDK برای MCP یک کتابخانه جدید است، در این مرحله ممکن است 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 " را تصور کند، فقط آن را به سمت بسته سطح بالا هدایت می‌کند.

۶. پیکربندی godoctor به عنوان یک سرور MCP برای رابط خط فرمان Gemini

بعد از اینکه دستیار هوش مصنوعی کد را برای کلاینت و سرور تولید کرد، می‌توانید به آن دستور دهید چند تست دستی را اجرا کند. برای مثال:

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. از CLI بخواهید فایل 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 را برای پیکربندی سرور MCP مجدداً راه‌اندازی کنیم. ابتدا، جلسه چت را ذخیره می‌کنیم تا پس از راه‌اندازی مجدد، بتوانید از جایی که متوقف شده‌اید، ادامه دهید.

/chat save godoctor-workshop

3. با دو بار فشردن Ctrl+D یا تایپ دستور /quit ‎ از محیط خط فرمان (CLI) خارج شوید.
4. در مراحل قبلی، عامل باید یک فایل باینری سرور را برای شما کامپایل می‌کرد، اما ما دوباره سرور را با نام دیگری کامپایل می‌کنیم تا هنگام تغییر کد منبع آن، تحت تأثیر قرار نگیرد:

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

5. پیکربندی رابط خط فرمان Gemini برای ابزار محلی: یک فایل .gemini/settings.json در ریشه پروژه خود ایجاد کنید و یک بخش mcpServers اضافه کنید تا به Gemini CLI بگویید چگونه سرور کامپایل شده شما را اجرا کند.

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

6. اکنون، محتوای زیر را با استفاده از ویرایشگر cloudshell یا IDE مورد علاقه خود به فایل جدید اضافه کنید.

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

7. اجرای Gemini CLI با دستور gemini
8. شما باید بتوانید با تایپ دستور /mcp ببینید که ابزار بارگذاری شده است. همچنین می‌توانید با استفاده از /mcp desc توضیحات کامل ابزارها را مشاهده کنید:

9. با درخواست از Gemini CLI برای استفاده از ابزار شما با یک اعلان مانند «مستندات مربوط به بسته net/http را به من نشان بده» ادغام را آزمایش کنید.

شما باید چیزی شبیه به این را ببینید:

توجه: اگر مدل سعی کرد مستندات را با استفاده از run_shell_command بخواند، آن را لغو کرده و به استفاده از ابزاری که تازه توسعه داده‌ایم هدایت کنید.

اگر ابزار به درستی کار کند، باید مستندات بازیابی شده از طریق فراخوانی ابزار را مشاهده کنید:

تبریک می‌گویم، شما یک ابزار MCP ساخته‌اید! اما این پایان کار نیست، ما هنوز می‌توانیم این سرور را کمی مفیدتر کنیم.

۷. افزودن یک بررسی‌کننده کد مبتنی بر هوش مصنوعی

بیایید یک ویژگی پیچیده‌تر مبتنی بر هوش مصنوعی اضافه کنیم: یک بررسی‌کننده کد که از رابط برنامه‌نویسی Gemini استفاده می‌کند.

اکنون می‌توانید جلسه چت قبلی را با دستور /chat resume godoctor-workshop. این کار زمینه جلسه را تا جایی که توسعه read_docs را تمام کردیم بارگذاری می‌کند، بنابراین مدل دانش لازم برای ساخت ابزار جدید را خواهد داشت.

این ابزار به دسترسی به Vertex AI نیاز دارد، بنابراین ابتدا باید API را فعال کنیم. می‌توانید با تایپ علامت تعجب (!) در یک پنجره خالی، دستورات shell را بدون ترک Gemini CLI اجرا کنید. این کار Gemini CLI را به حالت shell تغییر می‌دهد.

برای فعال کردن API هوش مصنوعی Vertex، دستور زیر را در حالت shell اجرا کنید:

gcloud services enable aiplatform.googleapis.com

پس از اتمام دستور، می‌توانید با تایپ کلید Escape (Esc) به حالت اعلان برگردید.

نکته مهم: کیت توسعه نرم‌افزار go-genai از متغیرهای محیطی که در مرحله راه‌اندازی این کارگاه تعریف کردیم استفاده خواهد کرد: GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION. اگر مشکلی دارید، بررسی کنید که این متغیرها به درستی در محیط شما تعریف شده باشند.

شما نمی‌توانید متغیرهای محیطی را از داخل حالت shell CLI در Gemini تغییر دهید (تغییرات حفظ نخواهند شد)، بنابراین باید از CLI خارج شوید، متغیرها را تعریف کنید و دوباره CLI را اجرا کنید.

هدف: یک ابزار جدید به نام code_review به پروژه موجود اضافه کنید. این ابزار از API Gemini برای تجزیه و تحلیل کد 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 را مشاهده کنید. اگر این اتفاق نیفتاد، همیشه می‌توانید این فرآیند را با کلید escape قطع کنید و به آن یادآوری کنید که اکنون ابزار read_docs در اختیار اوست.
2. اگر دیدید که سعی دارد از GenAI SDK اشتباه استفاده کند (حتی اگر لیست واضحی از موارد «غیرمجاز» در اعلان وجود داشته باشد)، آن را به حالت صحیح برگردانید.

آزمایش بررسی‌کننده کد

1. جلسه چت را با /chat save godoctor-workshop ذخیره کنید و سپس با دو بار فشردن Ctrl+D از رابط خط فرمان (CLI) خارج شوید.
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 را اجرا کنید. جلسه چت را با استفاده از /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 (CLI) خارج شوید.

۸. سرور خود را برای فضای ابری آماده کنید

سرور 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 را برای استفاده از سرور از طریق HTTP پیکربندی کنید:

1. جلسه خود را ذخیره کنید و از CLI خارج شوید
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 را مجدداً راه‌اندازی کنید و به آن اعلانی برای آزمایش اتصال بدهید، مثلاً «از ابزار godoctor برای دریافت مستندات مربوط به fmt.Println استفاده کنید.»
5. وقتی آزمایشتان تمام شد، سرور را با Ctrl+C متوقف کنید.

۹. کانتینریزه کردن برنامه با داکر

اکنون که سرور ما از پروتکل انتقال صحیح استفاده می‌کند، می‌توانیم آن را برای استقرار، کانتینرایز کنیم.

هدف: ایجاد یک 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

اختیاری: تست دستی ایمیج داکر

پس از ایجاد Dockerfile ، تصویر را بسازید و آن را اجرا کنید تا از عملکرد صحیح آن اطمینان حاصل شود.

1. ساخت کانتینر:

docker build -t godoctor:latest .

2. کانتینر را به صورت محلی اجرا کنید:

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

3. کانتینر در حال اجرا را آزمایش کنید: در یک ترمینال دیگر، Gemini CLI را اجرا کنید و از آن بخواهید مستندات را دریافت کند.
4. وقتی آزمایشتان تمام شد، سرور را با Ctrl+C متوقف کنید.

۱۰. استقرار در 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 APIs را فعال کنید.

پس از اتمام استقرار، رابط خط فرمان Gemini را برای استفاده از ابزاری که مستقر کرده‌اید پیکربندی خواهیم کرد.

فایل .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 را مجدداً راه‌اندازی کنید (اگر می‌خواهید متن خود را حفظ کنید، /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.

۱۱. تبریک می‌گویم!

شما با موفقیت یک دستیار هوش مصنوعی را برای ساخت، کانتینرسازی و استقرار یک ابزار پیشرفته مبتنی بر هوش مصنوعی راهنمایی کرده‌اید. مهم‌تر از آن، شما مهارت ضروری توسعه نرم‌افزار مدرن را تمرین کرده‌اید: تبدیل الزامات به دستورات مؤثر. شما با موفقیت Gemini CLI را با یک ابزار MCP سفارشی گسترش داده‌اید و آن را به یک دستیار توسعه Go قدرتمندتر و تخصصی‌تر تبدیل کرده‌اید.

اسناد مرجع

• وبلاگ اطلاعیه‌های رابط خط فرمان Gemini
• صفحه اصلی رابط خط فرمان Gemini
• مستندات رابط خط فرمان جمینی
• مشخصات پروتکل زمینه مدل
• برو SDK برای MCP
• کیت توسعه نرم‌افزاری گوگل Gen AI Go