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

شروع کار با سرورهای Google MCP

۱. مقدمه

خوش آمدید! در این آزمایشگاه کد، یاد خواهید گرفت که چگونه با استفاده از سرورهای پروتکل زمینه مدل مدیریت‌شده گوگل (MCP) عامل‌های هوش مصنوعی خود را تقویت کنید.

پروتکل زمینه مدل (MCP) یک استاندارد متن‌باز است که به مدل‌های هوش مصنوعی امکان می‌دهد تا به طور ایمن و کارآمد به منابع داده و ابزارهای خارجی متصل شوند. در حالی که اکثر پیاده‌سازی‌های MCP به صورت محلی روی دستگاه شما اجرا می‌شوند، گوگل سرورهای مدیریت‌شده MCP از راه دور را ارائه می‌دهد. این‌ها نقاط پایانی کاملاً میزبانی‌شده و آماده برای سازمان هستند که به نمایندگان شما اجازه می‌دهند بدون نیاز به مدیریت هیچ کد یا کانتینر سمت سرور، مستقیماً با زیرساخت Google Cloud تعامل داشته باشند.

مزیت «مدیریت‌شده»

برخلاف سرورهای محلی MCP که از ورودی/خروجی استاندارد (stdio) استفاده می‌کنند، سرورهای مدیریت‌شده گوگل از HTTP قابل پخش (Streamable HTTP ) استفاده می‌کنند. این معماری موارد زیر را ارائه می‌دهد:

زیرساخت صفر: هیچ سروری برای تأمین یا مقیاس‌پذیری وجود ندارد.
امنیت بر اساس طراحی: ادغام بومی با IAM و گزارش‌های حسابرسی Google Cloud.
مقیاس‌پذیری بدون وضعیت: تعامل یکپارچه از طریق متعادل‌کننده‌های بار استاندارد و پروکسی‌ها.

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

نحوه فعال‌سازی و احراز هویت سرورهای مدیریت‌شده MCP.
نحوه استفاده از سرور MCP ثبت وقایع ابری به عنوان یک مبنای اساسی.
چگونه چندین سرور MCP (دانش توسعه‌دهندگان، Firestore و غیره) را برای ایجاد گردش‌های کاری مستقل هماهنگ کنیم.

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

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

این آزمایشگاه کد، برای کاربران و توسعه‌دهندگان در تمام سطوح (از جمله مبتدیان) طراحی شده است.

گزارش مشکلات

همانطور که با آزمایشگاه کد و با Antigravity کار می‌کنید، ممکن است با مشکلاتی روبرو شوید.

برای مشکلات مربوط به codelab (غلط املایی، دستورالعمل‌های اشتباه)، لطفاً با استفاده از دکمه Report a mistake در گوشه پایین سمت چپ این codelab، یک اشکال (bug) ایجاد کنید:

۲. قبل از شروع

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

فعال کردن پوسته ابری

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

شناسه پروژه خود را تنظیم کنید

مطمئن شوید که Cloud Shell شما به پروژه صحیح اشاره می‌کند:

# Set your active project
gcloud config set project YOUR_PROJECT_ID

# Verify the setting
gcloud config list project

فعال کردن API های Foundation

سرورهای مدیریت‌شده‌ی MCP نیاز دارند که هم API محصول اصلی و هم رابط MCP فعال باشند. دستور زیر را برای فعال کردن Cloud Logging backend (که مبنای ما برای این آزمایش است) اجرا کنید:

# Enable the Cloud Logging API and its MCP interface
gcloud services enable logging.googleapis.com
gcloud beta services mcp enable logging.googleapis.com

توجه: سرویس‌های مدیریت‌شده MCP در حال حاضر در نسخه بتا هستند. برای فعال کردن آنها باید از کامپوننت بتای gcloud استفاده کنید.

تنظیمات اعتبارنامه‌های پیش‌فرض برنامه (ADC)

رابط خط فرمان Gemini از هویت کاربری شما برای ارتباط با سرورهای MCP استفاده می‌کند. به agent اجازه دهید از طرف شما عمل کند:

gcloud auth application-default login

آدرس اینترنتی (URL) را در ترمینال دنبال کنید، وارد سیستم شوید و کد مجوز را دوباره در Cloud Shell جایگذاری کنید.

