Suparse

Suparse MCP Server

Suparse のドキュメント処理 API 用 MCP stdio サーバーです。Claude Code や Codex などのローカル MCP クライアントから使用して、ドキュメントから構造化データを抽出し、JSON、CSV、XLSX、または Google Sheets に出力できます。暗号化された PDF を含む単一ファイルやフォルダーを処理したり、Suparse に抽出スキーマを自動検出させたり、チームのテンプレートを適用したりできます。また、スキーマを自動作成したり、複数ページにまたがる混在ドキュメントを分割したり、ドキュメント ID で結果をダウンロードまたは削除したりできます。

セキュリティ境界

これはローカルの stdio MCP サーバーです。接続された MCP クライアントは、ローカルのドキュメントパスを読み取り、サーバープロセスに許可されている任意の場所にエクスポートファイルを書き込むよう要求できます。信頼できる MCP クライアントとワークスペースのみ接続してください。

必要条件

• Suparse API キー
• Node.js 20+

認証

MCP サーバーは、次の順に認証情報を読み込みます。

1. SUPARSE_API_KEY
2. ~/.config/suparse/config.json

クライアントの環境変数設定またはシークレット入力機能を使って、SUPARSE_API_KEY を渡すことをおすすめします。フォールバックファイルは Suparse が実装したもので、{ "apiKey": "your_api_key" } が含まれます。認証情報ファイルとして適切に保護してください。

以下の例にある your_api_key を置き換えてください。クライアントの env 設定や CLI の --env オプションを使うと、キーをクライアント設定に保存できます。実際のキーを含むファイルは Git や共有ワークスペースに含めないでください。キーを含む CLI コマンドがシェルの履歴に残ることもあります。利用可能な場合は、スコープを限定した API キーを使用してください。

ローカルインストール

先に使用するクライアントをインストールし、Node.js 20+ と npx が利用可能であることを確認してください。以下の設定では、@suparse/mcp をローカルの stdio プロセスとして起動します。

• Claude Code
• Claude Desktop
• Codex CLI / IDE
• Cursor
• VS Code / GitHub Copilot
• Gemini CLI
• Windsurf / Cascade

JSON の例は、既存の他のサーバー設定を置き換えずに、既存の設定に統合してください。接続後、テンプレート一覧の確認を実行して、Suparse の認証を確認してください。

Claude Code

ユーザースコープで、すべてのプロジェクトにインストールします。

claude mcp add --scope user --transport stdio suparse \
  --env SUPARSE_API_KEY=your_api_key \
  -- npx -y @suparse/mcp

--env の前にサーバー名（suparse）を指定してください。指定しないと、Claude Code がこれを別の環境変数として解析し、Invalid environment variable format と報告することがあります。

既存の登録情報（たとえば、API キーや起動コマンド）を変更するには、再度追加コマンドを実行する前に削除してください。

claude mcp remove --scope user suparse

元のインストール時に使用した名前とスコープを指定してください。suparse-local として登録したユーザースコープのローカルテストの場合は、claude mcp remove --scope user suparse-local を実行します。更新した登録情報を追加した後、Claude Code を完全に終了して、新しいセッションを開始し、新しい設定を読み込んでください。

設定と接続を確認します。

claude mcp list
claude mcp get suparse

Claude Code 内で /mcp を使用してステータスとツールを確認し、テンプレート一覧の確認を実行してください。Claude Code MCP のドキュメントを参照してください。

Claude Desktop

macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json を開きます。mcpServers セクションに Suparse を追加します。

{
  "mcpServers": {
    "suparse": {
      "command": "npx",
      "args": ["-y", "@suparse/mcp"],
      "env": {
        "SUPARSE_API_KEY": "your_api_key"
      }
    }
  }
}

Claude Desktop を完全に終了して再起動し、利用可能なツールに Suparse が表示されることを確認してから、テンプレート一覧の確認を実行してください。

