این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

چگونه با Gemini CLI، MCP و Go یک دستیار کدنویسی بسازیم

1. مقدمه

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

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

در قلب این پروژه، پروتکل زمینه مدل (MCP) قرار دارد. MCP یک پروتکل منبع باز است که نحوه ارتباط مدل های زبان بزرگ (LLM) مانند 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 یا جدیدتر
یک پروژه Google Cloud با فعال کردن صورت‌حساب
Google Cloud SDK (gcloud CLI) نصب و راه اندازی شد
برو 1.24 یا بالاتر بر روی سیستم شما نصب شده است
Docker روی سیستم شما نصب شده است

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

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

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

نکاتی برای یک Codelab موفق

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

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

2. تنظیم محیط

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

به Google Cloud Console وارد شوید و یک پروژه جدید ایجاد کنید یا از یک موجود استفاده مجدد کنید. اگر قبلاً یک حساب Gmail یا Google Workspace ندارید، باید یک حساب ایجاد کنید .

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

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

Cloud Shell را راه اندازی کنید

در حالی که Google Cloud را می توان از راه دور از لپ تاپ شما کار کرد، در این کد لبه از Google Cloud Shell استفاده خواهید کرد، یک محیط خط فرمان که در Cloud اجرا می شود.

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

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

این ماشین مجازی با تمام ابزارهای توسعه که شما نیاز دارید بارگذاری شده است. این یک فهرست اصلی 5 گیگابایتی دائمی را ارائه می دهد و در Google Cloud اجرا می شود و عملکرد و احراز هویت شبکه را تا حد زیادی افزایش می دهد. تمام کارهای شما در این کد لبه را می توان در یک مرورگر انجام داد. شما نیازی به نصب چیزی ندارید.

3. شروع به کار با Gemini CLI

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

جمینی CLI چیست؟

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

نصب و راه اندازی

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

npm install -g @google/gemini-cli

با اجرای زیر می توانید تأیید کنید که CLI نصب شده است:

gemini --version

پیکربندی

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

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

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

یک فهرست پروژه ایجاد و مقداردهی اولیه کنید:

mkdir godoctor
cd godoctor
go mod init godoctor

با اعتبار پیش فرض برنامه Google Cloud احراز هویت:

ما باید به حسابی وارد شویم که به پروژه GCP که می‌خواهید برای این کد لبه استفاده کنید دسترسی داشته باشد:

مطمئن شوید که Google Cloud SDK را نصب و راه اندازی کرده اید.
برای تنظیم Application Default Credentials دستور زیر را اجرا کنید:

gcloud auth application-default login

4. دستورالعمل توسعه

برای اطمینان از اینکه دستیار هوش مصنوعی کد Go با کیفیت بالا و اصطلاحی تولید می کند، ارائه دستورالعمل های واضح برای آن ضروری است. این کار در فایل 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 را نشان می‌دهد و به LLM اجازه می‌دهد مستندات Go را استعلام کند.

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

gemini

هنگامی که برای اولین بار CLI را اجرا می کنید، از شما می خواهد یک حالت احراز هویت و یک موضوع را انتخاب کنید. برای حالت احراز هویت، «ورود با Google» را انتخاب کنید تا با یک حساب Google شخصی وارد شوید تا بتوانید از سطح رایگان سخاوتمندانه Gemini CLI بهره مند شوید. شما باید گزینه ای را برای انتخاب حالت احراز هویت خود مشابه این ببینید:

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

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

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

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

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 را برای ما بنویسد.

ایجاد سرور 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

توجه داشته باشید که دستور بالا توسط سه بخش اصلی تشکیل شده است:

مشخصات مشکل، از جمله آنچه می‌خواهیم بسازیم و محدودیت‌ها (مثلاً از SDK رسمی به جای هر SDK استفاده کنید)
اسناد مرجع برای مدل برای کمک به رفع ابهام درخواست
یک روش تست، که به عنوان معیار پذیرش برای کار عمل می کند

داشتن این سه مولفه به مدل کمک می کند تا به نتایج مطلوب تری دست یابد.

اجرای ابزار Go doc

هنگامی که شما یک پیاده سازی کار می کنید، می توانیم به سمت پیاده سازی ابزار واقعی "go doc" حرکت کنیم:

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.

با خیال راحت این دستور را آزمایش کنید یا سعی کنید درخواست خود را پیدا کنید.

یک رابط خط فرمان مفید

به محض اینکه به یک پیاده سازی خوب رضایت دادید، می توانید به مدل دستور دهید که یک Godoctor CLI با استفاده از یک مشتری 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 که به تازگی ایجاد کرده‌اید پیکربندی کنید تا از مزایای آن در برنامه‌نویسی بعدی استفاده کنید.

منابع مفید

با توجه به اینکه MCP هنوز یک مفهوم جدید است و Go SDK برای MCP یک کتابخانه جدید است، در این مرحله Gemini ممکن است زمان زیادی طول بکشد تا پیاده سازی مناسب را به تنهایی کشف کند. به منظور کمک به مدل در ارائه راه حل مناسب، ممکن است بخواهید مراجع زیر را به آن بدهید:

