Überspringen zum Inhalt
DE
API-Schlüssel
Dokumentation durchsuchen

Integrationen

Erstellen Sie einen MCP-Client

Verbinden Sie eine Node.js-Anwendung mit FlashData, überprüfen Sie den Zugriff und speichern Sie Ihr erstes Google Search-Ergebnis.

Auf dieser Seite

Bevor Sie anfangen

Verwenden Sie Node.js 22.18+, npm und einen API-Schlüssel mit google_search-Berechtigung. Ihre Anwendung ist der MCP-Client; FlashData hostet den Server unter https://data.flashdata.dev/mcp. Das Beispiel prüft die Verbindung kostenlos, sendet eine Suche mit --search und liest das gespeicherte Ergebnis mit --read.

1. Installieren Sie den Client SDK

Erstellen Sie ein neues Projekt. Verwenden Sie unter Windows npm.cmd, wenn npm.ps1 blockiert ist.

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

2. Stellen Sie Ihren API-Schlüssel ein

Setzen Sie den Schlüssel in diesem Terminal oder lassen Sie Ihren Agenten FLASHDATA_API_KEY aus seinem Geheimspeicher injizieren. Der Client sendet es als X-API-Key-Header an den gehosteten Streamable HTTP-Endpunkt. Führen Sie den Code in einem lokalen oder Serverprozess aus.

Schlüssel setzen
# 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. Speichern und überprüfen Sie den Client

Speichern Sie die vollständige Datei unten als mcp-client.mjs in Flashdata-mcp-Demo, neben package.json. Alle Befehle auf dieser Seite verwenden diese Datei. Es entdeckt Werkzeuge, überprüft die aktuelle Preisgestaltung und Balance und sammelt große Ergebnisse.

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

Überprüfen Sie die Verbindung kostenlos

Führen Sie von flashdata-mcp-demo in dem Terminal aus, in dem Sie den Schlüssel eingestellt haben. Erwarten Sie verfügbare Credits, eine Suche und verbunden. Keine bezahlte Anfrage eingereicht. Die letzte Zeile sagt, ob das Gleichgewicht eine Suche abdeckt. Ein Nullsaldo bedeutet nicht, dass die Authentifizierung fehlgeschlagen ist.

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

4. Führen Sie Ihre erste Suche aus

Verwenden Sie die Datei, die Sie in Schritt 3 gespeichert haben. Das --search-Flag fordert eine Google-Suche nach Batterierecycling-Forschung an. Der Kunde überprüft den Preis und das Gleichgewicht erneut, speichert dann die Antwort und druckt die verwendeten Quelllinks und Credits aus.

Eine Suche einreichen

Führen Sie einmal von flashdata-mcp-demo. Der Client erstellt mcp-search-output vor dem Einreichen; wenn dieses Verzeichnis bereits vorhanden ist, stoppt es, um die Wiederholung der Aufgabe zu vermeiden.

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

Überprüfen Sie das gespeicherte Ergebnis

Open mcp-search-output/result.json. Erwarten Sie status: done, results[].organic mit Titeln, Links und Snippets und usage.credits. Leere organische Ergebnisse können gültig sein. Die Antwort unten ist abgekürzt und illustrativ.

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

Lesen Sie das gespeicherte Ergebnis erneut

Aus dem gleichen Projektverzeichnis ausführen. Dieser liest result.json und druckt die verwendeten Quelllinks und Original-Credits aus. Es benötigt keinen API-Schlüssel, macht keine Netzwerkanforderung und sendet keine weitere Suche.

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

Wiederherstellen einer unterbrochenen Aufgabe

Behalten Sie mcp-search-output, wenn eine Suche vor dem Drucken von Ergebnissen beendet wird. Ein fehlendes result.json beweist nicht, dass die Anforderung fehlgeschlagen ist. Überprüfen Sie die folgenden Dateien und überprüfen Sie History, bevor Sie entscheiden, ob eine weitere Suche erforderlich ist.

Datei in mcp-search-outputWas es dir sagt
request.jsonDer beabsichtigte Tool Call. Vor der Einreichung gespeichert; es bestätigt nicht, dass FlashData es erhalten hat.
mcp-receipt.jsonDie ursprüngliche MCP-Antwort, einschließlich Fehler oder ein result_id zur Fortsetzung. isError und die Antwortstelle überprüfen; HTTP 200 allein ist kein Erfolg.
result.jsonDie zusammengestellte Antwort. Ein Status von done ist bereit, mit --read zu lesen; bewahren Sie request_id für die Fehlersuche auf.

