एमसीपी SDK टूल का इस्तेमाल करके, Developer Knowledge एमसीपी सर्वर से कनेक्ट करना

आधिकारिक मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) एसडीके की मदद से, आपके ऐप्लिकेशन और एआई एजेंट, Developer Knowledge MCP सर्वर से प्रोग्राम के हिसाब से कनेक्ट हो सकते हैं. अगर आपको कोई कस्टम एजेंट, बैकएंड सेवा या अपना एमसीपी सर्वर बनाना है, तो एमसीपी SDK का इस्तेमाल करें. ऐसा तब करें, जब आपको मौजूदा आईडीई या कोडिंग असिस्टेंट को कॉन्फ़िगर करने के बजाय, Google के डेवलपर से जुड़े आधिकारिक दस्तावेज़ों को खोजना और उन्हें वापस पाना हो.

इस गाइड में आपको इनके बारे में जानकारी मिलेगी:

  • Python या TypeScript के लिए, एमसीपी क्लाइंट एसडीके इंस्टॉल करें.
  • एपीआई पासकोड या ऐप्लिकेशन डिफ़ॉल्ट क्रेडेंशियल (एडीसी) की मदद से, Developer Knowledge एमसीपी सर्वर से कनेक्ट करें.
  • search_documents, get_documents, और answer_query टूल को कॉल करें.
  • पुष्टि करने, कोटा, और टूल से जुड़ी गड़बड़ियों को ठीक करना.

शुरू करने से पहले

शुरू करने से पहले, ये सेक्शन पूरे करें.

एपीआई चालू करना और क्रेडेंशियल बनाना

अपने Google क्लाउड प्रोजेक्ट में Developer Knowledge API को चालू करें. इसके बाद, पुष्टि करने के तरीके के लिए क्रेडेंशियल बनाएं. सिलसिलेवार निर्देशों के लिए, पुष्टि करने का तरीका चुनें लेख पढ़ें.

इस गाइड में दिए गए उदाहरणों में, एपीआई पासकोड का इस्तेमाल किया गया है. इसके बजाय, एडीसी का इस्तेमाल करने के लिए, ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल की मदद से पुष्टि करना लेख पढ़ें.

MCP SDK टूल इंस्टॉल करना

MCP क्लाइंट SDK इंस्टॉल करने के लिए, अपनी प्रोग्रामिंग भाषा चुनें:

Python

इस गाइड में, MCP Python SDK के वर्शन 2 का इस्तेमाल किया गया है. इसके लिए, Python 3.10 या इसके बाद के वर्शन की ज़रूरत होती है. SDK टूल के वर्शन 1.x में, अलग-अलग क्लास और फ़ंक्शन के नाम इस्तेमाल किए जाते हैं. इसलिए, ये उदाहरण इसके साथ काम नहीं करते:

pip install --upgrade "mcp>=2"

TypeScript

इस गाइड में, Node.js 18 या इसके बाद के वर्शन के साथ MCP TypeScript SDK का इस्तेमाल किया गया है:

npm install @modelcontextprotocol/sdk

अपना एपीआई पासकोड सेट करना

सोर्स कोड में एपीआई पासकोड को हार्डकोड करने से बचने के लिए, इसे एनवायरमेंट वैरिएबल में सेव करें. YOUR_API_KEY को अपने एपीआई पासकोड से बदलें:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

सर्वर से कनेक्ट करना

डेवलपर नॉलेज एमसीपी सर्वर, इस एंडपॉइंट पर स्ट्रीम किए जा सकने वाले एचटीटीपी ट्रांसपोर्ट का इस्तेमाल करता है:

https://developerknowledge.googleapis.com/mcp

पुष्टि करने के लिए, हर अनुरोध पर X-Goog-Api-Key एचटीटीपी हेडर में अपना एपीआई पासकोड डालें. एपीआई पासकोड को यूआरएल क्वेरी पैरामीटर के तौर पर पास न करें.

यहां दिए गए उदाहरण में, सर्वर से कनेक्ट करने और उपलब्ध टूल की सूची देखने का तरीका बताया गया है:

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 के साथ.

टूल कॉल करना