Windows で npx のプロセス起動エラーが表示される場合は、サーバーの command と args を次のように置き換えてください。

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@suparse/mcp"]
}

既存の env ブロックはそのままにしてください。この回避策が必要なのは、npx.cmd を直接起動できないクライアントのみです。

Codex

推奨されるインストール方法は、CLI を使用する方法です。

codex mcp add suparse \
  --env SUPARSE_API_KEY=your_api_key \
  -- npx -y @suparse/mcp

インストール後、既存の ~/.codex/config.toml の [mcp_servers.suparse] テーブル内に tool_timeout_sec = 300 を追加します。CLI コマンドでは、このタイムアウトは設定されません。

または、~/.codex/config.toml かプロジェクトスコープの .codex/config.toml でサーバーを手動設定します。

[mcp_servers.suparse]
command = "npx"
args = ["-y", "@suparse/mcp"]
tool_timeout_sec = 300

[mcp_servers.suparse.env]
SUPARSE_API_KEY = "your_api_key"

tool_timeout_sec を設定すると、Suparse の抽出ツールが完了するまで最大 5 分間待機します。Codex のデフォルトは 60 秒です。CLI と IDE 拡張機能はこの設定を共有します。Codex MCP のドキュメントを参照してください。

設定済みのサーバーを確認します。

codex mcp list

対話型の Codex セッションでは、/mcp を使ってアクティブなサーバーを確認し、テンプレート一覧の確認を実行します。

Cursor

すべてのプロジェクトに適用する場合は ~/.cursor/mcp.json に、現在のプロジェクトに適用する場合は .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "suparse": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@suparse/mcp"],
      "env": {
        "SUPARSE_API_KEY": "${env:SUPARSE_API_KEY}"
      }
    }
  }
}

Cursor を起動する前に、Cursor の環境変数として SUPARSE_API_KEY を設定してください。${env:SUPARSE_API_KEY} を参照することで、キーを JSON ファイルに記載せずに済みます。環境を変更した後は Cursor を再起動してください。または、キーを追跡対象外の個人用設定に記載します。

Cursor の MCP 設定を開き、Suparse が有効でツールを使用できることを確認してから、Agent チャットでテンプレート一覧の確認を実行します。Cursor MCP のドキュメントを参照してください。

VS Code / GitHub Copilot

Copilot CLI の場合は、次のコマンドでインストールと確認を行います。

copilot mcp add suparse \
  --env SUPARSE_API_KEY=your_api_key \
  --timeout 300000 \
  -- npx -y @suparse/mcp
copilot mcp list

タイムアウトはミリ秒単位で指定し、ツールの検出と呼び出しに最大 5 分間かけられます。次に、Copilot CLI でテンプレート一覧の確認を実行します。Copilot CLI コマンドリファレンスを参照してください。

ポータブルな Copilot の設定を行うには、ワークスペースのルートに .mcp.json を作成します。個人用にインストールする場合は、~/.copilot/mcp-config.json（または設定されている場合は $COPILOT_HOME/mcp-config.json）を使用します。

{
  "mcpServers": {
    "suparse": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@suparse/mcp"],
      "env": {
        "SUPARSE_API_KEY": "your_api_key"
      },
      "tools": ["*"]
    }
  }
}

実際のキーを含むファイルは、追跡対象外にしてください。VS Code のパスワード入力を使ってワークスペースを設定する場合は、代わりに .vscode/mcp.json を使用します。

{
  "inputs": [
    {
      "id": "suparse-api-key",
      "type": "promptString",
      "description": "Suparse API key",
      "password": true
    }
  ],
  "servers": {
    "suparse": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@suparse/mcp"],
      "env": {
        "SUPARSE_API_KEY": "${input:suparse-api-key}"
      }
    }
  }
}

