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

به سرور MCP دانش توسعه‌دهندگان متصل شوید

سرور MCP دانش توسعه‌دهندگان گوگل (Google Developer Knowledge MCP) به ابزارهای توسعه مبتنی بر هوش مصنوعی دسترسی مستقیم می‌دهد تا اسناد رسمی توسعه‌دهندگان گوگل را برای محصولاتی مانند Firebase، Google Cloud، Android، Google Maps Platform و موارد دیگر جستجو و بازیابی کنند. با اتصال دستیار کدنویسی خود به کتابخانه معتبر اسناد گوگل، از جستجوهای دستی وب، متن‌های قدیمی و کپی کردن اطلاعات اضافی جلوگیری می‌کنید.

قابلیت‌های سرور MCP

سرور MCP دانش توسعه‌دهندگان گوگل سه ابزار اصلی را در اختیار دستیار کدنویسی هوش مصنوعی شما قرار می‌دهد:

نام ابزار	توضیحات
`search_documents`	اسناد توسعه‌دهندگان گوگل را جستجو می‌کند و مرتبط‌ترین گزیده‌های صفحه را در کنار نام اسناد آنها برمی‌گرداند.
`get_documents`	محتوای کامل Markdown اسناد را با استفاده از نام‌های برگردانده شده توسط `search_documents` بازیابی می‌کند.
`answer_query`	پاسخ‌های ساختاریافته‌ای را که از مجموعه دانش توسعه‌دهندگان استخراج شده‌اند، تولید می‌کند.

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

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

روش احراز هویت خود را انتخاب کنید

سرور MCP دانش توسعه‌دهندگان، بسته به محیط توسعه و دستیار هوش مصنوعی شما، از دو رویکرد احراز هویت پشتیبانی می‌کند:

کلید API : بهترین گزینه برای IDEها و عوامل CLI شخص ثالث مانند Claude Code، Cursor، GitHub Copilot، Codex و سایر کلاینت‌های MCP از راه دور. کلید API را در هدر X-Goog-Api-Key از طریق HTTPS وارد کنید.
OAuth و ADC : بهترین گزینه برای Google Antigravity است که از Application Default Credentials (ADC) پشتیبانی داخلی دارد، یا برای گردش‌های کاری سازمانی که به جای کلید API به یک توکن حامل OAuth 2.0 یا شناسه کلاینت مستقل OAuth 2.0 نیاز دارند.

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

برای ایجاد اعتبارنامه‌های خود، یک برگه انتخاب کنید:

کلید API

پیش‌نیازها

قبل از ایجاد کلید API، مطمئن شوید که موارد زیر را دارید:

یک پروژه ابری گوگل .
رابط خط فرمان gcloud نصب شده باشد (در صورت پیکربندی از خط فرمان).

فعال کردن API و ایجاد کلید API

شما می‌توانید با استفاده از کنسول گوگل کلود یا رابط خط فرمان gcloud یک کلید API ایجاد کنید:

کنسول ابری گوگل

صفحه API دانش توسعه‌دهندگان را در کنسول Google Cloud باز کنید.
پروژه گوگل کلود خود را انتخاب کنید و روی فعال‌سازی کلیک کنید.
به صفحه اعتبارنامه‌ها بروید.
روی ایجاد اعتبارنامه کلیک کنید و کلید API را انتخاب کنید.
برای پیکربندی محدودیت‌ها، روی دکمه‌ی ویرایش کلید API کلیک کنید:
- در زیر محدودیت‌های API ، کلید محدود کردن را انتخاب کنید.
- API دانش توسعه‌دهنده را انتخاب کنید.
- اگر قصد دارید از همین کلید برای فراخوانی‌های مدل (مانند GEMINI_API_KEY ) استفاده کنید، Generative Language API را نیز انتخاب کنید.
روی ذخیره کلیک کنید، سپس کلید API خود را کپی کنید.

رابط خط فرمان جی‌کلاود