Wie große Ergebnisse gesammelt werden

Der Client liest structuredContent oder den JSON-Text im Inhalt, wenn structuredContent abwesend ist. Es überprüft isError, auch wenn der MCP-Transport HTTP 200 zurückgibt.

Wenn eine Antwort result_id enthält, ruft completeResult get_result mit dem gleichen Anmeldenachweis auf und gibt next_offset zurück, bis es null ist. Es überprüft die Sequenz, verkettet Brocken und analysiert das vollständige JSON. Die ursprüngliche Quittung bleibt in mcp-search-output/mcp-receipt.json.

Verwenden Sie diesen Client in Ihrer Anwendung

AufgabeWas zu ändern ist
Führen Sie eine andere Suche ausÄndern Sie request.arguments.query und geben Sie in mcp-client.mjs für eine neue Aufgabe aus. --read für die gleiche abgeschlossene Aufgabe wiederverwenden; frühere Ausgabeverzeichnisse beibehalten.
Lassen Sie Ihr Modell ein Werkzeug auswählenVerwenden Sie listTools, um Namen, Beschreibungen und Eingabeschemata zu lesen. Validieren Sie den ausgewählten Namen und Argumente, dann callTool unter Ihrer Anwendung Erlaubnis und Ausgabenpolitik.
Laufen Sie nach einem ZeitplanVerwenden Sie einen eigenen Nachweis aus persistenter geheimer Speicherung. Halten Sie einen dauerhaften Datensatz pro Zeitplan-Slot; Lesen Sie die gespeicherte Ausgabe, wenn sich derselbe Slot wiederholt.
Verbinden Sie andere BenutzerDieser Schlüssel belastet das Konto seines Besitzers. Verwenden Sie die eigenen Anmeldeinformationen jedes Benutzers und isolieren Sie die gespeicherten Ergebnisse. Eine OAuth-Integration benötigt auch eine Client-Registrierung, Zustimmung und Token-Speicherung; dieses API-Schlüsselbeispiel implementiert diesen Fluss nicht.

Fehlerbehebung

ProblemAktion
ERR_MODULE_NOT_FOUNDFühren Sie npm-Installation von flashdata-mcp-demo aus. Halten Sie mcp-client.mjs neben package.json und node_modules.
FLASHDATA_API_KEYSetzen Sie die Variable in demselben Terminal oder Prozess, der Node.js ausführt, und führen Sie dann den Knoten mcp-client.mjs ohne --search erneut aus.
401Suchen Sie nach einem abgelaufenen oder widerrufenen Schlüssel. Stellen Sie den gültigen Zugriff wieder her und führen Sie dann die Überprüfung der freien Verbindung erneut aus.
403Überprüfen Sie die google_search-Berechtigung und den Kontozugriff des Schlüssels. Eine erfolgreiche Bilanzprüfung beweist nicht, dass diese Quelle erlaubt ist.
402 / Insufficient creditsÜberprüfen Sie den Kontostand und die aktuellen Preise, bevor Sie eine andere Aufgabe einreichen.
EEXISTEin früherer Versuch besitzt das Ausgabeverzeichnis. Führen Sie den Knoten mcp-client.mjs --read aus, wenn result.json vollständig ist; ansonsten überprüfen Sie seinen Empfang und History. Behalten Sie das Verzeichnis.
ENOENT / ungültig JSON mit --readÜberprüfen Sie, ob Sie sich in der Flashdata-mcp-Demo befinden und mcp-search-output/result.json. inspizieren Wenn es fehlt oder unvollständig ist, folgen Sie Wiederherstellen einer unterbrochenen Aufgabe; --read sendet niemals eine Suche.
429Warten Sie auf Retry-After, wenn Sie bereitgestellt werden. Wenn eine Suche versucht wurde, überprüfen Sie die gespeicherten Dateien und History, bevor Sie erneut versuchen.
Timeout / result_unavailableBewahren Sie die Anfrage und den Empfang auf. Überprüfen Sie History oder einen vorhandenen Job; eine gespeicherte Fortsetzung ist möglicherweise abgelaufen.