Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Integrasi

Buat klien MCP

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.

Proyek baru
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.

Atur key Anda
# 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

3. 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

flashdata-mcp-demo/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.

Dalam flashdatta -mcp-demo
node mcp-client.mjs

4. 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.

Dalam flashdatta -mcp-demo
node mcp-client.mjs --search

Inspeksi 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.

mcp-search-output/result.json
{
  "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.

Dalam flashdatta -mcp-demo
node mcp-client.mjs --read

Mengembalikan 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-outputApa yang memberitahumu
request.jsonPanggilan yang ditujukan untuk alat. Disimpan sebelum penyerahan; tidak mengkonfirmasi bahwa FlashData menerimanya.
mcp-receipt.jsonMCP asli menjawab, termasuk kesalahan atau result_id untuk kelanjutan. Periksa isError dan tubuh respon; HTTP 200 saja tidak berhasil.
result.jsonRespon 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

TugasApa yang harus diubah
Jalankan pencarian yang berbedaUbah 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 alatGunakan 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 jadwalGunakan 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 lainKunci 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

MasalahAksi
ERR_MODULE_NOT_FOUNDJalankan npm install dari flashdata -mcp-demo. Jaga mcp-client.mjs di samping package.json dan node_modules.
FLASHDATA_API_KEYSet variabel dalam terminal atau proses yang sama yang berjalan Node.js, kemudian rerun node mcp-client.mjs tanpa --search.
401Periksa kunci yang kadaluwarsa atau dicabut. Kembalikan akses yang valid, lalu jalankan ulang pemeriksaan koneksi bebas.
403Periksa kunci izin google_search dan akses akun. Pemeriksaan keseimbangan yang sukses tidak membuktikan sumber ini diperbolehkan.
402 / Insufficient creditsPeriksa saldo akun dan nilai saat ini sebelum mengirimkan tugas lain.
EEXISTPercobaan 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 --readPeriksa 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.
429Tunggu Retry-After ketika disediakan. Jika pencarian sedang dicoba, periksa file yang disimpan dan History sebelum mencoba kembali.
Timeout / result_unavailableSimpan permintaan dan tanda terima. Periksa History atau pekerjaan yang ada; kelanjutan yang disimpan mungkin telah berakhir.