API دانش توسعه‌دهندگان را در پروژه خود فعال کنید و PROJECT_ID با شناسه پروژه خود جایگزین کنید:
```
gcloud services enable developerknowledge.googleapis.com \
  --project=PROJECT_ID
```
یک کلید API ایجاد کنید:
```
gcloud services api-keys create \
  --project=PROJECT_ID \
  --display-name="DK API Key"
```
این دستور جزئیات فراداده مربوط به کلید جدید شما را برمی‌گرداند. هر دو مقدار زیر را از خروجی دستور کپی و ذخیره کنید:
- keyString : این کلید خام API است (برای مثال، AIzaSy... ). شما این مقدار را در پیکربندی IDE خود قرار خواهید داد.
- name : این مسیر منبع کلید است (برای مثال، projects/PROJECT_ID/locations/global/keys/UNIQUE_ID ). شما از این مسیر برای محدود کردن کلید در مرحله بعدی استفاده خواهید کرد.
برای جلوگیری از استفاده غیرمجاز، کلید را به API دانش توسعه‌دهندگان محدود کنید. KEY_NAME با مسیر name کامل کپی شده از مرحله قبل جایگزین کنید:
```
gcloud services api-keys update KEY_NAME \
  --api-target=service=developerknowledge.googleapis.com
```
مهم: اگر قصد دارید از همین کلید برای فراخوانی‌های مدل عمومی کلاینت هوش مصنوعی خود استفاده کنید (برای مثال، GEMINI_API_KEY )، باید API زبان مولد را نیز مجاز کنید:
```
gcloud services api-keys update KEY_NAME \
  --api-target=service=developerknowledge.googleapis.com \
  --api-target=service=generativelanguage.googleapis.com
```

OAuth و ADC

پیش‌نیازها

قبل از پیکربندی OAuth یا ADC، مطمئن شوید که موارد زیر را دارید:

فعال کردن API

برای فعال کردن API دانش توسعه‌دهندگان در پروژه خود، دستور زیر را اجرا کنید:

gcloud services enable developerknowledge.googleapis.com \
  --project=PROJECT_ID

نوع اعتبارنامه OAuth خود را انتخاب کنید

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

مبدل آنالوگ به دیجیتال (ADC)

گوگل آنتی‌گراویتی (Google Antigravity) از ADC پشتیبانی داخلی دارد و توکن‌ها را به‌طور خودکار به‌روزرسانی می‌کند. سایر کلاینت‌های MCP می‌توانند با ارسال یک توکن حامل کوتاه‌مدت در هدر Authorization از ADC استفاده کنند:

با حساب گوگل خود احراز هویت کنید و پروژه سهمیه خود را تنظیم کنید:
```
gcloud auth application-default login \
  --project=PROJECT_ID
```
وقتی مرورگر شما باز شد، با حساب Google خود وارد شوید و مجوزهای درخواستی را اعطا کنید.
(اختیاری) اگر در حال پیکربندی یک کلاینت MCP شخص ثالث هستید که از ADC داخلی پشتیبانی نمی‌کند، یک توکن حامل (معتبر برای یک ساعت) ایجاد کنید تا در هدر Authorization کلاینت خود استفاده کنید:
```
gcloud auth application-default print-access-token
```

شناسه کلاینت OAuth

اگر دستیار هوش مصنوعی شما از جریان تعاملی OAuth استفاده می‌کند، یک شناسه و رمز کلاینت OAuth 2.0 ایجاد کنید، زیرا سرورهای MCP از راه دور گوگل از ثبت پویای کلاینت OAuth (DCR) پشتیبانی نمی‌کنند.

به صفحه برندسازی بروید و پروژه خود را انتخاب کنید. نام برنامه و ایمیل پشتیبانی کاربر را وارد کنید و روی ذخیره کلیک کنید.
به صفحه مخاطبان بروید و نوع کاربر را روی خارجی (External) تنظیم کنید.
در همان صفحه، در قسمت Test users روی Add users کلیک کنید، آدرس ایمیل گوگل خود را وارد کنید و روی Save کلیک کنید.
به صفحه مشتریان بروید، روی ایجاد مشتری کلیک کنید و نوع برنامه مورد نیاز مشتری MCP خود را انتخاب کنید:
- برای کلاینت‌های دسکتاپ که شناسه و رمز کلاینت را درخواست می‌کنند (مانند VS Code)، برنامه دسکتاپ را انتخاب کنید.
- برنامه وب را انتخاب کنید و URI تغییر مسیر کلاینت خود را برای کلاینت‌هایی که به فراخوانی‌های تغییر مسیر استاتیک OAuth نیاز دارند (مانند Cursor یا کانکتورهای سفارشی Claude Code) اضافه کنید. از URI تغییر مسیر دقیقی که کلاینت شما مستند می‌کند استفاده کنید؛ URIهای تغییر مسیر سفارشی پشتیبانی نمی‌شوند. برای URIهای تغییر مسیر خاص کلاینت، به پیکربندی MCP در یک برنامه هوش مصنوعی مراجعه کنید.
روی ایجاد کلیک کنید، سپس شناسه کلاینت و رمز کلاینت خود را کپی کنید (یا فایل اعتبارنامه‌های کلاینت JSON را دانلود کنید).

IDE یا عامل کدنویسی خود را پیکربندی کنید

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