می‌توانید دستور زیر را به مدل بدهید تا API SDK را با هماهنگی بیشتری پیدا کند: "از دستور go doc shell برای کشف api برای کتابخانه go-sdk استفاده کنید"
اگر مدل سعی کند کد منبع SDK را با ابزار read_file بازرسی کند، شکست می خورد زیرا Gemini CLI نمی تواند فایل های خارج از محدوده فعلی خود را بخواند. می توانید از طریق ابزار run_shell_command به آن دستور دهید که از دستورات cat و ls استفاده کند.
اگر مدل در اشکال‌زدایی برنامه مشکل دارد، به آن دستور دهید تا گزارش دقیق‌تری را اضافه کند و اطلاعات متنی را در پیام‌های خطا بهبود بخشد.
اگر همه چیز شکست خورد، به آن یک پیاده سازی مرجع بدهید: https://github.com/danicat/godoctor

6. پیکربندی godoctor به عنوان یک سرور MCP برای Gemini CLI

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

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.

اکنون می‌خواهیم سرور را پیکربندی کنیم تا Gemini CLI بتواند در مرحله بعدی توسعه از آن استفاده کند.

از CLI بخواهید 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.

اکنون باید Gemini CLI را مجددا راه اندازی کنیم تا پیکربندی شود. ابتدا، اجازه دهید جلسه چت را ذخیره کنیم تا پس از راه اندازی مجدد، بتوانید از جایی که توقف کرده اید، ادامه دهید.

/chat save workshop001

با دو بار فشار دادن Ctrl+D از CLI خارج شوید.
باینری سرور را کامپایل کنید: یک پوشه bin ایجاد کنید و سرور Godoctor را در آن کامپایل کنید.

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

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

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

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

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

اکنون Gemini CLI را راه اندازی کنید و جلسه چت را بازیابی کنید:

/chat resume workshop001

شما باید بتوانید با فشار دادن Ctrl+T بارگذاری ابزار را مشاهده کنید:

ادغام را با درخواست از Gemini CLI برای استفاده از ابزار شما با درخواستی مانند "دریافت مستندات برای net/http" آزمایش کنید.

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

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

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

7. اضافه کردن یک مرورگر کد با هوش مصنوعی

مهم: برای برقراری تماس‌های API با Gemini، باید یک پروژه GCP مرتبط با حساب صورت‌حساب داشته باشید. در سمت کلاینت، برای این کار باید یک متغیر محیطی به نام GEMINI_API_KEY را پیکربندی کنید.

Gemini CLI یک ردیف رایگان سخاوتمندانه برای تماس های مدل Gemini دارد، اما اگر یک GEMINI_API_KEY پیدا کند، CLI این گزینه را دارد که به جای آن از این کلید برای احراز هویت استفاده کند، که سهمیه های ردیف آزاد را دور می زند.

مطمئن شوید که از حالت احراز هویت مناسب برای جلوگیری از غیرفعال کردن لایه رایگان استفاده می کنید. با استفاده از دستور /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 . اگر اینطور نیست، همیشه می توانید با کلید escape فرآیند را قطع کنید و به آن یادآوری کنید که اکنون ابزار godoc را در اختیار دارد.

تست مرورگر کد

برای ساختن و بارگذاری مجدد سرور MCP باید Gemini CLI را مجددا راه اندازی کنیم. جلسه چت را با /chat save workshop002 ذخیره کنید و سپس با دو بار فشار دادن Ctrl+D از CLI خارج شوید.
ابزار code_review به یک کلید API نیاز دارد زیرا ما با یک مدل Gemini تماس می‌گیریم تا بررسی‌ها را برای ما انجام دهد. می‌توانید با استفاده از Google AI Studio یک کلید API ایجاد کنید.
متغیر محیطی GEMINI_API_KEY با کلید API ایجاد شده در مرحله بالا پیکربندی کنید:

export GEMINI_API_KEY="YOUR_API_KEY"

کامپایل مجدد سرور: پس از افزودن ابزار جدید، باید باینری سرور را مجدداً کامپایل کنید تا تغییرات در آن گنجانده شود.

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

جمینی CLI را دوباره راه اندازی کنید. جلسه چت را با /chat resume workshop002 بازیابی کنید.
مهم است. اطمینان حاصل کنید که با حساب شخصی جیمیل خود احراز هویت شده اید تا خود Gemini CLI از حساب صورتحساب شما استفاده نکند. می توانید این کار را با استفاده از دستور /auth انجام دهید:

با فشار دادن Ctrl+T فعال بودن ابزار را تأیید کنید. شما باید چیزی شبیه به این را ببینید:

حالا بیایید ابزار code-review با بررسی یکی از فایل های منبع ابزار آزمایش کنیم:

"از ابزار godoctor برای بررسی فایل cmd/godoctor/main.go استفاده کنید."

    You should see something like this:

با کارکرد ابزار بازبینی کد، اکنون می‌توانید مدل را برای اعمال برخی از پیشرفت‌هایی که پیدا کرده است، برای یک گردش کار کامل "خود-بهبود" پیشنهاد دهید!

اکنون تأیید کرده اید که ابزار code-review کار می کند. در بخش بعدی روی استقرار آن در فضای ابری کار خواهید کرد.

برای پاک کردن GEMINI_API_KEY:

جلسه فعلی خود را با /chat save workshop003 ذخیره کنید و از CLI خارج شوید
از کلید API در جایی امن پشتیبان بگیرید:

export | grep GEMINI_API_KEY > env.bkp

GEMINI_API_KEY را لغو تنظیم کنید:

export GEMINI_API_KEY=

CLI را مجدداً راه اندازی کنید و جلسه را با /chat resume workshop003 بارگذاری کنید
از مدل بخواهید بهبودهای بررسی کد را اعمال کند.

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

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

برای اینکه سرور MCP خود را مقیاس بندی کنیم، باید آن را از سروری که فقط I/O استاندارد صحبت می کند به سروری که می تواند HTTP صحبت کند تبدیل کنیم و آن را در جایی مستقر کنیم که توسعه دهندگان مختلف بتوانند به آن دسترسی داشته باشند. برای این هدف ما از یک حالت انتقال تعریف شده در مشخصات MCP به عنوان HTTP قابل پخش استفاده می کنیم و از Cloud Run به عنوان هدف استقرار خود استفاده می کنیم.

هدف: برای استفاده از انتقال HTTP قابل پخش، سرور Godoctor را بازسازی کنید.

درخواست مثال:

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.

منابع مفید

اگر مدل با اجرای انتقال HTTP قابل پخش مشکل دارد، می توانید این مرجع را به آن بدهید: https://github.com/modelcontextprotocol/go-sdk/blob/main/design/design.md
ممکن است مدل سعی کند به جای آن از 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 پیکربندی کنید:

جلسه خود را ذخیره کرده و از CLI خارج شوید
فایل .gemini/settings.json خود را ویرایش کنید و پیکربندی را تغییر دهید تا به سرور در حال اجرا محلی خود اشاره کند.

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

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

go run ./cmd/godoctor/main.go

در یک ترمینال جدید (از آنجایی که عملیات بالا مسدود شده است)، Gemini CLI را راه اندازی کنید و به آن دستور دهید تا اتصال را آزمایش کند، به عنوان مثال، "از ابزار godoctor برای دریافت اسناد fmt.Println استفاده کنید."
پس از اتمام تست، سرور را با Ctrl+C متوقف کنید.

9. کانتینر کردن برنامه با داکر

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

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

تست تصویر داکر

پس از ایجاد Dockerfile ، تصویر را بسازید و اجرا کنید تا مطمئن شوید که درست کار می کند. می توانید به Gemini دستور دهید که این کار را برای شما انجام دهد:

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

اختیاری: اگر می خواهید آزمایش را به صورت دستی انجام دهید:

ظرف را بسازید:

docker build -t godoctor:latest .

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

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

محفظه در حال اجرا را آزمایش کنید: در ترمینال دیگر، Gemini CLI را راه اندازی کنید و از آن بخواهید مستندات را واکشی کند.
پس از اتمام تست، سرور را با 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.

هنگامی که استقرار به پایان رسید، 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

اکنون برای آزمون نهایی و پایانی آماده هستید.

جمینی CLI را برای آخرین بار راه اندازی مجدد کنید (برای حفظ زمینه خود /chat save و /chat resume استفاده کنید). اکنون CLI باید بتواند سرور 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

CLI را مجدداً راه اندازی کنید و آن را با یک فرمان آزمایش کنید:

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

Gemini CLI اکنون به سرویس Cloud Run مستقر شما متصل می شود و بررسی کد را اجرا می کند.

اعلان مثال:

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 قدرتمندتر و تخصصی تر تبدیل کرده اید.

چگونه با Gemini CLI، MCP و Go یک دستیار کدنویسی بسازیم

1. مقدمه

چیزی که یاد خواهید گرفت

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

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

نکاتی برای یک Codelab موفق

2. تنظیم محیط

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

Cloud Shell را راه اندازی کنید

3. شروع به کار با Gemini CLI

جمینی CLI چیست؟

نصب و راه اندازی

پیکربندی

4. دستورالعمل توسعه

5. ساخت اولیه: یک سرور godoc

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

اجرای ابزار Go doc

یک رابط خط فرمان مفید

منابع مفید

6. پیکربندی godoctor به عنوان یک سرور MCP برای Gemini CLI

7. اضافه کردن یک مرورگر کد با هوش مصنوعی

نکات مفید

تست مرورگر کد

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

منابع مفید

تست سرور با استفاده از HTTP

9. کانتینر کردن برنامه با داکر

تست تصویر داکر

10. استقرار در Cloud Run

آزمایش استقرار Cloud Run

11. تبریک!

اسناد مرجع