Resmi Model Context Protocol (MCP) SDK'ları, kendi uygulamalarınızın ve yapay zeka aracılarının Developer Knowledge MCP sunucusuna programatik olarak bağlanmasına olanak tanır. Mevcut bir IDE'yi veya kod yazma desteğini yapılandırmak yerine resmi Google Developers geliştirici belgelerini arayıp alması gereken özel bir temsilci, arka uç hizmeti veya kendi MCP sunucunuzu oluştururken MCP SDK'sı kullanın.
Bu kılavuzda şunları nasıl yapacağınızı öğreneceksiniz:
- Python veya TypeScript için MCP istemci SDK'sını yükleyin.
- API anahtarı veya Uygulama Varsayılan Kimlik Bilgileri (ADC) ile Developer Knowledge MCP sunucusuna bağlanın.
search_documents,get_documentsveanswer_queryaraçlarını çağırın.- Kimlik doğrulama, kota ve araç hatalarını işleme
Başlamadan önce
Başlamadan önce aşağıdaki bölümleri tamamlayın.
API'yi etkinleştirme ve kimlik bilgileri oluşturma
Google Cloud projenizde Developer Knowledge API'yi etkinleştirin ve kimlik doğrulama yönteminiz için kimlik bilgilerini oluşturun. Adım adım talimatlar için Kimlik doğrulama yönteminizi seçme başlıklı makaleyi inceleyin.
Bu kılavuzdaki örneklerde API anahtarı kullanılmaktadır. Bunun yerine ADC'yi kullanmak için Uygulama Varsayılan Kimlik Bilgileri ile kimlik doğrulama başlıklı makaleyi inceleyin.
MCP SDK'sını yükleme
MCP istemci SDK'sını yüklemek için programlama dilinizi seçin:
Python
Bu kılavuzda, Python 3.10 veya sonraki sürümlerin gerekli olduğu MCP Python SDK'nın 2. sürümü kullanılmaktadır. SDK'nın 1.x sürümü farklı sınıf ve işlev adları kullandığından bu örnekler bu sürümle çalışmaz:
pip install --upgrade "mcp>=2"
TypeScript
Bu kılavuzda, Node.js 18 veya sonraki sürümlerle MCP TypeScript SDK'sı kullanılır:
npm install @modelcontextprotocol/sdk
API anahtarınızı ayarlama
API anahtarınızı kaynak koduna sabit kodlamamak için bir ortam değişkeninde saklayın. YOUR_API_KEY kısmını API anahtarınızla değiştirin:
export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"
Sunucuya bağlanma
Developer Knowledge MCP sunucusu, aşağıdaki uç noktada Streamable HTTP transport'u kullanır:
https://developerknowledge.googleapis.com/mcp
Kimlik doğrulamak için her istekte X-Goog-Api-Key HTTP başlığında API anahtarınızı iletin. API anahtarını URL sorgu parametresi olarak iletmeyin.
Aşağıdaki örnekte sunucuya bağlanılır ve kullanılabilir araçlar listelenir:
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();
Bağlantı başarılı olursa çıkışta üç araç listelenir:
Available tools: search_documents, answer_query, get_documents
Bu kılavuzun geri kalanındaki örnekler, bu bölümdeki bağlı istemci içinde çalıştırılır. TypeScript örneklerinde üst düzey await kullanıldığından bunları ES modülleri olarak (örneğin, npx tsx index.ts ile) çalıştırın.
Araçları çağırma
Her araç, sonucunu aracın çıkış şemasına uygun yapılandırılmış içerik olarak döndürür. Böylece, metni ayrıştırmak yerine alanları doğrudan okuyabilirsiniz. Giriş ve çıkış şemalarının tamamı için MCP referansına bakın.
Belgelerde arama yapma
En alakalı doküman parçalarını almak için search_documents işlevini query dizesiyle çağırın. Her sonuçta content parçası ve geldiği belgenin parent
kaynak adı bulunur:
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`);
}
Tam belgeleri alma
Bir parça yeterli bağlam içermiyorsa her sayfanın tam Markdown içeriğini almak için get_documents işlevine bir veya daha fazla parent değeri iletin. Tek bir görüşmede en fazla 20 belge isteğinde bulunabilirsiniz. Aynı dokümandan birden fazla parça gelebileceğinden, önce yinelenen parent değerlerini kaldırın:
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);
}
Tam belgeler büyük olabilir. Bu nedenle, yalnızca arama parçaları yeterli olmadığında get_documents işlevini çağırın. Daha fazla bilgi edinmek için Bağlam penceresini ve jeton kullanımını optimize etme başlıklı makaleyi inceleyin.
Yanıt oluşturma
answer_query işlevini çağırarak Developer Knowledge corpus'a dayalı bir yanıt oluşturun. Sonuç, answerText ve bunu oluşturmak için kullanılan references içerir:
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 alanı, get_documents yöntemine iletebileceğiniz doküman kaynağı adlarını içerir. Aynı belge birden fazla kez görünebilir. Bu nedenle, belgeleri almadan önce yinelenenleri kaldırın. answer_query aracının kotası diğer araçlara göre daha düşüktür. Daha fazla bilgi için Kota ve sınırlar başlıklı makaleyi inceleyin.
Uygulama Varsayılan Kimlik Bilgileri ile kimlik doğrulama
API anahtarı yerine Uygulama Varsayılan Kimlik Bilgileri (ADC) ile kimlik doğrulayabilirsiniz. ADC, yerel geliştirme sırasında kullanıcı kimlik bilgilerinizle, kodunuz Google Cloud'da çalışırken ise hizmet hesaplarıyla çalışır.
ADC'yi kullanırken her istekte aşağıdaki üstbilgileri gönderin:
Authorization:https://www.googleapis.com/auth/cloud-platformkapsamına sahip birBearerOAuth 2.0 erişim jetonu.X-Goog-User-Project: Developer Knowledge API'nin etkinleştirildiği ve kota için faturalandırılan projenin kimliği. Hesabınızın bu projedeserviceusage.services.useiznine sahip olması gerekir.
Erişim jetonlarının süresi dolduğundan uzun süre çalışan istemcilerin bu jetonları yenilemesi gerekir. Aşağıdaki örneklerde, her isteğe geçerli bir jeton eklemek için Google kimlik doğrulama kitaplıkları kullanılmaktadır.
OAuth kimlik bilgisi türünüzü seçin bölümündeki ADC sekmesinde yer alan adımları uygulayarak yerel geliştirme için ADC'yi ayarlayın.
GOOGLE_CLOUD_PROJECTortam değişkenini, Developer Knowledge API'nin etkin olduğu projeye ayarlayın. Örnekler, bu proje kimliğiniX-Goog-User-Projectüstbilgisinde gönderir:export GOOGLE_CLOUD_PROJECT="PROJECT_ID"Diliniz için Google kimlik doğrulama kitaplığını yükleyin:
Python
pip install --upgrade google-auth requestsTypeScript
npm install google-auth-libraryADC ile istemciyi oluşturun:
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);
Hataları işleme
Geliştirici Bilgisi MCP sunucusundan gelen hatalar kodunuza iki şekilde ulaşır:
- İstek hataları: Kimlik doğrulama, izin ve kota hataları
400,403veya429gibi bir HTTP hata durumuyla döndürülür. SDK'lar bunları istisna olarak bildirir: Python'daMCPErrorve TypeScript'teStreamableHTTPError. Araç çağrılarınızda bu istisnaları yakalayın. - Araç hataları: Bir araç çalıştırıldığında ancak isteği tamamlayamadığında sonuçta
is_error(Python) veyaisError(TypeScript)trueolarak ayarlanır vecontentalanında sorunun metin açıklaması yer alır. Yapılandırılmış içeriği okumadan önce bu alanı kontrol edin.
Aşağıdaki örnekte her iki hata türü de ele alınmaktadır:
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, kota hatası (429 RESOURCE_EXHAUSTED) döndürürse daha yüksek kotaya sahip olan search_documents'ye geri dönün. Eksponansiyel geri yükleme dahil olmak üzere yeniden deneme stratejileri için Hata işleme ve kota yönetimi başlıklı makaleyi inceleyin.
Kimlik doğrulama hatalarının yaygın nedenleri için API anahtarı hataları ve OAuth ve ADC hataları bölümlerine bakın.
Sırada ne var?
- MCP referansında tam araç şemalarını inceleyin.
- Corpus referansında hangi ürünlerin dizine eklendiğini öğrenin.
- İstemci kitaplıklarını kullanarak Developer Knowledge API'yi doğrudan çağırın.