نقش‌های اساسی IAM را تعیین کنید

سرورهای مدیریت‌شده‌ی MCP از یک مدل امنیتی دولایه استفاده می‌کنند. برای باز بودن به دو «دروازه» خاص نیاز دارید:

دروازه ۱ (دسترسی MCP): نقشی که به شما امکان فراخوانی پروتکل را می‌دهد.
دروازه ۲ (دسترسی به سرویس): نقشی که به شما امکان مشاهده داده‌ها را می‌دهد (مثلاً مشاهده گزارش‌ها).

برای اعطای دسترسی مورد نیاز، دستور زیر را اجرا کنید:

export PROJECT_ID=$(gcloud config get-value project)
export USER_EMAIL=$(gcloud config get-value account)

# Gate 1: Permission to use the MCP protocol
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/mcp.toolUser"

# Gate 2: Permission to view the actual logs
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/logging.viewer"

۳. مبانی: اتصال اولین سرور MCP شما

در این مرحله، شما عامل هوش مصنوعی خود (Gemini CLI) را به سرور Google Cloud Logging MCP متصل خواهید کرد. این «اساس» ماست زیرا به عامل اجازه می‌دهد تا به صورت بلادرنگ ببیند که درون پروژه شما چه اتفاقی می‌افتد.

وظیفه ۱: پیکربندی سرور ثبت وقایع MCP

رابط خط فرمان Gemini از فایل settings.json برای مدیریت اتصالات خود استفاده می‌کند. شما باید این فایل (که در پوشه ~/.gemini قرار دارد) را ویرایش کنید تا قطعه کد زیر را در بلوک mcpServers اضافه کنید. YOUR_PROJECT_ID را با شناسه پروژه واقعی خود جایگزین کنید:

"logging-mcp": {
      "httpUrl": "https://logging.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/logging.read"
        ]
      },
      "timeout": 30000,
      "headers": {
        "x-goog-user-project": "YOUR_PROJECT_ID"
      }
}

توجه : هدر x-goog-user-project برای سرورهای مدیریت‌شده MCP لازم است تا اطمینان حاصل شود که استفاده از API و پرداخت هزینه به درستی به پروژه شما نسبت داده می‌شود.

وظیفه ۲: شبیه‌سازی فعالیت پروژه (ایجاد گزارش‌ها)

اگر پروژه شما جدید یا غیرفعال است، ممکن است هیچ گزارش «جالب» جدیدی نداشته باشد. بیایید از رابط خط فرمان gcloud برای تزریق چند ورودی سفارشی استفاده کنیم تا عامل چیزی برای پیدا کردن داشته باشد.

برای شبیه‌سازی توالی رویدادها، این دستورات را یکی‌یکی اجرا کنید:

# 1. Simulate a standard system start
gcloud logging write mcp-test-log "System boot sequence initiated" --severity=INFO
# 2. Simulate a warning about resource limits
gcloud logging write mcp-test-log "High memory pressure detected in zone us-central1-a" --severity=WARNING
# 3. Simulate a critical authentication failure
gcloud logging write mcp-test-log "ERROR: Failed to connect to Cloud SQL. Permission Denied." --severity=ERROR

وظیفه ۳: تأیید ابزارها در Gemini CLI

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

gemini

وقتی وارد خط فرمان Gemini CLI ( > ) شدید، دستور list را اجرا کنید:

/mcp list

نقطه بررسی تأیید: باید ببینید که logging-mcp به عنوان Ready فهرست شده و تقریباً 6 ابزار از جمله list_log_entries در آن موجود است.

وظیفه ۴: اولین درخواست زیرساخت زنده شما

حالا، بیایید از عامل بخواهیم گزارش‌هایی را که تازه ایجاد کرده‌ایم پیدا کند. از آنجایی که قبلاً نقش roles/logging.viewer را اعطا کرده‌اید، عامل اکنون می‌تواند «به شما دسترسی پیدا کند» و وضعیت پروژه شما را بخواند.

دستور زیر را در رابط خط فرمان Gemini تایپ کنید:

Show me the 3 most recent log entries from the log named 'mcp-test-log'. What is the highest severity issue you see?