VS Code の形式では servers を、ポータブル形式では mcpServers を使用します。サーバーが重複しないよう、どちらか一方の設定を選んでください。対話型の入力は Copilot ハーネスのセッションに転送されません。そのようなセッションではポータブル形式を使用してください。

コマンドパレットから MCP: List Servers を実行し、Suparse を選択して起動してから、エージェントチャットでテンプレート一覧の確認を実行します。VS Code MCP 設定リファレンスを参照してください。

Gemini CLI

ユーザーアカウントにインストールします。

gemini mcp add --scope user \
  --env SUPARSE_API_KEY=your_api_key \
  suparse npx -y @suparse/mcp

これにより、サーバー設定が ~/.gemini/settings.json に書き込まれます。次のコマンドで接続状態を確認します。

gemini mcp list

対話型セッションでは、/mcp list を使ってツールを確認し、テンプレート一覧の確認を実行します。Gemini CLI MCP のドキュメントを参照してください。

Windsurf / Cascade

これらの手順は、旧式の Cascade エージェントを対象としています。新しいデフォルトの Devin Local エージェントについては、Devin CLI MCP configuration documentationを参照してください。設定場所と移行時の動作は、パスが Cascade と重複する場合でも、インストールされているバージョンによって異なります。

Cascade の MCP コントロールから MCP 設定を開きます。Windsurf のインストールでは ~/.codeium/windsurf/mcp_config.json（Windows では %USERPROFILE%\.codeium\windsurf\mcp_config.json）を使用します。現在の Devin Desktop リリースに含まれる Cascade では、macOS/Linux では ~/.config/devin/mcp_config.json（または $XDG_CONFIG_HOME/devin/mcp_config.json）、Windows では %APPDATA%\devin\mcp_config.json を使用します。Cascade からファイルを開くと、インストールされているバージョンに応じたパスが選択されます。

mcpServers の下に Suparse を追加します。

{
  "mcpServers": {
    "suparse": {
      "command": "npx",
      "args": ["-y", "@suparse/mcp"],
      "env": {
        "SUPARSE_API_KEY": "your_api_key"
      }
    }
  }
}

ファイルを保存し、MCP リストを更新するかクライアントを再起動して、Cascade で Suparse とそのツールが有効になっていることを確認します。テンプレート一覧の確認を実行してください。Cascade MCP のドキュメントを参照してください。

インストールを確認する

クライアントのエージェントチャットで、次のように依頼します。

Suparse の list_templates ツールを使って、チームで利用できる抽出テンプレートを一覧表示してください。

プロンプトが表示されたら、ツール呼び出しを承認します。正常な応答があれば、MCP 接続と Suparse API 認証の両方が確認できます。チームにテンプレートがない場合、team_templates が空のリストでも問題ありません。この確認では、ドキュメントのアップロードや処理は行われません。

サーバーが起動しない場合は、Node.js 20 以降と npx がクライアントの PATH に含まれていることを確認し、MCP ログを調べてください。認証エラーが発生した場合は、サーバーに渡されたキーまたは Suparse のフォールバックファイルを確認してください。デスクトップアプリケーションは、ターミナルで設定した環境変数を引き継がない場合があります。

ドキュメント処理を確認する（任意）

処理によって Suparse のクレジットが消費される場合があります。Suparse にアップロードしても問題のないデータを含む、小さなサンプル請求書またはレシートを使用してください。

1. サンプル PDF を MCP サーバーからアクセスできる場所に置き、絶対パスを使用します（ローカルパスを参照）。
2. クライアントに次のように依頼します。「Suparse の start_file_extraction を使って、/absolute/path/to/sample.pdf から構造化データを抽出してください。タスク ID と、返されたドキュメント ID または処理状況を返してください。アップロードしたドキュメントは削除しないでください。」
3. 返されたタスク ID を指定して wait_for_task_extraction を呼び出します。処理がまだ実行中の場合は ID を保持して再度ポーリングし、ファイルを再アップロードしないでください。
4. 処理が完了したら、返されたドキュメント ID を使って fetch_document_result を呼び出します。必要に応じて、タスク ID を指定して get_task_results を使用し、ドキュメント ID を確認してください。

