# UMUM membangun klien MCP

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

Referensi boonical: https://flashdata.dev/ms/docs/guides/mcp-custom-client
Diulas: 2026-11-05 oleh FlashData

<a id="prepare"></a>

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

- [Pasang Node.js](https://nodejs.org/en/download)
- [Xachive membuat kunci API](https://flashdata.dev/app/api-keys)
- [Domainkan sebuah aplikasi MCP yang sudah ada](https://flashdata.dev/ms/docs/integrations/mcp-clients/reference.md)

<a id="client"></a>

## 1. Pasanglah klien SDK

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

### Projek projek baru

```bash
node --version
mkdir flashdata-mcp-demo
cd flashdata-mcp-demo
npm init -y
npm install --save-exact @modelcontextprotocol/sdk@1.30.0
```


<a id="authenticate"></a>

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

### Bash

#### Tetapkan kunci anda

```bash
# 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

#### Tetapkan kunci anda

```powershell
# 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 flashdataSecureKey
```



<a id="client-run"></a>

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


<a id="client-source"></a>

### Simpan mcp-client.mjs

#### flashdata-mcp-demo/mcp-client.mjs

```javascript
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();
}
```


<a id="check-output"></a>

### 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

```bash
node mcp-client.mjs
```

- [Mengecek kredit](https://flashdata.dev/app/billing)

<a id="first-task"></a>

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


<a id="submit"></a>

### 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

```bash
node mcp-client.mjs --search
```


<a id="result"></a>

### 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

```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"
}
```


<a id="read-saved"></a>

### 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

```bash
node mcp-client.mjs --read
```


<a id="saved-files"></a>

## 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-output | Apa yang dikatakannya padamu? |
| --- | --- |
| request.json | Panggilan alat yang ditujukan. Cafierd disimpan sebelum penyerahan; tidak mengkonfirmasi bahwa FlashData menerimanya. |
| mcp-receipt.json | XAMCP asli balasan, termasuk kesalahan atau result_id untuk kelanjutan. Periksa isError dan tubuh respon; HTTP 200 saja tidak berhasil. |
| result.json | Tanggapan yang dihimpun. Sebuah status yang dilakukan siap dibaca dengan --read; jaga request_id untuk mencari masalah. |

- [Sejarah permintaan](https://flashdata.dev/app/jobs)
- [Rincian kontinuasi](https://flashdata.dev/ms/docs/guides/mcp-custom-client/reference.md#continuations)

<a id="continuations"></a>

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

- [Perangkat dan skema kelanjutan MCP](https://flashdata.dev/ms/docs/mcp/reference.md)

<a id="reuse"></a>

## Use Use this client dalam aplikasi Anda

| Task | Apa yang harus diubah |
| --- | --- |
| Xerlin menjalankan pencarian yang berbeda | Xaver 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 alat | Use 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 jadual | Gunakan 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 lain | Kunci 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. |

- [Tugas berulang](https://flashdata.dev/ms/docs/guides/recurring-tasks/reference.md)
- [Pilihan otentikasi austentifikasi berautomatika](https://flashdata.dev/ms/docs/guides/agent-access/reference.md)

<a id="operate"></a>

## Penerjemahan Masalah

| Problem | Aksi |
| --- | --- |
| ERR_MODULE_NOT_FOUND | Jalankan pemasangan npm dari flashdata-mcp-demo. mcp-client.mjs di samping package.json dan node_modules. |
| FLASHDATA_API_KEY | Diawal variabel dalam terminal atau proses yang sama yang menjalankan Node.js, kemudian jalankan kembali nodal mcp-client.mjs tanpa --search. |
| 401 | Periksa kunci yang sudah kadaluarsa atau dicabut. Pulihkan akses valid, kemudian jalankan ulang cek koneksi bebas. |
| 403 | Periksa izin dan akses akun google_search. Pemeriksaan keseimbangan yang berhasil tidak membuktikan sumber ini diperbolehkan. |
| 402 / Insufficient credits | Periksa keseimbangan akun dan harga saat ini sebelum menyerahkan tugas lain. |
| EEXIST | Usaha 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 --read | Periksa 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. |
| 429 | Wait untuk Retry-After ketika disediakan. Jika sebuah pencarian dicoba, periksa berkas tersimpannya dan History sebelum mencoba lagi. |
| Masa Tamat Masa Tamat / result_unavailable | Wajis menyimpan permintaan dan penerimaan. Cek History atau pekerjaan yang sudah ada; kelanjutan yang disimpan mungkin telah berakhir. |

- [Sejarah permintaan](https://flashdata.dev/app/jobs)
- [Penembakan masalah MCP](https://flashdata.dev/ms/docs/guides/troubleshooting/reference.md#mcp)