به نماینده توجه کنید:

ممکن است نماینده از شما شناسه پروژه گوگل کلود را بخواهد. لطفاً آن را ارائه دهید.
تشخیص می‌دهد که به ابزار list_log_entries نیاز دارد.
از شما اجازه اجرای ابزار را می‌خواهد. گزینه ۱ را انتخاب کنید. بله، یک بار اجازه دهید .
این ابزار پاسخ JSON را تجزیه می‌کند و خطای Cloud SQL Permission Denied که شبیه‌سازی کرده‌ایم را به شما اطلاع می‌دهد.

۴. سفر الف: مغز (دانش توسعه‌دهندگان MCP)

در این مسیر، با اتصال نماینده خود به سرور MCP دانش توسعه‌دهندگان گوگل، به او یک «مغز» خواهید داد.

یکی از بزرگترین خطرات مربوط به عامل‌های هوش مصنوعی، توهم است - ارائه مطمئن دستورات CLI قدیمی یا پارامترهای API منسوخ شده. این سرور MCP با قرار دادن عامل در مجموعه اسناد رسمی و زنده توسعه‌دهندگان گوگل (شامل Google Cloud، Firebase، Android و موارد دیگر) این مشکل را حل می‌کند.

وظیفه ۱: فعال کردن سرویس‌های دانش

همانند مرحله پایه، باید هم API بک‌اند و هم نقطه پایانی سرویس MCP را فعال کنیم.

# 1. Enable the Developer Knowledge API
gcloud services enable developerknowledge.googleapis.com

# 2. Enable the MCP Server interface
gcloud beta services mcp enable developerknowledge.googleapis.com

وظیفه ۲: ارائه یک کلید API محدود

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

برای ایجاد و بازیابی کلید خود، اسکریپت زیر را اجرا کنید:

# Create the restricted API key
gcloud alpha services api-keys create \
    --display-name="MCP-Knowledge-Key" \
    --api-target service=developerknowledge.googleapis.com

# Wait a few seconds for the key to propagate, then fetch the string
gcloud alpha services api-keys get-key-string \
    $(gcloud alpha services api-keys list \
    --filter="displayName='MCP-Knowledge-Key'" \
    --format="value(name)") \
    --format="value(keyString)"

رشته طولانی کاراکترهای برگردانده شده توسط دستور دوم را کپی کنید. این YOUR_API_KEY شماست.

وظیفه ۳: پیکربندی رابط خط فرمان Gemini

حالا، سرور Knowledge MCP را نزد نماینده خود ثبت کنید. این به نماینده اجازه می‌دهد هر زمان که با یک سوال فنی مواجه شد که نتوانست با اطمینان ۱۰۰٪ به آن پاسخ دهد، اسناد رسمی را جستجو کند.

قطعه کد زیر را در بخش mcpServers خود در فایل ~/.gemini/settings.json اضافه کنید و YOUR_API_KEY را با رشته‌ای که کپی کرده‌اید جایگزین کنید:

"developer-knowledge-mcp": {
      "httpUrl": "https://developerknowledge.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR_API_KEY"
      }
}

وظیفه ۴: آزمون ضد توهم

بیایید بررسی کنیم که آیا عامل اکنون به جای «حدس زدن»، «تحقیق» می‌کند یا خیر.

اجرای Gemini CLI:

gemini

تأیید کنید که سرور آماده است: دستور /mcp list تایپ کنید. باید google-developer-knowledge به همراه دو ابزار ( search_documents و get_document ) ببینید.

سوال: از اپراتور بخواهید یک دستور خاص و مدرن پیدا کند.

I want to create a Google Cloud Storage bucket using the modern gcloud storage command. Search the official documentation for the exact syntax and show me an example for a bucket in the 'us-central1' region.

چه چیزی را باید جستجو کرد:

جمینی برای استفاده از search_documents اجازه می‌خواهد.
سپس احتمالاً تابع get_document را برای خواندن صفحه خاصی که پیدا کرده است، فراخوانی می‌کند.
پاسخ نهایی باید شامل دستور gcloud storage buckets create ... باشد که مستقیماً از مستندات ذکر شده است.