これにより、ローカルファイルへのアクセス、認証、アップロード、処理、結果の取得を確認できます。後で明示的に削除する場合を除き、アップロードしたドキュメントはそのままにしてください。

ツール

目的	推奨ツール
ドキュメントを処理し、タスク ID／ドキュメント ID を取得する	デフォルトの result_mode: "defer" を指定した extract_file
処理を開始し、アップロード確認後に戻る	start_file_extraction
MCP 応答で JSON を直接取得する	result_mode: "return_json" を指定した extract_file
複数のドキュメントの処理を開始する	start_folder_extraction
中間結果を確認する	get_task_results
CSV/XLSX/JSON ファイルを保存する	download_results
再接続後に完了済みエクスポートをダウンロードする	download_export_job

defer は、処理が終端状態に達するかポーリングに失敗するまで、アップロード後にポーリングします。先送りされるのは結果のエクスポートであり、処理の完了を待つことではありません。開始のみを行うツールは、処理完了をポーリングせず、アップロード確認後にタスク ID を返します。ID をすぐに取得する必要がある場合、特に長時間のジョブや人によるレビューが必要な場合に使用してください。

return_json は、テキストと構造化コンテンツの両方で完全な結果を返します。大きなドキュメントやバッチでは、アシスタントのコンテキストを大幅に消費する場合があります。そのようなジョブでは、download_results を使ってエクスポートを保存することをお勧めします。

ローカルパス

入力パスと出力パスは、Suparse MCP を実行しているマシンおよびオペレーティングシステムのプロセスからアクセスできる必要があります。./invoice.pdf のような相対パスは、サーバープロセスの現在の作業ディレクトリを基準に解決されます。このディレクトリは MCP クライアントが起動時に選択するもので、開いているプロジェクトやチャットのディレクトリとは異なる場合があります。ファイルパスは Node SDK のファイルシステム操作に直接渡され、フォルダパスは同じ作業ディレクトリを基準に path.resolve で正規化されます。相対パスで指定したエクスポート先もプロセスの作業ディレクトリを基準にします。出力パスを省略した場合は、そのディレクトリが既定の出力先になります。サーバーはツールのパス引数に含まれる ~ を展開しません。

作業ディレクトリが不明な場合は、絶対パスを使用してください。サーバーのオペレーティングシステムに適したパスを使用します。たとえば、Windows プロセスでは C:\Users\you\invoice.pdf、そのドライブがマウントされている WSL2 プロセスでは /mnt/c/Users/you/invoice.pdf を指定します。別のマシン上にあるパスや、サーバーがアクセスできないファイルシステム上のパスは、チャットに表示されていても読み取ることはできません。

クレジット、削除、再試行

ドキュメントの処理とスキーマの自動作成には Suparse のクレジットが消費される場合があります。同じファイルを再度アップロードすると、新たな処理リクエストが作成されることがあります。リクエストがタイムアウトした場合は、新しい処理を送信する前に、保持されているタスク ID、エクスポートジョブ ID、または冪等性キーを使って処理を再開してください。

delete_documents は Suparse 上のドキュメントを削除します。ローカルの一時ファイルだけを削除するものではありません。統合抽出ツールの cleanup オプションでも、エクスポートが検証された後にリモートのドキュメントを削除できます。必要な結果が安全に保存されていることを確認してから、削除をリクエストしてください。

