1. مقدمه
نمای کلی
در این آزمایشگاه، شما یک سرور پروتکل زمینه مدل (MCP) ساخته و استقرار خواهید داد. سرورهای MCP برای دسترسی LLMها به ابزارها و خدمات خارجی مفید هستند. شما آن را به عنوان یک سرویس امن و آماده برای تولید در Cloud Run پیکربندی خواهید کرد که از چندین مشتری قابل دسترسی است. سپس به سرور MCP راه دور از Gemini CLI متصل خواهید شد.
کاری که خواهی کرد
ما از FastMCP برای ایجاد یک سرور MCP باغ وحش استفاده خواهیم کرد که دارای دو ابزار است: get_animals_by_species
و get_animal_details
. FastMCP یک راه سریع و پایتونیک برای ساخت سرورها و کلاینت های MCP ارائه می دهد.
چیزی که یاد خواهید گرفت
- سرور MCP را در Cloud Run مستقر کنید.
- با نیاز به احراز هویت برای همه درخواستها، نقطه پایانی سرور خود را ایمن کنید و اطمینان حاصل کنید که فقط مشتریان و نمایندگان مجاز میتوانند با آن ارتباط برقرار کنند.
- از Gemini CLI به نقطه پایانی سرور MCP امن خود متصل شوید
2. راه اندازی پروژه
- اگر قبلاً یک حساب Google ندارید، باید یک حساب Google ایجاد کنید .
- از حساب شخصی به جای حساب کاری یا مدرسه استفاده کنید. حسابهای محل کار و مدرسه ممکن است محدودیتهایی داشته باشند که شما را از فعال کردن APIهای مورد نیاز برای این آزمایشگاه باز میدارد.
- به Google Cloud Console وارد شوید.
- صورتحساب را در کنسول Cloud فعال کنید .
- تکمیل این آزمایشگاه باید کمتر از 1 دلار آمریکا در منابع Cloud هزینه داشته باشد.
- برای جلوگیری از هزینه های بیشتر، می توانید مراحل انتهای این آزمایشگاه را برای حذف منابع دنبال کنید.
- کاربران جدید واجد شرایط استفاده از نسخه آزمایشی رایگان 300 دلاری هستند.
- یک پروژه جدید ایجاد کنید یا استفاده مجدد از یک پروژه موجود را انتخاب کنید.
3. Cloud Shell Editor را باز کنید
- برای رفتن مستقیم به Cloud Shell Editor روی این پیوند کلیک کنید
- اگر امروز در هر نقطهای از شما خواسته شد مجوز دهید، برای ادامه روی تأیید کلیک کنید.
- اگر ترمینال در پایین صفحه ظاهر نشد، آن را باز کنید:
- روی View کلیک کنید
- روی ترمینال کلیک کنید
- در ترمینال، پروژه خود را با این دستور تنظیم کنید:
- قالب:
gcloud config set project [PROJECT_ID]
- مثال:
gcloud config set project lab-project-id-example
- اگر نمی توانید شناسه پروژه خود را به خاطر بسپارید:
- می توانید تمام شناسه های پروژه خود را با موارد زیر فهرست کنید:
gcloud projects list | awk '/PROJECT_ID/{print $2}'
- می توانید تمام شناسه های پروژه خود را با موارد زیر فهرست کنید:
- قالب:
- شما باید این پیام را ببینید:
اگر یکUpdated property [core/project].
WARNING
مشاهده کردید و ازDo you want to continue (Y/n)?
، پس احتمالاً شناسه پروژه را اشتباه وارد کرده اید.n
را فشار دهید،Enter
را فشار دهید و دوباره دستورgcloud config set project
اجرا کنید.
4. API ها را فعال کنید
در ترمینال، API ها را فعال کنید:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
اگر از شما خواسته شد که مجوز دهید، برای ادامه روی تأیید کلیک کنید.
تکمیل این دستور ممکن است چند دقیقه طول بکشد، اما در نهایت باید یک پیام موفقیت آمیز مشابه این پیام تولید کند:
Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.
5. پروژه پایتون خود را آماده کنید
- پوشه ای به نام
mcp-on-cloudrun
برای ذخیره کد منبع برای استقرار ایجاد کنید:mkdir mcp-on-cloudrun && cd mcp-on-cloudrun
- یک پروژه پایتون با ابزار
uv
ایجاد کنید تا یک فایلpyproject.toml
ایجاد کنید: دستورuv init --description "Example of deploying an MCP server on Cloud Run" --bare --python 3.13
uv init
یک فایلpyproject.toml
برای پروژه شما ایجاد می کند. برای مشاهده محتویات فایل موارد زیر را اجرا کنید: خروجی باید به شکل زیر باشد:cat pyproject.toml
[project] name = "mcp-on-cloudrun" version = "0.1.0" description = "Example of deploying an MCP server on Cloud Run" requires-python = ">=3.13" dependencies = []
6. سرور zoo MCP را ایجاد کنید
برای ارائه زمینه ارزشمند برای بهبود استفاده از LLM با MCP، یک سرور MCP باغ وحش با FastMCP راه اندازی کنید - یک چارچوب استاندارد برای کار با پروتکل بافت مدل. FastMCP راهی سریع برای ساخت سرورها و کلاینت های MCP با پایتون فراهم می کند. این سرور MCP داده هایی در مورد حیوانات در یک باغ وحش خیالی ارائه می دهد. برای سادگی، داده ها را در حافظه ذخیره می کنیم. برای یک سرور MCP تولیدی، احتمالاً می خواهید داده ها را از منابعی مانند پایگاه های داده یا API ارائه کنید.
- دستور زیر را برای اضافه کردن FastMCP به عنوان یک وابستگی در فایل
pyproject.toml
اجرا کنید: با این کار یک فایلuv add fastmcp==2.11.1 --no-sync
uv.lock
به پروژه شما اضافه می شود. - یک فایل
server.py
جدید برای کد منبع سرور MCP ایجاد و باز کنید: دستورcloudshell edit server.py
cloudshell edit
فایلserver.py
را در ویرایشگر بالای ترمینال باز می کند. - کد منبع سرور MCP باغ وحش زیر را در فایل
server.py
اضافه کنید:import asyncio import logging import os from typing import List, Dict, Any from fastmcp import FastMCP logger = logging.getLogger(__name__) logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO) mcp = FastMCP("Zoo Animal MCP Server 🦁🐧🐻") # Dictionary of animals at the zoo ZOO_ANIMALS = [ { "species": "lion", "name": "Leo", "age": 7, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "Nala", "age": 6, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "Simba", "age": 3, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "King", "age": 8, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "penguin", "name": "Waddles", "age": 2, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Pip", "age": 4, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Skipper", "age": 5, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Chilly", "age": 3, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Pingu", "age": 6, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Noot", "age": 1, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "elephant", "name": "Ellie", "age": 15, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Peanut", "age": 12, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Dumbo", "age": 5, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Trunkers", "age": 10, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "bear", "name": "Smokey", "age": 10, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Grizzly", "age": 8, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Barnaby", "age": 6, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Bruin", "age": 12, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "giraffe", "name": "Gerald", "age": 4, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Longneck", "age": 5, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Patches", "age": 3, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Stretch", "age": 6, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Speedy", "age": 2, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Dash", "age": 3, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Gazelle", "age": 4, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Swift", "age": 5, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "polar bear", "name": "Snowflake", "age": 7, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "polar bear", "name": "Blizzard", "age": 5, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "polar bear", "name": "Iceberg", "age": 9, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "walrus", "name": "Wally", "age": 10, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Tusker", "age": 12, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Moby", "age": 8, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Flippers", "age": 9, "enclosure": "The Walrus Cove", "trail": "Polar Path" } ] @mcp.tool() def get_animals_by_species(species: str) -> List[Dict[str, Any]]: """ Retrieves all animals of a specific species from the zoo. Can also be used to collect the base data for aggregate queries of animals of a specific species - like counting the number of penguins or finding the oldest lion. Args: species: The species of the animal (e.g., 'lion', 'penguin'). Returns: A list of dictionaries, where each dictionary represents an animal and contains details like name, age, enclosure, and trail. """ logger.info(f">>> 🛠️ Tool: 'get_animals_by_species' called for '{species}'") return [animal for animal in ZOO_ANIMALS if animal["species"].lower() == species.lower()] @mcp.tool() def get_animal_details(name: str) -> Dict[str, Any]: """ Retrieves the details of a specific animal by its name. Args: name: The name of the animal. Returns: A dictionary with the animal's details (species, name, age, enclosure, trail) or an empty dictionary if the animal is not found. """ logger.info(f">>> 🛠️ Tool: 'get_animal_details' called for '{name}'") for animal in ZOO_ANIMALS: if animal["name"].lower() == name.lower(): return animal return {} if __name__ == "__main__": logger.info(f"🚀 MCP server started on port {os.getenv('PORT', 8080)}") asyncio.run( mcp.run_async( transport="http", host="0.0.0.0", port=os.getenv("PORT", 8080), ) )
کد شما کامل است! زمان استقرار سرور MCP در Cloud Run فرا رسیده است.
7. استقرار در Cloud Run
اکنون یک سرور MCP را مستقیماً از کد منبع در Cloud Run مستقر کنید.
- یک
Dockerfile
جدید برای استقرار در Cloud Run ایجاد و باز کنید:cloudshell edit Dockerfile
- برای استفاده از ابزار
uv
برای اجرای فایلserver.py
کد زیر را در Dockerfile وارد کنید:# Use the official Python image FROM python:3.13-slim # Install uv COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/ # Install the project into /app COPY . /app WORKDIR /app # Allow statements and log messages to immediately appear in the logs ENV PYTHONUNBUFFERED=1 # Install dependencies RUN uv sync EXPOSE $PORT # Run the FastMCP server CMD ["uv", "run", "server.py"]
- دستور
gcloud
را برای استقرار برنامه در Cloud Run اجرا کنید برای احراز هویت از پرچمgcloud run deploy zoo-mcp-server \ --no-allow-unauthenticated \ --region=europe-west1 \ --source=. \ --labels=dev-tutorial=codelab-mcp
--no-allow-unauthenticated
استفاده کنید. این به دلایل امنیتی مهم است. اگر نیازی به احراز هویت ندارید، هر کسی میتواند با سرور MCP شما تماس بگیرد و احتمالاً به سیستم شما آسیب برساند. - ایجاد یک مخزن رجیستری جدید را تأیید کنید از آنجایی که اولین بار است که از کد منبع در Cloud Run مستقر می شوید، خواهید دید:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [europe-west1] will be created. Do you want to continue (Y/n)?
Y
را تایپ کنید وEnter
را فشار دهید، این یک مخزن رجیستری Artifact برای استقرار شما ایجاد می کند. این برای ذخیره کانتینر Docker سرور MCP برای سرویس Cloud Run لازم است. - بعد از چند دقیقه پیامی مانند:
Service [zoo-mcp-server] revision [zoo-mcp-server-12345-abc] has been deployed and is serving 100 percent of traffic.
شما سرور MCP خود را مستقر کرده اید. اکنون می توانید از آن استفاده کنید.
8. Remote MCP Server را به Gemini CLI اضافه کنید
اکنون که با موفقیت یک سرور MCP راه دور را راه اندازی کرده اید، می توانید با استفاده از برنامه های مختلف مانند Google Code Assist یا Gemini CLI به آن متصل شوید. در این بخش، با استفاده از Gemini CLI به سرور MCP راه دور جدید شما ارتباط برقرار می کنیم.
- به حساب کاربری خود اجازه تماس با سرور MCP راه دور را بدهید
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \ --member=user:$(gcloud config get-value account) \ --role='roles/run.invoker'
- اطلاعات کاربری Google Cloud و شماره پروژه خود را در متغیرهای محیطی برای استفاده در فایل تنظیمات Gemini ذخیره کنید:
export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)") export ID_TOKEN=$(gcloud auth print-identity-token)
- فایل Gemini CLI Settings خود را باز کنید
cloudshell edit ~/.gemini/settings.json
- فایل تنظیمات Gemini CLI خود را جایگزین کنید تا سرور MCP Cloud Run را اضافه کنید
{ "mcpServers": { "zoo-remote": { "httpUrl": "https://zoo-mcp-server-$PROJECT_NUMBER.europe-west1.run.app/mcp/", "headers": { "Authorization": "Bearer $ID_TOKEN" } } }, "selectedAuthType": "cloud-shell", "hasSeenIdeIntegrationNudge": true }
- Gemini CLI را در Cloud Shell راه اندازی کنید
ممکن است لازم باشدgemini
Enter
فشار دهید تا برخی تنظیمات پیش فرض را بپذیرید. - از جمینی بخواهید ابزارهای MCP را که در زمینه خود در دسترس است فهرست کند
/mcp
- از جوزا بخواهید چیزی در باغ وحش پیدا کند
Gemini CLI باید بداند که از سرور MCPWhere can I find penguins?
zoo-remote
استفاده کند و از شما می پرسد که آیا مایل به اجرای MCP هستید یا خیر. - از فلش رو به پایین استفاده کنید، سپس
Enter
فشار دهید تا انتخاب شودYes, always allow all tools from server "zoo-remote"
خروجی باید پاسخ صحیح و یک کادر نمایشی نشان دهد که سرور MCP استفاده شده است.
شما آن را انجام داده اید! شما با موفقیت یک سرور MCP راه دور را در Cloud Run مستقر کرده اید و آن را با استفاده از Gemini CLI آزمایش کرده اید.
هنگامی که برای پایان دادن به جلسه خود آماده شدید، /quit
را تایپ کنید و سپس Enter
فشار دهید تا از Gemini CLI خارج شوید.
اشکال زدایی
اگر خطای زیر را مشاهده کردید:
🔍 Attempting OAuth discovery for 'zoo-remote'... ❌ 'zoo-remote' requires authentication but no OAuth configuration found Error connecting to MCP server 'zoo-remote': MCP server 'zoo-remote' requires authentication. Please configure OAuth or check server settings.
به احتمال زیاد زمان شناسه شناسه تمام شده است و نیاز به تنظیم مجدد ID_TOKEN
دارد.
-
/quit
را تایپ کنید و سپسEnter
فشار دهید تا از Gemini CLI خارج شوید. - پروژه خود را در ترمینال خود تنظیم کنید
gcloud config set project [PROJECT_ID]
- در مرحله 2 بالا راه اندازی مجدد کنید
9. (اختیاری) بررسی تماس های ابزار در گزارش های سرور
برای تأیید اینکه سرور MCP Cloud Run شما فراخوانی شده است، گزارشهای سرویس را بررسی کنید.
gcloud run services logs read zoo-mcp-server --region europe-west1 --limit=5
شما باید یک گزارش خروجی را ببینید که تأیید می کند که یک ابزار تماس برقرار شده است. 🛠️
2025-08-05 19:50:31 INFO: 169.254.169.126:39444 - "POST /mcp/ HTTP/1.1" 200 OK 2025-08-05 19:50:31 [INFO]: Processing request of type CallToolRequest 2025-08-05 19:50:31 [INFO]: >>> 🛠️ Tool: 'get_animals_by_species' called for 'penguin'
10. (اختیاری) اعلان MCP را به سرور اضافه کنید
یک اعلان MCP میتواند گردش کار شما را برای اعلانهایی که اغلب اجرا میکنید با ایجاد کوتاهنویسی برای یک اعلان طولانیتر سرعت دهد.
Gemini CLI به طور خودکار اعلانهای MCP را به دستورات اسلش سفارشی تبدیل میکند، به طوری که میتوانید با تایپ /prompt_name
یک اعلان MCP را فراخوانی کنید، جایی که prompt_name
نام دستور MCP شما است.
یک اعلان MCP ایجاد کنید تا بتوانید با تایپ /find animal
در Gemini CLI به سرعت حیوانی را در باغ وحش پیدا کنید.
- این کد را به فایل
server.py
خود در بالای محافظ اصلی اضافه کنید (if __name__ == "__main__":
)@mcp.prompt() def find(animal: str) -> str: """ Find which exhibit and trail a specific animal might be located. """ return ( f"Please find the exhibit and trail information for {animal} in the zoo. " f"Respond with '[animal] can be found in the [exhibit] on the [trail].'" f"Example: Penguins can be found in The Arctic Exhibit on the Polar Path." )
- برنامه خود را مجدداً در Cloud Run مستقر کنید
gcloud run deploy zoo-mcp-server \ --no-allow-unauthenticated \ --region=europe-west1 \ --source=. \ --labels=dev-tutorial=codelab-mcp
- ID_TOKEN خود را برای سرور MCP راه دور خود بازخوانی کنید
export ID_TOKEN=$(gcloud auth print-identity-token)
- پس از استقرار نسخه جدید برنامه، Gemini CLI را راه اندازی کنید.
gemini
- در خط فرمان از دستور سفارشی جدیدی که ایجاد کردید استفاده کنید:
/find --animal="lions"
باید ببینید که Gemini CLI ابزار get_animals_by_species
فراخوانی می کند و پاسخ را مطابق دستور MCP فرمت می کند!
╭───────────────────────────╮ │ > /find --animal="lion" │ ╰───────────────────────────╯ ╭───────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✔ get_animals_by_species (zoo-remote MCP Server) get_animals_by_species (zoo-remote MCP Server) │ │ │ │ [{"species":"lion","name":"Leo","age":7,"enclosure":"The Big Cat │ │ Plains","trail":"Savannah │ │ Heights"},{"species":"lion","name":"Nala","age":6,"enclosure":"The Big Cat │ │ Plains","trail":"Savannah │ │ Heights"},{"species":"lion","name":"Simba","age":3,"enclosure":"The Big Cat │ │ Plains","trail":"Savannah │ │ Heights"},{"species":"lion","name":"King","age":8,"enclosure":"The Big Cat │ │ Plains","trail":"Savannah Heights"}] │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────╯ ✦ Lions can be found in The Big Cat Plains on the Savannah Heights.
اهداف خود را برای آزمایش خود تنظیم کنید
برای یک چالش بیشتر، ببینید آیا میتوانید همان مراحل را دنبال کنید تا حقایق جالبی درباره گونههای جانوری خاص در باغ وحش ایجاد کنید.
یا بهعنوان بخش بزرگتری برای آزمایش آموختههایتان، ایدهای برای ابزاری که اغلب از آن استفاده میکنید بیابید و یک سرور MCP راه دور دوم را راهاندازی کنید. سپس آن را به تنظیمات Gemini CLI خود اضافه کنید تا ببینید آیا کار می کند یا خیر.
11. نتیجه گیری
تبریک می گویم! شما با موفقیت مستقر شده و به یک سرور MCP راه دور ایمن متصل شده اید.
به آزمایشگاه بعدی ادامه دهید
این آزمایشگاه اولین آزمایشگاه از یک سری سه قسمتی است. در آزمایشگاه دوم، از سرور MCP که با یک عامل ADK ایجاد کرده اید استفاده خواهید کرد.
از یک سرور MCP در Cloud Run با یک عامل ADK استفاده کنید
(اختیاری) تمیز کردن
اگر به آزمایشگاه بعدی ادامه نمیدهید و میخواهید آنچه را ایجاد کردهاید پاک کنید، میتوانید پروژه Cloud خود را حذف کنید تا هزینههای اضافی متحمل نشوید.
در حالی که Cloud Run زمانی که از سرویس استفاده نمیشود شارژ نمیشود، ممکن است همچنان برای ذخیره تصویر ظرف در Artifact Registry هزینه دریافت کنید. با حذف پروژه Cloud، صورتحساب تمام منابع مورد استفاده در آن پروژه متوقف میشود.
در صورت تمایل پروژه را حذف کنید:
gcloud projects delete $GOOGLE_CLOUD_PROJECT
همچنین ممکن است بخواهید منابع غیر ضروری را از دیسک پوسته ابری خود حذف کنید. شما می توانید:
- دایرکتوری پروژه codelab را حذف کنید:
rm -rf ~/mcp-on-cloudrun
- هشدار! این اقدام بعدی قابل واگرد نیست! اگر میخواهید همه چیز را در Cloud Shell خود حذف کنید تا فضا آزاد شود، میتوانید کل فهرست اصلی خود را حذف کنید . مراقب باشید هر چیزی که می خواهید نگه دارید در جای دیگری ذخیره شود.
sudo rm -rf $HOME