کیت‌های توسعه نرم‌افزار (SDK) «پروتکل بافتار مدل» (MCP) رسمی به برنامه‌ها و عامل‌های هوش مصنوعی شما امکان می‌دهند به‌صورت برنامه‌نویسی‌شده به سرور MCP «دانش توسعه‌دهنده» متصل شوند. وقتی کارگزار سفارشی، سرویس زیرینه، یا سرور MCP خودتان را می‌سازید که باید اسناد رسمی توسعه‌دهندگان Google را جستجو و بازیابی کند، به‌جای پیکربندی IDE موجود یا دستیار کدنویسی، از MCP SDK استفاده کنید.
در این راهنما، با نحوه انجام کارهای زیر آشنا می‌شوید:
- کیت توسعه نرم‌افزار کارخواه MCP را برای Python یا TypeScript نصب کنید.
- با کلید API یا «اعتبارنامه‌های پیش‌فرض برنامه» (ADC) به سرور MCP «دانش توسعه‌دهنده» متصل شوید.
- ابزارهای
search_documents،get_documents، وanswer_queryرا فراخوانی کنید. - خطاهای اصالت‌سنجی، سهمیه، و ابزار را مدیریت کنید.
قبل‌از شروع
قبل‌از شروع، بخش‌های زیر را تکمیل کنید.
فعال کردن میانای برنامه‌سازی کاربردی و ایجاد اعتبارنامه‌ها
Developer Knowledge API را در پروژه Google Cloud خود فعال کنید و اعتبارنامه‌های روش اصالت‌سنجی‌تان را ایجاد کنید. برای دستورالعمل‌های گام‌به‌گام، به انتخاب روش اصالت‌سنجی مراجعه کنید.
نمونه‌های این راهنما از کلید میانای API استفاده می‌کنند. برای استفاده از ADC، به اصالت‌سنجی با «اعتبارنامه‌های پیش‌فرض برنامه» مراجعه کنید.
نصب کیت توسعه نرم‌افزار MCP
زبان برنامه‌نویسی‌تان را برای نصب کیت توسعه نرم‌افزار کارخواه MCP انتخاب کنید:
Python
این راهنما از نسخه ۲ کیت توسعه نرم‌افزار Python برای MCP استفاده می‌کند که به Python نسخه ۳.۱۰ یا جدیدتر نیاز دارد. نسخه 1.x از کیت توسعه نرم‌افزار از نام‌های کلاس و تابع متفاوتی استفاده می‌کند، بنابراین این نمونه‌ها با آن کار نمی‌کنند:
pip install --upgrade "mcp>=2"
TypeScript
این راهنما از MCP TypeScript SDK با Node.js 18 یا جدیدتر استفاده می‌کند:
npm install @modelcontextprotocol/sdk
تنظیم کلید میانای برنامه‌سازی کاربردی
برای جلوگیری از کدنویسی ثابت کلید میانای برنامه‌سازی کاربردی در کد منبع، آن را در متغیر محیطی ذخیره کنید. YOUR_API_KEY را با کلید میانای برنامه‌سازی کاربردی خودتان جایگزین کنید:
export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"
به سرور متصل شوید
سرور MCP «دانش توسعه‌دهنده» از انتقال HTTP جاری‌شدنی در نقطه پایانی زیر استفاده می‌کند:
https://developerknowledge.googleapis.com/mcp
برای اصالت‌سنجی، کلید میانای برنامه‌سازی کاربردی خود را در سرصفحه X-Goog-Api-Key HTTP در هر درخواست ارسال کنید. کلید API را به‌عنوان پارامتر پُرسمان نشانی وب ارسال نکنید.
مثال زیر به سرور متصل می‌شود و ابزارهای دردسترس را فهرست می‌کند:
Python
import asyncio
import os
from mcp import Client
from mcp.client.streamable_http import (
create_mcp_http_client,
streamable_http_client,
)
MCP_URL = "https://developerknowledge.googleapis.com/mcp"
async def main() -> None:
headers = {"X-Goog-Api-Key": os.environ["DEVELOPERKNOWLEDGE_API_KEY"]}
async with create_mcp_http_client(headers=headers) as http_client:
transport = streamable_http_client(MCP_URL, http_client=http_client)
async with Client(transport) as client:
tools = await client.list_tools()
names = ", ".join(tool.name for tool in tools.tools)
print("Available tools:", names)
if __name__ == "__main__":
asyncio.run(main())
TypeScript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import {
StreamableHTTPClientTransport,
} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const apiKey = process.env.DEVELOPERKNOWLEDGE_API_KEY;
if (!apiKey) {
throw new Error('Set the DEVELOPERKNOWLEDGE_API_KEY variable.');
}
const transport = new StreamableHTTPClientTransport(
new URL('https://developerknowledge.googleapis.com/mcp'),
{ requestInit: { headers: { 'X-Goog-Api-Key': apiKey } } },
);
const client = new Client({ name: 'my-docs-agent', version: '1.0.0' });
await client.connect(transport);
const { tools } = await client.listTools();
console.log('Available tools:', tools.map((tool) => tool.name).join(', '));
await client.close();
اگر اتصال موفقیت‌آمیز باشد، برونداد سه ابزار را فهرست می‌کند:
Available tools: search_documents, answer_query, get_documents
بقیه مثال‌های این راهنما در کارخواه متصل از این بخش اجرا می‌شوند. نمونه‌های TypeScript از await سطح بالا استفاده می‌کنند، بنابراین آن‌ها را به‌عنوان
مدول‌های ES اجرا کنید (برای مثال، با npx tsx index.ts).
فراخوانی ابزارها
هر ابزار نتیجه خود را به‌عنوان محتوای ساختاریافته‌ای که با طرح‌واره خروجی ابزار مطابقت دارد برمی‌گرداند، بنابراین می‌توانید به‌جای تجزیه کردن نوشتار، فیلدها را مستقیماً بخوانید. برای طرحوارههای کامل ورودی و خروجی، به مرجع MCP مراجعه کنید.
جستجوی سند
search_documents را با رشته query فراخوانی کنید تا مرتبط‌ترین بخش‌های سند بازیابی شود. هر نتیجه حاوی بخش content وparent
نام منبع سندی است که از آن آمده است:
Python
search = await client.call_tool(
"search_documents",
{"query": "How do I create a Cloud Storage bucket?"},
)
results = search.structured_content["results"]
for chunk in results[:3]:
print(f"{chunk['parent']}\n{chunk['content'][:200]}...\n")
TypeScript
const search = await client.callTool({
name: 'search_documents',
arguments: { query: 'How do I create a Cloud Storage bucket?' },
});
const { results } = search.structuredContent as {
results: { parent: string; id: string; content: string }[];
};
for (const chunk of results.slice(0, 3)) {
console.log(`${chunk.parent}\n${chunk.content.slice(0, 200)}...\n`);
}
بازیابی اسناد کامل
اگر یک بخش حاوی زمینه کافی نباشد، یک یا چند مقدار parent را به get_documents ارسال کنید تا محتوای کامل Markdown هر صفحه را بازیابی کنید. می‌توانید
در یک تماس حداکثر ۲۰ سند درخواست کنید. چون چند بخش می‌تواند از یک سند باشد، ابتدا مقادیر تکراری parent را بردارید:
Python
names = list(dict.fromkeys(chunk["parent"] for chunk in results[:3]))
get = await client.call_tool("get_documents", {"names": names})
for document in get.structured_content["documents"]:
print(f"{document['title']} ({document['uri']})")
print(document["content"])
TypeScript
const names = [...new Set(results.slice(0, 3).map((c) => c.parent))];
const get = await client.callTool({
name: 'get_documents',
arguments: { names },
});
const { documents } = get.structuredContent as {
documents: {
name: string;
uri: string;
title: string;
content: string;
}[];
};
for (const document of documents) {
console.log(`${document.title} (${document.uri})`);
console.log(document.content);
}
اسناد کامل می‌تواند بزرگ باشد، بنابراین فقط زمانی با get_documents تماس بگیرید که
تکه‌های جستجو کافی نباشد. برای کسب اطلاعات بیشتر، به
بهینه‌سازی پنجره بافت و استفاده از شناسه مراجعه کنید.
تولید پاسخ
با answer_query تماس بگیرید تا پاسخی مبتنی بر
مجموعه داده «دانش توسعه‌دهندگان» تولید کند. نتیجه
شامل answerText و references استفاده‌شده برای تولید آن است:
Python
answer = await client.call_tool(
"answer_query",
{"query": "How do I create a Cloud Storage bucket?"},
)
print(answer.structured_content["answerText"])
for reference in answer.structured_content["references"]:
print(reference)
TypeScript
const answer = await client.callTool({
name: 'answer_query',
arguments: { query: 'How do I create a Cloud Storage bucket?' },
});
const { answerText, references } = answer.structuredContent as {
answerText: string;
references: string[];
};
console.log(answerText);
console.log(references.join('\n'));
فیلد references حاوی نام‌های منبع سند است که می‌توانید به
get_documents منتقل کنید. ممکن است یک سند بیش‌از یک بار نشان داده شود، بنابراین قبل‌از بازیابی اسناد، موارد تکراری را بردارید. سهمیه ابزار answer_query
کمتر از ابزارهای دیگر است. برای کسب اطلاعات بیشتر، به
سهمیه و محدودیت‌ها مراجعه کنید.
اصالت‌سنجی با «اعتبارنامه‌های پیش‌فرض برنامه»
به‌جای کلید میانای برنامه‌سازی کاربردی، می‌توانید با اعتبارنامه‌های پیش‌فرض برنامه (ADC) اصالت‌سنجی کنید. ADC درطول توسعه محلی با اطلاعات اعتباری کاربر شما و وقتی کدتان در Google Cloud اجرا می‌شود با حساب‌های سرویس کار می‌کند.
وقتی از ADC استفاده می‌کنید، سرصفحه‌های زیر را در هر درخواست ارسال کنید:
-
Authorization: کد دسترسیBearerOAuth 2.0 با محدودهhttps://www.googleapis.com/auth/cloud-platform. -
X-Goog-User-Project: شناسه پروژه‌ای که Developer Knowledge API در آن فعال است و صورت‌حساب سهمیه برای آن صادر می‌شود. حساب شما باید اجازهserviceusage.services.useرا در این پروژه داشته باشد.
نمودارهای دسترسی منقضی می‌شوند، بنابراین سرویس‌گیرنده‌های طولانی‌مدت باید آن‌ها را بازآوری کنند. نمونه‌های زیر از کتابخانه‌های اصالت‌سنجی Google برای افزودن یک کد فعلی به هر درخواست استفاده می‌کنند.
با دنبال کردن مراحل موجود در برگه ADC در انتخاب نوع اطلاعات کاربری OAuth، ADC را برای توسعه محلی راه‌اندازی کنید.
متغیر محیط
GOOGLE_CLOUD_PROJECTرا روی پروژه‌ای تنظیم کنید که میانای برنامه‌سازی کاربردی «دانش توسعه‌دهنده» در آن فعال است. نمونه‌ها این شناسه پروژه را در سرایندX-Goog-User-Projectارسال می‌کنند:export GOOGLE_CLOUD_PROJECT="PROJECT_ID"کتابخانه اصالت‌سنجی Google را برای زبان خود نصب کنید:
Python
pip install --upgrade google-auth requestsTypeScript
npm install google-auth-libraryایجاد کارخواه با ADC:
Python
import os import google.auth import google.auth.transport.requests import httpx2 # Installed automatically with mcp>=2 from mcp import Client from mcp.client.streamable_http import ( create_mcp_http_client, streamable_http_client, ) MCP_URL = "https://developerknowledge.googleapis.com/mcp" class GoogleCredentialsAuth(httpx2.Auth): """Adds a current ADC access token and quota project to requests.""" def __init__(self, project_id: str) -> None: self.credentials, _ = google.auth.default( scopes=["https://www.googleapis.com/auth/cloud-platform"] ) self.project_id = project_id def auth_flow(self, request): if not self.credentials.valid: self.credentials.refresh( google.auth.transport.requests.Request() ) request.headers["Authorization"] = ( f"Bearer {self.credentials.token}" ) request.headers["X-Goog-User-Project"] = self.project_id yield request async def main() -> None: auth = GoogleCredentialsAuth(os.environ["GOOGLE_CLOUD_PROJECT"]) async with create_mcp_http_client(auth=auth) as http_client: transport = streamable_http_client( MCP_URL, http_client=http_client ) async with Client(transport) as client: ...TypeScript
import { GoogleAuth } from 'google-auth-library'; import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { StreamableHTTPClientTransport, } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; const auth = new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/cloud-platform', }); const projectId = process.env.GOOGLE_CLOUD_PROJECT; if (!projectId) { throw new Error('Set the GOOGLE_CLOUD_PROJECT variable.'); } const transport = new StreamableHTTPClientTransport( new URL('https://developerknowledge.googleapis.com/mcp'), { // Add a current access token and the quota project to each request. fetch: async (url, init) => { const headers = new Headers(init?.headers); for (const [name, value] of await auth.getRequestHeaders()) { headers.set(name, value); } headers.set('X-Goog-User-Project', projectId); return fetch(url, { ...init, headers }); }, }, ); const client = new Client({ name: 'my-docs-agent', version: '1.0.0' }); await client.connect(transport);
مدیریت کردن خطاها
خطاهای سرور Developer Knowledge MCP به دو روش به کد شما می‌رسند:
- خطاهای درخواست: خطاهای اصالت‌سنجی، اجازه، و سهمیه با وضعیت خطای HTTP، مانند
400،403، یا429برگردانده می‌شوند. کیت‌های توسعه نرم‌افزار این موارد را به‌عنوان استثنا مطرح می‌کنند:MCPErrorدر Python وStreamableHTTPErrorدر TypeScript. این استثناها را در تماس‌های ابزارتان درنظر بگیرید. - خطاهای ابزار: وقتی ابزاری اجرا می‌شود اما نمی‌تواند درخواست را تکمیل کند،
نتیجه دارای
is_error(Python) یاisError(TypeScript) تنظیم‌شده رویtrueاست، و فیلدcontentحاوی شرح نوشتاری مشکل است. پیش‌از خواندن محتوای ساختاریافته، این فیلد را بررسی کنید.
مثال زیر هر دو نوع خطا را مدیریت می‌کند:
Python
from mcp import MCPError
try:
result = await client.call_tool(
"search_documents", {"query": "Cloud Storage buckets"}
)
except MCPError as error:
print(f"Request failed ({error.code}): {error.message}")
else:
if result.is_error:
print("Tool error:", result.content)
else:
results = result.structured_content["results"]
TypeScript
import {
StreamableHTTPError,
} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
try {
const result = await client.callTool({
name: 'search_documents',
arguments: { query: 'Cloud Storage buckets' },
});
if (result.isError) {
console.error('Tool error:', result.content);
} else {
const { results } = result.structuredContent as {
results: { parent: string; id: string; content: string }[];
};
}
} catch (error) {
if (error instanceof StreamableHTTPError) {
console.error(`Request failed (${error.code}): ${error.message}`);
} else {
throw error;
}
}
اگر answer_query خطای سهمیه (429 RESOURCE_EXHAUSTED) برگرداند، به search_documents که سهمیه بالاتری دارد برگردید. برای راهبردهای تکرار،
ازجمله عقب‌نشینی نمایی، به
مدیریت سهمیه و رسیدگی به خطا مراجعه کنید.
برای دلایل رایج خطاهای اصالت‌سنجی، به
خطاهای کلید میانای برنامه‌سازی کاربردی و
خطاهای OAuth و ADC مراجعه کنید.
قدم بعدی چیست
- طرحوارههای کامل ابزار را در مرجع MCP کاوش کنید.
- ببینید کدام محصولات در مرجع مجموعه نمایه‌سازی شده‌اند.
- «میانای برنامه‌سازی کاربردی دانش توسعه‌دهنده» را مستقیماً با کتابخانه‌های مشتری فراخوانی کنید.