محیط کدنویسی	روش‌های احراز هویت
گوگل ضد جاذبه	اعتبارنامه‌های گوگل (ADC) یا کلید API داخلی
کلود کد، کرسر، گیت‌هاب، کمک خلبان، کدکس	کلید API
دیگر	کلید API، توکن حامل ADC یا شناسه کلاینت OAuth 2.0

برای استفاده از توکن حامل ADC یا شناسه کلاینت OAuth 2.0 با Claude Code، Cursor، GitHub Copilot یا Codex، دستورالعمل‌های موجود در برگه Other را دنبال کنید.

بسته به الگویی که استفاده می‌کنید، متغیرهای زیر را جایگزین کنید:

کلید API ( YOUR_API_KEY ): با رشته کلید API خام خود جایگزین کنید.
شناسه پروژه ( PROJECT_ID ): آن را با شناسه پروژه Google Cloud خود جایگزین کنید.
توکن دسترسی ( ACCESS_TOKEN ): با توکن حامل از gcloud auth application-default print-access-token جایگزین کنید.

گوگل ضد جاذبه

محیط توسعه یکپارچه ضد جاذبه و افزونه‌های آن

برای پیکربندی سرور MCP در Antigravity IDE یا افزونه Antigravity (مانند VS Code)، روش احراز هویت خود را انتخاب کنید:

اعتبارنامه‌های گوگل

برای نصب سرور MCP با استفاده از تنظیمات تک کلیکی:

در پنل نمایندگان، روی منوی گزینه‌های اضافی ( ) کلیک کنید و سرورهای MCP را انتخاب کنید.
عبارت «دانش توسعه‌دهندگان» را در گوگل جستجو کنید.
روی آیکون نصب ( ) کلیک کنید. آنتی‌گراویتی به‌طور خودکار سرور را پیکربندی می‌کند و با استفاده از اعتبارنامه‌های فعال گوگل شما متصل می‌شود.

کلید API

برای پیکربندی یک کلید API در Antigravity IDE یا افزونه Antigravity:

در پنل Agent، روی منوی گزینه‌های اضافی ( ) > سرورهای MCP > مدیریت سرورهای MCP > مشاهده پیکربندی خام کلیک کنید (یا .agents/mcp_config.json را باز کنید).

پیکربندی سرور زیر را اضافه کنید:

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

رابط خط فرمان ضد جاذبه

سرور MCP را در فایل .agents/mcp_config.json پروژه خود (یا به صورت سراسری در ~/.gemini/config/mcp_config.json ) پیکربندی کنید:

اعتبارنامه‌های گوگل

{
  "mcpServers": {
    "google-developer-knowledge": {
      "httpUrl": "https://developerknowledge.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/cloud-platform"
        ]
      },
      "timeout": 30000,
      "headers": {
        "X-goog-user-project": "PROJECT_ID"
      }
    }
  }
}

کلید API

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

کلود کد

دستور زیر را در ترمینال خود اجرا کنید:

claude mcp add google-developer-knowledge \
  --transport http https://developerknowledge.googleapis.com/mcp \
  --header "X-Goog-Api-Key: YOUR_API_KEY"

مکان نما

برای پیکربندی Cursor، .cursor/mcp.json را در ریشه پروژه خود ویرایش کنید یا برای دسترسی سراسری، ~/.cursor/mcp.json را ویرایش کنید:

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

گیت‌هاب، کمک خلبان

تنظیمات فضای کاری

برای پیکربندی GitHub Copilot در VS Code برای یک فضای کاری خاص، .vscode/mcp.json را ایجاد یا ویرایش کنید:

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

تنظیمات کاربر سراسری

برای اینکه سرور در تمام فضاهای کاری VS Code در دسترس باشد، Command Palette را باز کنید، MCP: Open User Configuration را اجرا کنید و موارد زیر را به فایل mcp.json در پروفایل کاربری خود اضافه کنید:

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

کدکس

برای پیکربندی Codex CLI یا عامل Codex، پیکربندی سرور را به ~/.codex/config.toml (یا .codex/config.toml پروژه خود) اضافه کنید:

[mcp_servers.google-developer-knowledge]
  url = "https://developerknowledge.googleapis.com/mcp"
  http_headers = { "X-Goog-Api-Key" = "YOUR_API_KEY" }

دیگر

برای پیکربندی هر کلاینت MCP از راه دور دیگر (مانند JetBrains AI Assistant، Windsurf، Cline، Zed، Continue یا Claude Desktop) یا برای استفاده از توکن حامل ADC یا شناسه کلاینت OAuth 2.0 در یک کلاینت شخص ثالث، روش احراز هویت خود را انتخاب کنید:

کلید API

یک سرور انتقال HTTP با تنظیمات زیر پیکربندی کنید:

آدرس سرور : https://developerknowledge.googleapis.com/mcp
هدر HTTP : X-Goog-Api-Key: YOUR_API_KEY

الگوی پیکربندی استاندارد JSON:

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

توکن حامل ADC

اگر کلاینت MCP شما از ADC داخلی پشتیبانی نمی‌کند، می‌توانید با ارسال توکن حامل از gcloud auth application-default print-access-token و شناسه پروژه Google Cloud خود در هدرهای درخواست، با ADC احراز هویت کنید:

{
  "mcpServers": {
    "google-developer-knowledge": {
      "url": "https://developerknowledge.googleapis.com/mcp",
      "headers": {
        "Authorization": "Bearer ACCESS_TOKEN",
        "X-Goog-User-Project": "PROJECT_ID"
      }
    }
  }
}

هدر X-Goog-User-Project به مجوز serviceusage.services.use در پروژه نیاز دارد. صاحبان و ویرایشگران پروژه این مجوز را دارند. سایر کاربران به نقشی نیاز دارند که شامل آن باشد، مانند Service Usage Consumer ( roles/serviceusage.serviceUsageConsumer ).

شناسه کلاینت OAuth

برای احراز هویت با استفاده از شناسه و رمز کلاینت OAuth 2.0 مستقل:

نقطه پایانی سرور MCP را بدون هدر کلید API به پیکربندی کلاینت خود اضافه کنید:
```
{
  "mcpServers": {
    "google-developer-knowledge": {
      "url": "https://developerknowledge.googleapis.com/mcp"
    }
  }
}
```
توجه: VS Code به جای mcpServers از کلید servers سطح بالا استفاده می‌کند. سرور را به .vscode/mcp.json در پوشه‌ای که به عنوان فضای کاری خود باز می‌کنید اضافه کنید، یا MCP: Open User Configuration را از Command Palette اجرا کنید تا در همه فضاهای کاری در دسترس باشد. برای ساختار فایل VS Code، به تب GitHub Copilot مراجعه کنید و بخش headers را حذف کنید.
تنظیمات OAuth را برای کلاینت خود تکمیل کنید:
- اعلان تعاملی (مانند VS Code) : یک اعلان آزمایشی به عامل ارسال کنید. وقتی از شما پرسیده شد که ثبت نام پویای کلاینت پشتیبانی نمی‌شود، ادامه دهید و شناسه کلاینت و رمز کلاینت خود را وارد کنید، سپس با حساب گوگل خود وارد شوید.
- پیکربندی استاتیک OAuth (مانند Cursor یا Claude Code) : شناسه کلاینت OAuth، رمز کلاینت و URL تغییر مسیر خود را در تنظیمات OAuth کلاینت خود ارائه دهید. برای دستورالعمل‌های خاص کلاینت، به پیکربندی MCP در یک برنامه هوش مصنوعی مراجعه کنید.
اگر کلاینت شما از شما خواست که محدوده‌های OAuth را مشخص کنید، https://www.googleapis.com/auth/devprofiles.full_control استفاده کنید.

در این پیکربندی نیازی به مشخص کردن شناسه پروژه Google Cloud ندارید. درخواست‌ها به پروژه‌ای که شناسه کلاینت OAuth شما را دارد، نسبت داده می‌شوند.

اتصال را تأیید کنید

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

How do I list Cloud Storage buckets using the Google Cloud Python SDK?

اگر عامل search_documents یا answer_query را فراخوانی کند و اطلاعات را از مستندات گوگل برگرداند، سرور شما متصل و فعال است.

از مهارت عامل دانش توسعه‌دهنده استفاده کنید

مهارت رسمی retrieving-developer-knowledge agent را نصب کنید تا به دستیار خود بیاموزید چه زمانی و چگونه از ابزارهای اصلی ارائه شده توسط سرور Developer Knowledge MCP استفاده کند.

مهارت عامل، مجموعه‌ای از دستورالعمل‌ها است که دستیار کدنویسی هوش مصنوعی شما قبل از شروع یک کار می‌خواند. مهارت retrieving-developer-knowledge با هر دستیاری که از استاندارد مهارت‌های عامل باز پشتیبانی می‌کند، کار می‌کند و به دستیار شما در انجام موارد زیر کمک می‌کند:

ابزار مناسب را انتخاب کنید : دستیار شما را راهنمایی می‌کند تا answer_query برای سوالات و مقایسه‌های کلی «چگونه» استفاده کند، و هنگام جستجوی دقیق پرچم‌های CLI، مجوزهای IAM یا نحو کد، search_documents (با دو تا پنج کلمه کلیدی متمرکز) استفاده کند.
قبل از پاسخ دادن، خطاها را بررسی کنید : به دستیار شما می‌گوید قبل از نوشتن پاسخ، مطمئن شود که جستجوی مستندات واقعاً موفقیت‌آمیز بوده است، بنابراین خطای کلید API یا سهمیه را با فقدان مستندات اشتباه نمی‌گیرد یا به حدس زدن از داده‌های آموزشی قدیمی‌تر متوسل نمی‌شود.
بازگشت به REST API : به دستیار curl شما دستوراتی می‌دهد تا در صورت عدم پشتیبانی ویرایشگر شما از سرورهای MCP یا قطع اتصال MCP، مستقیماً با Developer Knowledge API تماس بگیرد.

مهارت عامل را نصب کنید

دستیار کدنویسی خود را برای نصب مهارت retrieving-developer-knowledge در دایرکتوری پروژه خود انتخاب کنید:

گوگل ضد جاذبه

npx skills add google/skills --skill retrieving-developer-knowledge \
  --agent=antigravity

کلود کد

npx skills add google/skills --skill retrieving-developer-knowledge \
  --agent=claude-code

مکان نما

npx skills add google/skills --skill retrieving-developer-knowledge \
  --agent=cursor

کدکس

npx skills add google/skills --skill retrieving-developer-knowledge \
  --agent=codex

دیگر

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

npx skills add google/skills --skill retrieving-developer-knowledge

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

npx skills update

برای مشاهده دستورالعمل‌های کامل مهارت و راهنماهای مرجع، به دایرکتوری retrieving-developer-knowledge در GitHub مراجعه کنید.

بهینه‌سازی پنجره زمینه و استفاده از توکن

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

برای اطمینان از پاسخ‌های سریع و مقرون‌به‌صرفه، این بهترین شیوه‌های مهندسی سریع را دنبال کنید:

مهارت عامل (توصیه شده) را نصب کنید : مهارت عامل retrieving-developer-knowledge را نصب کنید تا دستیار شما به طور خودکار ابزار جستجوی مناسب ( answer_query یا search_documents ) را انتخاب کند، از جستجوهای کلمات کلیدی کوتاه استفاده کند و فقط در صورت نیاز صفحات کامل را دانلود کند.
به بازیابی دو مرحله‌ای تکیه کنید : اجازه دهید عامل با فراخوانی search_documents شروع کند. این کار قطعه کدهای متمرکز (chunks) را برمی‌گرداند که اغلب حاوی سینتکس دقیق یا امضای API مورد نیاز شما هستند، بدون اینکه توکن‌های کل صفحه را مصرف کنید. به عامل خود دستور دهید که get_documents فقط زمانی فراخوانی کند که متن اطراف کاملاً ضروری باشد.
برای سوالات مفهومی answer_query ترجیح دهید : وقتی به یک توضیح تولید شده یا مقایسه طراحی نیاز دارید، به نماینده خود دستور دهید از answer_query استفاده کند. این ابزار بدون بازگرداندن صفحات خام کامل Markdown، مستقیماً از مجموعه دانش توسعه‌دهندگان، پاسخی تولید می‌کند.
دستورالعمل‌های خاص و محدود بنویسید : از دستورالعمل‌های کلی مانند «توضیح همه چیز در مورد فایربیس» خودداری کنید. در عوض، محصول، پلتفرم و زبان هدف را مشخص کنید:
```
How do I write a Firestore transaction in Dart with error handling?
```
قوانین سفارشی عامل را اضافه کنید : اگر از مهارت retrieving-developer-knowledge استفاده نمی‌کنید، دستورالعمل‌های سطح پروژه را به فایل‌های دستورالعمل دستیار خود (برای مثال، .cursorrules ، CLAUDE.md یا .github/copilot-instructions.md ) اضافه کنید تا واکشی خودکار تمام صفحه را محدود کنید:
```
When searching Google developer documentation, inspect search_documents
snippets first. Do not call get_documents unless the snippet lacks
necessary code context.
```

تنظیمات امنیتی و حفاظتی اختیاری

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

برای اطلاعات بیشتر در مورد امنیت و مدیریت MCP، به امنیت و ایمنی هوش مصنوعی مراجعه کنید.

از زره مدل استفاده کنید