۵. سفر ب: تریاژ (عیب‌یابی خودکار)

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

در این مسیر، شما چشم‌های عامل خود (Cloud Logging MCP) و مغز (Developer Knowledge MCP) را برای ساخت یک حلقه عیب‌یابی خودکار ترکیب خواهید کرد.

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

وظیفه ۱: شبیه‌سازی یک «روز بد» در GCP

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

در Cloud Shell، یک پوشه به دلخواه خود ایجاد کنید و به داخل آن بروید.
یک فایل با نام simulate_errors.py ایجاد کنید:

nano simulate_errors.py

کد زیر را در ویرایشگر قرار دهید:

import argparse
from google.cloud import logging

def simulate_errors(project_id):
    client = logging.Client(project=project_id)
    logger = client.logger("mcp-scenario-logger")

    print(f"Simulating realistic errors for project: {project_id}...")

    # 1. GCS Permission Error
    logger.log_text("ERROR: GCS Upload failed for 'gs://my-app-bucket/data.json'. Status: 403 Forbidden. Missing 'storage.objects.create' for service account.", severity="ERROR")

    # 2. Cloud Run Startup Error
    logger.log_text("ERROR: Cloud Run service 'api-gateway' failed to start. Container failed to listen on port 8080. Check 'Cloud Run container startup requirements'.", severity="ERROR")

    # 3. Secret Manager Access Error
    logger.log_text("ERROR: Access denied to secret 'API_KEY'. The identity lacks 'secretmanager.versions.access'.", severity="ERROR")

    print("Log entries written to 'mcp-scenario-logger'.")

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--project", required=True)
    args = parser.parse_args()
    simulate_errors(args.project)

برای ذخیره و خروج، کلیدهای Ctrl+O، Enter و Ctrl+X را فشار دهید.
کتابخانه Google Cloud Logging را نصب کنید و اسکریپت را اجرا کنید:

python -m venv mcp_env
source mcp_env/bin/activate
pip install google-cloud-logging
python simulate_errors.py --project $(gcloud config get-value project)

وظیفه ۲: اجرای حلقه خودمختار

اکنون، یک اعلان پیچیده اجرا می‌کنیم که به Gemini دستور می‌دهد هر دو سرور MCP را به‌طور همزمان هماهنگ کند.

اجرای Gemini CLI:

gemini

این "دستورالعمل اصلی" را در عامل تایپ کنید:

I need to troubleshoot recent issues in my project. Perform the following autonomous loop:

Step 1 : Retrieval: Use the Logging MCP to fetch the 5 most recent ERROR entries from the log 'mcp-scenario-logger'.
Step 2 : Iteration: For every unique error found, extract the service and specific error message.
Step 3 : Research: Use the Developer Knowledge MCP to find the official resolution or gcloud command to fix each issue.
Step 4 : Resolution: Consolidate everything into a markdown table with columns: | Service | Error Summary | Recommended Fix |.

چه انتظاری باید داشت

اکنون شما در حال مشاهده‌ی گردش کار Agentic به صورت بلادرنگ هستید. Agent کارهای زیر را انجام خواهد داد:

برای دیدن «روز بدی» که شبیه‌سازی کردیم، تابع list_log_entries را فراخوانی کنید.
متن را تجزیه و تحلیل کنید تا مشخص شود که GCS، Cloud Run و Secret Manager از کار افتاده‌اند.
برای یافتن نقش‌های صحیح IAM یا اصلاحات پیکربندی، برای هر یک از این سرویس‌ها search_documents و get_document را فراخوانی کنید.
یک جدول ساختاریافته شبیه به این به شما ارائه می‌دهد (توصیه‌ها ممکن است متفاوت باشند):

خدمات	خلاصه خطا	راه حل پیشنهادی
فضای ذخیره‌سازی ابری	۴۰۳ آپلود ممنوع	`roles/storage.objectCreator` را به حساب سرویس اعطا کنید.
اجرای ابری	گوش دادن به پورت ۸۰۸۰ ناموفق بود	مطمئن شوید که برنامه به پورت 0.0.0.0 که توسط `$PORT` تعریف شده است، متصل می‌شود.
مدیر مخفی	نقش دسترسی به نسخه وجود ندارد	به هویت `roles/secretmanager.secretAccessor` اختصاص دهید.

