İçeriğe geç
TR
API anahtarı al
Belgeleri incele

Entegrasyonlar

Bir MCP müşteri oluşturun

Node.js uygulamasına FlashData'ye bağlanın ve ilk Google Search sonucunu kurtarın.

Bu sayfada

Başlamadan önce başlamadan önce

Node.js 22.18+, npm ve API anahtarını google_search izni ile kullanın. Uygulamanız MCP müşteridir; FlashData sunucuya ev sahipliği yapın https://data.flashdata.dev/mcp. Örnek ücretsiz bağlantıyı kontrol eder, --search ile bir arama yapar ve --read ile kaydedilen sonucu okur.

1. Müşteri SDK

Yeni bir proje oluşturun. Windows, npm.cmd'u npm.ps1'un bloke edilmesi durumunda kullanır.

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

2. API anahtarını ayarlayın

Bu terminaldeki anahtarı ayarlayın veya ajanınızın FLASHDATA_API_KEY'yu gizli mağazasından enjekte etmesine izin verin. Müşteri onu X-API-Key başlığıyla barındırılan Streamable HTTP uç noktası olarak gönderir. Kodu yerel veya sunucu sürecinde çalıştırın.

Anahtarınızı ayarlayın
# 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. Kurtarın ve müşteriyi kontrol edin

mcp-client.mjs olarak aşağıdaki tam dosyayı flaşda-mcp-demo'nun içinde package.json'nun yanında kurtarın. Bu sayfada tüm komutlar bu dosyayı kullanır. Araçlar keşfeder, mevcut fiyat ve dengeyi kontrol eder ve büyük sonuçları toplar.

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

Ücretsiz olarak bağlantıyı kontrol edin

Anahtarı belirlediğiniz terminalde flaştan-mcp-demo'dan hareket edin. Mevcut krediler, One search and Connected. Hiçbir ödeme sorgusu sunulmadı. Nihai çizgi, dengenin bir aramayı kapsadığını söylüyor. Sıfır bir denge, kimlik doğrulamanın başarısız olduğu anlamına gelmez.

flaşda-mcp-demo
node mcp-client.mjs

4. İlk aramanızı çalıştırın

3 adımında kaydettiğiniz dosyayı kullanın. --search bayrağı bir Google arama batarya geri dönüşüm araştırmasını talep ediyor. Müşteri fiyatı ve bakiyeyi tekrar kontrol eder, sonra kullanılan kaynak bağlantılarını ve kredilerini kurtarır.

Bir arama gönder

flashdata-mcp-demo klasöründen bir kez çalıştırın. İstemci göndermeden önce mcp-search-output klasörünü oluşturur; klasör zaten varsa görevi tekrarlamamak için durur.

flaşda-mcp-demo
node mcp-client.mjs --search

Kurtarılan sonucun

Açık mcp-search-output/result.json. status: done, results[].organic'u başlıklar, bağlantılar ve parçalarla ve usage.credits'yu bekleyin. Boş organik sonuçlar geçerli olabilir. Aşağıdaki yanıt kısaltılmış ve açıklayıcıdır.

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

Kurtarılan sonucu tekrar okuyun

Aynı proje rehberinden hareket edin. Bu, result.json'u okur ve kullanılan kaynak bağlantılarını ve orijinal kredileri yazdırır. API anahtarına ihtiyacı yoktur, ağ isteği yapmayın ve başka bir arama sunmuyor.

flaşda-mcp-demo
node mcp-client.mjs --read

Bir kesinti görevi yeniden keşfedin

Arama sonuçları yazdırılmadan durursa mcp-search-output klasörünü koruyun. result.json dosyasının bulunmaması isteğin başarısız olduğunu kanıtlamaz. Yeni bir aramanın gerekip gerekmediğine karar vermeden önce aşağıdaki dosyaları ve History bölümünü inceleyin.