サーバーはすでに MCP アノテーションを提供しています。ステータス、テンプレート、結果の確認ツールは読み取り専用です。アップロード／スキーマ作成ツールは変更を伴い、冪等ではありません。統合抽出ツールはクリーンアップを実行する可能性があるため、破壊的な操作としてマークされています。また、delete_documents は破壊的な操作としてマークされています。エクスポート送信ツールは、あらゆる状況で冪等であるとは示されていません。安全に再実行するには、同じキーと同一のリクエストオプションを使用する必要があります。ディスクへのエクスポートツールは、ローカルファイルを書き込んだり上書きしたりする場合もあります。こうしたヒントはクライアントがツール呼び出しを評価する際に役立ちますが、権限を強制したり、任意の再試行を安全にしたりするものではありません。

ツールリファレンス

• extract_file、extract_folder：アップロードと処理をまとめて行います。デフォルトの defer はポーリング後にタスク ID とドキュメント ID を返します。タスクは partially_completed になる場合があります。return_json は入力ごとのタスクステータスとドキュメント ID を含むエクスポート済みグループを返します。一部完了のタスクや空のエクスポートは未完了として報告されます。cleanup はベストエフォートで実行され、return_json の場合にのみ有効です。
• start_file_extraction、start_folder_extraction：アップロード後、ポーリングやエクスポートを行わずにタスク ID をすぐに返します。フォルダーのスキャンは、並べ替え済み、非再帰で、同時アップロード数は最大 10 件です。
• wait_for_task_extraction：リモートタスクをポーリングします。ポーリング間隔はデフォルトで 2 秒、試行回数は 3 回です。再試行と SDK のバックオフがあるため、厳密な実時間の期限ではありません。
• get_task_results：部分的なタスクドキュメントを、上限付きの 1 ページ分読み取ります。不透明なカーソルはスナップショットの終端を示すもので、タスク処理の終了を示すものではありません。新たに呼び出すと、さらにドキュメントが表示されることがあります。
• list_templates：テンプレートの概要または全レコードを一覧表示します。直接利用可能な team_templates と、検出専用の system_templates に分類されます。
• start_quick_schema_creation、get_quick_schema_creation、wait_for_quick_schema_creation：スキーマの自動作成を開始して、その状態を確認します。実行 ID は、タスク ID、ドキュメント ID、エクスポートジョブ ID とは別のものです。
• fetch_json_results：ドキュメント ID を指定して、検証済みの TaskExport[] JSON を返します。ZIP アーティファクトの展開や、任意の JSON スキーマの受け入れには対応していません。
• fetch_document_result：単一ドキュメント用の直接エンドポイントを通じて、1 件のドキュメントの構造化 JSON 結果を取得します。
• download_results：ドキュメントをエクスポートし、レスポンスをローカルパスに保存します。JSON、CSV、XLSX、即時 Google Sheets に対応しています。既存の出力パスには SDK の上書き動作が適用されます。
• get_export_job、wait_for_export_job、download_export_job：既知のリモートエクスポートジョブを、MCP の再起動後も確認、待機、ダウンロードできます。ダウンロードでは ZIP を含む元のバイト列を保持し、アーティファクトを検証してからアトミックに公開します。download_export_job のデフォルトは overwrite: false です。
• delete_documents：ID を指定してリモートドキュメントを削除します。クリーンアップが必要な場合は、エクスポート／ダウンロードが成功したことを確認してから使用してください。

エクスポート形式

fetch_json_results では次の値を受け付けます。

入力	値	デフォルト
export_type	original、unified	unified

JSON エクスポートは構造化された results として返されます。fetch_json_results と download_results では、wait_timeout_ms（正の整数でミリ秒単位、デフォルトは 60000）と、任意の UUID idempotency_key を指定できます。待機値は、ポーリングの再試行を含む完了待ちの時間を制限します。送信と転送は別々のフェーズであるため、MCP クライアントにはツール全体で十分な実行時間が必要です。レスポンスが失われた場合は、同じドキュメント ID、形式、エクスポート形式、レイアウト、キーを指定して再実行してください。

