Parcourir la documentation
Intégrations
Connectez une application Node.js à FlashData, vérifiez l’accès et enregistrez votre premier résultat Google Search.
Sur cette page
Avant de commencer
Utilisez Node.js 22.18+, npm et une clé API avec la permission google_search. Votre application est le client MCP ; FlashData héberge le serveur à l’adresse https://data.flashdata.dev/mcp. L’exemple vérifie gratuitement la connexion, soumet une recherche avec --search et lit le résultat enregistré avec --read.
1. Installer le SDK client
Créez un nouveau projet. Sous Windows, utilisez npm.cmd si npm.ps1 est bloqué.
node --version
mkdir flashdata-mcp-demo
cd flashdata-mcp-demo
npm init -y
npm install --save-exact @modelcontextprotocol/[email protected]2. Configurer votre clé API
Définissez la clé dans ce terminal, ou laissez votre agent injecter FLASHDATA_API_KEY depuis son gestionnaire de secrets. Le client l’envoie dans l’en-tête X-API-Key au point d’accès Streamable HTTP hébergé. Exécutez le code dans un processus local ou côté serveur.
# 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. Enregistrer et vérifier le client
Enregistrez le fichier complet ci-dessous sous le nom mcp-client.mjs dans flashdata-mcp-demo, à côté de package.json. Toutes les commandes de cette page utilisent ce fichier. Il découvre les outils, vérifie les tarifs et le solde actuels, puis assemble les résultats volumineux.
Enregistrer 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();
}Vérifier gratuitement la connexion
Exécutez la commande depuis flashdata-mcp-demo, dans le terminal où vous avez défini la clé. Les sorties attendues sont « Available credits », « One search » et « Connected. No paid query submitted. ». La dernière ligne indique si le solde couvre une recherche. Un solde nul ne signifie pas que l’authentification a échoué.
node mcp-client.mjs4. Lancer votre première recherche
Utilisez le fichier enregistré à l’étape 3. L’option --search demande une recherche Google sur le recyclage des batteries. Le client vérifie à nouveau le tarif et le solde, puis enregistre la réponse et affiche les liens des sources et les crédits utilisés.
Soumettre une recherche
Exécutez la commande une seule fois depuis flashdata-mcp-demo. Le client crée mcp-search-output avant la soumission ; si ce répertoire existe déjà, il s’arrête pour éviter de répéter la tâche.
node mcp-client.mjs --searchInspecter le résultat enregistré
Ouvrez mcp-search-output/result.json. Le résultat attendu contient status: done, results[].organic avec les titres, liens et extraits, ainsi que usage.credits. Un tableau de résultats organiques vide peut être valide. La réponse ci-dessous est un exemple abrégé.
{
"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"
}Relire le résultat enregistré
Exécutez la commande depuis le même répertoire de projet. Elle lit result.json et affiche les liens des sources ainsi que les crédits utilisés lors de la requête initiale. Elle ne nécessite aucune clé API, ne fait aucun appel réseau et ne soumet pas de nouvelle recherche.
node mcp-client.mjs --readReprendre une tâche interrompue
Conservez mcp-search-output si une recherche s’arrête avant d’afficher les résultats. L’absence de result.json ne prouve pas que la requête a échoué. Inspectez les fichiers ci-dessous et consultez History avant de décider si une nouvelle recherche est nécessaire.
| Fichier dans mcp-search-output | Ce qu’il indique |
|---|---|
| request.json | L’appel d’outil prévu. Enregistré avant la soumission, il ne confirme pas que FlashData l’a reçu. |
| mcp-receipt.json | La réponse MCP d’origine, y compris les erreurs ou un result_id permettant de poursuivre la lecture. Vérifiez isError et le corps de la réponse ; un statut HTTP 200 ne suffit pas à confirmer la réussite. |
| result.json | La réponse assemblée. Le statut done indique qu’elle peut être lue avec --read ; conservez request_id pour le dépannage. |
Collecter les résultats volumineux
Le client lit structuredContent ou, si ce champ est absent, le texte JSON de content. Il vérifie isError même lorsque le transport MCP renvoie HTTP 200.
Lorsqu’une réponse contient result_id, completeResult appelle get_result avec les mêmes identifiants et le next_offset renvoyé, jusqu’à ce que celui-ci vaille null. Il vérifie la séquence, concatène les fragments et analyse le JSON complet. Le reçu d’origine reste dans mcp-search-output/mcp-receipt.json.
Utiliser ce client dans votre application
| Tâche | Modification à effectuer |
|---|---|
| Lancer une autre recherche | Modifiez request.arguments.query et output dans mcp-client.mjs pour une nouvelle tâche. Réutilisez --read pour relire la même tâche terminée ; conservez les répertoires de sortie précédents. |
| Laisser votre modèle choisir un outil | Utilisez listTools pour lire les noms, descriptions et schémas d’entrée. Validez le nom et les arguments choisis, puis appelez callTool en respectant la politique d’autorisations et de dépenses de votre application. |
| Exécuter à intervalles réguliers | Réutilisez des identifiants propriétaires conservés dans un stockage persistant de secrets. Gardez un enregistrement durable par créneau planifié ; relisez le résultat enregistré si le même créneau est relancé. |
| Connecter d’autres utilisateurs | Cette clé facture le compte de son propriétaire. Utilisez les identifiants propres à chaque utilisateur et isolez leurs résultats enregistrés. Une intégration OAuth nécessite aussi l’enregistrement d’un client, le consentement et le stockage des jetons ; cet exemple avec clé API n’implémente pas ce parcours. |
Dépannage
| Problème | Action |
|---|---|
| ERR_MODULE_NOT_FOUND | Exécutez npm install depuis flashdata-mcp-demo. Gardez mcp-client.mjs à côté de package.json et de node_modules. |
| FLASHDATA_API_KEY | Définissez la variable dans le terminal ou le processus qui exécute Node.js, puis relancez node mcp-client.mjs sans --search. |
| 401 | Vérifiez si la clé a expiré ou a été révoquée. Rétablissez un accès valide, puis relancez la vérification gratuite de la connexion. |
| 403 | Vérifiez la permission google_search de la clé et l’accès au compte. Une vérification du solde réussie ne prouve pas que cette source est autorisée. |
| 402 / Insufficient credits | Vérifiez le solde du compte et les tarifs actuels avant de soumettre une autre tâche. |
| EEXIST | Une tentative précédente utilise déjà le répertoire de sortie. Exécutez node mcp-client.mjs --read si result.json est complet ; sinon, inspectez son reçu et History. Conservez le répertoire. |
| ENOENT / JSON invalide avec --read | Vérifiez que vous êtes dans flashdata-mcp-demo et inspectez mcp-search-output/result.json. S’il manque ou est incomplet, suivez « Reprendre une tâche interrompue » ; --read ne soumet jamais de recherche. |
| 429 | Respectez le délai Retry-After lorsqu’il est fourni. Si une recherche a été tentée, consultez ses fichiers enregistrés et History avant de réessayer. |
| Délai d’attente dépassé / result_unavailable | Conservez la requête et le reçu. Consultez History ou une tâche existante ; les fragments d’un résultat enregistré peuvent avoir expiré. |