۶. سفر C: داده‌ها (Firestore MCP)

در این سفر، شما از Firestore MCP Server برای مدیریت یک پایگاه داده سند NoSQL با استفاده از زبان طبیعی استفاده خواهید کرد.

فایراستور یک پایگاه داده انعطاف‌پذیر و مقیاس‌پذیر است، اما مدیریت آن اغلب نیاز به نوشتن کد پیچیده SDK یا پیمایش کنسول دارد. با MCP، عامل شما به یک مدیر پایگاه داده تبدیل می‌شود که قادر به بارگذاری داده‌ها، پرس‌وجو از رکوردها و حتی انجام مهاجرت‌های پیچیده طرحواره از طریق چت است.

وظیفه ۱: فعال کردن سرویس‌های Firestore

ابتدا، API فایراستور و نقطه پایانی MCP مربوط به آن را فعال کنید.

# 1. Enable the Firestore API
gcloud services enable firestore.googleapis.com

# 2. Enable the MCP Server interface
gcloud beta services mcp enable firestore.googleapis.com

وظیفه 2: اختصاص نقش‌های IAM در Firestore

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

# Grant Firestore User role
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/datastore.user"

وظیفه ۳: ایجاد یک پایگاه داده تست اختصاصی

برای ایمن نگه داشتن آزمایش‌هایمان، یک پایگاه داده اختصاصی Firestore با نام mcp-lab-db ایجاد خواهیم کرد.

gcloud firestore databases create --database=mcp-lab-db --location=nam5 --type=firestore-native

وظیفه ۴: پیکربندی رابط خط فرمان Gemini

سرور Firestore MCP را به نماینده خود اضافه کنید. پیکربندی زیر را به بخش mcpServers در فایل ~/.gemini/settings.json اضافه کنید. YOUR_PROJECT_ID را با شناسه پروژه واقعی خود جایگزین کنید:

"firestore-mcp": {
      "httpUrl": "https://firestore.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/cloud-platform"
        ]
      },
      "timeout": 30000,
      "headers": {
        "x-goog-user-project": "YOUR_PROJECT_ID"
      }
}

وظیفه ۵: عملیات پایگاه داده زبان طبیعی

رابط خط فرمان Gemini را اجرا کنید و برخی عملیات اولیه را برای تأیید اتصال انجام دهید.

اجرای Gemini CLI:

gemini

تأیید کنید که سرور آماده است: دستور /mcp list تایپ کنید. باید firestore-mcp به همراه چندین ابزار ( add_document, create_database, list_documents, etc ) مشاهده کنید.

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

داده‌های بذر:

In the 'mcp-lab-db' database, add three documents to a 'products' collection. Include a laptop (stock 5), a mouse (stock 25), and a keyboard (stock 8).

تأیید کنید:

List all documents in the 'products' collection from the 'mcp-lab-db' database.

سایر دستورالعمل‌هایی را که به شما در مدیریت پایگاه‌های داده و مجموعه‌های Firestore از طریق زبان طبیعی کمک می‌کنند، امتحان کنید.

۷. سفر D: هوش (BigQuery و Maps)

در این مسیر، شما با استفاده از سرورهای BigQuery و Maps Grounding Lite MCP، به کارشناس خود توانایی تجزیه و تحلیل پتابایت‌ها داده و درک دنیای فیزیکی را خواهید داد.

در پایان این بخش، عامل شما قادر خواهد بود زبان طبیعی را به پرس‌وجوهای پیچیده SQL ترجمه کند و توصیه‌های مکانی-مکانی آگاه از متن (مانند زمان سفر و آب و هوا) ارائه دهد تا پاسخ‌های خود را بر اساس واقعیت بنا کند.

وظیفه ۱: فعال کردن سرویس‌های اطلاعاتی

رابط‌های API و MCP را برای BigQuery و Google Maps فعال کنید.

# 1. Enable product APIs
gcloud services enable bigquery.googleapis.com mapstools.googleapis.com

# 2. Enable MCP Server interfaces
gcloud beta services mcp enable bigquery.googleapis.com
gcloud beta services mcp enable mapstools.googleapis.com

