Langkau ke kandungan
MS
Dapatkan kunci API
Semak dokumentasi

Integrasi

UMUM membangun klien MCP

Sambungkan aplikasi Node.js ke FlashData, periksa akses dan simpan hasil Google Search pertama anda.

Pada halaman ini

Sebelum kau mulai

Gunakan Node.js 22.18+, npm dan kunci API dengan izin google_search. Aplikasi Anda adalah klien MCP; FlashData host server di https://data.flashdata.dev/mcp. Contoh itu memeriksa koneksi secara gratis, mengirimkan satu pencarian dengan --search dan membaca hasil disimpannya dengan --read.

1. Pasanglah klien SDK

Buat proyek baru. Windows, gunakan npm.cmd jika npm.ps1 diblokir.

Projek projek baru
node --version
mkdir flashdata-mcp-demo
cd flashdata-mcp-demo
npm init -y
npm install --save-exact @modelcontextprotocol/[email protected]

2. Ketikkan kunci API anda

Dia menetapkan kunci di terminal ini, atau membiarkan agenmu menyuntikkan FLASHDATA_API_KEY dari toko rahasianya. Klien tersebut mengirimkannya sebagai header X-API-Key ke titik akhir Streamable HTTP yang dapat dihost. Kode dalam proses lokal atau server.

Tetapkan kunci 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 sebagai mcp-client.mjs di dalam flashdata-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 koneksi gratis

Lari dari flashdata-mcp-demo di terminal di mana Anda menetapkan kunci. AWAL BELAKANG BELAKANG, 1 pencarian dan koneksi. Tidak ada pertanyaan terbayar yang diajukan. garis akhir mengatakan apakah keseimbangan meliputi satu pencarian. Keseimbangan nol tidak berarti otentikasi gagal.

Di flashdata-mcp-demo
node mcp-client.mjs

4. Kau harus mencari

Gunakan file yang kau simpan dalam langkah 3. permintaan bendera --search permintaan satu Google pencarian penelitian daur ulang baterai. Klien tersebut memeriksa harga dan saldonya lagi, kemudian menyimpan respon dan sidik jari sumber link dan kredit yang digunakan.

Ajukan satu pencarian

Lari sekali dari flashdata-mcp-demo. Klien membuat mcp-search-output sebelum mengirimkan; jika direktori tersebut sudah ada, berhenti untuk menghindari pengulangan tugas.

Di flashdata-mcp-demo
node mcp-client.mjs --search

Periksa hasil yang disimpan

Open mcp-search-output/result.json. Expect status: done, results[].organic dengan judul, link dan snippet, dan usage.credits. Hasil organik yang kosong dapat valid. Tanggapan di bawah ini adalah singkatan dan ilustrasi.

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 proyek yang sama. Ini dibaca result.json dan mencetak sumber link dan kredit asli digunakan. Ia tidak memerlukan kunci API, tidak membuat permintaan jaringan dan tidak menyerahkan pencarian lain.

Di flashdata-mcp-demo
node mcp-client.mjs --read

Pulihkan tugas yang terganggu

¡Aquid tetap melakukan mcp-search-output jika pencarian berhenti sebelum hasil pencetakan. A hilang result.json tidak membuktikan permintaan gagal. Periksa berkas di bawah dan periksa History sebelum memutuskan apakah pencarian lain diperlukan.

Berkas dalam mcp-search-outputApa yang dikatakannya padamu?
request.jsonPanggilan alat yang ditujukan. Cafierd disimpan sebelum penyerahan; tidak mengkonfirmasi bahwa FlashData menerimanya.
mcp-receipt.jsonXAMCP asli balasan, termasuk kesalahan atau result_id untuk kelanjutan. Periksa isError dan tubuh respon; HTTP 200 saja tidak berhasil.
result.jsonTanggapan yang dihimpun. Sebuah status yang dilakukan siap dibaca dengan --read; jaga request_id untuk mencari masalah.

Berapa banyak hasil dikumpulkan

Klien membaca structuredContent, atau teks JSON dalam konten ketika structuredContent tidak hadir. Ia memeriksa isError bahkan ketika transport MCP mengembalikan HTTP 200.

Ketika respon berisi result_id, completeResult memanggil get_result dengan kredensial yang sama dan mengembalikan next_offset sampai null. Ini memeriksa urutan, mengkonkatenkan potongan dan mengurai JSON penuh. Penerimaan asli dalam mcp-search-output/mcp-receipt.json.

Use Use this client dalam aplikasi Anda

TaskApa yang harus diubah
Xerlin menjalankan pencarian yang berbedaXaver request.arguments.query dan output dalam mcp-client.mjs untuk tugas baru. Andai semula --read untuk tugas yang sama selesai; simpan direktori keluaran sebelumnya.
Biarkan model Anda memilih alatUse listTools untuk membaca nama, deskripsi dan skema masukan. Memvalidasi nama dan argumen yang dipilih, kemudian callTool dengan izin dan kebijakan pengeluaran aplikasi Anda.
Jalankan mengikut jadualGunakan semula kelayakan akaun yang disimpan dalam stor rahsia kekal. Simpan satu rekod kekal bagi setiap slot jadual; baca output tersimpan apabila slot yang sama berulang.
Tak bisa menyambung pengguna lainKunci ini menuntut rekening pemiliknya. Ousin menggunakan kredensial masing-masing pengguna sendiri dan mengisolasi hasil yang disimpan mereka. Integrasi OAuth juga membutuhkan pendaftaran klien, persetujuan dan penyimpanan token; contoh API-key ini tidak mengimplementasikan aliran tersebut.

Penerjemahan Masalah

ProblemAksi
ERR_MODULE_NOT_FOUNDJalankan pemasangan npm dari flashdata-mcp-demo. mcp-client.mjs di samping package.json dan node_modules.
FLASHDATA_API_KEYDiawal variabel dalam terminal atau proses yang sama yang menjalankan Node.js, kemudian jalankan kembali nodal mcp-client.mjs tanpa --search.
401Periksa kunci yang sudah kadaluarsa atau dicabut. Pulihkan akses valid, kemudian jalankan ulang cek koneksi bebas.
403Periksa izin dan akses akun google_search. Pemeriksaan keseimbangan yang berhasil tidak membuktikan sumber ini diperbolehkan.
402 / Insufficient creditsPeriksa keseimbangan akun dan harga saat ini sebelum menyerahkan tugas lain.
EEXISTUsaha sebelumnya memiliki direktori output. Pemberlakuan node mcp-client.mjs --read jika result.json selesai; jika tidak inspeksi penerimaannya dan History. Tetap di sana.
ENOENT / JSON tidak sah dengan --readPeriksa bahwa Anda berada dalam flashdata-mcp-demo dan inspeksi mcp-search-output/result.json. OLEH Jika hilang atau tidak lengkap, ikuti Pemulihan tugas terganggu; --read tidak pernah mengirimkan pencarian.
429Wait untuk Retry-After ketika disediakan. Jika sebuah pencarian dicoba, periksa berkas tersimpannya dan History sebelum mencoba lagi.
Masa Tamat Masa Tamat / result_unavailableWajis menyimpan permintaan dan penerimaan. Cek History atau pekerjaan yang sudah ada; kelanjutan yang disimpan mungkin telah berakhir.