download_results では、json、csv、xlsx、google_sheets と、任意の output_path（ローカルのファイルパスまたは既存のディレクトリ）を指定できます。XLSX エクスポートでは xlsx_layout: "standard" | "flat" も指定でき、デフォルトは standard です。エクスポートをディスクに直接書き込み、保存先の output_path を返します。即時の Google Sheets レスポンスには対応していますが、バックグラウンドの Google Sheets には対応していません。ディスクツールはスプレッドシートのバイナリではなく、URL を含む Sheets レスポンスのメタデータを保存します。MCP クライアントは CSV、XLSX、Google Sheets、保存する JSON ファイルに download_results を使用してください。base64 データを取得し、シェルや Python でデコードする方法は使用しないでください。ジョブを指定したダウンロードでは未加工のアーティファクトバイト列が保持され、ZIP や正確な JSON アーティファクトの取得に使用できます。

CSV／XLSX エクスポートでは、複数のファイル（例：請求書と銀行取引明細書）を含む ZIP が返されることがあります。どちらのダウンロードツールも requested_format、artifact_format、content_type を報告し、アーティファクトに合わせて保存時の拡張子を修正します。そのため、results.xlsx を明示的に指定していても、API がアーカイブを返す場合は results.zip になります。返された output_path を確認してください。 個別のローカルファイルを取得するには、unpack: true を指定して download_results を呼び出します。

{"document_ids":["invoice-id","statement-id"],"format":"xlsx","output_path":"/absolute/path/results.xlsx","unpack":true}

ZIP は保持され、output_paths には、ZIP の隣に新しく作成された results_files-* フォルダー内の展開済みファイルが一覧表示されます。既存の展開済みファイルが置き換えられることはありません。単一のワークブックは .xlsx のまま保持され、output_paths に直接表示されます。 展開のデフォルトは false で、CSV/XLSX のみに適用されます。また、安全でないアーカイブパス、リンク、重複する保存先、1000 件を超えるエントリー、512 MiB を超える展開データは拒否されます。展開に失敗した場合、部分的に作成されたファイルは削除されます。アーカイブがすでに保存されている場合、エラー復旧情報には saved_artifact_path が含まれます。 download_export_job は常に、展開せずに元のアーティファクトを保持します。 CSV/XLSX の download_results は、SDK の raw-download API を介してアーティファクトをバッファーします。既知のジョブの復旧では、アーティファクトをストリーミングして検証してから公開します。

result_mode は、展開結果を JSON 形式で直接返すかどうかを制御します。MCP の応答で JSON の展開結果全体が必要な場合にのみ、return_json を使用してください。それ以外の場合は、download_results を使用して、希望する形式で結果を取得できます。

明示的に return_json を指定した場合、クリーンアップが有効なときも含め、完全な JSON がテキストと構造化コンテンツの両方で返されます。tasks レコードには、ポーリングした各入力のタスク ID、ステータス、ドキュメント ID が保持されます。一部のみ完了した場合やエクスポートが空の場合は、エクスポート済みデータを保持したまま failed_count が増加し、クリーンアップ中も親タスクは保持されます。複合展開では、JSON エクスポートごとに wait_timeout_ms を指定できます。デフォルトは 60000 ミリ秒です。defer モードでは無視されます。任意の exports レコードには、生成された冪等性キーと受け付けられたジョブ ID が、各ローカル入力と関連付けられて記録されます。複合展開では、呼び出し元が指定した冪等性キーは受け付けられません。

キャンセルされたフォルダー応答では、スキャンされたすべてのファイルが考慮されます。開始されなかった入力は、cancelled: true、unstarted: true、コード OPERATION_NOT_STARTED を含む failed に表示され、failed_count にも含まれます。これらのエントリーは元の順序で保持され、開始しても安全な入力と、復旧が必要な送信済みタスクとを区別します。復旧では、既知のエクスポートジョブが最優先され、次に保持されたキーを使った同一エクスポートの再実行、その後にタスクのポーリングが行われます。