مدل آرمور یک سرویس ابری گوگل است که برای افزایش امنیت و ایمنی برنامه‌های هوش مصنوعی شما طراحی شده است. این سرویس با غربالگری فعال درخواست‌ها و پاسخ‌های LLM، محافظت در برابر خطرات مختلف و پشتیبانی از شیوه‌های مسئولانه هوش مصنوعی کار می‌کند. چه در حال استقرار هوش مصنوعی در محیط ابری خود باشید و چه در ارائه‌دهندگان ابری خارجی، مدل آرمور می‌تواند به شما در جلوگیری از ورودی‌های مخرب، تأیید ایمنی محتوا، محافظت از داده‌های حساس، حفظ انطباق و اجرای مداوم سیاست‌های ایمنی و امنیتی هوش مصنوعی در سراسر چشم‌انداز متنوع هوش مصنوعی شما کمک کند.

وقتی Model Armor با قابلیت ثبت وقایع (logging) فعال باشد، Model Armor کل داده‌های مخرب (payload) را ثبت می‌کند. این کار ممکن است اطلاعات حساس موجود در گزارش‌های شما را افشا کند.

مسیریابی درخواست MCP به Model Armor

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

فعال کردن زره مدل

برای فعال کردن Model Armor، مراحل موجود در بخش «ادغام با سرورهای Google و Google Cloud MCP» را دنبال کنید.

پیکربندی حفاظت برای سرورهای MCP از راه دور

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

تنظیمات کف مدل زره را با فعال کردن پاکسازی MCP تنظیم کنید. برای اطلاعات بیشتر، به پیکربندی تنظیمات کف مدل زره مراجعه کنید.

به مثال دستور زیر توجه کنید:

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-floor-setting-enforcement=TRUE \
--add-integrated-services=GOOGLE_MCP_SERVER \
--google-mcp-server-enforcement-type=INSPECT_AND_BLOCK \
--enable-google-mcp-server-cloud-logging \
--malicious-uri-filter-settings-enforcement=ENABLED \
--add-rai-settings-filters='[{"confidenceLevel": "MEDIUM_AND_ABOVE", "filterType": "DANGEROUS"}]'

به جای PROJECT_ID ، شناسه پروژه گوگل کلود خود را وارد کنید.

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

INSPECT_AND_BLOCK : نوع اجرایی که محتوا را برای سرور Google MCP بررسی می‌کند و اعلان‌ها و پاسخ‌هایی را که با فیلترها مطابقت دارند، مسدود می‌کند.
ENABLED ): تنظیماتی که یک فیلتر یا الزام را فعال می‌کند.
MEDIUM_AND_ABOVE : سطح اطمینان برای تنظیمات فیلتر Responsible AI - Dangerous. می‌توانید این تنظیم را تغییر دهید، اگرچه مقادیر پایین‌تر ممکن است منجر به مثبت‌های کاذب بیشتری شود. برای اطلاعات بیشتر، به سطوح اطمینان Model Armor مراجعه کنید.

غیرفعال کردن اسکن ترافیک MCP با Model Armor

برای جلوگیری از اسکن خودکار ترافیک ورودی و خروجی سرورهای Google MCP توسط Model Armor بر اساس تنظیمات طبقه پروژه، دستور زیر را اجرا کنید:

gcloud model-armor floorsettings update \
  --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
  --remove-integrated-services=GOOGLE_MCP_SERVER

PROJECT_ID با شناسه پروژه Google Cloud جایگزین کنید. Model Armor به طور خودکار قوانین تعریف شده در تنظیمات طبقه این پروژه را بر روی هیچ ترافیک سرور Google MCP اعمال نمی‌کند.

تنظیمات و پیکربندی کلی کف Model Armor می‌تواند نه تنها بر MCP تأثیر بگذارد، بلکه بر موارد دیگری نیز تأثیر بگذارد. از آنجا که Model Armor با سرویس‌هایی مانند Vertex AI ادغام می‌شود، هرگونه تغییری که در تنظیمات کف ایجاد کنید، می‌تواند بر اسکن ترافیک و رفتارهای ایمنی در تمام سرویس‌های یکپارچه، و نه فقط MCP، تأثیر بگذارد.

تنظیمات زره مدل را تنظیم کنید

اگر از Model Armor برای محافظت از برنامه خود استفاده می‌کنید، ممکن است برای برخی از پرس‌وجوها با خطای 403 PERMISSION_DENIED مواجه شوید. از آنجا که سرور Developer Knowledge MCP فقط اسناد عمومی را از منابع معتبر گوگل برمی‌گرداند، توصیه می‌کنیم فیلترهای Prompt Injection و Jailbreak (PIJB) را روی سطح اطمینان HIGH_AND_ABOVE تنظیم کنید تا موارد مثبت کاذب کاهش یابد. اگر مورد استفاده شما شامل ابزارهای دیگری نیست که به داده‌های خصوصی یا حساس دسترسی دارند، می‌توانید غیرفعال کردن فیلترهای PIJB را نیز در نظر بگیرید.

عیب‌یابی

