‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

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

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

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

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

سرور Google Developer Knowledge MCP سه ابزار اصلی را برای دستیار کدنویسی هوش مصنوعی شما فراهم می‌کند:

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

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

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

روش اصالت‌سنجی را انتخاب کنید

سرور MCP «دانش توسعه‌دهنده» بسته به محیط توسعه و دستیار هوش مصنوعی شما از دو رویکرد اصالت‌سنجی پشتیبانی می‌کند:

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

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

برگه‌ای را برای ایجاد اطلاعات اعتباری انتخاب کنید:

کلید میانای API

پیش‌نیازها

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

پروژه Google Cloud.
«میانای خط فرمان gcloud» نصب شده باشد (اگر از خط فرمان پیکربندی می‌کنید).

فعال کردن میانای برنامه‌سازی کاربردی و ایجاد کلید میانای برنامه‌سازی کاربردی

می‌توانید بااستفاده از کنسول Google Cloud یا gcloud CLI کلید API تولید کنید:

Google Cloud Console

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

gcloud CLI

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

OAuth و ADC

پیش‌نیازها

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

فعال کردن میانای برنامه‌سازی کاربردی

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

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

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

رویکرد اطلاعات اعتباری موردنیاز ابزارتان را انتخاب کنید:

ADC

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

با «حساب Google» خود اصالت‌سنجی کنید و پروژه سهمیه‌تان را تنظیم کنید:
```
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 از دور Google از «ثبت کارخواه پویا» (DCR) در OAuth پشتیبانی نمی‌کنند.

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

دامنه‌های OAuth

سرور MCP «دانش توسعه‌دهنده» دامنه‌های OAuth زیر را می‌پذیرد:

https://www.googleapis.com/auth/cloud-platform: گستره پیش‌فرضی که توسط «اعتبارنامه‌های پیش‌فرض برنامه» (ADC) و gcloud CLI استفاده می‌شود.
‫https://www.googleapis.com/auth/devprofiles.full_control: گستره مورداستفاده برای جریان‌های رضایت شناسه کارخواه OAuth 2.0 و کشف سرور MCP.
‫https://www.googleapis.com/auth/developerprofiles.readonly: محدوده فقط خواندنی برای حساب‌های خدماتی و اطلاعات اعتباری که به صفحه کسب رضایت OAuth کاربر نهایی نیاز ندارند پشتیبانی می‌شود.

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

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

محیط کدنویسی	روش‌های اصالت‌سنجی
Google Antigravity	اعتبارنامه Google داخلی (ADC) یا کلید میانای برنامه‌سازی کاربردی (API)
Claude Code،‏ Cursor،‏ GitHub Copilot،‏ Codex	کلید میانای API
غیره	کلید میانای API، رمزیاب دارنده ADC، یا شناسه کارخواه OAuth 2.0

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

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

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

Google Antigravity

Antigravity IDE و افزونه‌ها

برای پیکربندی سرور MCP در Antigravity IDE یا افزونه Antigravity (مثلاً در VS Code)، روش اصالت‌سنجی خود را انتخاب کنید:

اعتبارنامه‌های Google

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

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

کلید میانای API

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

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

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

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

Antigravity CLI

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

اعتبارنامه‌های Google

{
  "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 Code

فرمان زیر را در پایانه‌تان اجرا کنید:

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

تنظیمات Workspace

برای پیکربندی 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، «پالت فرمان» را باز کنید، 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 در پروژه نیاز دارد. مالکان پروژه و تدوین‌گران این اجازه را دارند. کاربران دیگر به نقشی نیاز دارند که شامل آن باشد، مثل «مصرف‌کننده استفاده از سرویس» (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 (ام‌سی‌پی: باز کردن پیکربندی کاربر) را از «پالت فرمان» اجرا کنید تا در همه فضاهای کاری دردسترس قرار گیرد. برای ساختار فایل VS Code، به زبانه GitHub Copilot مراجعه کنید و بخش headers را حذف کنید.
راه‌اندازی OAuth را برای کارخواهتان تکمیل کنید:
- پیام‌واره تعاملی (مانند VS Code): پیام‌واره آزمایشی به نماینده ارسال کنید. وقتی پیام‌واره‌ای دریافت کردید که می‌گوید «ثبت کارخواه پویا» پشتیبانی نمی‌شود، ادامه دهید و شناسه کارخواه و رمز کارخواه را وارد کنید، سپس با «حساب Google» خود به سیستم وارد شوید.
- پیکربندی OAuth ایستا (مثل Cursor یا Claude Code): شناسه کارخواه OAuth، رمز کارخواه، و نشانی وب هدایت را در تنظیمات 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 را فراخوانی کند و اطلاعاتی از اسناد Google برگرداند، سرور شما متصل و فعال است.

استفاده از مهارت نماینده «دانش توسعه‌دهنده»

مهارت عامل رسمی retrieving-developer-knowledge را نصب کنید تا به دستیارتان آموزش دهید که چه زمانی و چگونه از ابزارهای اصلی ارائه‌شده توسط سرور MCP «دانش توسعه‌دهنده» استفاده کند.

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

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

نصب مهارت عامل

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

Google Antigravity

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

کد Claude

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

مکان‌نما

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

Codex

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 بررسی کنید.

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

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

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

مهارت نماینده را نصب کنید (توصیه می‌شود): مهارت نماینده retrieving-developer-knowledge را نصب کنید تا دستیارتان به‌طور خودکار ابزار جستجوی مناسب (answer_query یا search_documents) را انتخاب کند، از جستجوهای کلیدواژه کوتاه استفاده کند، و فقط درصورت نیاز صفحه‌های کامل را بارگیری کند.
به بازیابی دومرحله‌ای تکیه کنید: اجازه دهید عامل با فراخوانی search_documents شروع کند. این کار باعث برگرداندن گزیده‌های کانونی (تکه‌هایی) می‌شود که اغلب حاوی دستورگان دقیق یا امضای میانای برنامه‌سازی کاربردی موردنیاز شما است بدون اینکه برای کل صفحه از نشان استفاده کند. به نماینده‌تان دستور دهید get_documents را فقط زمانی فراخوانی کند که بافت پیرامون کاملاً ضروری باشد.
برای پرسش‌های مفهومی، answer_query را ترجیح دهید: وقتی به توضیح تولیدشده یا مقایسه طراحی نیاز دارید، کارگزارتان را راهنمایی کنید از answer_query استفاده کند. این ابزار مستقیماً از مجموعه Developer Knowledge پاسخ تولید می‌کند، بدون اینکه صفحات کامل Markdown خام را برگرداند.
پیام‌واره‌های خاص و محدود بنویسید: از پیام‌واره‌های بیش‌ازحد کلی مانند «همه Firebase را توضیح بده» اجتناب کنید. درعوض، محصول، پلاتفرم، و زبان هدف را مشخص کنید:
```
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، به امنیت و ایمنی هوش مصنوعی مراجعه کنید.