وظیفه ۲: اختصاص نقش‌های IAM در BigQuery

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

# Grant BigQuery Job User and Data Viewer roles
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/bigquery.dataViewer"

وظیفه ۳: ارائه کلید API نقشه‌ها

برخلاف سایر سرویس‌هایی که صرفاً به IAM متکی هستند، سرور Maps Grounding Lite برای سهمیه‌بندی و صدور صورتحساب به یک کلید API نیاز دارد.

کلید را ایجاد کنید:

gcloud alpha services api-keys create --display-name="MCP-Maps-Key"

رشته کلید را دریافت کنید:

# Wait a few seconds for the key to propagate, then fetch the string
gcloud alpha services api-keys get-key-string \
    $(gcloud alpha services api-keys list \
    --filter="displayName='MCP-Maps-Key'" \
    --format="value(name)") \
    --format="value(keyString)"

رشته کلید را برای مرحله بعدی کپی کنید .

وظیفه ۴: پیکربندی رابط خط فرمان Gemini

حالا هر دو سرور را ثبت کنید. قطعه کدهای زیر را به بخش mcpServers در فایل ~/.gemini/settings.json اضافه کنید. YOUR_PROJECT_ID و YOUR_MAPS_API_KEY را به ترتیب جایگزین کنید.

"bigquery-mcp": {
      "httpUrl": "https://bigquery.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/cloud-platform"
        ]
      },
      "timeout": 30000,
      "headers": {
        "x-goog-user-project": "YOUR_PROJECT_ID"
      }
},
"maps-grounding-lite-mcp": {
      "httpUrl": "https://mapstools.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR_MAPS_API_KEY"
      }
}

وظیفه ۵: هوش در عمل

رابط خط فرمان Gemini را اجرا کنید و قابلیت‌های جدید «هوش» را آزمایش کنید.

gemini

تأیید کنید که سرور آماده است: عبارت /mcp list تایپ کنید. باید bigquery-mcp و maps-grounding-lite-mcp به همراه چندین ابزار فهرست شده ببینید.

سناریو ۱: موتور تحلیلی (BigQuery) از عامل بخواهید بدون اینکه شما هیچ SQL بدانید، از یک مجموعه داده عمومی پرس‌وجو کند:

Run a query to count the number of penguins on each island in the BigQuery public dataset ml_datasets.penguins.

سناریو ۲: زمینه جغرافیایی (نقشه‌ها) از نماینده بخواهید یک سفر در دنیای واقعی را برنامه‌ریزی کند:

I am planning a drive from Mumbai to Pune tomorrow morning. Based on current weather and routing, what should I expect in terms of travel time and what should I carry?

چه چیزی را باید جستجو کرد:

برای BigQuery، عامل execute_sql را فراخوانی می‌کند تا طرحواره را کشف کرده و پرس‌وجو را اجرا کند.
برای نقشه‌ها، lookup_weather و compute_routes را هماهنگ می‌کند تا یک برنامه سفر مفید و مطمئن به شما ارائه دهد.

۸. مقاوم‌سازی: امنیت تولید و IAM

در این مرحله نهایی، شما از استفاده از مجوزهای گسترده "مالک" به یک مدل دفاع در عمق سطح تولید (Production-Grade Defense-in-Depth) منتقل خواهید شد.

عامل‌های هوش مصنوعی ذاتاً «مفید» هستند. اگر ابزاری را در سطح رابط کاربری محدود کنید، یک عامل هوشمند ممکن است سعی کند با اجرای یک دستور shell از آن محدودیت عبور کند. برای ایمن‌سازی واقعی زیرساخت خود، باید با استفاده از Google Cloud IAM مرزهای سختی ایجاد کنید.

مدل امنیتی دولایه

برای اجرای هر عملی، یک عامل باید از دو دروازه عبور کند:

دروازه ۱ (دروازه MCP): آیا هویت دارای roles/mcp.toolUser است؟ (مجوز استفاده از پروتکل).
دروازه ۲ (دروازه سرویس): آیا هویت نقش خاص محصول (مثلاً roles/datastore.viewer ) را دارد؟ (مجوز مشاهده داده‌ها).

