# MCPクライアントの構築

Node.jsアプリケーションをFlashDataに接続し、アクセスを確認し、最初のGoogle Search結果を保存します。

キャニシニカル参照: https://flashdata.dev/ja/docs/guides/mcp-custom-client
レビュー: FlashData による 2026-11-05

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

## はじめる前に

Node.js 22.18+、npm、google_searchの許可とAPIキーを使用します。 アプリケーションは MCP クライアントです。 FlashDataはhttps://data.flashdata.dev/mcp.でサーバーをホストします 例では、--searchで1つの検索を1つ提出し、保存した結果を--readで読み込みます。

- [Node.jsをインストールする](https://nodejs.org/en/download)
- [APIキーを作成する](https://flashdata.dev/app/api-keys)
- [既存のMCPアプリを接続](https://flashdata.dev/ja/docs/integrations/mcp-clients/reference.md)

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

## 1. クライアントをインストール SDK

新規プロジェクトを作成します。 にほんご Windows、使用して下さい npm.cmd もしも npm.ps1 ブロックされます。

### 新規プロジェクト

```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 ヘッダーとしてホストされている Streamable 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. クライアントの保存とチェック

package.jsonの横にあるフラッシュデータmcp-demoの内部でmcp-client.mjsとして下の完全なファイルを保存して下さい。 このページの全てのコマンドは、このファイルを使用します。 ツールを発見し、現在の価格設定と残高を確認し、大きな結果を収集します。


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

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

### 無料で接続を確認してください

キーボードをセットするターミナルのフラッシュデータmcp-demoから実行します。 利用可能なクレジット、ワン検索、コネクティッドを期待できます。 有料の問い合わせは受け付けません。 最後の行は、残高が1つの検索をカバーするかどうかを言います。 ゼロバランスは認証が失敗するわけではありません。

#### Flashdata-mcp-demo で

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

- [クレジットの確認](https://flashdata.dev/app/billing)

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

## 4. 最初の検索を実行する

保存したファイルをステップ3で使用してください。 --search フラグは、バッテリーのリサイクル研究のための Google の検索を 1 つリクエストします。 クライアントは、価格を確認し、再びバランスをとり、応答を保存し、ソースリンクと使用されるクレジットを印刷します。


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

### 1つの検索を提出する

flashdata-mcp-demo から一度実行します。 クライアントは、送信する前に mcp-search-output を作成します。そのディレクトリが既に存在している場合は、タスクを繰り返すのを避けるため停止します。

#### 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キーを必要としないため、ネットワークのリクエストはなく、別の検索を提出しません。

#### Flashdata-mcp-demo で

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


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

## 中断されたタスクを回復する

結果を印刷する前に検索が停止した場合、mcp-search-output を保持します。 result.json が見つからない場合、リクエストの失敗は証明できません。 下のファイルを調べて、別の検索が必要かどうかを決定する前に History を確認してください。

| mcp-search-output のファイル | それがあなたに言うもの |
| --- | --- |
| request.json | 意図したツールコール。 投稿前に保存されます。FlashData が受信したことは確認できません。 |
| mcp-receipt.json | MCP は、エラーや result_id などの応答を継続します。 isErrorと応答ボディをチェックする。 HTTP 200だけでは成功しません。 |
| result.json | 組み立てられた応答。 --readで読みやすく、トラブルシューティングにrequest_idを保存します。 |

- [リクエスト履歴](https://flashdata.dev/app/jobs)
- [継続的詳細](https://flashdata.dev/ja/docs/guides/mcp-custom-client/reference.md#continuations)

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

## 結果の収集方法

クライアントが読み込まれる structuredContent, または JSON コンテンツのテキスト structuredContent 不在です。 MCP トランスポートが HTTP 200 を返す場合でも、isError をチェックします。

応答にresult_idが含まれている場合、completeResultは同じ資格とget_resultを呼び出し、nullになるまでnext_offsetを返しました。 これは、シーケンスをチェックします, チャンクを連結し、完全なJSONを解析. mcp-search-output/mcp-receipt.json.に元のレシートが滞在

- [MCP ツールと継続スキーマ](https://flashdata.dev/ja/docs/mcp/reference.md)

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

## アプリケーションでこのクライアントを使用する

| タスク | 変更点 |
| --- | --- |
| 異なる検索を実行 | request.arguments.query を変更し、mcp-client.mjs で新しいタスクを出力します。 --read を同一の完了タスクに再利用し、以前の出力ディレクトリを保持します。 |
| モデルをツールを選ぶようにする | listTools を使用して、名前、説明、入力スキーマを読みます。 選択した名前と引数を検証し、アプリケーションの許可と支出ポリシーの下の callTool を検証します。 |
| スケジュールで実行する | 永続的な秘密の保管から所有する資格を再利用します。 スケジュールスロットごとに1つの耐久性のあるレコードを保持します。同じスロットが繰り返すと保存された出力を読みます。 |
| 他のユーザー同士の接続 | 所有者のアカウントを請求するキーです。 ユーザーのそれぞれにクレデンシャルを使用し、保存した結果を隔離します。 OAuthの統合には、クライアントの登録、同意、トークンストレージも必要です。このAPIキーの例では、そのフローを実行していません。 |

- [定期実行タスク](https://flashdata.dev/ja/docs/guides/recurring-tasks/reference.md)
- [認証オプション](https://flashdata.dev/ja/docs/guides/agent-access/reference.md)

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

## トラブルシューティング

| 問題の問題 | アクション |
| --- | --- |
| ERR_MODULE_NOT_FOUND | Flashdata-mcp-demo から npm をインストールします。 package.jsonとnode_modulesの横にmcp-client.mjsを保って下さい。 |
| FLASHDATA_API_KEY | Node.jsを実行し、--searchなしでノードmcp-client.mjsを再実行する同じターミナルまたはプロセスで変数を設定します。 |
| 401 | 期限切れまたは再発されたキーを確認します。 有効なアクセスを復元し、無料接続チェックを再実行します。 |
| 403 | 鍵の google_search の許可とアカウントのアクセスを確認してください。 残高チェックが成功すると、このソースが許可されていません。 |
| 402 / Insufficient credits | 別のタスクを提出する前に、アカウント残高と現在の価格をチェックしてください。 |
| EEXIST | 以前の試みは出力ディレクトリを所有しています。 result.jsonが完成したら、ノードmcp-client.mjs --readを実行します。そうしないと、そのレシートとHistoryを検査します。 ディレクトリをキープします。 |
| --readのENOENT/無効JSON | Flashdata-mcp-demo にあることを確認し、mcp-search-output/result.json. を検査する それが欠落または不完全である場合は、中断されたタスクを回復してください。 --readは、検索を提出しません。 |
| 429 | Retry-After のご提供をお待ちください。 検索が試みられたら、保存したファイルと再試行する前に History を確認してください。 |
| タイムアウト / result_unavailable | 受取および受取りを保って下さい。 History または既存のジョブをチェックしてください。保存された継続が期限切れになる場合があります。 |

- [リクエスト履歴](https://flashdata.dev/app/jobs)
- [MCPのトラブルシューティング](https://flashdata.dev/ja/docs/guides/troubleshooting/reference.md#mcp)