استفاده از Model Armor

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

وقتی Model Armor با ثبت گزارش فعال فعال باشد، Model Armor کل بارداده را ثبت می‌کند. این کار ممکن است اطلاعات حساس را در گزارش‌هایتان آشکار کند.

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

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

فعال کردن Model Armor

برای فعال کردن «زره مدل»، مراحل ادغام با سرورهای Google و Google Cloud MCP را دنبال کنید.

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

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

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

فرمان نمونه زیر را ببینید:

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 را با شناسه پروژه Google Cloud خودتان جایگزین کنید.

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

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

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

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

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

اگر از Model Armor برای محافظت از برنامه‌تان استفاده می‌کنید، ممکن است برای برخی پُرسمان‌ها با خطاهای 403 PERMISSION_DENIED مواجه شوید. چون سرور MCP «دانش توسعه‌دهنده» فقط اسناد عمومی را از منابع معتبر Google برمی‌گرداند، توصیه می‌کنیم فیلترهای «تزریق پیام‌واره» و «قفل‌شکنی» (PIJB) را روی سطح اطمینان HIGH_AND_ABOVE تنظیم کنید تا موارد مثبت کاذب کاهش یابد. اگر مورد استفاده شما شامل ابزارهای دیگری که به داده‌های خصوصی یا حساس دسترسی دارند نمی‌شود، می‌توانید فیلترهای PIJB را نیز غیرفعال کنید.

عیب‌یابی

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

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

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

خطاهای کلید میانای برنامه‌سازی کاربردی

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

خطاهای OAuth و ADC

نشانه یا خطا	علت احتمالی	وضوح
`401 UNAUTHENTICATED` یا اعتبارنامه ADC موجود نیست	اطلاعات اعتباری پیش‌فرض برنامه یا کد حامل 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 > مخاطب، نشانی ایمیل Google فعال خود را در بخش کاربران آزمایشی اضافه کنید.
خطای کارخواه OAuth یا URI هدایت نامعتبر	کارخواه OAuth با نوع برنامه پشتیبانی‌نشده یا بدون URI تغییرمسیر ایجاد شده است.	از برنامه میزکار برای مشتریانی که پیام‌واره‌های تعاملی دارند (مثل VS Code) یا از برنامه وب با نشانی وب تغییر مسیر مجاز مشتری‌تان (مثل Cursor یا Claude Code) استفاده کنید.

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

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

اسناد موجود

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

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

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

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

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

روش اصالت‌سنجی را انتخاب کنید

کلید میانای API

پیش‌نیازها

فعال کردن میانای برنامه‌سازی کاربردی و ایجاد کلید میانای برنامه‌سازی کاربردی

Google Cloud Console

gcloud CLI

OAuth و ADC

پیش‌نیازها

فعال کردن میانای برنامه‌سازی کاربردی

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

ADC

شناسه کارخواه OAuth

دامنه‌های OAuth

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

Google Antigravity

Antigravity IDE و افزونه‌ها

اعتبارنامه‌های Google

کلید میانای API

Antigravity CLI

اعتبارنامه‌های Google

کلید میانای API

Claude Code

مکان‌نما

GitHub Copilot

تنظیمات Workspace

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

کدکس

غیره

کلید میانای API

کد حاملی ADC

شناسه کارخواه OAuth

درستی‌سنجی اتصال

استفاده از مهارت نماینده «دانش توسعه‌دهنده»

نصب مهارت عامل

Google Antigravity

کد Claude

مکان‌نما

Codex

غیره

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

پیکربندی‌های اختیاری ایمنی و امنیت

استفاده از Model Armor

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

فعال کردن Model Armor

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

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

تنظیم کردن تنظیمات Model Armor

عیب‌یابی

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

خطاهای کلید میانای برنامه‌سازی کاربردی

خطاهای OAuth و ADC

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

اسناد موجود

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

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