mcp-search-output içindeki dosyaSize ne diyor ki
request.jsonAmaçlı araç çağrısı. Sunmadan önce kurtarıldı; FlashData'nun bunu aldığını doğrulamaz.
mcp-receipt.jsonOrijinal MCP Cevap, hataları veya devam etmek için result_id. isError ve yanıt gövdesini kontrol edin; HTTP 200 tek başına başarı değildir.
result.jsonBir araya gelen yanıt. Yapılan bir durum --read ile okumaya hazır; request_id'u sorun giderme için korumak için.

Ne kadar büyük sonuçlar toplanıyor

Müşteri, structuredContent veya JSON metnini structuredContent'nun olmadığı durumlarda okur. isError'u MCP taşıması HTTP 200'yu geri döndürür.

Bir cevap result_id, completeResult, get_result ile aynı haçlı ve next_offset'yu null'ye kadar geri döndü. Diziyi kontrol eder, kıkırıklar ve JSON ile dolu parlar. Orijinal makbuz mcp-search-output/mcp-receipt.json.'da kalır

Uygulamanızda bu müşteriyi kullanın

Görev Görev GöreviNe değiştirmek için
Farklı bir aramarequest.arguments.query ve mcp-client.mjs'da yeni bir görev için çıktı. --read'u aynı tamamlanmış görev için kullanın; daha önce üretilen yönetmenleri tut.
Modelinizin bir alet seçmesine izin verinlistTools'u isimleri, açıklamaları ve giriş şemalarını okumak için kullanın. Seçilen adı ve argümanları geçerli, sonra callTool uygulamanızın izni ve harcama politikası altında.
Bir programda Run on a scheduleKalıcı gizli depolamadan ait bir haçlı kullanın. Program slotunda kalıcı bir kayıt tutun; aynı slot tekrarlandığında kaydedilen çıktıyı okuyun.
Diğer kullanıcılarla bağlantı kurunBu anahtar, sahibinin hesabını öder. Her kullanıcının kendi credential ve kurtarılmış sonuçlarını izole edin. Bir OAuth entegrasyonu da bir müşteri kaydına, onay ve token depolamaya ihtiyaç duyar; bu API-key örneği bu akışı uygulamaz.

Sorun Giderme

Problem Sorun Problem Problem ProblemAction Action Action
ERR_MODULE_NOT_FOUNDRun npm install from flashdata-mcp-demo. Keep Keep Keep mcp-client.mjs yanında başka bir yerde package.json Ve ve node_modules.
FLASHDATA_API_KEYAynı terminalde veya işlemdeki değişkenleri ayarlayın Node.jsDaha sonra yeniden kovalan mcp-client.mjs Hayırsız olmadan --search.
401Geç veya iptal edilen bir anahtar için kontrol edin. Geçerli erişim geri yükleme, sonra ücretsiz bağlantı kontrolü yeniden çalıştırın.
403Anahtarın google_search iznini ve hesap erişimini kontrol edin. Başarılı bakiye kontrolü bu kaynağa izin verildiğini kanıtlamaz.
402 / Insufficient creditsBaşka bir görevi sunmadan önce hesap dengesi ve mevcut fiyatlandırmayı kontrol edin.
EEXISTÖnceki bir girişim, çıktı dizinine sahiptir. mcp-client.mjs --read eğer result.json tamamlanmışsa; aksi takdirde makb ve History'yu inceler. rehberi tut.
ENOENT / geçersiz JSON with with with ile --readFlashdata-mcp-demo'da olduğunuzu kontrol edin ve mcp-search-output/result.json. Eksik veya eksikse, kesintiye uğrayan bir görevi yeniden keşfedin; --read asla bir arama göndermez.
429Retry-After için bekleyin. Bir arama denediyse, kurtarılan dosyaları ve History'yu yeniden denemeden önce kontrol edin.
Timeout / result_unavailableİstek ve makbuz tut. History veya mevcut bir iş kontrol edin; kurtarılan bir devam süresi sona ermiş olabilir.