۱. مقدمه
با AllStrides، یک پلتفرم مدیریت رویداد کامل برای جوامع تناسب اندام، آشنا شوید. با وجود ویژگیهای غنی، وضعیت فعلی آن "فقط محلی" است. این پلتفرم به یک پایگاه داده محلی SQLite و اجرای دستی Node.js متکی است. برای رشد جامعه، AllStrides به مقیاس، قابلیت اطمینان و امنیت Google Cloud نیاز دارد.
در این آزمایشگاه کد، شما یک مهاجرت سنتی انجام نخواهید داد. در عوض، شما به عنوان یک معمار محصول عمل خواهید کرد و از Gemini CLI به عنوان شریک عامل خود استفاده خواهید کرد. با تجهیز Gemini به سه سرور Google Cloud Model Context Protocol (MCP)، به هوش مصنوعی اجازه میدهید تا "به سرویس های Google Cloud دسترسی پیدا کند" و مستقیماً با آنها تعامل داشته باشد. شما با استفاده از Developer Knowledge MCP برای شناسایی بهترین پایگاه داده Google Cloud برای برنامه allstrides شروع خواهید کرد. سپس از Cloud SQL MCP برای تهیه یک نمونه پایگاه داده و انتقال دادههای جامعه محلی خود به ابر با یک اعلان واحد استفاده خواهید کرد. در نهایت، از Cloud Run MCP برای کانتینر کردن برنامه استفاده خواهید کرد و AllStrides را زنده و در دسترس جهانی قرار خواهید داد.
پیشنیازها
- درک اولیه از کنسول گوگل کلود
- مهارتهای پایه در رابط خط فرمان و Cloud Shell
آنچه یاد خواهید گرفت
- نحوهی استقرار پیکربندی Gemini CLI برای کار با MCP از راه دور
- نحوه استفاده از سرور MCP دانش توسعه
- نحوه استفاده از سرور MCP از راه دور Cloud SQL برای انتقال دادهها به ابر
- نحوه استفاده از سرور MCP از راه دور Cloud Run برای استقرار برنامه در فضای ابری
- نحوه استفاده از Gemini CLI در Google Cloud Shell
آنچه نیاز دارید
- یک حساب کاربری گوگل کلود و پروژه گوگل کلود
- یک مرورگر وب مانند کروم که از کنسول گوگل کلود و کلود شل پشتیبانی میکند
۲. تنظیمات و الزامات
راهاندازی پروژه
- وارد کنسول ابری گوگل شوید. اگر از قبل حساب جیمیل یا گوگل ورکاسپیس ندارید، باید یکی ایجاد کنید .
به جای حساب کاری یا تحصیلی از حساب شخصی استفاده کنید.
- یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید. برای ایجاد یک پروژه جدید در کنسول Google Cloud، در سربرگ، روی دکمه «انتخاب پروژه» کلیک کنید که یک پنجره بازشو باز میشود.
در پنجره انتخاب پروژه، دکمه «پروژه جدید» را فشار دهید که یک کادر محاورهای برای پروژه جدید باز میکند.
در کادر محاورهای، نام پروژه مورد نظر خود را وارد کرده و مکان را انتخاب کنید.
- نام پروژه ، نام نمایشی برای شرکتکنندگان این پروژه است. نام پروژه توسط APIهای گوگل استفاده نمیشود و میتوان آن را در هر زمانی تغییر داد.
- شناسه پروژه در تمام پروژههای گوگل کلود منحصر به فرد و غیرقابل تغییر است (پس از تنظیم، دیگر قابل تغییر نیست). کنسول گوگل کلود به طور خودکار یک شناسه منحصر به فرد تولید میکند، اما میتوانید آن را سفارشی کنید. اگر شناسه تولید شده را دوست ندارید، میتوانید یک شناسه تصادفی دیگر ایجاد کنید یا شناسه خودتان را برای بررسی در دسترس بودن آن ارائه دهید. در اکثر آزمایشگاههای کد، باید شناسه پروژه خود را که معمولاً با عبارت PROJECT_ID مشخص میشود، ارجاع دهید.
- برای اطلاع شما، یک مقدار سوم، شماره پروژه ، وجود دارد که برخی از APIها از آن استفاده میکنند. برای کسب اطلاعات بیشتر در مورد هر سه این مقادیر، به مستندات مراجعه کنید.
فعال کردن صورتحساب
یک حساب پرداخت شخصی تنظیم کنید
اگر صورتحساب را با استفاده از اعتبارهای Google Cloud تنظیم کردهاید، میتوانید از این مرحله صرف نظر کنید.
- روی این لینک کلیک کنید و با یک حساب گوگل شخصی وارد شوید.
- چیزی شبیه به این خواهید دید:
- روی دکمهی «برای دسترسی به اعتبارات خود اینجا کلیک کنید» کلیک کنید. این کار شما را به صفحهای میبرد که میتوانید پروفایل صورتحساب خود را تنظیم کنید. اگر با صفحهی ثبتنام آزمایشی رایگان مواجه شدید، روی لغو کلیک کنید و به پیوند صورتحساب ادامه دهید.
- روی تأیید کلیک کنید. اکنون به حساب پرداخت آزمایشی پلتفرم گوگل کلود متصل شدهاید.
یک حساب پرداخت شخصی تنظیم کنید
اگر صورتحساب را با استفاده از اعتبارهای Google Cloud تنظیم کردهاید، میتوانید از این مرحله صرف نظر کنید.
برای تنظیم یک حساب پرداخت شخصی، به اینجا بروید تا پرداخت را در کنسول ابری فعال کنید .
برخی نکات:
- تکمیل این آزمایشگاه باید کمتر از ۳ دلار آمریکا از طریق منابع ابری هزینه داشته باشد.
- شما میتوانید مراحل انتهای این آزمایش را برای حذف منابع دنبال کنید تا از هزینههای بیشتر جلوگیری شود.
- کاربران جدید واجد شرایط استفاده از دوره آزمایشی رایگان ۳۰۰ دلاری هستند.
شروع پوسته ابری
اگرچه میتوان از راه دور و از طریق لپتاپ، گوگل کلود را مدیریت کرد، اما در این آزمایشگاه کد، از گوگل کلود شل ، یک محیط خط فرمان که در فضای ابری اجرا میشود، استفاده خواهید کرد.
از کنسول گوگل کلود ، روی آیکون Cloud Shell در نوار ابزار بالا سمت راست کلیک کنید:
همچنین میتوانید دکمههای G و سپس S را فشار دهید. اگر در کنسول ابری گوگل باشید یا از این لینک استفاده کنید، این توالی، Cloud Shell را فعال میکند.
آمادهسازی و اتصال به محیط فقط چند لحظه طول میکشد. وقتی تمام شد، باید چیزی شبیه به این را ببینید:
این ماشین مجازی با تمام ابزارهای توسعهای که نیاز دارید، مجهز شده است. این ماشین مجازی یک دایرکتوری خانگی پایدار ۵ گیگابایتی ارائه میدهد و روی فضای ابری گوگل اجرا میشود که عملکرد شبکه و احراز هویت را تا حد زیادی بهبود میبخشد. تمام کارهای شما در این آزمایشگاه کد را میتوان در یک مرورگر انجام داد. نیازی به نصب چیزی ندارید.
۳. قبل از شروع
فعال کردن API پایه
برای استفاده از سرویسهای پایگاه داده مدیریتشده مانند Cloud SQL و سایر سرویسها برای ساخت و استقرار برنامه خود در Cloud Run، باید APIهای مربوطه را در پروژه Google Cloud خود فعال کنید.
بسته به رویکردتان، میتوانید به صورت اختیاری از این مرحله صرف نظر کنید و اجازه دهید Gemini CLI بعداً تمام APIهای مورد نیاز را فعال کند، اما در چنین حالتی ممکن است در حین اجرا با تأخیر و مراحل تکراری مواجه شوید.
در داخل ترمینال Cloud Shell، مطمئن شوید که شناسه پروژه شما تنظیم شده است:
gcloud config set project [YOUR-PROJECT-ID]
متغیر محیطی PROJECT_ID را تنظیم کنید:
PROJECT_ID=$(gcloud config get-value project)
فعال کردن تمام سرویسهای لازم:
gcloud services enable sqladmin.googleapis.com \
aiplatform.googleapis.com \
secretmanager.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
run.googleapis.com \
containerregistry.googleapis.com
خروجی مورد انتظار:
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable sqladmin.googleapis.com \
aiplatform.googleapis.com \
secretmanager.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
run.googleapis.com \
containerregistry.googleapis.com
Operation "operations/acat.p2-812263612774-c2dbeef3-c4c1-4a7d-a4b2-b5380be65044" finished successfully.
اعطای مجوز به حساب سرویس
برای اینکه بتوانید تصاویر برنامه را بسازید و ذخیره کنید، باید مجوزهای مدیریت ذخیرهسازی را به حساب کاربری پیشفرض سرویس محاسباتی ارائه دهید. مانند مرحله قبل، میتوانید بعداً در حین اجرا، این کار را به Gemini CLI واگذار کنید.
PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID --member=serviceAccount:$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")-compute@developer.gserviceaccount.com --role=roles/storage.admin
فعال کردن MCP از راه دور
سرویسهای MCP از راه دور باید به طور صریح برای هر سرویس در یک پروژه فعال شوند. آنها به طور پیشفرض غیرفعال هستند و به تنظیم دسترسی API در سطح پروژه و سرویس کمک میکنند.
بیایید با سرویس Developer Knowledge MCP شروع کنیم. برای فعال کردن API Developer Knowledge و سرویس Remote MCP، باید دستورات gcloud زیر را اجرا کنید.
PROJECT_ID=$(gcloud config get-value project)
gcloud beta services mcp enable developerknowledge.googleapis.com --project=$PROJECT_ID
وقتی API و Remote MCP برای Developer Knowledge فعال شدند، میتوانید همین کار را برای سرویس Cloud SQL Remote MCP انجام دهید.
gcloud beta services mcp enable sqladmin.googleapis.com --project=$PROJECT_ID
همانند تمام MCPهای از راه دور برای پایگاههای داده، دسترسی و مجوزهای MCP به صورت مرحلهای تنظیم شدهاند و دسترسی جزئی در سطح پروژه به خود API را فراهم میکنند و فقط یک مدیر اصلی (کاربر یا حساب کاربری سرویس) با نقش Service Usage Admin (roles/serviceusage.serviceUsageAdmin) میتواند این کار را انجام دهد.
و فقط مدیرانی که نقش MCP Tool User (roles/mcp.toolUser) را دارند میتوانند به API راه دور MCP فراخوانی انجام دهند.
برای مثال، اگر نقش Cloud SQL Admin (roles/cloudsql.admin) را نداشته باشید، نمیتوانید هیچ نمونهای را در پروژه ایجاد، کپی یا بهروزرسانی کنید.
میتوانید اطلاعات بیشتر در مورد نقشها و مجوزهای مورد نیاز را در مستندات مطالعه کنید.
همانطور که میبینیم، احراز هویت مرحلهای و جزئی، حتی زمانی که نقطه پایانی MCP از راه دور فعال است، ما را از حمله غیرمجاز محافظت میکند و آن را برای محیط عملیاتی ما به اندازه کافی ایمن میسازد.
MCP از راه دور بعدی که قصد فعال کردن آن را داریم، برای سرویس Cloud Run است. رویکرد فعالسازی و دسترسی به MCP از راه دور Cloud Run مشابه MCP از راه دور Cloud SQL است.
سرویس Cloud Run MCP را با دستور زیر فعال کنید.
gcloud beta services mcp enable run.googleapis.com --project=$PROJECT_ID
در نهایت میتوانیم با استفاده از دستور زیر، فعال بودن تمام MCPهای از راه دور در پروژه خود را تأیید کنیم.
gcloud beta services mcp list --project=$PROJECT_ID
خروجی مورد انتظار:
student@cloudshell:~ (test-project-001-402417)$ gcloud beta services mcp list --project=$PROJECT_ID NAME: services/developerknowledge.googleapis.com MCP_ENDPOINT: developerknowledge.googleapis.com NAME: services/run.googleapis.com MCP_ENDPOINT: run.googleapis.com/mcp NAME: services/sqladmin.googleapis.com MCP_ENDPOINT: sqladmin.googleapis.com/mcp
حالا که همه APIها و سرویسهای ما فعال شدهاند، باید رابط خط فرمان Gemini را پیکربندی کنیم.
۴. پیکربندی رابط خط فرمان Gemini
این آزمایشگاه به گونهای طراحی شده است که از رابط خط فرمان Gemini به عنوان عامل اصلی برای انجام اکثر اقدامات استفاده کند و اولین قدم پیکربندی آن برای کار با سرورهای MCP از راه دور است. همچنین اکیداً توصیه میشود از آخرین نسخه رابط خط فرمان Gemini و آخرین نسخه Gemini مانند Gemini-3-pro یا Gemini-3-flash (که در حال حاضر در مرحله پیشنمایش است) استفاده کنید.
اگر از قبل آخرین نسخه Gemini CLI را دارید و آن را برای استفاده از آخرین مدلهای Gemini پیکربندی کردهاید، میتوانید از دو مرحله بعدی صرف نظر کنید و مستقیماً به مرحله ۳ بروید.
۱. یک کلید API جمینی دریافت کنید
برای استفاده از جدیدترین مدلهای Gemini در رابط خط فرمان Gemini، باید آن را با احراز هویت با کلید API پیکربندی کنید. میتوانیم کلید API را از Google AI Studio دریافت کنیم.
- به Google AI Studio بروید -> کلید API را در مرورگر خود دریافت کنید .
- در سمت راست صفحه، روی دکمهی
Create API keyکلیک کنید. - در پنجره بازشو، پروژه خود را انتخاب کنید یا اگر در آنجا قابل مشاهده نیست، آن را وارد کنید
- کلید API را ایجاد کنید.
- میتوانید با استفاده از دکمه کپی در سمت راست، کلید را کپی کنید.
کلید آماده شده است و اکنون میتوانیم از آن برای Gemini CLI استفاده کنیم.
۲. پیکربندی رابط خط فرمان Gemini
رابط خط فرمان Gemini را میتوان از طریق فایل تنظیمات یا به صورت تعاملی با استفاده از دستور /settings پیکربندی کرد. ما میخواهیم تنظیمات ما در فایل تنظیمات حفظ شود.
ابتدا یک دایرکتوری برای پروژه خود ایجاد میکنیم. بیایید دایرکتوری را projectmcp بنامیم و با استفاده از دستورات زیر به آن دایرکتوری برویم.
mkdir ~/projectmcp
cd ~/projectmcp
در این دایرکتوری، یک دایرکتوری برای فایلهای پیکربندی gemini ایجاد خواهیم کرد و تمام دستورات خود را اجرا خواهیم کرد. رابط خط فرمان Gemini به طور پیشفرض از یک فایل پیکربندی محدوده کاربر و افزونههای نصب شده در دایرکتوری ~/.gemini استفاده میکند. اما ما قصد داریم پیکربندی محدوده پروژه خود را در دایرکتوری ~/projectmcp ایجاد کنیم. بیایید از ایجاد دایرکتوری و فایلهای پیکربندی شروع کنیم.
mkdir ~/projectmcp/.gemini
touch ~/projectmcp/.gemini/settings.json
سپس فایل ~/projectmcp/.gemini/settings.json را با استفاده از ویرایشگر cloud shell باز میکنیم.
edit ~/projectmcp/.gemini/settings.json
در پنجره ویرایشگر باز شده، پیکربندی زیر را اضافه کنید.
{
"general": {
"preferredEditor": "vscode",
"previewFeatures": true,
"sessionRetention": {
"enabled": true
}
},
"ide": {
"enabled": true,
"hasSeenNudge": true
},
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
},
"ui": {
"theme": "Default"
},
"tools": {
"shell": {
"enableInteractiveShell": false
}
}
}
پس از ویرایش فایل، میتوانید با استفاده از ctrl+s تغییرات خود را ذخیره کرده و با کلیک بر روی دکمهی Open Terminal به ترمینال بازگردید.
فایل settings.json بالا، نوع احراز هویت Gemini CLI شما را به صورت gemini-api-key تنظیم میکند و شما باید کلید را به مدل ارائه دهید. میتوانید این کار را با ایجاد یک فایل .env در دایرکتوری که میخواهید با Gemini CLI کار کنید، انجام دهید و کلید API خود را برای احراز هویت Gemini CLI به عنوان یک متغیر محیطی ذخیره کنید که هنگام شروع IDE دریافت میشود.
بیایید فایل را با استفاده از ویرایشگر Cloud Shell ویرایش کنیم
edit ~/projectmcp/.env
و کلید API خود را که در مرحله 1 ایجاد کردهاید، ذخیره کنید.
GEMINI_API_KEY= <YOUR_API_KEY>
حالا میتوانید به ترمینال برگردید و ادامه دهید. مرحله بعدی بهروزرسانی Gemini CLI به آخرین نسخه است. نسخه موجود در Google Cloud Shell یا در محیط شما میتواند قدیمی باشد و با آخرین پیکربندیها و سرویسهای MCP به درستی کار نکند. بنابراین مهم است که Gemini CLI را به آخرین نسخه بهروزرسانی کرده و آن را راهاندازی کنید. در ترمینال، دستور زیر را اجرا کنید.
cd ~/projectmcp/
npm install -g @google/gemini-cli@latest
اکنون میتوانید نسخه را تأیید کنید. لطفاً در نظر داشته باشید که اگر در پوسته ابری گوگل (Google Cloud Shell) کار میکنید، هر بار که پوسته را مجدداً راهاندازی میکنید، ممکن است به نسخه قبلی بازگردد. تغییراتی که در خود رابط خط فرمان Gemini ایجاد میکنید، در پوسته ابری دائمی نیستند.
gemini --version
باید آخرین نسخه Gemini CLI (نسخه 0.27 در زمان نوشتن آزمایشگاه) را نشان دهد. میتوانید آخرین نسخه Gemini CLI را اینجا تأیید کنید. و اکنون میتوانیم آن را اجرا کنیم و مطمئن شویم که از آخرین مدل Gemini استفاده میکند. دستور زیر را در پوشه پروژه خود اجرا کنید تا Gemini CLI شروع به کار کند.
gemini
و وقتی رابط خط فرمان Gemini شروع به کار کرد، میتوانید با اجرای دستور /about در رابط، نسخه و مدل را بررسی کنید. باید چیزی شبیه به تصویر زیر دریافت کنید.
میتوانید ببینید که از آخرین مدل جمینی-۳ استفاده میکند.
۲. پیکربندی سرورهای MCP در رابط خط فرمان Gemini
حالا وقت آن رسیده که تمام سرورهای MCP فعالشدهمان را اضافه کنیم. شما دو راه برای فعال کردن آنها در Gemini CLI دارید - از طریق افزونهها یا مستقیماً در تنظیمات. در این تمرین، از فایل setting.json مربوط به محدوده پروژه خود استفاده خواهید کرد و جزئیات احراز هویت سرورهای MCP را در آنجا اضافه خواهید کرد.
- برای سرور MCP مربوط به Developer Knowledge، باید یک کلید API ایجاد کنید تا در نقطه پایانی مجاز شود.
مراحل به شرح زیر است:
- در کنسول گوگل کلود مربوط به پروژهای که API را در آن فعال کردهاید، به صفحه اعتبارنامهها (Credentials) بروید.
- روی ایجاد اعتبارنامه کلیک کنید و سپس کلید API را از منو انتخاب کنید. کادر محاورهای ایجاد کلید API، رشته مربوط به کلید تازه ایجاد شده شما را نمایش میدهد.
- روی پیوند
Edit API keyدر کادر محاورهای کلیک کنید. - در فیلد
Name، یک نام برای کلید وارد کنید. برای مثالDK API Key. - در زیر محدودیتهای API،
Restrict keyانتخاب کنید. - از لیست Select APIs، گزینه
Developer Knowledge APIرا فعال کرده و روی OK کلیک کنید. - روی ذخیره کلیک کنید.
حالا اگر نیاز به استفاده از کلید دارید، میتوانید به صفحه بروید و روی نمایش کلید در سمت راست کلیک کنید.
حالا باید آن کلید را در پیکربندی ذخیره کنید. بخش MCP در فایل settings.json ما به این شکل خواهد بود (باید مقداری برای کلید DK API خود در آنجا قرار دهید). در اینجا مثالی از بخش MCP در فایل settings.json در صورتی که فقط DK API اضافه شود، آورده شده است. بعداً در تمرین، خواهید دید که فایل settings.json با وجود همه سرورهای MCP چگونه باید به نظر برسد.
"mcpServers": {
"DeveloperKnowledge": {
"httpUrl": "https://developerknowledge.googleapis.com/mcp",
"headers": {
"X-Goog-Api-Key": "<Your DK API Key>"
}
}
},
- در مرحله بعد، میتوانید پیکربندی سرور Cloud SQL MCP ما را اضافه کنید. برای Cloud SQL MCP، به جای API از اعتبارنامههای گوگل خود استفاده خواهید کرد. این روش امنتر است و به ما امکان میدهد نقشها و دامنه اقدامات مجاز برای یک کاربر را تعریف کنیم. در اینجا پیکربندی سرور MCP آمده است. لطفاً "<YOUR_GCP_PROJECT>" را با شناسه پروژه خود جایگزین کنید.
"Cloud SQL MCP Server": {
"httpUrl": "https://sqladmin.googleapis.com/mcp",
"authProviderType": "google_credentials",
"oauth": {
"scopes": [
"https://www.googleapis.com/auth/cloud-platform"
]
},
"timeout": 500000,
"trust": false,
"headers": {
"X-Goog-User-Project": "<YOUR_GCP_PROJECT>"
}
},
- این بخش بعدی از فایل json شامل پیکربندی مربوط به سرور Cloud Run MCP است. این بخش از الگوی مشابه مثال بالا پیروی میکند و از اعتبارنامههای گوگل برای احراز هویت و مجوز استفاده میکند. در اینجا نمونه پیکربندی آمده است.
"CloudRun": {
"httpUrl": "https://run.googleapis.com/mcp",
"authProviderType": "google_credentials",
"oauth": {
"scopes": [
"https://www.googleapis.com/auth/cloud-platform"
]
}
}
همه این موارد باید به فایل ~/projectmcp/.gemini/settings.json اضافه شوند.
فایل ~/projectmcp/.gemini/settings.json را با استفاده از ویرایشگر cloud shell باز کنید.
edit ~/projectmcp/.gemini/settings.json
و محتویات را با پیکربندی زیر جایگزین کنید. لطفاً کلید API و شناسه پروژه خود را مطابق با محیط خود در فیلدهای "X-Goog-Api-Key" و "X-Goog-User-Project" قرار دهید .
{
"general": {
"preferredEditor": "vscode",
"previewFeatures": true,
"sessionRetention": {
"enabled": true
}
},
"ide": {
"enabled": true,
"hasSeenNudge": true
},
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
},
"mcpServers": {
"DeveloperKnowledge": {
"httpUrl": "https://developerknowledge.googleapis.com/mcp",
"headers": {
"X-Goog-Api-Key": "<Your DK API Key>"
}
},
"Cloud SQL MCP Server": {
"httpUrl": "https://sqladmin.googleapis.com/mcp",
"authProviderType": "google_credentials",
"oauth": {
"scopes": [
"https://www.googleapis.com/auth/cloud-platform"
]
},
"timeout": 500000,
"trust": false,
"headers": {
"X-Goog-User-Project": "<YOUR_GCP_PROJECT>"
}
},
"CloudRun": {
"httpUrl": "https://run.googleapis.com/mcp",
"authProviderType": "google_credentials",
"oauth": {
"scopes": [
"https://www.googleapis.com/auth/cloud-platform"
]
}
}
},
"ui": {
"theme": "Default"
},
"tools": {
"shell": {
"enableInteractiveShell": false
}
}
}
اکنون میتوانیم رابط خط فرمان Gemini را اجرا کنیم و تمام سرورهای MCP فعالشده را در آنجا ببینیم.
cd ~/projectmcp/
gemini
وقتی رابط خط فرمان Gemini شروع به کار کرد، میتوانید دستور /mcp را اجرا کنید تا تمام سرورهای MCP فعال و در حال اجرا را مشاهده کنید.
۵. آمادهسازی درخواست
در مثال زیر، شما سعی خواهید کرد برنامه محلی نمونه خود را به Google Cloud منتقل کنید. ابتدا برنامه را به صورت محلی نصب کرده و آن را آزمایش میکنیم.
۱. کپی کردن کد منبع
ما باید برنامه خود را از مخزن GitHub کپی کنیم. آن را در Cloud Shell یا ترمینال محلی خود در پوشه پروژه اجرا کنید.
git clone https://github.com/google/mcp.git
۲. اجرای برنامه به صورت محلی
بیایید برنامه را آزمایش کنیم و برخی از دادههای نمونه را بارگذاری کنیم
در همان پوسته، به پوشه برنامه بروید و برنامه را با استفاده از دستور زیر اجرا کنید.
cd mcp/examples/allstrides
./start_allstrides.sh
۳. برنامه را آزمایش کنید
اگر در Cloud Shell کار میکنید، دکمه Web preview را در بالای پنجره cloud shell فشار دهید و Preview on port 8080 انتخاب کنید.
یک تب مرورگر جدید با رابط کاربری برنامه باز میشود که در آن میتوانید، برای مثال، روی دکمه Events کلیک کنید.
در حال حاضر شما هیچ رویدادی ندارید.
۴. بارگذاری دادههای نمونه
شما میتوانید به صورت اختیاری در برنامه ثبتنام کنید و رویدادها، پیامهای چت و کاربران خود را ایجاد کنید یا میتوانید از دادههای نمونه ارائه شده همراه با برنامه استفاده کنید.
با استفاده از علامت "+" در بالا، یک تب Cloud Shell دیگر باز کنید.
در تب جدید cloud shell، به دایرکتوری برنامه بروید و با استفاده از ابزار sqllite3، دستور import را اجرا کنید:
cd ~/projectmcp/mcp/examples/allstrides
sqlite3 allstrides.db < seed_data.sql
اگر دوباره به صفحه برنامه برگردید، پس از کلیک روی دکمه رویدادها، باید چندین رویداد را ببینید.
همچنین میتوانید صفحه چت را امتحان کنید و برخی از پیامها را در آنجا ببینید.
حالا میتوانید با تایپ کردن exit تب دوم را ببندید.
exit
و با استفاده از ترکیب ctrl+c، برنامه را در تب اول متوقف کنید.
6. آزمایش دانش توسعهدهنده MCP
MCP دانش توسعهدهندگان به ما این امکان را میدهد که مستقیماً از ابزارهای مستقل خود از اسناد گوگل استفاده کنیم و امکان تأیید دستورالعملها، ایجاد آموزشها و سایر کارهایی را که میتوان با جدیدترین اسناد گوگل تکمیل کرد، فراهم کنیم.
رابط خط فرمان Gemini خود را اجرا کنید و ابزارهای MCP موجود را در سرور MCP دانش توسعهدهندگان فهرست کنید.
/mcp
برای MCP دانش توسعهدهنده، باید سه ابزار موجود را ببینید:
خروجی مورد انتظار:
🟢 DeveloperKnowledge - Ready (3 tools) Tools: - batch_get_documents - get_document - search_documents
وظیفه ما انتقال برنامه به فضای ابری گوگل است و این به این معنی است که باید از پایگاه داده محلی Sqlite به یک راهکار مقیاسپذیرتر و بومی فضای ابری مهاجرت کنیم. بیایید از Gemini بخواهیم کد برنامه ما را تجزیه و تحلیل کند و در مورد راهکار پایگاه داده به ما مشاوره دهد.
در خط فرمان Gemini CLI موارد زیر را تایپ کنید:
Hello, I need to choose a database platform for my allstrides application in Google Cloud. Can you analyze documentation and prepare a tutorial to choose the correct database engine?
رابط خط فرمان Gemini کار خود را با تجزیه و تحلیل کد شما آغاز میکند و سپس از شما میخواهد که آن را اجرا کنید.
خروجی مورد انتظار
? search_documents (DeveloperKnowledge MCP Server) {"query":"choose google cloud database"} ← │
│ │
│ MCP Server: DeveloperKnowledge │
│ Tool: search_documents │
│ │
│ Allow execution of MCP tool "search_documents" from server "DeveloperKnowledge"? │
│ │
│ ● 1. Allow once │
│ 2. Allow tool for this session │
│ 3. Allow all server tools for this session │
│ 4. No, suggest changes (esc)
میتوانیم ببینیم که این ابزار از MCP برای پایهگذاری پاسخ توسط مستندات گوگل استفاده میکند. اجازه اجرای درخواست MCP دانش توسعهدهنده را بدهید. ممکن است قبل از ارائه پاسخ، یک یا دو بار دیگر از شما بخواهد تا اطلاعات بیشتری کسب کند. در حال حاضر هیچ تغییری در برنامه خود ایجاد نکنید.
در پایان، یک آموزش با خلاصهای ایجاد کرده است که در آن Cloud SQL برای Postgres به عنوان بهترین انتخاب برای backend پایگاه داده تعریف شده است. ممکن است به دلیل ماهیت غیرقطعی مدلهای Generative AI، پاسخ کمی متفاوت دریافت کنید.
خروجی مورد انتظار:
By switching to Cloud SQL for PostgreSQL, AllStrides gains a robust, scalable foundation suitable for production deployment on Google Cloud. The transition is straightforward due to the use of Sequelize ORM.
همچنین میتوانیم درخواست کنیم که یک راهنمای گام به گام برای مهاجرت دادهها تهیه کنیم. یک اعلان جدید به رابط خط فرمان Gemini وارد کنید:
I agree with the recommendation to use Cloud SQL for PostgreSQL as the new database for my application. Can you prepare a detailed migration tutorial based on Google documentation on how to move data from my local database to Cloud SQL in the cloud?
و در اینجا دوباره انتظار داریم که Gemini CLI هنگام تهیه آموزش از Developer Knowledge MCP به عنوان منبع حقیقت استفاده کند. توالی اقدامات انجام شده توسط Gemini CLI بسته به مدل دقیق و سایر عوامل میتواند کمی متفاوت باشد. به عنوان مثال، میتواند ابتدا درخواست کند که اسکریپتهای مهاجرت آماده شوند و تنها پس از آن روی مستندات نهایی آموزش کار شود.
در اینجا یکی از مثالهایی که در آن برای اجرای MCP دانش توسعهدهندگان درخواست مجوز میکند، آورده شده است:
? search_documents (DeveloperKnowledge MCP Server) {"query":"migrate local database to Cloud SQL for PostgreSQL"} ← │
│ │
│ MCP Server: DeveloperKnowledge │
│ Tool: search_documents │
│ │
│ Allow execution of MCP tool "search_documents" from server "DeveloperKnowledge"? │
│ │
│ ● 1. Allow once │
│ 2. Allow tool for this session │
│ 3. Allow all server tools for this session │
│ 4. No, suggest changes (esc) │
│ │
│ │
│ ⊷ search_documents (DeveloperKnowledge MCP Server) {"query":"import data into Cloud SQL PostgreSQL"}
در طول اجرا، رابط خط فرمان Gemini ممکن است از شما بخواهد برخی دستورات را اجرا کنید. به عنوان مثال، برای درک بهتر طرح دادهها و تهیه دستورالعملهای صحیح برای مهاجرت دادهها.
و در پایان باید یک دستورالعمل گام به گام برای مهاجرت دادهها تهیه کند.
سپس میتوانید از Gemini CLI بخواهید که آموزش را بنویسد.
Please write the tutorial down
و یک فایل نشانهگذاری جدید با سند آموزشی ایجاد میکند.
خروجی مورد انتظار:
✦ I have created a detailed migration guide for you. You can find the tutorial in the new file: MIGRATION_GUIDE.md. This guide covers: 1. Exporting your local SQLite data to CSV format. 2. Creating the PostgreSQL schema with compatible data types. 3. Uploading data to Google Cloud Storage. 4. Importing data into Cloud SQL in the correct order to respect relationships. 5. Resetting ID sequences to ensure new data can be added without errors.
در مرحله بعدی، ما با Cloud SQL MCP کار خواهیم کرد و پایگاه داده خود را آماده کرده و دادهها را منتقل خواهیم کرد.
۷. آزمایش Cloud SQL Remote MCP
۱. ایجاد نمونهی Cloud SQL
میتوانید با تایپ کردن /mcp در رابط خط فرمان Gemini، ابزارهای موجود در سرور Cloud SQL MCP را بررسی کنید.
/mcp
در حال حاضر ابزارهای زیر برای ما در دسترس است.
خروجی مورد انتظار:
🟢 Cloud SQL MCP Server - Ready (11 tools) Tools: - clone_instance - create_instance - create_user - execute_sql - get_instance - get_operation - import_data - list_instances - list_users - update_instance - update_user
ما قبلاً تصمیم گرفتهایم که از Cloud SQL برای Postgres به عنوان backend برای برنامه خود در Google Cloud استفاده کنیم. اکنون میتوانیم از Gemini بخواهیم که یک نمونه Cloud SQL برای ما ایجاد کند.
در خط فرمان Gemini CLI درخواست خود را مانند زیر تایپ کنید:
Please create a Cloud SQL for Postgres instance with appropriate edition and version in the us-central1 region to be a backend for our application with a public IPs in the current project with 2 CPU and 8 GB memory.
برای جلوگیری از فراخوانیهای اضافی برای شناسایی پروژه فعلی خود، میتوانید هنگام وارد کردن اعلان، شناسه پروژه خود را به طور صریح مشخص کنید. اگر نام پروژه در متن قبلی استفاده نشده باشد، مدل یا شناسه پروژه را میپرسد یا از شما میخواهد دستور gcloud را برای شناسایی پروژه اجرا کنید.
سپس ابزارهای موجود را تجزیه و تحلیل کرده و از شما درخواست اجرای ابزارهای Cloud SQL MCP را میکند. باید انتظار داشته باشید که درخواست تأیید زیر را مشاهده کنید.
? create_instance (Cloud SQL MCP Server MCP Server) {"tier":"db-custom-2-8192","region":"us-central1","project":"gleb-test-short-001-486416","databaseVersion":"POSTGRES_17","edition":"ENTERPRISE","nam... ← │
│ │
│ MCP Server: Cloud SQL MCP Server │
│ Tool: create_instance │
│ │
│ Allow execution of MCP tool "create_instance" from server "Cloud SQL MCP Server"? │
│ │
│ ● 1. Allow once │
│ 2. Allow tool for this session │
│ 3. Allow all server tools for this session │
│ 4. No, suggest changes (esc)
پس از شروع اجرا، از شما خواسته میشود که وضعیت عملیات و درخواستهای احتمالی خواب (sleep) را بین بررسیها رصد کنید. چیزی شبیه به کد زیر.
✦ I will wait for 30 seconds before checking the status of the instance creation. ╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ⊶ Shell sleep 30 [current working directory /home/gleb/demo] │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ⠋ Refining Instance Configuration (esc to cancel, 11s)
پس از آن، یک ابزار get_operation برای Cloud SQL Server MCP ارائه میشود.
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ? get_operation (Cloud SQL MCP Server MCP Server) {"project":"gleb-test-short-001-486416","operation":"73c39ca7-65fe-46d1-bdb8-0dfa00000032"} ← │
│ │
│ MCP Server: Cloud SQL MCP Server │
│ Tool: get_operation │
│ │
│ Allow execution of MCP tool "get_operation" from server "Cloud SQL MCP Server"? │
│ │
│ ● 1. Allow once
پس از درخواست نهایی get_instance، باید اطلاعاتی در مورد نمونه ایجاد شده دریافت کنید. چیزی شبیه به موارد زیر.
خروجی مورد انتظار:
✦ I will wait for 30 seconds before checking the status of the instance creation. ╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ⊶ Shell sleep 30 [current working directory /home/gleb/demo] │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ⠋ Refining Instance Configuration (esc to cancel, 11s)
پس از آن، ابزار get_operation برای Cloud SQL Server MCP و فراخوانی ابزار get_insance MCP اجرا میشود. ممکن است بررسیها و فراخوانیهای بیشتری توسط Gemini CLI برای تأیید تکمیل موفقیتآمیز وظیفه انجام شود.
The Cloud SQL for Postgres instance allstrides-db has been successfully created in the us-central1 region with 2 vCPUs and 8 GB of RAM. Instance Details: - Project ID: gleb-test-short-001-486416 - Instance Name: allstrides-db - Public IP Address: 35.226.187.246 - Database Version: POSTGRES_17 - Machine Type: db-custom-2-8192 (2 vCPU, 8 GB RAM) - Region: us-central1 - Connection Name: gleb-test-short-001-486416:us-central1:allstrides-db The instance is configured with public IP enabled, IAM authentication turned on, and Data API access allowed.
۲. انتقال دادهها
نمونه آماده است و اکنون میتوانیم انتقال تمام دادههای خود را از پایگاه داده SQLite موجود به یک پایگاه داده جدید در فضای ابری ادامه دهیم.
در خط فرمان Gemini CLI درخواست زیر را تایپ کنید
Now when we have our Cloud SQL instance ready it is time to move the data from our local database. Please migrate all the data to a new database in our Cloud SQL instance where the new user for application would be the database owner? Let's call the new database allstrides-db and the user allstrides. Please use our MCP tools whenever it is possible.
در طول اجرا، رابط خط فرمان Gemini مدل داده ما را تجزیه و تحلیل میکند و برای انجام این کار، مجوزهایی برای اجرای برخی دستورات درخواست میکند. گردش کار ۱۰۰٪ قطعی نیست و برخی مراحل میتوانند متفاوت باشند.
در اینجا مثالی از نحوه شروع آن آورده شده است.
خروجی مورد انتظار:
✦ I will read the allstrides/README.md and allstrides/seed_data.sql files to understand the local database structure and data. ╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ ReadFile allstrides/README.md │ │ │ │ │ │ ✓ ReadFile allstrides/seed_data.sql │ │ │ ╰─────────────────────────────────────────────────────────────────────────
سپس پس از طی چندین مرحله، از Cloud SQL MCP برای آمادهسازی پایگاه داده، کاربر و در نهایت انتقال دادهها استفاده میکند. یکی از اولین اقداماتی که روی پایگاه داده انجام میدهد، اضافه کردن شما به عنوان کاربر IAM و اعطای مجوزهای لازم برای ایجاد پایگاه داده و کاربر است. شما باید در Google Cloud به عنوان IAM از امتیازات کافی برخوردار باشید.
در اینجا مثالی از برخی مراحل در طول گردش کار آورده شده است
خروجی مورد انتظار:
✓ execute_sql (Cloud SQL MCP Server MCP Server) {"project":"gleb-test-short-001-486416","instance":"allstrides-db","sqlStatement":"CREATE DATABASE \"allstrides-db\";","database":"postgres"} │
│ │
│ { │
│ "messages": [ │
│ { │
│ "message": "Execution complete. 1 result set(s) returned.", │
│ "severity": "INFO" │
│ } │
│ ], │
│ "metadata": { │
│ "sqlStatementExecutionTime": "0.075591388s" │
│ }, │
│ "results": [ │
│ {} │
│ ] │
│ } │
│
۳. استقرار برنامه در Cloud Run
اکنون، پایگاه داده ایجاد شده و دادههای برنامه محلی به پایگاه داده CloudSQL شما منتقل شدهاند. اکنون آمادهاید تا برنامه خود را در Cloud Run مستقر کنید. در طول استقرار، از ترکیبی از Google Cloud SDK برای ساخت تصویر در Google cloud استفاده خواهید کرد و سپس آن را با استفاده از Cloud Run MCP مستقر خواهید کرد.
در Gemini CLI، دستور زیر را اجرا کنید.
Now, when all the data is successfully migrated to our Cloud SQL instance allstrides-db we can migrate our allstrides application to Cloud Run and deploy using my Cloud SQL database. Please put the username and the password for my database user user to Secret Manager to not show openly in Cloud Run.
Let's build the image first and then use MCP to create the Cloud Run service.
در حین اجرا، APIها بررسی میشوند، دادهها برای مدیریت رمز آماده میشوند و رمزهای مورد نیاز ایجاد میشوند. همچنین، برنامه برای کار با پایگاه داده PostgreSQL بهروزرسانی شده و ماژولهای npm لازم اضافه میشوند.
سپس پس از ساخت تصویر و قرار دادن آن در رجیستری مصنوعات، از سرویس MCP برای استقرار برنامه در Cloud Run استفاده میکند.
در اینجا مثالی از فراخوانی Cloud Run MCP آورده شده است.
خروجی مورد انتظار:
✦ I will deploy the 'allstrides' service to Cloud Run using the deploy_service_from_image tool. I will configure the environment variables and map the
database credentials from Secret Manager. Note that the MCP tool's schema does not explicitly expose the Cloud SQL instance attachment parameter, which is
typically required for the Unix socket connection (/cloudsql/...) to work. I will proceed with the deployment as requested, but if the database connection
fails due to the missing instance attachment, we may need to use gcloud to update that specific configuration.
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Action Required 1 of 1 │
│ │
│ ? deploy_service_from_image (CloudRun MCP Server) {"service":{"invokerIamDisabled":true,"name":"projects/gleb-test-short-001-486416/locations/us-centra... │
│ │
│ MCP Server: CloudRun │
│ Tool: deploy_service_from_image │
│ Allow execution of MCP tool "deploy_service_from_image" from server "CloudRun"? │
│ │
│ ● 1. Allow once │
│ 2. Allow tool for this session │
│ 3. Allow all server tools for this session │
│ 4. No, suggest changes (esc) │
│ │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
مسیر دقیق برای تکمیل تمام عملیات میتواند از اجرایی به اجرای دیگر متفاوت باشد. عاملهای هوش مصنوعی مسیر را بر اساس زمینه، خروجی دستور و چندین متغیر دیگر انتخاب میکنند. و در اینجا قدرت نرمافزار عامل هوش مصنوعی نهفته است - میتواند واکنش نشان دهد، رویکرد خود را تنظیم کند و مراحل را برای تکمیل وظایف و ارائه نتایج موفقیتآمیز دوباره امتحان کند.
اکنون باید برنامه allstrides خود را در Cloud Run مستقر و اجرا کرده و به پایگاه داده Cloud SQL خود متصل کرده باشید.
این چیزی است که ممکن است در پایان بتوانید ببینید.
خروجی مورد انتظار:
✦ The application allstrides has been successfully migrated to Cloud Run and is connected to the Cloud SQL database allstrides-db.
Deployment Details:
* Service URL: https://allstrides-812263612774.us-central1.run.app
* Database: allstrides-db (PostgreSQL)
* Database User: allstrides (Password updated and stored in Secret Manager)
* Secrets: db-user and db-pass are mounted as environment variables.
* Region: us-central1
Steps Taken:
1. Database Configuration:
* Updated the allstrides database user password.
* Created db-user and db-pass secrets in Google Cloud Secret Manager.
* Updated database.ts to support PostgreSQL connections via Cloud SQL socket.
2. Build:
* Built the container image gcr.io/gleb-test-short-001-486416/allstrides using Cloud Build.
3. Deployment:
* Initiated deployment using the MCP deploy_service_from_image tool.
* Granted the Secret Manager Secret Accessor role to the Cloud Run service account.
* Attached the Cloud SQL instance connection using gcloud (as the MCP tool currently lacks this specific configuration parameter).
The application is now serving traffic and successfully connected to the database.
و وقتی آدرس اینترنتی ارائه شده را در مرورگر باز میکنید، باید صفحه برنامه را ببینید.
و تمام رویدادهای ما باید در آنجا قابل مشاهده باشند
تبریک! شما توانستید از Gemini CLI و سرویسهای Remote MCP گوگل کلود برای انتقال برنامه محلی خود به فضای ابری استفاده کنید. به این ترتیب، استقرار به پایان رسیده و تمام منابع میتوانند پاکسازی شوند.
۸. محیط را تمیز کنید
سادهترین راه برای پاکسازی محیط این است که از رابط خط فرمان Gemini بخواهید تمام اجزایی را که ایجاد کردهاید حذف کند. این کار باید تمام داراییها را در متن نگه دارد. اما اگر به نحوی از سیستم خارج شدهاید و هیچ سابقه ذخیرهشدهای ندارید، میتوانید دقیقتر باشید و درخواست پاکسازی سرویس Cloud Run، تصویر و نمونه Cloud SQL را بدهید. برای حذف سرویس، باید توسط کاربری که مجوزهای لازم را دارد و از دستور gcloud استفاده میکند، احراز هویت شود.
در اینجا مثالی از یک اعلان آمده است
Now, when we've tested the application can you please delete the created Cloud Run service, the image we've built and the Cloud SQL instance we've created in the project.
پس از حذف، میتوانید از سرویسهای MCP از راه دور برای تأیید حذف موفقیتآمیز سرویس Cloud Run یا نمونه Cloud SQL استفاده کنید.
Can you please list all Cloud SQL instances in the project and Cloud Run services in the project.
در پایان باید پیامی مانند پیام زیر را ببینید:
خروجی مورد انتظار:
✦ There are currently no Cloud SQL instances or Cloud Run services (in us-central1) in the project gleb-test-short-001-486416.
بدین ترتیب مراحل آزمایشگاه به پایان میرسد.
۹. تبریک
تبریک میگویم که آزمایشگاه کد را تمام کردی.
مسیر یادگیری فضای ابری گوگل
آنچه ما پوشش دادهایم
- نحوهی استقرار و پیکربندی Gemini CLI برای کار با MCP های از راه دور Google Cloud
- نحوه استفاده از Development KnowledgeMCP
- نحوه استفاده از Cloud SQL MCP برای انتقال دادهها به فضای ابری
- نحوه استفاده از Cloud Run MCP برای استقرار برنامه در فضای ابری
- نحوه استفاده از رابط خط فرمان Gemini در پوسته ابری گوگل
۱۰. نظرسنجی
خروجی: