# بناء عميل من شركة MCP

تماسكوا Node.js الطلب إلى FlashDataتحقق من الدخول ووفر أول Google Search نتيجة.

مرجع كانوني: https://flashdata.dev/ar/docs/guides/mcp-custom-client
Reviewed: 2026-11-05 by FlashData

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

## قبل أن تبدأ

استخدم Node.js 22.18+ وnpm ومفتاح API بصلاحية google_search. تطبيقك هو عميل MCP؛ وتستضيف FlashData الخادم على https://data.flashdata.dev/mcp. يفحص المثال الاتصال مجانًا، ويرسل بحثًا واحدًا باستخدام --search، ويقرأ نتيجته المحفوظة باستخدام --read.

- [Install Node.js](https://nodejs.org/en/download)
- [Create an API key](https://flashdata.dev/app/api-keys)
- [Connect an existing MCP app](https://flashdata.dev/ar/docs/integrations/mcp-clients/reference.md)

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

## 1. تركيب العميل SDK

إنشاء مشروع جديد. On Windows, use npm.cmd if npm.ps1 is blocked.

### المشروع الجديد

```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 المفتاح

ضع المفتاح في هذه المحطة أو دع عميلك يحقن FLASHDATA_API_KEY من متجرها السري ويرسله العميل كرئيس لشركة X-API-Key إلى نقطة نهاية ثابتة من طراز HTTP. تشغيل الرمز في عملية محلية أو خادم.

### Bash

#### اضبط المفتاح

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

#### اضبط المفتاح

```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. أنقذ وتحقق من العميل

وفّر الملف الكامل تحت الرمز mcp-client.mjs داخل فلاشداتا-mcp-demo، بجانب package.json. جميع الأوامر على هذه الصفحة تستخدم هذا الملف وهو يكتشف الأدوات، ويتحقق من التسعير والتوازن الحاليين، ويجمع نتائج كبيرة.


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

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

### تحققي من الاتصال بالمجان

اهرب من (فلادداتا) و(مكوب ديمو) في المحطة حيث وضعت المفتاح توقع الائتمانات المتاحة، بحث واحد و متصل. No paid query submitted. السطر الأخير يقول ما إذا كان الميزان يغطي بحثا واحدا ولا يعني أي توازن صفري أن التوثيق قد فشل.

#### In flashdata-mcp-demo

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

- [الأرصدة الدائنة الشيكة](https://flashdata.dev/app/billing)

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

## 4. أجري بحثك الأول

استخدم الملف الذي انقذته في الخطوة 3. ويطالب علم --search ببحث واحد من طراز Google بحثا عن إعادة تدوير البطاريات. ويتحقق العميل من السعر والتوازن مرة أخرى، ثم يحفظ الرد ويطبع وصلات المصدر والائتمانات المستخدمة.


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

### قم بتفتيش واحد

اركض مرة من فيلداتا-ماكب-ديمو ويقوم الزبون بخلق ماكب - سيك - أوب - أوت قبل تقديمه؛ وإذا كان هذا الدليل موجودا بالفعل، فإنه يتوقف عن تكرار المهمة.

#### In flashdata-mcp-demo

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


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

### فحص النتيجة المنقذة

افتح mcp-search-output/result.json. توقّع status: done وresults[].organic مع عناوين وروابط ومقتطفات، وusage.credits. قد تكون النتائج العضوية الفارغة صالحة. الاستجابة أدناه مختصرة وتوضيحية.

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

### إقرأ النتيجة المنقذة مرة أخرى

اهرب من نفس دليل المشروع ويقرأ هذا الرقم result.json ويطبع وصلات المصدر والائتمانات الأصلية المستخدمة. ولا يحتاج إلى مفتاح API، ولا يقدم أي طلب من الشبكة ولا يقدم بحثاً آخر.

#### In flashdata-mcp-demo

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


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

## استرداد مهمة مقاطعه

احتفظ بـ mcp-search-output إذا توقف البحث قبل طباعة النتائج. غياب result.json لا يثبت فشل الطلب. افحص الملفات أدناه وسجل History قبل تقرير الحاجة إلى بحث آخر.

| File in mcp-search-output | ما يخبرك به |
| --- | --- |
| request.json | نداء الأدوات المقصود. تم إنقاذه قبل تقديمه، ولا يؤكد أن شركة FlashData تلقته. |
| mcp-receipt.json | الرد الأصلي MCP، بما في ذلك الأخطاء أو result_id للاستمرار. (أ) التحقق من الـ isError وجهاز الاستجابة؛ HTTP 200 alone is not success. |
| result.json | الاستجابة المجمّعة. تعني الحالة done أنها جاهزة للقراءة باستخدام --read؛ احتفظ بـ request_id لاستكشاف الأخطاء. |

- [التاريخ](https://flashdata.dev/app/jobs)
- [تفاصيل الاستمرارية](https://flashdata.dev/ar/docs/guides/mcp-custom-client/reference.md#continuations)

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

## مدى جمع النتائج الكبيرة

ويقرأ الزبون structuredContent، أو نص JSON في المحتوى عندما يكون structuredContent غائبا. ويتحقق من شركة isError حتى عندما تعود شركة MCP للنقل إلى شركة HTTP 200.

عندما تحتوي الاستجابة result_id، تستدعي completeResult الأداة get_result ببيانات الاعتماد نفسها وقيمة next_offset العائدة حتى تصبح null. تتحقق من التسلسل، وتجمع الأجزاء، وتحلل JSON كاملًا. يبقى الإيصال الأصلي في mcp-search-output/mcp-receipt.json.

- [أدوات MCP وخصائص استمرارية](https://flashdata.dev/ar/docs/mcp/reference.md)

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

## استخدم هذا العميل في طلبك

| المهام | ما الذي سيتغير |
| --- | --- |
| أجري بحثا مختلفا | غيّر request.arguments.query وoutput في mcp-client.mjs لمهمة جديدة. أعد استخدام --read للمهمة المكتملة نفسها؛ واحتفظ بدلائل الإخراج السابقة. |
| دع نموذجك يختار أداة | الاستخدام listTools لقراءة الأسماء والأوصاف والخصائص نقيم الاسم المختار والحجج، ثم callTool تحت إذن الطلب وسياسة الإنفاق. |
| تشغيل على جدول زمني | إعادة استخدام عقيدة ملكية من التخزين السري المستمر. احتفظ بسجل دائم واحد لكل جدول زمني؛ وقراءة الناتج المنقذ عندما يكرر نفس الجدول الزمني. |
| الاتصال بالمستعملين الآخرين | هذا المفتاح يتهم حساب مالكها إستخدم كلّ مُستعمِل خاصّ وعزل نتائجهم المُنقذة. An OAuth ويحتاج الإدماج أيضا إلى تسجيل العملاء والموافقة والتخزين المكسور؛ API- مثال لا يُنفذ هذا التدفق. |

- [المهام المتكررة](https://flashdata.dev/ar/docs/guides/recurring-tasks/reference.md)
- [خيارات التوثيق](https://flashdata.dev/ar/docs/guides/agent-access/reference.md)

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

## اضطرابات

| المشكلة | الإجراء |
| --- | --- |
| ERR_MODULE_NOT_FOUND | تشغيل npm install من الوميضات-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 / invalid JSON with --read | تحقق من أنك في وفللداتا مكسيكو ديمو وتفقد mcp-search-output/result.json. وإذا كانت مفقودة أو ناقصة، تتبع شركة " Recover an interrupted task; --read " لا تقدم أي بحث. |
| 429 | انتظر Retry-After عندما تقدم. إذا حاول البحث، تحقق من ملفاته المحفوظة و History قبل إعادة التجريب. |
| الوقت المتوقّع/ result_unavailable | احتفظ بالطلب و الإيصال (ج) التحقق من أن شركة History أو وظيفة قائمة؛ وقد تكون فترة الاستمرار الموفرة قد انتهت. |

- [التاريخ](https://flashdata.dev/app/jobs)
- [MCP troubleshooting](https://flashdata.dev/ar/docs/guides/troubleshooting/reference.md#mcp)
