Jelajahi dokumentasi
Integrasi
Hubungkan aplikasi Node.js ke FlashData, periksa akses dan simpan hasil Google Search pertamamu.
Di halaman ini
Sebelum Anda mulai
Gunakan Node.js 22.18+, npm dan API kunci dengan google_search izin. Aplikasi Anda adalah klien MCP; FlashData host server di https://data.flashdata.dev/mcp. Contoh memeriksa sambungan secara gratis, mengajukan satu pencarian dengan --search dan membaca hasilnya yang tersimpan dengan --read.
1. Pasang klien SDK
Buat proyek baru. Pada Windows, gunakan npm.cmd jika npm.ps1 diblokir.
node --version
mkdir flashdata-mcp-demo
cd flashdata-mcp-demo
npm init -y
npm install --save-exact @modelcontextprotocol/[email protected]2. Set kunci API Anda
Atur kunci di terminal ini, atau biarkan agenmu menyuntikkan FLASHDATA_API_KEY dari toko rahasianya. Klien mengirimkannya sebagai header X-API-Key kepada endpoint Streamable yang diselenggarakan HTTP. Jalankan kode dalam proses lokal atau server.
# 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. Simpan dan periksa klien
Simpan berkas lengkap di bawah ini sebagai mcp-client.mjs didalam flatdatma -mcp-demo, di samping package.json. Semua perintah pada halaman ini menggunakan berkas ini. Ia menemukan alat, memeriksa harga dan keseimbangan saat ini, dan mengumpulkan hasil yang besar.
Simpan 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();
}Periksa sambungan secara gratis
Jalankan dari flashdata -mcp-demo di terminal di mana Anda mengatur kunci. Diharapkan kredit Tersedia, Satu pencarian dan Terhubung. Tidak ada permintaan berbayar yang diajukan. Garis akhir mengatakan apakah keseimbangan mencakup satu pencarian. Sebuah keseimbangan nol tidak berarti otentikasi gagal.
node mcp-client.mjs4. Jalankan pencarian pertama Anda
Gunakan file yang Anda simpan dalam langkah 3. Flag --search meminta satu Google mencari penelitian daur ulang baterai. Klien memeriksa harga dan keseimbangan lagi, kemudian menyimpan respon dan sumber cetak link dan kredit yang digunakan.
Kirim satu pencarian
Jalankan sekali dari flashdata -mcp-demo. Klien membuat mcp-search-output sebelum mengirimkan; jika direktori itu sudah ada, itu berhenti untuk menghindari mengulangi tugas.
node mcp-client.mjs --searchInspeksi hasil yang disimpan
Buka mcp-search-output/result.json. Mengharapkan status: done, results[].organic dengan judul, link dan snippets, dan usage.credits. Hasil organik kosong bisa valid. Respon di bawah ini disingkat dan ilustratif.
{
"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"
}Baca hasil yang disimpan lagi
Jalankan dari direktori projek yang sama. Ini tertulis result.json dan cetakan sumber link dan kredit asli yang digunakan. Ini tidak membutuhkan kunci API, tidak membuat permintaan jaringan dan tidak mengirimkan pencarian lain.
node mcp-client.mjs --readMengembalikan tugas yang diinterupsi
Simpan mcp-search-output jika pencarian berhenti sebelum hasil pencetakan. result.json yang hilang tidak membuktikan permintaan gagal. Inspeksi berkas di bawah ini dan periksa History sebelum memutuskan apakah pencarian lain diperlukan.
| Berkas dalam mcp-search-output | Apa yang memberitahumu |
|---|---|
| request.json | Panggilan yang ditujukan untuk alat. Disimpan sebelum penyerahan; tidak mengkonfirmasi bahwa FlashData menerimanya. |
| mcp-receipt.json | MCP asli menjawab, termasuk kesalahan atau result_id untuk kelanjutan. Periksa isError dan tubuh respon; HTTP 200 saja tidak berhasil. |
| result.json | Respon yang dirakit. Status yang telah selesai telah siap untuk dibaca dengan --read; pertahankan request_id untuk penyerapan. |
Seberapa besar hasil yang dikumpulkan
Klien membaca structuredContent, atau JSON teks dalam konten ketika structuredContent absen. Ini memeriksa isError bahkan ketika MCP transportasi kembali HTTP 200.
Ketika respon berisi result_id, completeResult memanggil get_result dengan kredensial yang sama dan mengembalikan next_offset sampai null. Ini memeriksa urutan, konkatenat potongan dan parses penuh JSON. Tanda terima asli tetap di mcp-search-output/mcp-receipt.json.
Gunakan klien ini dalam aplikasi Anda
| Tugas | Apa yang harus diubah |
|---|---|
| Jalankan pencarian yang berbeda | Ubah request.arguments.query dan keluaran dalam mcp-client.mjs untuk tugas baru. Gunakan --read untuk tugas yang selesai; tetap simpan direktori keluaran sebelumnya. |
| Biarkan model Anda memilih alat | Gunakan listTools untuk membaca nama, deskripsi dan skema masukan. Validasi nama dan argumen terpilih, kemudian callTool di bawah izin aplikasi Anda dan kebijakan pengeluaran. |
| Jalankan sesuai jadwal | Gunakan kembali kredensial milik dari penyimpanan rahasia yang gigih. Simpan satu rekor tahan lama per slot jadwal; baca keluaran yang disimpan ketika slot yang sama berulang. |
| Hubungkan pengguna lain | Kunci ini mengisi rekening pemiliknya. Gunakan kredensial masing-masing pengguna dan mengisolasi hasil yang disimpan mereka. An OAuth Integrasi juga membutuhkan pendaftaran klien, persetujuan dan penyimpanan token; ini API-key contoh tidak mengimplementasikan arus itu. |
Permasalahan menarik
| Masalah | Aksi |
|---|---|
| ERR_MODULE_NOT_FOUND | Jalankan npm install dari flashdata -mcp-demo. Jaga mcp-client.mjs di samping package.json dan node_modules. |
| FLASHDATA_API_KEY | Set variabel dalam terminal atau proses yang sama yang berjalan Node.js, kemudian rerun node mcp-client.mjs tanpa --search. |
| 401 | Periksa kunci yang kadaluwarsa atau dicabut. Kembalikan akses yang valid, lalu jalankan ulang pemeriksaan koneksi bebas. |
| 403 | Periksa kunci izin google_search dan akses akun. Pemeriksaan keseimbangan yang sukses tidak membuktikan sumber ini diperbolehkan. |
| 402 / Insufficient credits | Periksa saldo akun dan nilai saat ini sebelum mengirimkan tugas lain. |
| EEXIST | Percobaan sebelumnya memiliki direktori keluaran. Jalankan titik mcp-client.mjs --read jika result.json selesai; jika tidak pemeriksaan tanda terima dan History. Simpan saja direkturnya. |
| ENOENT / JSON tidak valid dengan --read | Periksa bahwa Anda berada dalam flashdata -mcp-demo dan pemeriksaan mcp-search-output/result.json. Jika hilang atau tidak lengkap, ikuti Pengambilan kembali tugas yang terganggu; --read tidak pernah menyerahkan pencarian. |
| 429 | Tunggu Retry-After ketika disediakan. Jika pencarian sedang dicoba, periksa file yang disimpan dan History sebelum mencoba kembali. |
| Timeout / result_unavailable | Simpan permintaan dan tanda terima. Periksa History atau pekerjaan yang ada; kelanjutan yang disimpan mungkin telah berakhir. |