重要：extract_file と extract_folder の cleanup は、result_mode: "return_json" と併用する場合にのみ有効です。クリーンアップはベストエフォートであり、タスクが完全に完了し、要求されたすべてのドキュメント ID を対象とする JSON エクスポートが必要です。対象範囲が不足している、または検証できない場合は、INCOMPLETE_EXPORT エラーとなり、親タスクが保持されます。一部のみ完了したタスク、空のエクスポート、バックエンド処理の状態が不確かな入力は保持されます。フォルダーのクリーンアップは、すべての展開ワーカーの処理が終了するまで待機し、キャンセル後はスキップされます。CSV/XLSX/Google Sheets または保存済み JSON ファイルの場合は、開始または複合展開を実行し、タスクの完了を待ってから結果をダウンロードし、必要に応じて delete_documents を呼び出してください。ローカルでのアーティファクト書き込みに失敗しただけでは、バックエンド処理がまだ実行中であるとは判断できません。クリーンアップが要求された場合、cleanup はそのステータスと、削除または保持されたドキュメント ID をテキストと構造化結果の両方で報告します。保持された ID には、削除を確認できなかった ID も含まれます。複合展開の進捗は、処理が完了した入力ファイル数を示し、通知のたびに増加します。 extract_file、extract_folder、start_file_extraction、start_folder_extraction は、template_id、split、pdf_password、folder_id、auto_approve を受け付けます。承認のデフォルトは有効です。人によるレビューが必要な場合に限り、auto_approve: false を設定し、処理待ちになる前にタスク ID が返されるよう、開始専用ツールを使用してください。MCP は人によるレビューやドキュメントの承認を実行できません。タスク ID を保持し、レビュー完了後にポーリングを再開してください。これによって、バックエンドの awaiting_approval ステータスが作成されたり報告されたりすることはありません。pdf_password は機密性の高い入力として扱ってください。MCP は、返されるエラー、メタデータ、部分的な結果、進捗からこれを除外しますが、MCP クライアントは独自の動作に応じて送信されたツール引数を保持する場合があります。

Google Sheets の要件と結果

• format: "google_sheets" をリクエストする前に、Suparse で Google Sheets を接続してください。SDK では、Google との連携が正常に動作している必要があります。
• Suparse 連携機能 は、スプレッドシートの新規作成または既存のスプレッドシートへの追加に対応しています。この MCP ツールには、対象のスプレッドシート ID や追加オプションはなく、SDK でもエクスポートエンドポイントがどちらの方法で出力先を選ぶかは明示されていません。この MCP サーバーでは、出力先の選択や行の明示的な追加には対応していません。
• ここでサポートされるのは、Google Sheets への即時エクスポート応答のみです。このワークフローでは、バックグラウンドの Google Sheets ジョブをダウンロードできません。
• download_results は JSON メタデータファイルを保存し、output_path と、利用可能な場合は google_sheets_metadata を返します。google_sheets_metadata には、スプレッドシートやフォルダーの URL が含まれる場合があります。ローカルの .xlsx ファイルは保存されません。その場合は format: "xlsx" を使用してください。

復旧ガイド

既知の情報	次の操作
エクスポートジョブ ID	get_export_job を実行し、キュー待ち／処理中の場合は wait_for_export_job を実行してから、完了後に download_export_job を実行します。
タスク ID	wait_for_task_extraction を実行し、続けて get_task_results を実行するか、既知のドキュメント ID をエクスポートします。
エクスポート応答を失い、UUID キーを保持している	同じ ID、形式、種類、レイアウト、キーで、同一のリクエストを再送します。
アップロード参照はあるが、アップロード確認が不明	参照を保持して調査してください。新しいアップロードは送信しないでください。MCP にはアップロードの復旧エンドポイントがありません。

典型的なワークフロー

通常の抽出とダウンロード：

extract_file(file_path="./invoice.pdf")
download_results(document_ids=["<document-id>"], format="csv", output_path="./exports")

