# Xây dựng a MCP ứng dụng khách

Kết nối Node.js ứng dụng cho FlashDatakiểm tra truy cập và lưu lần đầu Google Search Kết quả.

Tài liệu tham khảo chính điển: https://flashdata.dev/vi/docs/guides/mcp-custom-client
Xem lại: 2026-11-05 by FlashData

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

## Trước khi bắt đầu

Dùng Node.js 22.18+, npm và a API phím với google_search Cho phép. Ứng dụng của bạn là MCP Khách hàng; FlashData Máy phục vụ tại https://data.flashdata.dev/mcp. Các ví dụ kiểm tra kết nối miễn phí, gửi một tìm kiếm với --search và đọc kết quả cứu mạng của nó với --read.

- [Cài đặt Node.js](https://nodejs.org/en/download)
- [Tạo ra một API Khóa](https://flashdata.dev/app/api-keys)
- [Kết nối MCP ứng dụng](https://flashdata.dev/vi/docs/integrations/mcp-clients/reference.md)

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

## 1. Cài đặt ứng dụng khách SDK

Tạo một dự án mới. Vào Windowssử dụng npm.cmd nếu npm.ps1 bị chặn rồi.

### Dự án mới

```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. Đặt khóa API

Đặt chìa khóa trong thiết bị cuối này, hoặc để đại diện của bạn tiêm FLASHDATA_API_KEY từ cửa hàng bí mật của nó. Khách hàng gửi nó như một X-API-Key Đầu trang tới máy chủ có thể chảy HTTP điểm cuối. Chạy mã trong tiến trình máy chủ hay cục bộ.

### Bash

#### Đặt khóa

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

#### Đặt khóa

```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. Lưu và kiểm tra khách hàng

Lưu toàn bộ tập tin bên dưới như mcp-client.mjs bên trong flashdata-mcp-demo, package.json. Mọi lệnh trên trang này dùng tập tin này. Nó khám phá ra các công cụ, kiểm tra giá cả hiện tại và sự số dư, và thu thập kết quả lớn.


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

### Lưu 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>

### Kiểm tra kết nối miễn phí

Chạy từ đèn flashdata-mcp-demo trong thiết bị cuối nơi bạn đặt chìa khóa. Mong đợi tín dụng sẵn sàng, một tìm kiếm và kết nối. Không có truy vấn trả tiền gửi. Dòng cuối cùng cho biết sự số dư bao gồm một tìm kiếm. Một số không số dư không có nghĩa là xác thực thất bại.

#### Trong flashdata-mcp-demo

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

- [Kiểm tra tín dụng](https://flashdata.dev/app/billing)

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

## 4. Chạy tìm kiếm đầu tiên

Dùng tập tin bạn đã lưu trong bước 3. Hạt --search Yêu cầu cờ 1 Google Tìm kiếm nghiên cứu tái chế pin. Khách hàng kiểm tra lại giá cả và sự số dư, rồi lưu lại các phản hồi và in đường dẫn gốc và tín dụng được dùng.


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

### Gửi một cuộc tìm kiếm

Chạy một lần khỏi Flashdata-mcp-demo. Ứng dụng khách tạo thông tin- tìm kiếm- ra trước khi gửi; nếu thư mục đó đã có, nó sẽ dừng lại để tránh lặp lại tác vụ.

#### Trong flashdata-mcp-demo

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


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

### Xem xét kết quả đã lưu

Mở mcp-search-output/result.json. Mong đợi status: done, results[].organic với tiêu đề, liên kết và đoạn trích, và usage.credits. Kết quả hữu cơ rỗng có thể hợp lệ. Câu trả lời dưới đây được viết tắt và diễn tả lại.

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

### Đọc lại kết quả đã lưu

Chạy từ cùng một thư mục dự án. Đây là result.json và in các liên kết gốc và tín dụng gốc được dùng. Không cần đâu API Khóa: không yêu cầu mạng nào và cũng không gửi một cuộc tìm kiếm khác.

#### Trong flashdata-mcp-demo

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


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

## Phục hồi tác vụ bị ngắt quãng

Giữ sổ ghi nhớ để tìm kiếm kỹ càng nếu việc tìm kiếm dừng lại trước khi có kết quả in. Một result.json bị mất không chứng minh yêu cầu đã thất bại. Kiểm tra các tập tin bên dưới và kiểm tra History Trước khi quyết định xem có cần tìm kiếm thêm không.

| Tập tin ở dạng thực hiện tìm kiếm mtp | Những gì nó nói với bạn |
| --- | --- |
| request.json | Cuộc gọi công cụ đã định trước. Được cứu trước khi phục tùng; nó không xác nhận rằng FlashData Đã nhận nó. |
| mcp-receipt.json | Bản gốc MCP trả lời, bao gồm lỗi hoặc a result_id để tiếp tục. Kiểm tra isError và cơ thể phản ứng. HTTP 200 một mình thì không thành công. |
| result.json | Các anh chị đã hưởng ứng. Tình trạng hoàn tất sẵn sàng để đọc --read; Bảo tồn request_id Để bắn rắc rối. |

- [Yêu cầu lịch sử](https://flashdata.dev/app/jobs)
- [Chi tiết liên tục](https://flashdata.dev/vi/docs/guides/mcp-custom-client/reference.md#continuations)

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

## Kết quả thu được lớn như thế nào

Khách hàng đọc structuredContenthoặc là JSON Văn bản trong nội dung khi structuredContent là vắng mặt. Kiểm tra rồi isError Thậm chí khi MCP Vận chuyển trở lại HTTP 200.

Khi có phản ứng chứa result_id, completeResult cuộc gọi get_result Với cùng một thẻ ủy nhiệm và trở lại next_offset Cho đến khi nó là null. Nó kiểm tra chuỗi, phân loại các đoạn và phân tích đầy đủ JSON. Hóa đơn gốc vẫn còn trong đó. mcp-search-output/mcp-receipt.json.

- [MCP Công cụ và kế hoạch hóa](https://flashdata.dev/vi/docs/mcp/reference.md)

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

## Dùng trình khách này trong ứng dụng của bạn

| Tác vụ | Thay đổi gì đây? |
| --- | --- |
| Chạy tìm kiếm khác | Thay đổi request.arguments.query và kết xuất vào mcp-client.mjs cho một nhiệm vụ mới. Dùng lại --read tác vụ hoàn thành tương tự; giữ thư mục xuất trước đó. |
| Hãy để mô hình của bạn chọn một công cụ | Dùng listTools để đọc tên, mô tả và thiết bị nhập. Kiểm tra tên và đối số đã chọn, rồi callTool dưới sự cho phép và chính sách chi tiêu của ứng dụng. |
| Chạy theo lịch | Sử dụng lại một giấy chứng nhận sở hữu từ kho bí mật dai dẳng. Giữ một ghi chú bền vững mỗi khe cắm thời gian biểu; đọc lưu kết xuất khi cùng khe lặp lại. |
| Kết nối người dùng khác | Chìa khóa này tính tiền tài khoản của chủ nó. Sử dụng thẻ tín dụng của mỗi người dùng và cô lập kết quả cứu mạng của họ. An OAuth Sự tích hợp cũng cần một giấy đăng ký khách hàng, sự đồng ý và sự lưu trữ có hiệu lực; điều này API- Ví dụ quan trọng không thực hiện dòng chảy đó. |

- [Tác vụ định kỳ](https://flashdata.dev/vi/docs/guides/recurring-tasks/reference.md)
- [Tùy chọn xác thực](https://flashdata.dev/vi/docs/guides/agent-access/reference.md)

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

## Khắc phục sự cố

| Vấn đề | Hành động |
| --- | --- |
| ERR_MODULE_NOT_FOUND | Chạy npm cài đặt từ flashdata-mcp-demo. Giữ mcp-client.mjs bên cạnh package.json và node_modules. |
| FLASHDATA_API_KEY | Đặt biến trong cùng thiết bị cuối hay tiến trình chạy Node.jsSau đó, chạy lại nút mcp-client.mjs không có --search. |
| 401 | Kiểm tra có phím hết hạn hoặc bị thu hồi không. Phục hồi quyền truy cập hợp lệ, rồi chạy lại kiểm tra kết nối miễn phí. |
| 403 | Kiểm tra chìa khóa google_search Cho phép và truy cập tài khoản. Kiểm tra số dư thành công không chứng minh nguồn này được cho phép. |
| 402 / Insufficient credits | Kiểm tra số dư tài khoản và giá trị hiện tại trước khi gửi một tác vụ khác. |
| EEXIST | Một lần thử trước sở hữu thư mục xuất. Chạy nút mcp-client.mjs --read nếu result.json là hoàn tất; nếu không kiểm tra biên lai của nó và History. Giữ lại thư mục. |
| _Không có / không hợp lệ JSON có --read | Kiểm tra xem bạn đang ở trong Lightdata-mcp-demo và thanh tra mcp-search-output/result.json. Nếu nó còn thiếu hay không đầy đủ, hãy theo dõi lại một tác vụ bị ngắt quãng; --read Không bao giờ nộp đơn tìm kiếm. |
| 429 | Đợi Retry-After được cung cấp. Nếu tìm kiếm đã cố gắng, kiểm tra các tập tin đã lưu của nó và History trước khi thử lại. |
| Thời hạn / result_unavailable | Giữ lại yêu cầu và hóa đơn. Kiểm tra History hoặc một công việc đã có; một việc tiếp tục lưu có thể đã hết hạn. |

- [Yêu cầu lịch sử](https://flashdata.dev/app/jobs)
- [MCP tiếng súng nổ](https://flashdata.dev/vi/docs/guides/troubleshooting/reference.md#mcp)
