> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Data Hub MCPツールリファレンス
> Data Hub汎用MCPの6つの安定したツールと、Data Appの検索・実行・結果取得の標準フローをまとめたリファレンスです。同期・非同期実行や大きな結果の扱いも解説します。
このページでは**Data Hub汎用MCP**を説明します。まずエージェントが適切なData Appを発見できるようにし、次にアプリの最新の契約を読み取って実行します。「先に特定のアプリを選んでから接続する」チュートリアルと同じData Hubの機能を使い、違いはアプリを選ぶタイミングだけです。
Data Appの数、名前、発行者、価格、入出力は継続的に変わります。MCPプロトコルのツールは比較的安定しています。そのため、このページはツールの契約と汎用フローに絞って説明し、カタログのある時点のスナップショットを長期的なリストとして扱いません。
## 2つの機能レイヤー
| レイヤー | 内容 | 使い方 |
| ------------- | ------------------------------------ | -------------------------- |
| **プロトコルレイヤー** | 検索、詳細取得、実行、ステータス取得、結果取得、実行キャンセルの6ツール | エージェントやシステムが統合するための安定したフロー |
| **データレイヤー** | 各Data Appの機能、価格、フィールド、可視性、実行モード | 毎回の呼び出し前に最新の情報を検索して詳細を読む |
固定のアプリを長期的に統合する場合は、その`app_id`を記録してください。`namespace/app_name`でもアプリを参照できますが、発行者やアプリの名前が変わると機能しなくなる可能性があります。
## 6つのMCPツール
### `search_data_apps`：カタログを検索する
業務キーワードでData Appを発見します。`query`は任意の言語のキーワードに対応します。空にすると、閲覧可能なカタログをページ単位で表示します。`type`で収集・照会系アプリ（`data`）と加工系アプリ（`transform`）を絞り込み、`scope`で`all`、`public`、`private`、`shared`を選択できます。
| パラメータ | 説明 |
| ---------------- | ------------------------------ |
| `query` | 任意の業務キーワード。空の場合はカタログを一覧表示 |
| `type` | 任意：`data`または`transform` |
| `scope` | 任意の可視性範囲。デフォルトは`all` |
| `offset`、`limit` | ページング。`limit`は`1-20`、デフォルトは`5` |
各結果カードには`app_id`、名前、概要、実行モード（`sync` / `async`）、入出力のヒント、開始価格、可視性が含まれます。まず検索して比較し、確認前に実行しないでください。
### `get_data_app_details`：完全な契約を読む
実行前に呼び出します。`app_id`または`/`を渡すと、次の情報を取得できます。
* `input_schema`：この実行が満たすべき標準JSON Schema。
* `output_schema`：返される可能性のあるフィールド。
* `knowledge`：機能の境界、想定レイテンシ、注意事項。
* `pricing`：課金の説明。
* `examples`：出発点として使える入力例。
最も確実な方法は、`examples`から`input`をコピーして調整することです。ページタイトル、チャットの説明、過去のタスクからフィールド名を推測しないでください。
### `run_data_app`：実行を開始する
`app`、`input_schema`を満たす`input`、必要に応じて結果件数の上限を指定する`max_records`を渡します。入力が契約に一致しない場合、ツールはすぐに`[invalid-input]`を返し、問題のあるフィールドを指摘します。
一般的な戻り値には`run_id`、`state`、`progress`、`usage`、`billing`、`next_step`が含まれます。初回は小さな`max_records`を使い、データ、所要時間、費用を確認してください。
### `get_run_status`：実行ステータスを確認する
`run_id`を渡して進捗、失敗の詳細、利用量、費用を確認します。データは読み取りません。非同期タスクでは`wait_seconds`（`0-60`）でロングポーリングできます。間隔なしで頻繁にポーリングするのではなく、1回の呼び出しで60秒待ってください。
一般的なステータスは`QUEUED`、`RUNNING`、`SUCCEEDED`、`PARTIALLY_SUCCEEDED`、`FAILED`、`CANCELLED`です。失敗時は`error.code`、`error.category`、`error.message`、`error.retryable`を確認してください。
### `get_run_result`：結果を読む
1回の呼び出しで最大50件を読み取ります。`offset`でページングし、`fields`で`title,price,url`のようにカンマ区切りのフィールドの部分集合を指定すると、不要な大きなフィールドが会話に流れ込むのを防げます。
レスポンスに`handoff`が含まれる場合、結果が大きいか、会話内でのページングに適していません。エージェントに完全なJSONを繰り返し運ばせるのではなく、`handoff`に示されたSDKまたはRESTコマンドに従ってファイルをエクスポートしてください。
### `cancel_run`：実行をキャンセルする
`run_id`を渡して、キュー内または実行中のタスクをキャンセルします。実行中のタスクは協調的に停止するまで数秒かかることがあります。すでに生成された部分的な結果は保持され、`get_run_result`で引き続き読み取れます。課金されるのは生成されたデータ分のみです。
## 標準ワークフロー
```text theme={null} theme={null}
search_data_apps
→ get_data_app_details
→ run_data_app
→ get_run_status（非同期のみ、ロングポーリング）
→ get_run_result
→ cancel_run（停止が必要な時）
```
### 同期アプリと非同期アプリ
| 実行モード | 動作 | 推奨 |
| ------- | -------------------------------- | ----------------------------------------------------- |
| `sync` | 数秒で完了。少量の結果は`records`を直接返すことがある | まず戻り値を確認し、`next_step`に従って続ける |
| `async` | すぐに`run_id`を返し、実際の収集をバックグラウンドで実行 | 複数の対象を連続で送信し、`get_run_status(wait_seconds=60)`でまとめて待つ |
非同期タスクで`run_id`を受け取っても、収集が成功したことにはなりません。結果を読む前に最終状態を確認し、待ち時間を理由に同じ対象を再送信しないでください。
## Data Appの扱い方
Data AppはData Hub上の具体的なデータ機能です。新しいアプリが追加され、既存のアプリも変わるため、このページでは固定の一覧を持ちません。使用前に`search_data_apps`で検索し、`get_data_app_details`で現在の入出力、価格、境界を確認してください。
## 接続と利用のアドバイス
* **アプリをまだ決めていない**：汎用接続：エージェント内でアプリを選ぶに従って先にData Hub MCPを接続し、検索・比較・確認します。
* **固定のアプリを長期的に使う**：Codex：特定のアプリを接続またはClaude Code：特定のアプリを接続でツールの範囲を絞ります。
* **費用や大量データが関わる**：まず詳細ツールで`pricing`と`examples`を確認し、少量のデータで試し、大きな結果が必要な場合は`handoff`を処理します。
Data Hub汎用MCPは`https://mcp-v2.octoparse.com`をベースとし、APIキーまたはOAuthに対応しています。接続設定と現在のパラメータは、Data Hubオープンプラットフォームが生成する内容に従います。これは上部ナビゲーションにあるOctoparseのスクレイピング用MCP Serverとは異なります。アドレス、認証、ツール名を混同しないでください。