تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

الاتصال بخادم MCP الخاص بـ Developer Knowledge باستخدام حِزم تطوير البرامج (SDK) الخاصة بـ MCP

تتيح حزم SDK الرسمية لـ بروتوكول سياق النموذج (MCP) لتطبيقاتك الخاصة وعملاء الذكاء الاصطناعي الاتصال بخادم MCP الخاص بـ "معارف المطوّرين" آليًا. استخدِم حزمة تطوير البرامج (SDK) لبروتوكول سياق النموذج (MCP) عند إنشاء وكيل مخصّص أو خدمة الخلفية أو خادم بروتوكول سياق النموذج (MCP) الخاص بك الذي يحتاج إلى البحث عن مستندات المطوّرين الرسمية من Google Developers واستردادها، بدلاً من ضبط بيئة تطوير متكاملة (IDE) أو مساعدة في البرمجة حاليَين.

ستتعرَّف في هذا الدليل على ما يلي:

تثبيت حزمة MCP Client SDK للغة Python أو TypeScript
الاتصال بخادم MCP الخاص بـ "معارف المطوّرين" باستخدام مفتاح واجهة برمجة التطبيقات أو "بيانات الاعتماد التلقائية للتطبيق" (ADC)
استدعاء الأدوات search_documents وget_documents وanswer_query
التعامل مع أخطاء المصادقة والحصص والأدوات

قبل البدء

قبل البدء، يُرجى إكمال الأقسام التالية.

تفعيل واجهة برمجة التطبيقات وإنشاء بيانات الاعتماد

فعِّل واجهة برمجة التطبيقات Developer Knowledge API في مشروعك على السحابة الإلكترونية على Google Cloud وأنشئ بيانات اعتماد طريقة المصادقة. للاطّلاع على التعليمات التفصيلية، يُرجى الرجوع إلى مقالة اختيار طريقة المصادقة.

تستخدم الأمثلة الواردة في هذا الدليل مفتاح واجهة برمجة التطبيقات. لاستخدام "بيانات الاعتماد التلقائية للتطبيق" بدلاً من ذلك، يُرجى الرجوع إلى مقالة المصادقة باستخدام "بيانات الاعتماد التلقائية للتطبيق".

تثبيت حزمة MCP SDK

اختَر لغة البرمجة لتثبيت حزمة MCP Client SDK:

Python

يستخدم هذا الدليل الإصدار 2 من حزمة MCP Python SDK، الذي يتطلّب Python 3.10 أو إصدارًا أحدث. يستخدم الإصدار 1.x من حزمة SDK أسماء مختلفة للفئات والدوال، لذا لا تعمل هذه الأمثلة معه:

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 الخاص بـ "معارف المطوّرين" بروتوكول النقل Streamable HTTP على نقطة النهاية التالية:

https://developerknowledge.googleapis.com/mcp

للمصادقة، عليك تمرير مفتاح واجهة برمجة التطبيقات في عنوان HTTP X-Goog-Api-Key في كل طلب. لا تمرِّر مفتاح واجهة برمجة التطبيقات كمَعلمة طلب بحث في عنوان URL.

يتصل المثال التالي بالخادم ويسرد الأدوات المتاحة:

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 الكامل لكل صفحة. يمكنك طلب ما يصل إلى 20 مستندًا في طلب واحد. بما أنّ عدة أجزاء يمكن أن تأتي من المستند نفسه، عليك إزالة قيم 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). تعمل "بيانات الاعتماد التلقائية للتطبيق" مع بيانات اعتماد المستخدم أثناء التطوير المحلي ومع حسابات الخدمة عندما يتم تشغيل الرمز البرمجي على Google Cloud.

عند استخدام "بيانات الاعتماد التلقائية للتطبيق"، عليك إرسال العناوين التالية في كل طلب:

Authorization: رمز دخول Bearer OAuth 2.0 مع النطاق https://www.googleapis.com/auth/cloud-platform
X-Goog-User-Project: رقم تعريف المشروع الذي تم تفعيل واجهة برمجة التطبيقات Developer Knowledge API فيه والذي يتم تحصيل الرسوم منه مقابل الحصة يحتاج حسابك إلى إذن serviceusage.services.use في هذا المشروع.

تنتهي صلاحية رموز الوصول، لذا يجب أن تعيد العملاء الذين يستغرقون وقتًا طويلاً تحديثها. تستخدم الأمثلة التالية مكتبات مصادقة Google لإضافة رمز حالي إلى كل طلب.

يمكنك إعداد "بيانات الاعتماد التلقائية للتطبيق" للتطوير المحلي باتّباع الخطوات في علامة التبويب ADC في مقالة اختيار نوع بيانات اعتماد OAuth.
اضبط متغيّر البيئة GOOGLE_CLOUD_PROJECT على المشروع الذي تم تفعيل واجهة برمجة التطبيقات Developer Knowledge API فيه. ترسل الأمثلة رقم تعريف هذا المشروع في عنوان X-Goog-User-Project:
```
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
```
ثبِّت مكتبة مصادقة Google للغة البرمجة التي تستخدمها:
Python
pip install --upgrade google-auth requests
TypeScript
npm install google-auth-library

أنشئ العميل باستخدام "بيانات الاعتماد التلقائية للتطبيق":

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);

التعامل مع الأخطاء

تصل الأخطاء من خادم MCP الخاص بـ "معارف المطوّرين" إلى الرمز البرمجي بطريقتَين:

أخطاء الطلب: يتم عرض أخطاء المصادقة والأذونات والحصص مع رمز حالة خطأ HTTP، مثل 400 أو 403 أو 429. تُظهر حزم SDK هذه الأخطاء كاستثناءات: 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 و"بيانات الاعتماد التلقائية للتطبيق".

الخطوات التالية

استكشِف مخططات الأدوات الكاملة في الـ مرجع MCP.
تعرَّف على المنتجات التي تم فهرستها في الـ مرجع مجموعة البيانات.
استدعِ واجهة برمجة التطبيقات Developer Knowledge API مباشرةً باستخدام الـ مكتبات البرامج.

الاتصال بخادم MCP الخاص بـ Developer Knowledge باستخدام حِزم تطوير البرامج (SDK) الخاصة بـ MCP تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

قبل البدء

تفعيل واجهة برمجة التطبيقات وإنشاء بيانات الاعتماد

تثبيت حزمة MCP SDK

Python

TypeScript

ضبط مفتاح واجهة برمجة التطبيقات

الاتصال بالخادم

Python

TypeScript

استدعاء الأدوات

البحث عن المستندات

Python

TypeScript

استرداد المستندات الكاملة

Python

TypeScript

إنشاء إجابة

Python

TypeScript

المصادقة باستخدام "بيانات الاعتماد التلقائية للتطبيق"

Python

TypeScript

Python

TypeScript

التعامل مع الأخطاء

Python

TypeScript

الخطوات التالية

الاتصال بخادم MCP الخاص بـ Developer Knowledge باستخدام حِزم تطوير البرامج (SDK) الخاصة بـ MCP