Dokumentation durchsuchen
Integrationen
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.
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.
# 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: 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 flashdataSecureKey3. 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
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.
node mcp-client.mjs4. 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.
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.
{
"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.
node mcp-client.mjs --readWiederherstellen 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-output | Was es dir sagt |
|---|---|
| request.json | Der beabsichtigte Tool Call. Vor der Einreichung gespeichert; es bestätigt nicht, dass FlashData es erhalten hat. |
| mcp-receipt.json | Die 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.json | Die 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
| Aufgabe | Was 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ählen | Verwenden 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 Zeitplan | Verwenden 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 Benutzer | Dieser 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
| Problem | Aktion |
|---|---|
| ERR_MODULE_NOT_FOUND | Führen Sie npm-Installation von flashdata-mcp-demo aus. Halten Sie mcp-client.mjs neben package.json und node_modules. |
| FLASHDATA_API_KEY | Setzen 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. |
| 401 | Suchen 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. |
| EEXIST | Ein 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. |
| 429 | Warten 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_unavailable | Bewahren Sie die Anfrage und den Empfang auf. Überprüfen Sie History oder einen vorhandenen Job; eine gespeicherte Fortsetzung ist möglicherweise abgelaufen. |