Ga naar de inhoud
NL
API-sleutel ophalen
Documentatie bekijken

Integraties

Bouw een MCP-client

Sluit een Node.js-toepassing aan op FlashData, controleer de toegang en sla uw eerste Google Search-resultaat op.

Op deze pagina

Voordat u begint

Gebruik Node.js 22.18+, npm en een API sleutel met google_search toestemming. Uw toepassing is de MCP client; FlashData ondersteunt de server op https://data.flashdata.dev/mcp. Het voorbeeld controleert de verbinding gratis, stuurt een zoekopdracht met --search en leest het opgeslagen resultaat met --read.

1. Installeer de client SDK

Maak een nieuw project aan. Aan WindowsGebruik npm.cmd als npm.ps1 is geblokkeerd.

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

2. Stel uw API-sleutel in

Stel de sleutel in deze terminal in of laat uw agent FLASHDATA_API_KEY injecteren vanuit zijn geheime opslagruimte. De client stuurt het als een X-API-Key header naar het hosted Streamable HTTP eindpunt. Voer de code uit in een lokaal of server proces.

Je sleutel instellen
# 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. Opslaan en controleren van de client

Sla het volledige bestand hieronder op als mcp-client.mjs in flashdata-mcp-demo, naast package.json. Alle commando's op deze pagina gebruiken dit bestand. Het ontdekt tools, controleert de huidige prijzen en evenwicht, en verzamelt grote resultaten.

mcp-client.mjs opslaan

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

Controleer de verbinding gratis

Uitvoeren van flashdata-mcp-demo in de terminal waar u de sleutel hebt ingesteld. Verwacht Beschikbare credits, One search and Connected. Geen betaalde vraag ingediend. De laatste regel zegt of het saldo één zoektocht dekt. Een nulbalans betekent niet dat authenticatie mislukt is.

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

4. Voer je eerste zoekopdracht uit

Gebruik het bestand dat u in stap 3 hebt opgeslagen. De --search vlag vraagt om één Google zoekopdracht voor batterijrecyclingonderzoek. De klant controleert opnieuw de prijs en het saldo, bespaart vervolgens de respons en drukt de gebruikte bronlinks en credits af.

Een zoekopdracht indienen

Ren één keer van flashdata-mcp-demo. De client maakt mcp-search-output aan voordat deze wordt ingediend; als die directory al bestaat, stopt deze om herhaling van de taak te voorkomen.

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

Het opgeslagen resultaat controleren

mcp-search-output/result.json. openen Verwacht status: done, results[].organic met titels, links en knipsels, en usage.credits. Lege biologische resultaten kunnen geldig zijn. De reactie hieronder is afgekort en illustratief.

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

Lees het opgeslagen resultaat opnieuw

Uitvoeren vanuit dezelfde projectmap. Dit leest result.json en drukt de bronlinks en de originele credits af. Het heeft geen API-sleutel nodig, maakt geen netwerkverzoek en stuurt geen andere zoekopdracht.

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

Herstellen van een onderbroken taak

Houd mcp-search-output als een zoekopdracht stopt voordat de resultaten worden afgedrukt. Een ontbrekende result.json bewijst niet dat het verzoek mislukt is. Controleer de onderstaande bestanden en controleer History alvorens te beslissen of een andere zoekopdracht nodig is.

Bestand in mcp-search-outputWat het je vertelt
request.jsonHet beoogde gereedschapsgesprek. Opgeslagen voor indiening; het bevestigt niet dat FlashData het ontvangen heeft.
mcp-receipt.jsonHet originele MCP antwoord, inclusief fouten of een result_id voor voortzetting. Controleer isError en het responslichaam; HTTP 200 alleen is geen succes.
result.jsonDe verzamelde reactie. Een status van gedaan is klaar om te lezen met --read; behoud request_id voor probleemoplossing.

Hoe groot de resultaten worden verzameld

De client leest structuredContent, of de JSON tekst in inhoud wanneer structuredContent afwezig is. Het controleert isError zelfs wanneer het MCP transport HTTP 200 retourneert.

Wanneer een antwoord result_id bevat, roept completeResult get_result aan met dezelfde credential en gaf next_offset terug tot het null is. Het controleert de volgorde, concateert brokken en ontleedt de volledige JSON. Het originele ontvangstbewijs blijft in mcp-search-output/mcp-receipt.json.

Gebruik deze client in uw toepassing

TaakWat te veranderen
Een andere zoekopdracht uitvoerenWijzig request.arguments.query en uitvoer in mcp-client.mjs voor een nieuwe taak. Hergebruik --read voor dezelfde voltooide taak; bewaar eerdere uitvoermappen.
Laat uw model een gereedschap kiezenGebruik listTools om namen, beschrijvingen en invoerschema's te lezen. Valideer de geselecteerde naam en argumenten, dan callTool onder toestemming van uw toepassing en uitgaven beleid.
Uitvoeren op een schemaHergebruik een eigendomsgetrouwheid uit de permanente geheime opslag. Houd één duurzame record per schema slot; lees opgeslagen uitvoer wanneer dezelfde sleuf herhaalt.
Andere gebruikers verbindenDeze sleutel laadt de rekening van de eigenaar op. Gebruik de eigen geloofwaardigheid van elke gebruiker en isoleer de opgeslagen resultaten. Een OAuth integratie heeft ook een client registratie, toestemming en token opslag nodig; dit API-sleutel voorbeeld implementeert die flow niet.

Problemen oplossen

ProbleemActie
ERR_MODULE_NOT_FOUNDStart npm installatie van flashdata-mcp-demo. Houd mcp-client.mjs naast package.json en node_modules.
FLASHDATA_API_KEYStel de variabele in in dezelfde terminal of hetzelfde proces dat Node.js draait en voer vervolgens knooppunt mcp-client.mjs uit zonder --search.
401Controleer op een verlopen of ingetrokken sleutel. Herstellen van geldige toegang, vervolgens opnieuw uitvoeren van de gratis verbinding controle.
403Controleer de google_search-machtiging en accounttoegang van de sleutel. Een succesvolle balanscontrole bewijst niet dat deze bron is toegestaan.
402 / Insufficient creditsControleer rekeningsaldo en actuele prijzen voordat u een andere taak.
EEXISTEen vorige poging bezit de uitvoermap. Voer knooppunt mcp-client.mjs --read uit als result.json voltooid is; inspecteer anders het ontvangstbewijs en History. Hou de directory.
ENOENT / ongeldig JSON met --readControleer of u in flashdata-mcp-demo bent en inspecteer mcp-search-output/result.json. Als het ontbreekt of onvolledig is, volg Recover een onderbroken taak; --read dient nooit een zoekopdracht in.
429Wacht op Retry-After wanneer deze beschikbaar is. Als een zoekopdracht werd geprobeerd, controleer dan de opgeslagen bestanden en History voordat opnieuw te proberen.
Tijdslimiet / result_unavailableHou het verzoek en de ontvangst. Controleer History of een bestaande taak; een opgeslagen voortzetting kan verlopen zijn.