اگر در اتصال یا پرس و جو از سرور Developer Knowledge MCP با مشکل مواجه شدید، مشکل یا پیام خطای خود را در جداول زیر پیدا کنید.

خطاهای راه‌اندازی و اتصال

علامت یا خطا	علت احتمالی	وضوح تصویر
`404 NOT_FOUND` در نقطه پایانی `/mcp`	API برای پروژه شما فعال نیست.	API دانش توسعه‌دهنده را در کنسول Google Cloud فعال کنید یا `gcloud services enable developerknowledge.googleapis.com` .
`403 PERMISSION_DENIED` : `Developer Knowledge API has not been used`	رابط برنامه‌نویسی کاربردی (API) دانش توسعه‌دهندگان در پروژه گوگل کلود فعال نیست.	API را در کنسول Google Cloud فعال کنید یا `gcloud services enable developerknowledge.googleapis.com` .
ابزارهای MCP وجود ندارند یا اتصال برقرار نمی‌شود	ابزار کدنویسی شما از سرورهای HTTP MCP از راه دور پشتیبانی نمی‌کند یا نمی‌تواند به سرور متصل شود.	مهارت `retrieving-developer-knowledge` agent را نصب کنید، که به دستیار شما می‌گوید چگونه وقتی ابزارهای MCP در دسترس نیستند، با استفاده از `curl` به نقاط انتهایی Developer Knowledge API REST بازگردد.

خطاهای کلید API

علامت یا خطا	علت احتمالی	وضوح تصویر
`400 Bad Request: API key not valid`	رشته کلید API وجود ندارد، نامعتبر است یا ناقص شکل گرفته است.	تأیید کنید که کلید API به درستی کپی شده و در شیء `headers` با کلید `X-Goog-Api-Key` پیکربندی شده است. کلید API را به عنوان پارامتر پرس و جو در URL ارسال نکنید.
`403 PERMISSION_DENIED: API target restriction`	فهرست محدودیت‌های کلید API، API دانش توسعه‌دهندگان را شامل نمی‌شود.	محدودیت‌های کلید API خود را در صفحه اعتبارنامه‌ها در کنسول Google Cloud به‌روزرسانی کنید تا شامل API دانش توسعه‌دهندگان شود.

خطاهای OAuth و ADC

علامت یا خطا	علت احتمالی	وضوح تصویر
`401 UNAUTHENTICATED` یا مفقود است.	اعتبارنامه‌های پیش‌فرض برنامه یا توکن‌های حامل ADC منقضی شده یا مقداردهی اولیه نشده‌اند.	برای به‌روزرسانی اعتبارنامه‌های محلی، `gcloud auth application-default login --project=PROJECT_ID` را اجرا کنید، یا برای تولید یک توکن حامل جدید `gcloud auth application-default print-access-token` اجرا کنید.
`403 PERMISSION_DENIED` : `API requires a quota project, which is not set by default`	این درخواست از یک توکن حامل ADC بدون هدر `X-Goog-User-Project` استفاده می‌کند.	هدر `X-Goog-User-Project` را به همراه شناسه پروژه Google Cloud خود به پیکربندی کلاینت MCP خود اضافه کنید.
`403 PERMISSION_DENIED` با هدر `X-Goog-User-Project`	حساب کاربری شما فاقد مجوز `serviceusage.services.use` در پروژه ذکر شده در هدر است.	از یک مدیر پروژه بخواهید که نقش مصرف‌کننده‌ی استفاده از سرویس ( `roles/serviceusage.serviceUsageConsumer` ) را به شما اعطا کند.
`403 access_denied` / "دسترسی مسدود شد: خطای مجوز"	صفحه رضایت OAuth شما در حالت آزمایشی از نوع کاربر خارجی استفاده می‌کند و حساب شما به عنوان کاربر آزمایشی فهرست نشده است.	در کنسول Google Cloud > Auth Platform > Audience ، آدرس ایمیل فعال گوگل خود را در قسمت Test users اضافه کنید.
خطای کلاینت OAuth یا آدرس تغییر مسیر نامعتبر	کلاینت OAuth با نوع برنامه‌ای پشتیبانی نشده ایجاد شده یا URI تغییر مسیر ندارد.	برای کلاینت‌هایی که اعلان‌های تعاملی دارند (مانند VS Code) از برنامه دسکتاپ یا برای کلاینت‌هایی که URI ریدایرکت مجاز کلاینت شما را دارند (مانند Cursor یا Claude Code) از برنامه وب استفاده کنید.

خطاهای فیلتر سهمیه‌بندی و ایمنی