وظیفه ۱: لایه ۱ - فیلترینگ سمت کلاینت ( `excludeTools` )

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

تنظیمات Gemini CLI خود را در ویرایشگر Cloud Shell باز کنید:

cloudshell edit ~/.gemini/settings.json

بلوک firestore-mcp را پیدا کنید و دستورالعمل excludeTools را برای پنهان کردن اقدامات مخرب اضافه کنید:

"firestore-mcp": {
  "httpUrl": "https://firestore.googleapis.com/mcp",
  "excludeTools": ["delete_database", "update_database", "delete_document"],
  ...
}

فایل را ذخیره کنید و Gemini CLI را مجدداً راه اندازی کنید. دستور /mcp list را اجرا کنید و متوجه خواهید شد که آن ابزارها اکنون از بین رفته‌اند.

وظیفه ۲: لایه ۲ - برتری زیرساخت (IAM Bouncer)

فیلترینگ سمت کلاینت یک مانع «نرم» است. اگر از عامل بخواهید «پایگاه داده Firestore من را حذف کند» و ابزار پنهان باشد، ممکن است سعی کند gcloud firestore databases delete اجرا کند. برای جلوگیری از این امر، ما از یک حساب سرویس با حداقل امتیاز استفاده می‌کنیم.

یک حساب کاربری سرویس «فقط خواننده» ایجاد کنید:

# Create the service account
gcloud iam service-accounts create mcp-reader-sa --display-name="MCP Reader Only"

# Grant ONLY the necessary roles (Gate 1 + Gate 2)
export PROJECT_ID=$(gcloud config get-value project)
SA_EMAIL="mcp-reader-sa@$PROJECT_ID.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/mcp.toolUser"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/datastore.viewer"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/aiplatform.user"

کلید را تولید و فعال کنید:

gcloud iam service-accounts keys create reader-key.json --iam-account=$SA_EMAIL
export GOOGLE_APPLICATION_CREDENTIALS=$(pwd)/reader-key.json

وظیفه ۳: آزمون بازتاب «عامل مفید»

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

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

فعال کردن حساب کاربری سرویس:

دستور زیر را اجرا کنید و [PATH_TO_KEY_FILE] را با مسیر واقعی فایل کلید JSON خود (مثلاً reader-key.json ) جایگزین کنید.

gcloud auth activate-service-account --key-file=[PATH_TO_KEY_FILE]

تغییر را تأیید کنید:

پس از اجرای دستور، می‌توانید با اجرای دستور زیر از فعال بودن حساب سرویس اطمینان حاصل کنید:

gcloud auth list

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

اجرای Gemini CLI:

gemini

این دستور را تایپ کنید:

I want to delete the 'mcp-lab-db' firestore database. If the tool is missing, try using the gcloud firestore command in the terminal.

چه اتفاقی می‌افتد؟

عامل ابتدا سعی می‌کند از ابزار delete_database در سرور Firestore MCP استفاده کند. این کار به دلیل عدم مجوز با شکست مواجه خواهد شد.
سپس با بازگشت به ابزار run_shell_command برای استفاده از دستور gcloud firestore، سعی می‌کند «مفید» باشد.

نتیجه:

دستور با خطای Forbidden اجرا نمی‌شود. از آنجا که عامل تحت هویت mcp-reader-sa در حال اجرا است، فاقد مجوز datastore.databases.delete است. IAM پشتیبان نهایی است. مهم نیست که عامل چگونه سعی در دسترسی به منبع داشته باشد، "Bouncer" در سطح Google Cloud API درخواست را مسدود می‌کند.

به حساب کاربری خود برگردید:

برای بازگشت به حساب کاربری خود، دستور زیر را وارد کنید:

gcloud config set account YOUR_EMAIL_ADDRESS

۹. پاکسازی

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

# Delete the Firestore database
gcloud firestore databases delete --database=mcp-lab-db

# Remove the service account
gcloud iam service-accounts delete mcp-reader-sa@$PROJECT_ID.iam.gserviceaccount.com

۱۰. نتیجه‌گیری

تبریک! شما با موفقیت به تمام سرورهای مدیریت‌شده‌ی MCP گوگل دسترسی پیدا کردید.

