दस्तावेज़ देखें
इंटीग्रेशन
FlashData के लिए एक Node.js अनुप्रयोग कनेक्ट करें, अपनी पहली Google Search परिणाम की जाँच करें और सहेजें।
इस पेज पर
शुरू करने से पहले
Node.js 22.18+, npm और google_search अनुमति के साथ एक API कुंजी का उपयोग करें। आपका अनुप्रयोग MCP क्लाइंट है; FlashData सर्वर को https://data.flashdata.dev/mcp. पर होस्ट करता है उदाहरण मुफ्त के लिए कनेक्शन की जांच करता है, एक खोज को --search के साथ प्रस्तुत करता है और इसके सहेजे गए परिणाम को --read के साथ पढ़ता है।
1. क्लाइंट SDK स्थापित करें
एक नई परियोजना बनाएँ। Windows पर, npm.cmd का उपयोग करें यदि npm.ps1 को अवरुद्ध किया गया है।
node --version
mkdir flashdata-mcp-demo
cd flashdata-mcp-demo
npm init -y
npm install --save-exact @modelcontextprotocol/[email protected]2. अपने API कुंजी सेट करें
इस टर्मिनल में कुंजी सेट करें, या अपने एजेंट को अपने गुप्त स्टोर से FLASHDATA_API_KEY इंजेक्ट करने दें। ग्राहक इसे होस्ट किए गए स्ट्रीमेबल HTTP एंडपॉइंट में X-API-Key हेडर के रूप में भेजता है। कोड को स्थानीय या सर्वर प्रक्रिया में चलाएं।
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey3. क्लाइंट को सहेजें और चेक करें
mcp-client.mjs के रूप में नीचे पूरी फ़ाइल को बचाने के लिए फ्लैशडाटा-mcp-demo के अंदर, package.json के बगल में। इस पृष्ठ पर सभी आदेश इस फाइल का उपयोग करते हैं। यह उपकरण की खोज करता है, वर्तमान मूल्य निर्धारण और संतुलन की जांच करता है, और बड़े परिणाम एकत्र करता है।
बचाओ mcp-client.mjs
import { mkdir, readFile, writeFile } from 'node:fs/promises';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const client = new Client({ name: 'flashdata-first-task', version: '1.0.0' });
const output = 'mcp-search-output';
let searchAttempted = false;
function bodyOf(reply) {
const body = reply.structuredContent ?? JSON.parse(
reply.content.filter(item => item.type === 'text').map(item => item.text).join(''));
if (reply.isError) {
throw new Error(JSON.stringify({
code: body.code, http_status: body.http_status, request_id: body.request_id,
}));
}
return body;
}
async function completeResult(reply) {
let body = bodyOf(reply);
if (!body.result_id) return body;
const id = body.result_id;
let text = body.chunk;
let offset = body.next_offset;
while (offset !== null) {
body = bodyOf(await client.callTool({
name: 'get_result', arguments: { result_id: id, offset },
}));
if (body.result_id !== id || body.offset !== offset ||
(body.next_offset !== null && body.next_offset <= offset)) {
throw new Error('Invalid continuation; preserve ' + output + '/mcp-receipt.json.');
}
text += body.chunk;
offset = body.next_offset;
}
return JSON.parse(text);
}
function printResult(response, saved = false) {
if (response.status !== 'done') throw new Error('Search is not done; inspect ' + output + '/result.json.');
const hits = (response.results ?? []).flatMap(page => page.organic ?? []);
for (const hit of hits) console.log(hit.title ?? '(no title)', hit.link ?? '(no URL)', hit.snippet ?? '');
if (!hits.length) console.log('No organic results returned.');
console.log(saved ? 'Original credits used:' : 'Credits used:', response.usage?.credits ?? 'not reported');
console.log('Saved response: ' + output + '/result.json');
}
async function main() {
const mode = process.argv[2] ?? '--check';
if (process.argv.length > 3 || !['--check', '--search', '--read'].includes(mode)) {
throw new Error('Usage: node mcp-client.mjs [--check | --search | --read]');
}
if (mode === '--read') {
printResult(JSON.parse(await readFile(output + '/result.json', 'utf8')), true);
console.log('Local file only. No API call or new charge.');
return;
}
const key = process.env.FLASHDATA_API_KEY?.trim();
if (!key) throw new Error('Set FLASHDATA_API_KEY in this terminal.');
await client.connect(new StreamableHTTPClientTransport(
new URL('https://data.flashdata.dev/mcp'),
{ requestInit: { headers: { 'X-API-Key': key } } },
));
const names = [];
let cursor;
do {
const page = await client.listTools(cursor ? { cursor } : {});
names.push(...page.tools.map(tool => tool.name));
cursor = page.nextCursor;
} while (cursor);
for (const name of ['google_search', 'get_balance', 'get_pricing']) {
if (!names.includes(name)) throw new Error('Missing tool: ' + name);
}
const balance = bodyOf(await client.callTool({ name: 'get_balance', arguments: {} }));
const pricing = bodyOf(await client.callTool({
name: 'get_pricing', arguments: { source: 'google_search', request_count: 1 },
}));
const price = pricing.prices.find(p => p.source === 'google_search' && p.available);
const cost = price?.estimatedCredits;
if (!Number.isFinite(cost) || cost < 0) throw new Error('No current price; stop here.');
if (!Number.isFinite(balance.availableCredits)) throw new Error('No current balance; stop here.');
console.log('Available credits:', balance.availableCredits, 'One search:', cost);
if (mode === '--check') {
console.log('Connected. No paid query submitted.');
console.log(balance.availableCredits >= cost ? 'Ready for one search.' : 'Add credits before searching.');
} else {
if (balance.availableCredits < cost) throw new Error('Insufficient credits.');
// Reserve a new directory before submitting. A repeat run stops here.
await mkdir(output);
const request = {
name: 'google_search',
arguments: { query: 'battery recycling research', num: 5, mode: 'realtime' },
};
await writeFile(output + '/request.json', JSON.stringify(request, null, 2), { flag: 'wx' });
searchAttempted = true;
const reply = await client.callTool(request, undefined, { timeout: 120_000 });
await writeFile(output + '/mcp-receipt.json', JSON.stringify(reply, null, 2), { flag: 'wx' });
const response = await completeResult(reply);
await writeFile(output + '/result.json', JSON.stringify(response, null, 2), { flag: 'wx' });
printResult(response);
}
}
try {
await main();
} catch (error) {
console.error(error instanceof Error ? error.message : String(error));
if (searchAttempted) console.error('Search was attempted. Preserve saved files and check History before retrying.');
else console.error('No search submitted by this run.');
process.exitCode = 1;
} finally {
await client.close();
}मुफ्त के लिए कनेक्शन की जाँच करें
टर्मिनल जहां आप कुंजी सेट में flashdata-mcp-demo से भागो। उपलब्ध क्रेडिट्स, एक खोज और कनेक्टेड की उम्मीद है। कोई भुगतान क्वेरी प्रस्तुत नहीं की गई है। अंतिम पंक्ति का कहना है कि संतुलन एक खोज को कवर करता है। शून्य शेष का मतलब प्रमाणीकरण विफल नहीं होता है।
node mcp-client.mjs4. अपनी पहली खोज चलायें
जिस फाइल को आपने चरण 3 में सेव किया था उसका उपयोग करें। --search ध्वज एक Google खोज को बैटरी रीसाइक्लिंग अनुसंधान के लिए अनुरोध करता है। ग्राहक फिर से मूल्य और शेष राशि की जांच करता है, फिर प्रयोग किए जाने वाले उत्तरदायित्व और प्रिंट स्रोत लिंक और क्रेडिट को बचाता है।
एक खोज सबमिट करें
एक बार flashdata-mcp-demo से चलाएं। ग्राहक प्रस्तुत करने से पहले mcp-search-output बनाता है; यदि वह पहले से मौजूद है तो यह कार्य दोहराने से बचने के लिए रुक जाता है।
node mcp-client.mjs --searchसहेजे गए परिणाम का निरीक्षण करें
ओपन mcp-search-output/result.json status: done, results[].organic को शीर्षकों, लिंक्स और स्निपेट्स और usage.credits के साथ एक्सपेक्ट करें। खाली कार्बनिक परिणाम मान्य हो सकते हैं। नीचे दी गई प्रतिक्रिया संक्षिप्त और स्पष्ट है।
{
"source": "google_search",
"status": "done",
"results": [
{
"organic": [
{
"title": "Battery recycling research",
"link": "https://example.org/recycling",
"snippet": "An example search excerpt."
}
]
}
],
"usage": {
"credits": 0.02
},
"http_status": 200,
"request_id": "example-request-id"
}फिर से सहेजे गए परिणाम पढ़ें
उसी परियोजना डायरेक्टरी से भागो। यह result.json को पढ़ता है और उपयोग किए जाने वाले स्रोत लिंक और मूल क्रेडिट को प्रिंट करता है। यह कोई API कुंजी की जरूरत है, कोई नेटवर्क अनुरोध नहीं करता है और किसी अन्य खोज को प्रस्तुत नहीं करता है।
node mcp-client.mjs --readएक बाधित कार्य को पुनर्प्राप्त करें
यदि एक खोज मुद्रण परिणाम से पहले बंद हो जाता है तो mcp-search-output रखें। एक लापता result.json अनुरोध विफल साबित नहीं करता है। नीचे की फ़ाइलों का निरीक्षण करें और यह तय करने से पहले History की जाँच करें कि क्या किसी अन्य खोज की आवश्यकता है।
| Mcp-search-output में फ़ाइल | क्या यह आपको बताता है |
|---|---|
| request.json | इच्छित टूल कॉल। जमा करने से पहले सेव किया गया; यह पुष्टि नहीं करता कि FlashData ने इसे प्राप्त किया। |
| mcp-receipt.json | मूल MCP उत्तर, त्रुटियों या बंद करने के लिए result_id सहित। चेक isError और प्रतिक्रिया शरीर; HTTP 200 अकेले सफलता नहीं है। |
| result.json | इकट्ठे प्रतिक्रिया। एक स्थिति में किया गया है --read के साथ पढ़ने के लिए तैयार है; समस्या निवारण के लिए request_id को संरक्षित करें। |
कैसे बड़े परिणाम एकत्र किए जाते हैं
क्लाइंट ने structuredContent, या JSON टेक्स्ट को कंटेंट में पढ़ा जब structuredContent अनुपस्थित है। यह भी जब MCP परिवहन रिटर्न HTTP 200 वापस आता है isError की जाँच करता है।
जब एक जवाब में result_id, completeResult कॉल get_result को उसी क्रेडेंशियल के साथ कॉल करता है और next_offset को लौटाता है जब तक कि यह null है। यह अनुक्रम की जांच करता है, चंकड़ों को जोड़ता है और पूर्ण JSON को पार करता है। मूल रसीद mcp-search-output/mcp-receipt.json में रहती है।
अपने आवेदन में इस क्लाइंट का उपयोग करें
| कार्य | क्या बदलना है |
|---|---|
| विभिन्न खोजों को चलाएं | request.arguments.query बदलें और mcp-client.mjs में एक नए कार्य के लिए आउटपुट करें। उसी पूर्ण कार्य के लिए --read का पुन: उपयोग करें; पहले आउटपुट डायरेक्टरीज़ को रखें। |
| अपने मॉडल को एक उपकरण का चयन करते हैं | नाम, विवरण और इनपुट स्कीमा पढ़ने के लिए listTools का उपयोग करें। चयनित नाम और तर्कों को मान्य करें, फिर अपने आवेदन की अनुमति और खर्च नीति के तहत callTool। |
| एक अनुसूची पर भागो | लगातार गुप्त भंडारण से स्वामित्व वाली क्रेडेंशियल का पुन: उपयोग करें। प्रति शेड्यूल स्लॉट एक टिकाऊ रिकॉर्ड रखें; सहेजे गए आउटपुट को उसी स्लॉट दोहराने पर पढ़ें। |
| अन्य उपयोगकर्ताओं को कनेक्ट करें | यह कुंजी अपने मालिक के खाते को चार्ज करती है। प्रत्येक उपयोगकर्ता के अपने क्रेडेंशियल का उपयोग करें और अपने सहेजे गए परिणामों को अलग करें। एक OAuth एकीकरण को ग्राहक पंजीकरण, सहमति और टोकन भंडारण की भी आवश्यकता होती है; यह API-key उदाहरण उस प्रवाह को लागू नहीं करता है। |
समस्या निवारण
| समस्या | कार्रवाई |
|---|---|
| ERR_MODULE_NOT_FOUND | Run npm flashdata-mcp-demo से स्थापित है। mcp-client.mjs को package.json और node_modules के बगल में रखें। |
| FLASHDATA_API_KEY | उसी टर्मिनल या प्रक्रिया में परिवर्तनीय सेट करें जो Node.js को चलाता है, फिर --search के बिना नोड mcp-client.mjs को फिर से शुरू करता है। |
| 401 | एक समाप्त हो गया है या कुंजी रद्द करने के लिए जाँच करें। वैध पहुंच को पुनर्स्थापित करें, फिर मुफ्त कनेक्शन जांच को फिर से शुरू करें। |
| 403 | कुंजी की google_search अनुमति और खाता एक्सेस की जाँच करें। इस स्रोत को साबित नहीं किया गया है कि एक सफल बैलेंस चेक की अनुमति है। |
| 402 / Insufficient credits | किसी अन्य कार्य को जमा करने से पहले खाता शेष और वर्तमान मूल्य निर्धारण की जांच करें। |
| EEXIST | पिछले प्रयास में आउटपुट डायरेक्टरी का मालिकाना है। यदि result.json पूरा हो गया है तो नोड mcp-client.mjs --read को चलाएं; अन्यथा इसकी रसीद और History का निरीक्षण करें। निर्देशिका रखें। |
| ENOENT / invalid JSON के साथ --read | जाँच करें कि आप flashdata-mcp-demo में हैं और mcp-search-output/result.json का निरीक्षण करते हैं। यदि यह गायब है या अधूरी है, तो एक बाधित कार्य को पुनर्प्राप्त करें; --read कभी एक खोज प्रस्तुत नहीं करता है। |
| 429 | जब प्रदान की जाती है तो Retry-After के लिए प्रतीक्षा करें। यदि किसी खोज का प्रयास किया गया था, तो पुनः प्रयास करने से पहले अपनी सहेजी गई फ़ाइलों और History की जांच करें। |
| टाइमआउट / result_unavailable | अनुरोध और रसीद रखें। History या मौजूदा नौकरी की जाँच करें; एक बचाया निरंतरता समाप्त हो सकती है। |