۱. مقدمه
در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه یک سرور Model Context Protocol (MCP) بسازید و مستقر کنید تا قابلیتهای Gemini CLI را گسترش دهید. شما در حال ساخت godoctor ، یک سرور مبتنی بر Go هستید که ابزارهای سفارشی برای توسعه Go ارائه میدهد و Gemini CLI را از یک دستیار کدنویسی عمومی به یک متخصص توسعه Go تخصصی تبدیل میکند.
این آزمایشگاه کد از رویکرد «هدایتمحور» استفاده میکند. شما به عنوان یک سرپرست فنی، دستورالعملهایی را به دستیار هوش مصنوعی خود (خود رابط خط فرمان Gemini) ارائه خواهید داد. هدف شما یادگیری نحوه تبدیل الزامات پروژه به دستورالعملهای مؤثر و سپردن جزئیات پیادهسازی به هوش مصنوعی است.
در قلب این پروژه، پروتکل زمینه مدل (MCP) قرار دارد. MCP یک پروتکل متنباز است که نحوه ارتباط مدلهای زبانی بزرگ (LLM) مانند Gemini با ابزارها و سرویسهای خارجی را استاندارد میکند. این پروتکل به عنوان یک پل عمل میکند و به هوش مصنوعی اجازه میدهد تا به اطلاعات دنیای واقعی دسترسی پیدا کند و اقداماتی فراتر از دانش داخلی خود انجام دهد. با ساخت یک سرور MCP، شما در حال ایجاد یک افزونه سفارشی هستید که Gemini CLI میتواند آن را کشف و استفاده کند و به طور مؤثر مهارتهای جدید را به آن آموزش دهد.
آنچه یاد خواهید گرفت
- نحوه نصب و پیکربندی رابط خط فرمان Gemini
- چگونه دستورالعملهای مؤثری برای راهنمایی یک دستیار هوش مصنوعی در توسعه نرمافزار تدوین کنیم؟
- نحوه ارائه زمینه و دستورالعملها به یک دستیار هوش مصنوعی
- نحوه ایجاد و پیکربندی یک سرور MCP برای افزایش قابلیتهای Gemini CLI
- نحوه کانتینرایز کردن و استقرار یک برنامه Go در Google Cloud Run
آنچه نیاز دارید
این کارگاه آموزشی میتواند بهطور کامل درون پوسته ابری گوگل اجرا شود، که بهصورت پیشفرض با تمام وابستگیهای لازم (gcloud CLI، Go، Docker، Gemini CLI) نصب شده است.
از طرف دیگر، اگر ترجیح میدهید روی دستگاه خودتان کار کنید، به موارد زیر نیاز خواهید داشت:
- Node.js نسخه ۲۰ یا بالاتر
- یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
- نصب و راهاندازی Google Cloud SDK (gcloud CLI)
- نسخه ۱.۲۴ یا بالاتر را روی سیستم خود نصب کنید.
- داکر روی سیستم شما نصب شده باشد
فناوریهای کلیدی
در اینجا میتوانید اطلاعات بیشتری در مورد فناوریهایی که ما استفاده خواهیم کرد، بیابید:
- رابط خط فرمان Gemini : رابط خط فرمان مبتنی بر هوش مصنوعی که ما آن را گسترش خواهیم داد
- پروتکل زمینه مدل (MCP) : پروتکل متنبازی که به Gemini CLI اجازه میدهد تا با ابزار سفارشی ما ارتباط برقرار کند.
- کیت توسعه نرمافزار Go برای MCP : کتابخانه Go که برای پیادهسازی سرور MCP خود استفاده خواهیم کرد.
نکاتی برای یک آزمایشگاه کد موفق
کار با یک دستیار هوش مصنوعی روشی جدید برای توسعه نرمافزار است. در اینجا چند نکته برای ایجاد یک تجربه روان و موفق ارائه شده است:
- از زدن دکمه ESC نترسید. هوش مصنوعی گاهی اوقات اقدامات یا کدهایی را پیشنهاد میدهد که شما با آنها موافق نیستید. از کلید ESC برای لغو اقدام پیشنهادی آن استفاده کنید و یک پیام جدید برای هدایت آن در مسیر درست ارائه دهید. شما خلبان هستید.
- استفاده از ابزار را تشویق کنید. اگر به نظر میرسد هوش مصنوعی اطلاعات را گم کرده یا در حال ساخت اطلاعات است، آن را تشویق کنید که از ابزارهای موجود خود استفاده کند. عباراتی مانند «آیا میتوانید از جستجوی گوگل برای تأیید آن استفاده کنید؟» یا «قبل از ایجاد تغییرات، از ابزار read_file برای درک کد فعلی استفاده کنید» میتوانند بسیار مؤثر باشند.
- در برابر تغییرات دستی مقاومت کنید. سعی کنید تمام کارها را هوش مصنوعی انجام دهد. این مهارت اصلی است که شما در حال تمرین آن هستید. با این حال، اگر مجبور به ایجاد تغییر دستی هستید، بعداً به هوش مصنوعی در مورد آن بگویید. عبارتی مانند «من فایل README.md را به صورت دستی بهروزرسانی کردهام. لطفاً دوباره آن را بخوانید تا دانش خود را بهروز کنید» تضمین میکند که هوش مصنوعی با پروژه شما همگام میماند.
- آیا سعی کردهاید آن را خاموش و روشن کنید؟ در موارد نادری که هوش مصنوعی سعی میکند مسیر مشخصی را در برابر دستور شما اعمال کند، ممکن است به دلیل تخریب زمینه (که گاهی اوقات "پوسیدگی زمینه" نیز نامیده میشود) باشد. در این حالت میتوانید از دستور "/compress" در رابط خط فرمان Gemini برای کاهش نویز زمینه استفاده کنید یا در موارد شدید، میتوانید از دستور "/clear" برای پاک کردن کل تاریخچه جلسه استفاده کنید.
۲. تنظیمات محیطی
تنظیم محیط خودتنظیم
- وارد کنسول گوگل کلود شوید و یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید. اگر از قبل حساب جیمیل یا گوگل ورک اسپیس ندارید، باید یکی ایجاد کنید .
- نام پروژه، نام نمایشی برای شرکتکنندگان این پروژه است. این یک رشته کاراکتری است که توسط APIهای گوگل استفاده نمیشود. شما همیشه میتوانید آن را بهروزرسانی کنید.
- شناسه پروژه در تمام پروژههای گوگل کلود منحصر به فرد است و تغییرناپذیر است (پس از تنظیم، قابل تغییر نیست). کنسول کلود به طور خودکار یک رشته منحصر به فرد تولید میکند؛ معمولاً برای شما مهم نیست که چه باشد. در اکثر آزمایشگاههای کد، باید شناسه پروژه خود را (که معمولاً با عنوان
PROJECT_IDشناخته میشود) ارجاع دهید. اگر شناسه تولید شده را دوست ندارید، میتوانید یک شناسه تصادفی دیگر ایجاد کنید. به عنوان یک جایگزین، میتوانید شناسه خودتان را امتحان کنید و ببینید که آیا در دسترس است یا خیر. پس از این مرحله قابل تغییر نیست و در طول پروژه باقی میماند. - برای اطلاع شما، یک مقدار سوم، شماره پروژه ، وجود دارد که برخی از APIها از آن استفاده میکنند. برای کسب اطلاعات بیشتر در مورد هر سه این مقادیر، به مستندات مراجعه کنید.
- در مرحله بعد، برای استفاده از منابع/API های ابری، باید پرداخت صورتحساب را در کنسول ابری فعال کنید . اجرای این آزمایشگاه کد هزینه زیادی نخواهد داشت، اگر اصلاً هزینهای داشته باشد. برای خاموش کردن منابع به منظور جلوگیری از پرداخت صورتحساب پس از این آموزش، میتوانید منابعی را که ایجاد کردهاید یا پروژه را حذف کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان ۳۰۰ دلاری هستند.
شروع پوسته ابری
اگرچه میتوان از راه دور و از طریق لپتاپ، گوگل کلود را مدیریت کرد، اما در این آزمایشگاه کد، از گوگل کلود شل ، یک محیط خط فرمان که در فضای ابری اجرا میشود، استفاده خواهید کرد.
از کنسول گوگل کلود ، روی آیکون Cloud Shell در نوار ابزار بالا سمت راست کلیک کنید:
آمادهسازی و اتصال به محیط فقط چند لحظه طول میکشد. وقتی تمام شد، باید چیزی شبیه به این را ببینید:
این ماشین مجازی با تمام ابزارهای توسعهای که نیاز دارید، مجهز شده است. این ماشین مجازی یک دایرکتوری خانگی پایدار ۵ گیگابایتی ارائه میدهد و روی فضای ابری گوگل اجرا میشود که عملکرد شبکه و احراز هویت را تا حد زیادی بهبود میبخشد. تمام کارهای شما در این آزمایشگاه کد را میتوان در یک مرورگر انجام داد. نیازی به نصب چیزی ندارید.
۳. شروع کار با رابط خط فرمان Gemini
در این بخش با رابط خط فرمان Gemini، از جمله نحوه نصب و پیکربندی آن برای محیط خود، آشنا خواهید شد.
رابط خط فرمان جمینی چیست؟
رابط خط فرمان 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 در مرحله بعدی پیکربندی خواهد شد.
- ایجاد و مقداردهی اولیه یک دایرکتوری پروژه:
mkdir godoctor
cd godoctor
go mod init godoctor
- با استفاده از اعتبارنامههای پیشفرض برنامه Google Cloud، احراز هویت کنید:
ما باید به حسابی وارد شویم که به پروژه GCP که قرار است برای این آزمایشگاه کد استفاده کنید، دسترسی داشته باشد:
- مطمئن شوید که Google Cloud SDK را نصب و راهاندازی کردهاید .
- برای تنظیم اعتبارنامههای پیشفرض برنامه، دستور زیر را اجرا کنید:
gcloud auth application-default login
۴. دستورالعملهای توسعه
برای اطمینان از اینکه دستیار هوش مصنوعی، کد 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.
اکنون محیط توسعه شما کاملاً راهاندازی شده است.
۵. ساخت اولیه: یک سرور godoc
هدف اول شما ایجاد نسخه اولیه سرور godoctor است. این نسخه باید یک برنامه مینیمال و آماده برای تولید باشد که ابزاری واحد به نام godoc را ارائه میدهد که امکان جستجوی مستندات Go را فراهم میکند.
هدف: ایجاد یک سرور MCP آماده برای تولید که دستور go doc را در معرض نمایش قرار دهد و به یک LLM اجازه دهد تا مستندات Go را جستجو کند.
دستور Gemini CLI را روی shell اجرا کنید:
gemini
وقتی برای اولین بار CLI را اجرا میکنید، از شما میخواهد که یک حالت احراز هویت و یک قالب انتخاب کنید. برای حالت احراز هویت، گزینه «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" بسازد.
یک نمونه اعلان در زیر نشان داده شده است:
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.
میتوانید این دستور را امتحان کنید یا سعی کنید دستور خودتان را ابداع کنید.
یک رابط خط فرمان مفید
به محض اینکه روی یک پیادهسازی خوب به توافق رسیدید، میتوانید به مدل دستور دهید که با استفاده از یک کلاینت MCP، یک رابط خط فرمان (CLI) برای godoctor ایجاد کند. این کار با جلوگیری از نیاز به ساخت دستی فراخوانیهای 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
۶. پیکربندی 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 بتواند در فاز بعدی توسعه از آن استفاده کند.
- از 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 یا تایپ دستور
/quit از محیط خط فرمان (CLI) خارج شوید. - کامپایل فایل باینری سرور: یک دایرکتوری
binایجاد کنید و سرور godoctor را در آن کامپایل کنید.
mkdir -p bin
go build -o ./bin/godoctor ./cmd/godoctor # adjust paths as needed
- پیکربندی رابط خط فرمان Gemini برای ابزار محلی: یک فایل
.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
- شما باید بتوانید با تایپ دستور
/mcpببینید که ابزار بارگذاری شده است. همچنین میتوانید با استفاده از/mcp descتوضیحات کامل ابزارها را مشاهده کنید:
- با درخواست از Gemini CLI برای استفاده از ابزارتان با پیامی مانند «مستندات مربوط به net/http را دریافت کنید» ادغام را آزمایش کنید.
شما باید چیزی شبیه به این را ببینید:
اگر ابزار به درستی کار کند، باید مستندات بازیابی شده از طریق فراخوانی ابزار را مشاهده کنید:
تبریک میگویم، شما یک ابزار MCP ساختهاید! اما این پایان کار نیست، ما هنوز میتوانیم آن را کمی مفیدتر کنیم.
۷. افزودن یک بررسیکننده کد مبتنی بر هوش مصنوعی
بیایید یک ویژگی پیچیدهتر مبتنی بر هوش مصنوعی اضافه کنیم: یک بررسیکننده کد که از رابط برنامهنویسی Gemini استفاده میکند.
هدف: یک ابزار جدید به نام code_review به پروژه موجود اضافه کنید. این ابزار از API Gemini برای تجزیه و تحلیل کد Go و ارائه بازخورد استفاده خواهد کرد.
مثال:
I want to add a new tool to my project called code_review. This tool should use the Gemini API on Vertex AI (with gemini-2.5-flash) 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 در اختیار اوست.
آزمایش بررسیکننده کد
- جلسه چت را با
/chat save workshop002ذخیره کنید و سپس با دو بار فشردن Ctrl+D از رابط خط فرمان (CLI) خارج شوید. - ابزار
code_reviewنیاز به دسترسی به Vertex AI دارد، بنابراین ابتدا باید API را فعال کنیم:
gcloud services enable aiplatform.googleapis.com
- یک فایل
.envبا محتویات زیر ایجاد کنید. فراموش نکنید که متغیر GOOGLE_CLOUD_PROJECT را با شناسه پروژه واقعی که در ابتدای این تمرین ایجاد کردهاید و GOOGLE_CLOUD_LOCATION را با مکان مورد نظر خود (مثلاً 'us-central1') جایگزین کنید.
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='your-location'
- فایل .env را با دستور source بارگذاری کنید:
source .env
- سرور را با تعریف ابزار جدید دوباره کامپایل کنید:.
go build -o ./bin/godoctor ./cmd/godoctor
- دوباره رابط خط فرمان Gemini را اجرا کنید. جلسه چت را با استفاده از
/chat resume workshop002بازیابی کنید. - با تایپ دستور
/mcpاز فعال بودن ابزار اطمینان حاصل کنید. باید چیزی شبیه به این را ببینید:
- حالا بیایید ابزار
code-reviewرا با بررسی یکی از فایلهای منبع ابزار آزمایش کنیم:
از ابزار godoctor برای بررسی فایل cmd/godoctor/main.go استفاده کنید.
You should see something like this:
با فعال شدن ابزار بررسی کد، اکنون میتوانید به مدل پیشنهاد دهید تا برخی از بهبودهای یافتهشده را اعمال کند تا یک گردش کار کاملاً «خودبهبودی» داشته باشیم!
اکنون تأیید کردهاید که ابزار code-review کار میکند. در بخش بعدی، روی استقرار آن در فضای ابری کار خواهید کرد. جلسه فعلی خود را با /chat save workshop003 ذخیره کنید و از رابط خط فرمان (CLI) خارج شوید.
۸. سرور خود را برای فضای ابری آماده کنید
سرور MCP که تاکنون توسعه دادهایم، فقط روی دستگاه محلی اجرا میشود که اگر در حال توسعه ابزارها برای استفاده شخصی خود هستید، مشکلی ندارد، اما اغلب در محیطهای سازمانی نیاز داریم ابزارهایی را برای استفاده گستردهتر صدها یا حتی هزاران توسعهدهنده مستقر کنیم.
برای مقیاسپذیری سرور MCP خود، باید آن را از سروری که فقط ورودی/خروجی استاندارد دارد به سروری که میتواند از HTTP پشتیبانی کند تبدیل کنیم و آن را در جایی مستقر کنیم که توسط توسعهدهندگان مختلف قابل دسترسی باشد. برای این منظور، ما از یک حالت انتقال تعریف شده در مشخصات MCP به عنوان HTTP قابل پخش استفاده خواهیم کرد و از Cloud Run به عنوان هدف استقرار خود استفاده خواهیم کرد.
هدف: سرور godoctor را برای استفاده از انتقال HTTP قابل پخش، بازسازی کنید.
مثال:
The godoctor server is currently using the stdio transport. I want to deploy it to Cloud Run, so I need to refactor it to use the streamable HTTP transport instead. Please modify the server to comply with the streamable HTTP specification.
منابع مفید
- اگر مدل در پیادهسازی انتقال 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 را برای استفاده از سرور از طریق HTTP پیکربندی کنید:
- جلسه خود را ذخیره کنید و از CLI خارج شوید
- فایل
.gemini/settings.jsonخود را ویرایش کنید و پیکربندی را طوری تغییر دهید که به سرور محلی در حال اجرا اشاره کند.
"mcpServers": {
"godoctor": {
"httpUrl": "http://localhost:8080"
}
}
- سرور بازسازیشده را بهصورت محلی اجرا کنید:
go run ./cmd/godoctor/main.go
- در یک ترمینال جدید (از آنجایی که عملیات بالا مسدودکننده است)، رابط خط فرمان Gemini را اجرا کنید و به آن اعلانی برای آزمایش اتصال بدهید، مثلاً «از ابزار godoctor برای دریافت مستندات مربوط به fmt.Println استفاده کنید.»
- وقتی آزمایشتان تمام شد، سرور را با 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.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 متوقف کنید.
۱۰. استقرار در 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. Configure Cloud Run to use the environment variables in the .env file.
پس از اتمام استقرار، رابط خط فرمان 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
تمیز کردن
پس از اتمام آزمایش، به یاد داشته باشید که محیط را پاکسازی کنید. میتوانید به 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 قدرتمندتر و تخصصیتر تبدیل کردهاید.