شما با «ترانک» آزمایشگاه شروع کردید و یک اتصال بنیادی به Cloud Logging برقرار کردید. از آنجا، به «ماجراجویی‌های» ماژولار روی آوردید - پایه‌گذاری دانش عامل خود، خودکارسازی حلقه‌های عیب‌یابی پیچیده، انتقال داده‌ها در Firestore و استخراج اطلاعات از BigQuery و Maps .

از همه مهم‌تر، شما با تثبیت عامل خود در ریشه‌های امنیت تولید، کار را به پایان رساندید. شما ثابت کردید که اگرچه یک عامل می‌تواند در مواقع بروز خطا «مفید» باشد، اما Google Cloud IAM بهترین راه حل است و تضمین می‌کند که گردش‌های کاری مستقل شما همیشه اصل حداقل امتیاز را رعایت کنند.

نکات کلیدی

مدیریت‌شده = مقیاس‌پذیر: شما از طریق Streamable HTTP بدون استقرار حتی یک سرور، به ابزارهای سطح زیرساخت متصل شدید.
اتصال به زمین اجباری است: شما «حدس زدن» LLM را با دانش توسعه‌دهنده MCP جایگزین کردید و مطمئن شدید که عامل شما از دستورات معتبر و به‌روز استفاده می‌کند.
هماهنگی قدرت است: دیدید که جادوی واقعی زمانی اتفاق می‌افتد که یک اپراتور چندین سرور MCP را برای حل یک مشکل تجاری واحد ترکیب می‌کند.

شروع کار با سرورهای Google MCP

۱. مقدمه

مزیت «مدیریت‌شده»

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

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

گزارش مشکلات

۲. قبل از شروع

فعال کردن پوسته ابری

شناسه پروژه خود را تنظیم کنید

فعال کردن API های Foundation

تنظیمات اعتبارنامه‌های پیش‌فرض برنامه (ADC)

نقش‌های اساسی IAM را تعیین کنید

۳. مبانی: اتصال اولین سرور MCP شما

وظیفه ۱: پیکربندی سرور ثبت وقایع MCP

وظیفه ۲: شبیه‌سازی فعالیت پروژه (ایجاد گزارش‌ها)

وظیفه ۳: تأیید ابزارها در Gemini CLI

وظیفه ۴: اولین درخواست زیرساخت زنده شما

۴. سفر الف: مغز (دانش توسعه‌دهندگان MCP)

وظیفه ۱: فعال کردن سرویس‌های دانش

وظیفه ۲: ارائه یک کلید API محدود

وظیفه ۳: پیکربندی رابط خط فرمان Gemini

وظیفه ۴: آزمون ضد توهم

۵. سفر ب: تریاژ (عیب‌یابی خودکار)

وظیفه ۱: شبیه‌سازی یک «روز بد» در GCP

وظیفه ۲: اجرای حلقه خودمختار

۶. سفر C: داده‌ها (Firestore MCP)

وظیفه ۱: فعال کردن سرویس‌های Firestore

وظیفه 2: اختصاص نقش‌های IAM در Firestore

وظیفه ۳: ایجاد یک پایگاه داده تست اختصاصی

وظیفه ۴: پیکربندی رابط خط فرمان Gemini

وظیفه ۵: عملیات پایگاه داده زبان طبیعی

۷. سفر D: هوش (BigQuery و Maps)

وظیفه ۱: فعال کردن سرویس‌های اطلاعاتی

وظیفه ۲: اختصاص نقش‌های IAM در BigQuery

وظیفه ۳: ارائه کلید API نقشه‌ها

وظیفه ۴: پیکربندی رابط خط فرمان Gemini

وظیفه ۵: هوش در عمل

۸. مقاوم‌سازی: امنیت تولید و IAM

مدل امنیتی دولایه

وظیفه ۱: لایه ۱ - فیلترینگ سمت کلاینت ( excludeTools )

وظیفه ۲: لایه ۲ - برتری زیرساخت (IAM Bouncer)

وظیفه ۳: آزمون بازتاب «عامل مفید»

۹. پاکسازی

۱۰. نتیجه‌گیری

نکات کلیدی

وظیفه ۱: لایه ۱ - فیلترینگ سمت کلاینت ( `excludeTools` )