हर टूल, नतीजे को स्ट्रक्चर्ड कॉन्टेंट के तौर पर दिखाता है. यह टूल के आउटपुट स्कीमा से मेल खाता है, ताकि टेक्स्ट को पार्स करने के बजाय सीधे फ़ील्ड पढ़े जा सकें. पूरे इनपुट और आउटपुट स्कीमा के लिए, एमसीपी रेफ़रंस देखें.

दस्तावेज़ खोजें

सबसे काम के दस्तावेज़ के हिस्सों को वापस पाने के लिए, query स्ट्रिंग के साथ search_documents को कॉल करें. हर नतीजे में चंक 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`);
}

पूरे दस्तावेज़ों को वापस पाना

अगर किसी चंक में ज़रूरत के मुताबिक कॉन्टेक्स्ट नहीं है, तो हर पेज का पूरा Markdown कॉन्टेंट पाने के लिए, get_documents को एक या उससे ज़्यादा parent वैल्यू पास करें. एक कॉल में ज़्यादा से ज़्यादा 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 टूल का कोटा, अन्य टूल के मुकाबले कम होता है. ज़्यादा जानने के लिए, कोटा और सीमाएं देखें.

ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल की मदद से पुष्टि करना

एपीआई पासकोड के बजाय, ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल (एडीसी) से पुष्टि की जा सकती है. एडीसी, लोकल डेवलपमेंट के दौरान आपके उपयोगकर्ता क्रेडेंशियल के साथ काम करता है. साथ ही, Google Cloud पर आपका कोड चलने पर, सेवा खातों के साथ काम करता है.

एडीसी का इस्तेमाल करते समय, हर अनुरोध पर ये हेडर भेजें:

  • Authorization: https://www.googleapis.com/auth/cloud-platform स्कोप वाला Bearer OAuth 2.0 ऐक्सेस टोकन.
  • X-Goog-User-Project: यह उस प्रोजेक्ट का आईडी है जिसमें Developer Knowledge API चालू है और जिसके लिए कोटा का बिल भेजा जाता है. आपके खाते के पास इस प्रोजेक्ट के लिए, serviceusage.services.use की अनुमति होनी चाहिए.

ऐक्सेस टोकन की समयसीमा खत्म हो जाती है. इसलिए, लंबे समय तक चलने वाले क्लाइंट को उन्हें रीफ़्रेश करना होगा. यहां दिए गए उदाहरणों में, Google की पुष्टि करने वाली लाइब्रेरी का इस्तेमाल करके, हर अनुरोध में मौजूदा टोकन जोड़ा गया है.

  1. लोकल डेवलपमेंट के लिए एडीसी सेट अप करें. इसके लिए, अपने OAuth क्रेडेंशियल का टाइप चुनें में जाकर, ADC टैब पर दिया गया तरीका अपनाएं.

  2. GOOGLE_CLOUD_PROJECT एनवायरमेंट वैरिएबल को उस प्रोजेक्ट पर सेट करें जिसमें Developer Knowledge API चालू है. उदाहरणों में, इस प्रोजेक्ट आईडी को X-Goog-User-Project हेडर में भेजा जाता है:

    export GOOGLE_CLOUD_PROJECT="PROJECT_ID"

  3. अपनी भाषा के लिए, Google authentication library इंस्टॉल करें:

    Python

    pip install --upgrade google-auth requests

    TypeScript

    npm install google-auth-library

  4. एडीसी की मदद से क्लाइंट बनाएं:

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

गड़बड़ियां ठीक करना

डेवलपर नॉलेज एमसीपी सर्वर से मिलने वाली गड़बड़ियां, आपके कोड तक दो तरीकों से पहुंचती हैं:

  • अनुरोध से जुड़ी गड़बड़ियां: पुष्टि करने, अनुमति, और कोटा से जुड़ी गड़बड़ियां, एचटीटीपी गड़बड़ी की स्थिति के साथ दिखती हैं. जैसे, 400, 403 या 429. SDK, इन्हें अपवाद के तौर पर दिखाता है: Python में MCPError और TypeScript में StreamableHTTPError. टूल कॉल के दौरान होने वाली इन गड़बड़ियों को हैंडल करें.
  • टूल से जुड़ी गड़बड़ियां: जब कोई टूल चलता है, लेकिन अनुरोध पूरा नहीं कर पाता, तो नतीजे में 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 और एडीसी से जुड़ी गड़बड़ियां देखें.

आगे क्या करना है