Перейти до вмісту
UK
Отримати ключ API
Переглянути документацію

Інтеграції

Створіть клієнт MCP

Підключіть програму Node.js до FlashData, перевірте доступ і заощаджуйте свій перший результат Google Search.

На цій сторінці

Перед тим, як початися

Використовуйте Node.js 22.18+, npm та ключ API з дозволом google_search. Ваше звернення - клієнт MCP; FlashData запускає сервер на https://data.flashdata.dev/mcp. Приклад перевіряє підключення безкоштовно, подає один пошук за допомогою --search і читає його збережений результат з --read.

1. Встановіть клієнт SDK

Створення нового проекту. На Windows використовуйте npm.cmd, якщо npm.ps1 заблоковано.

Новий проект
node --version
mkdir flashdata-mcp-demo
cd flashdata-mcp-demo
npm init -y
npm install --save-exact @modelcontextprotocol/[email protected]

2. Настроювання ключа API

Встановити ключ в цьому терміналі або дати агента в FLASHDATA_API_KEY з його секретного магазину. Клієнт відправив його як заголовок X-API-Key до розміщеної потокової точки HTTP. Запустіть код в локальний або серверний процес.

Задайте ключ
# 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. Заощаджуйте та перевірте клієнт

Заощаджуйте повний файл нижче, як mcp-client.mjs всередині flashdata-mcp-demo, beside package.json. Всі команди на цій сторінці використовують цей файл. Відкриває інструменти, перевіряє поточні ціни та баланс, і збирає великі результати.

Зберегти 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();
}

Перевірити підключення безкоштовно

Запуск з флешки-mcp-demo в терміналі, де ви встановлюєте ключ. Очікуйте наявні кредити, один пошук та підключення. Подано не оплачену запит. Заключна лінія говорить про те, що баланс охоплює один пошук. Нульовий баланс не означає автентифікації.

У флешки-mcp-demo
node mcp-client.mjs

4. Запуск першого пошуку

Використовуйте файл, який ви збережені в крокі 3. Про нас --search прапорець запитати один Google пошук досліджень з переробки акумуляторів. Клієнт перевіряє ціну та баланс знову, після чого зберігає відповідь та друк вихідних посилань та кредитних коштів, що використовуються.

Подати заявку

Запуск один раз з флешки-mcp-demo. Клієнт створює mcp-search-вихід перед поданням; якщо цей каталог вже існує, він перестає уникати повторення завдання.

У флешки-mcp-demo
node mcp-client.mjs --search

Опитування збереженого результату

Відкрити mcp-search-output/result.json. Визначити status: done, results[].organic з назвами, посиланнями та хіппети, і usage.credits. Ви можете бути дійсними. Відповідність нижче скорочена і ілюстративна.

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

Читати збережений результат знову

Запуск з того ж каталогу проекту. Це читає result.json і друкує вихідні посилання та оригінальні кредити, які використовуються. Не потрібно ключ API, не вимагає мережевого запиту і не подає іншого пошуку.

У флешки-mcp-demo
node mcp-client.mjs --read

Відновити переривання завдання

Зберігати mcp-search-вихід, якщо пошук припиняється до результатів друку. Відсутній result.json не доводить запит не вдалося. Переглядайте файли нижче і перевірте History перед тим, як вирішити, чи потрібен інший пошук.

Файл в mcp-search-вихідЩо це говорить вам
request.jsonПідказка призначеного інструменту. Заощаджується перед подачею; не підтверджується, що FlashData отримала його.
mcp-receipt.jsonОригінальний MCP відповідь, включаючи помилки або result_id для продовження. Перевірити isError і тіло відповіді; HTTP 200 самостійно не є успіхом.
result.jsonЗбірний відгук. Статус на сервери - --read; зберегти request_id для усунення несправностей.

Як зібрані великі результати

Клієнт читає structuredContent, або текст JSON в змісті, коли structuredContent немає. Він перевіряє isError навіть коли транспорт MCP повертає HTTP 200.

Коли відповідь містить result_id, completeResult називає get_result з однаковим обліковим записом і повернув next_offset до тих пір, поки це null. Він перевіряє послідовність, приховує шматки і припаркує повну JSON. Оригінальна квитанція залишається в mcp-search-output/mcp-receipt.json.

Використовуйте цей клієнт у додатку

ЗаяваЩо змінити
Виконувати різні пошукиЗміна request.arguments.query і виведення в mcp-client.mjs для нового завдання. Запобігти --read для того ж завершення завдання; зберігати раніше вихідні каталоги.
Нехай ваша модель вибирає інструментВикористовуйте listTools для зчитування імен, описів та вхідних схем. Визначте вибране ім’я та аргументи, потім callTool під дозволом та політикою витрат.
Запуск на графікуВикористовувати власні облікові дані з стійкого секретного зберігання. Зберігати один міцний рекорд за розкладом; читати збережений вихід, коли однаковий слот повторюється.
Підключення інших користувачівЦей ключ стягує свій обліковий запис власника. Використовуйте власні облікові дані кожного користувача та оцінюйте збережені результати. Анжела OAuth інтеграція також вимагає реєстрації клієнтів, згоди та зберігання даних; це API-Приміром не реалізовано цей потік.

Виправлення несправностей

ПроблемаДія
ERR_MODULE_NOT_FOUNDЗапустіть npm встановити з флешки-файлів-mcp-demo. Зареєструватися mcp-client.mjs кицька package.json і node_modules.
FLASHDATA_API_KEYВстановіть змінну в одному терміналі або процес, який працює Node.js, потім перезапустіть вузол mcp-client.mjs без --search.
401Перевірити на екран або відкликати ключ. Відновити дійсний доступ, після чого перезапустіть перевірку вільного підключення.
403Перевірити доступ до облікового запису ключа google_search. Успішний контроль балансу не доведе цього джерела.
402 / Insufficient creditsПеревірити залишок рахунку та поточне ціноутворення перед поданням іншого завдання.
EEXISTПопередня спроба власноручає вихідний каталог. Запуск вузла mcp-client.mjs --read, якщо result.json завершено; в іншому випадку перевірте його отримання і History. Збережіть каталог.
ENOENT / Неймовірний JSON з --readПеревірити, що ви в флешки-mcp-demo і перевірити mcp-search-output/result.json. Якщо він відсутній або неповний, слід відновити переривання завдання; --read ніколи не подає пошук.
429Зачекайте Retry-After при наданні. Якщо було спробовано пошук, перевірте збережені файли і History перед перездобленням.
Часовий час / result_unavailableЗберігайте запит і отримання. Перевірити History або існуючу роботу; збережене продовження може бути продовжено.