علامت یا خطا	علت احتمالی	وضوح تصویر
`429 RESOURCE_EXHAUSTED`	شما به سقف سهمیه پروژه خود رسیده‌اید.	میزان استفاده خود را در صفحه سهمیه‌های API دانش توسعه‌دهندگان در کنسول Google Cloud بررسی کنید. برای کسب اطلاعات در مورد محدودیت‌ها و درخواست افزایش، به سهمیه API دانش توسعه‌دهندگان مراجعه کنید.
`403 PERMISSION_DENIED` با زره مدل	یک خطای مثبت از فیلتر PIJB مدل آرمور، یک پرس‌وجوی امن را مسدود کرد.	در تنظیمات الگوی Model Armor، ضریب اطمینان فیلتر PIJB را روی `HIGH_AND_ABOVE` تنظیم کنید.

مستندات گنجانده شده

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

محدودیت‌های شناخته‌شده

فقط اسناد عمومی : سرور فقط اسناد عمومی موجود در مرجع Corpus را فهرست‌بندی می‌کند. اسناد داخلی، مخازن خصوصی و منابع شخص ثالث شامل نمی‌شوند.
زبان انگلیسی : سرور مستندات را فقط به زبان انگلیسی فهرست‌بندی و برمی‌گرداند.
کنترل‌های وابستگی به شبکه و سرویس VPC : از آنجا که سرور Developer Knowledge MCP یک سرویس میزبانی شده از راه دور است، کلاینت شما باید برای دسترسی به https://developerknowledge.googleapis.com به شبکه متصل باشد.
- درون شبکه‌های Google Cloud VPC : نیازی به خروجی اینترنت عمومی نیست. شما می‌توانید بدون آدرس‌های IP خارجی یا Cloud NAT و با مسیریابی ترافیک با استفاده از private.googleapis.com Google Access ( developerknowledge.googleapis.com / 199.36.153.8/30 ) یا یک نقطه پایانی Private Service Connect (PSC) که بسته all-apis را هدف قرار می‌دهد، به developerknowledge.googleapis.com به صورت خصوصی دسترسی پیدا کنید.
- کنترل‌های سرویس VPC (VPC-SC) : developerknowledge.googleapis.com در نقاط پایانی Restricted VIP ( restricted.googleapis.com / 199.36.153.4/30 ) یا PSC vpc-sc پشتیبانی نمی‌شود. اگر VPC شما *.googleapis.com را به restricted.googleapis.com مسیریابی می‌کند، یک سیاست پاسخ Cloud DNS خاص یا رکورد DNS خصوصی برای developerknowledge.googleapis.com پیکربندی کنید تا به private.googleapis.com ( 199.36.153.8/30 ) تبدیل شود.

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

قابلیت‌های سرور MCP

روش احراز هویت خود را انتخاب کنید

کلید API

پیش‌نیازها

فعال کردن API و ایجاد کلید API

کنسول ابری گوگل

رابط خط فرمان جی‌کلاود

OAuth و ADC

پیش‌نیازها

فعال کردن API

نوع اعتبارنامه OAuth خود را انتخاب کنید

مبدل آنالوگ به دیجیتال (ADC)

شناسه کلاینت OAuth

IDE یا عامل کدنویسی خود را پیکربندی کنید

گوگل ضد جاذبه

محیط توسعه یکپارچه ضد جاذبه و افزونه‌های آن

اعتبارنامه‌های گوگل

کلید API

رابط خط فرمان ضد جاذبه

اعتبارنامه‌های گوگل

کلید API

کلود کد

مکان نما

گیت‌هاب، کمک خلبان

تنظیمات فضای کاری

تنظیمات کاربر سراسری

کدکس

دیگر

کلید API

توکن حامل ADC

شناسه کلاینت OAuth

اتصال را تأیید کنید

از مهارت عامل دانش توسعه‌دهنده استفاده کنید

مهارت عامل را نصب کنید

گوگل ضد جاذبه

کلود کد

مکان نما

کدکس

دیگر

بهینه‌سازی پنجره زمینه و استفاده از توکن

تنظیمات امنیتی و حفاظتی اختیاری

از زره مدل استفاده کنید

مسیریابی درخواست MCP به Model Armor

فعال کردن زره مدل

پیکربندی حفاظت برای سرورهای MCP از راه دور

غیرفعال کردن اسکن ترافیک MCP با Model Armor

تنظیمات زره مدل را تنظیم کنید

عیب‌یابی

خطاهای راه‌اندازی و اتصال

خطاهای کلید API

خطاهای OAuth و ADC

خطاهای فیلتر سهمیه‌بندی و ایمنی

مستندات گنجانده شده

محدودیت‌های شناخته‌شده

به سرور MCP دانش توسعه‌دهندگان متصل شوید