時間のかかる処理と部分的な確認：

start_file_extraction(file_path="./invoice.pdf")
wait_for_task_extraction(task_id="<task-id>", poll_interval=2, max_poll_attempts=3)
get_task_results(task_id="<task-id>", limit=25, cursor=null)

poll_interval の単位は秒です。エクスポートの wait_timeout_ms の単位はミリ秒です。タスクは partially_completed になる場合があります。その場合は、完了したドキュメント ID を保持し、後で確認してください。ページから next_cursor: null が返されると、そのスナップショットの取得は完了していますが、タスクからさらにドキュメントが生成される可能性があります。後で新しいページリクエストを開始し、重複を避けるために ID を追跡してください。

人によるレビュー：

start_file_extraction(file_path="./contract.pdf", auto_approve=false)

返される task_id はリモートタスク ID、document_ids はリモートドキュメントを識別する ID、run_id はクイックスキーマ作成に属する ID、export_job_id はリモートのエクスポートジョブを識別する ID、output_path はローカルファイルシステム上のパスです。

タイムアウトまたは応答の消失後に、受理済みのエクスポートを復旧する：

get_export_job(export_job_id="<export-job-id>")
wait_for_export_job(export_job_id="<export-job-id>", wait_timeout_ms=60000)
download_export_job(export_job_id="<export-job-id>", output_path="./exports/result.zip")

SDK の 60000 ミリ秒の待機上限にはポーリングの再試行が含まれますが、送信や成果物の転送は含まれません。操作全体を対象とする適切なタイムアウトを MCP クライアントに設定してください。解析済み JSON を返すツールは、検証済みの TaskExport[] を返します。既知のジョブのダウンロードでは生の成果物バイトが保持されます。形式は ZIP またはそのままの JSON の場合があります。base64 や生のバッファをチャットに公開したり、シェルコマンドで成果物をデコードしたりしないでください。

スキーマの自動作成

ローカルファイルを指定して start_quick_schema_creation を呼び出し、その正規化された run_id を get_quick_schema_creation または wait_for_quick_schema_creation に渡してください。終了時の結果には、生成されたテンプレート ID、保存されたドキュメント、失敗したドキュメントの詳細、再試行の可否が保持されます。開始ツールは pdf_password と folder_id も受け付けます。

upload_batch_id と source_upload_id は、これらの ID を別の場所で取得する高度なワークフローでのみサポートされます。MCP サーバーはアップロードバッチを作成しません。

MCP エージェント向けテンプレートの選択

MCP エージェントが抽出ツールに template_id を渡す場合は、team_templates のみを使用してください。通常の選択ではデフォルトの要約ビューを使用し、スキーマ、プロンプト、検証、または作成者のメタデータが必要な場合に限り、view: "full" をリクエストしてください。

ユーザーから領収書などの文書タイプの処理を依頼された場合は、次の手順に従ってください。

1. まず team_templates を確認し、一致するチームテンプレートがあれば使用します。
2. 一致するチームテンプレートがない場合は、include_system: true を指定して list_templates を呼び出し、system_templates を確認します。
3. システムテンプレートは検索専用です。MCP ではチームに追加できず、ID を抽出に直接使用することもできません。
4. 一致するチームテンプレートがない場合は、自動検出のために template_id を省略するか、ユーザーがスキーマの作成を許可している場合は start_quick_schema_creation を使用し、その run_id に従ってください。カスタムテンプレートの編集と手動設定は MCP では利用できません。求められた場合は、その制限について説明してください。

開発

パッケージをビルドします。

pnpm build

MCP Inspector でテストします。

npx @modelcontextprotocol/inspector node dist/index.mjs

MCP サーバーは、JSON-RPC プロトコルメッセージに stdout を使用します。サーバーのパスに console.log の出力を追加しないでください。stderr または MCP ツールのレスポンスを使用してください。