# Bir MCP müşteri oluşturun

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

Canonical referans: https://flashdata.dev/tr/docs/guides/mcp-custom-client
İnceleme: 2026-11-05 Tarafından FlashData

<a id="prepare"></a>

## 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.

- [Yükleme yükleme Node.js](https://nodejs.org/en/download)
- [Bir API anahtarı oluşturun](https://flashdata.dev/app/api-keys)
- [Mevcut bir MCP uygulaması](https://flashdata.dev/tr/docs/integrations/mcp-clients/reference.md)

<a id="client"></a>

## 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

```bash
node --version
mkdir flashdata-mcp-demo
cd flashdata-mcp-demo
npm init -y
npm install --save-exact @modelcontextprotocol/sdk@1.30.0
```


<a id="authenticate"></a>

## 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.

### Bash

#### Anahtarınızı ayarlayın

```bash
# 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

#### Anahtarınızı ayarlayın

```powershell
# 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 flashdataSecureKey
```



<a id="client-run"></a>

## 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.


<a id="client-source"></a>

### Save Kaydet mcp-client.mjs

#### flashdata-mcp-demo/mcp-client.mjs

```javascript
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();
}
```


<a id="check-output"></a>

### Ü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

```bash
node mcp-client.mjs
```

- [Check kredi](https://flashdata.dev/app/billing)

<a id="first-task"></a>

## 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.


<a id="submit"></a>

### 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

```bash
node mcp-client.mjs --search
```


<a id="result"></a>

### 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

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


<a id="read-saved"></a>

### 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

```bash
node mcp-client.mjs --read
```


<a id="saved-files"></a>

## 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 dosya | Size ne diyor ki |
| --- | --- |
| request.json | Amaçlı araç çağrısı. Sunmadan önce kurtarıldı; FlashData'nun bunu aldığını doğrulamaz. |
| mcp-receipt.json | Orijinal 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.json | Bir araya gelen yanıt. Yapılan bir durum --read ile okumaya hazır; request_id'u sorun giderme için korumak için. |

- [Tarih İstek Tarihi](https://flashdata.dev/app/jobs)
- [Süreklilik ayrıntıları](https://flashdata.dev/tr/docs/guides/mcp-custom-client/reference.md#continuations)

<a id="continuations"></a>

## 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

- [MCP araçları ve devam şemaları](https://flashdata.dev/tr/docs/mcp/reference.md)

<a id="reuse"></a>

## Uygulamanızda bu müşteriyi kullanın

| Görev Görev Görevi | Ne değiştirmek için |
| --- | --- |
| Farklı bir arama | request.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 verin | listTools'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 schedule | Kalı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ı kurun | Bu 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. |

- [Yinelenen görevler](https://flashdata.dev/tr/docs/guides/recurring-tasks/reference.md)
- [Kimlik seçenekleri](https://flashdata.dev/tr/docs/guides/agent-access/reference.md)

<a id="operate"></a>

## Sorun Giderme

| Problem Sorun Problem Problem Problem | Action Action Action |
| --- | --- |
| ERR_MODULE_NOT_FOUND | Run 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_KEY | Aynı terminalde veya işlemdeki değişkenleri ayarlayın Node.jsDaha sonra yeniden kovalan mcp-client.mjs Hayırsız olmadan --search. |
| 401 | Geç 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. |
| 403 | Anahtarı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 credits | Baş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 --read | Flashdata-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. |
| 429 | Retry-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. |

- [Tarih İstek Tarihi](https://flashdata.dev/app/jobs)
- [MCP sorun giderme](https://flashdata.dev/tr/docs/guides/troubleshooting/reference.md#mcp)
