dropbox

Dropbox

Dropbox 内のファイルやフォルダーを操作するためのツールです。ファイルのアップロードや書き込み、整理（移動／コピー／削除／フォルダーの作成）、移動や検索、ファイル内容の読み取り、共有リンクの作成や変更、共有フォルダーのメンバー管理、ファイルリクエストの作成を行えます。Dropbox API v2（https://api.dropboxapi.com/2/<namespace>/<method>。アップロードとダウンロードには https://content.dropboxapi.com を使用）をラップしています。読み取り専用のツールには明確な印が付いています。書き込みツールは、リンクや内容を暗黙に添付するのではなく、整理されたファイル／フォルダーのメタデータを返します。

Dropbox 用の、独立した非公式コネクターです。Dropbox とは提携、承認、後援の関係にありません。「Dropbox」は所有者の商標であり、このコネクターが連携するサービスを特定する目的でのみ使用しています。

使用する場面

• エージェントが Dropbox 内のファイルやフォルダーを保存、移動、コピー、名前変更、または削除する必要がある場合。
• エージェントがファイルやフォルダーを（名前または内容で）検索したり、操作の前にフォルダーの内容を一覧表示したりする必要がある場合。
• エージェントがテキストファイルの内容をインラインで読み取るか、一時的または永続的なリンクを使ってファイルのバイトデータを引き渡す必要がある場合。
• エージェントがファイル／フォルダーを共有したり、リンク設定を変更したり、共有フォルダーへのアクセス権を持つユーザーを管理したりする必要がある場合。

セットアップ

これは agentskills.io スキルです。

コネクターがまだスキルとしてインストールされていない場合は、まず npx skills add zapier/connectors --skill dropbox（または使用するハーネス独自のスキルインストール方法）でインストールしてから、ここに進んでください。スキルをインストールすると、依存関係ではなく、これらのファイルがコピーされます。CLI、ローカル MCP サーバー、または zapier-sdk の認証コマンドを実行する前に、ここで一度 npm install --omit=dev を実行してください。このパッケージを依存関係として自分のプロジェクトにインポートする場合は、npm install によってすでにすべての依存関係が解決されます。詳しくは references/use-as-sdk.md をご覧ください。

リポジトリのソース自体を見たい場合（references/ の閲覧、このコネクターのテストの実行、または変更など）は、範囲を限定した git clone について README.md をご覧ください。

このコネクターの実行には Node.js 22.18+ が必要です。実行方法に合ったリファレンスを選び、ほかの作業を始める前に読み込んでください。

使用環境	読み込むリファレンス
MCP 対応クライアント。ツールがすでに読み込まれている場合（例：mcp__dropbox__<tool>）や、自分でローカルサーバーを登録できる場合（またはユーザーに案内できる場合）	references/use-as-mcp.md
ターミナル／サブプロセスへのアクセス（node を実行できる）	references/use-as-cli.md
このパッケージを依存関係としてインポートする、自分のコードのみ	references/use-as-sdk.md
ツールやターミナルを使えず、このパッケージをインポートできない場合。Dropbox API を直接呼び出す独自のコードを記述する場合（例：コード実行サンドボックス）	references/use-as-recipe.md

スクリプト

21 個すべてのスクリプトで、単一の dropbox 接続を使用します。各スクリプトファイル内の inputSchema／outputSchema（Zod）が、そのスクリプトの仕様の正式な情報源です。

スクリプト	スクリプト名	接続先	説明
scripts/uploadFile.ts	uploadFile	Single (dropbox)	URL からバイトデータを取得してファイルをアップロードします（大きなファイルにはチャンク分割セッションを使用します）。
scripts/createTextFile.ts	createTextFile	Single (dropbox)	プレーンテキストの内容からファイルを作成または上書きします。
scripts/appendToTextFile.ts	appendToTextFile	Single (dropbox)	テキストファイルにテキストを追加します（存在しない場合は作成します）。
scripts/createFolder.ts	createFolder	Single (dropbox)	パスにフォルダーを作成します。
scripts/moveFile.ts	moveFile	Single (dropbox)	ファイルまたはフォルダーを移動または名前変更します。
scripts/copyFile.ts	copyFile	Single (dropbox)	ファイルまたはフォルダーを新しいパスにコピーします。
scripts/deletePath.ts	deletePath	Single (dropbox)	ファイルまたはフォルダーを削除します（一定期間内であれば復元できます）。
scripts/listFolder.ts	listFolder	Single (dropbox)	フォルダー直下の内容を一覧表示します（カーソルでページ分割）。
scripts/searchFiles.ts	searchFiles	Single (dropbox)	名前または内容でファイルやフォルダーを検索します（カーソルでページ分割）。
scripts/getFileMetadata.ts	getFileMetadata	Single (dropbox)	パスまたは ID で指定したファイルまたはフォルダーのメタデータを取得します。
scripts/getTemporaryLink.ts	getTemporaryLink	Single (dropbox)	ファイルの約 4 時間有効な直接ダウンロード URL を取得します。
scripts/getFileContents.ts	getFileContents	Single (dropbox)	テキストファイルのインラインコンテンツを読み取ります（UTF-8、サイズ上限あり）。
scripts/createSharedLink.ts	createSharedLink	Single (dropbox)	継続して利用できる共有リンクを作成します（すでに存在する場合はそのリンクを返します）。
scripts/modifySharedLinkSettings.ts	modifySharedLinkSettings	Single (dropbox)	既存の共有リンクの設定を変更します。url は listSharedLinks で解決してください。
scripts/listSharedLinks.ts	listSharedLinks	Single (dropbox)	既存の共有リンクを一覧表示します。必要に応じてパスを指定できます。
scripts/listSharedFolders.ts	listSharedFolders	Single (dropbox)	アカウントが参加している共有フォルダーを一覧表示します（shared_folder_id の解決に使用します）。
scripts/addFolderMember.ts	addFolderMember	Single (dropbox)	共有フォルダーにメンバーを（メールアドレスで）追加します。shared_folder_id は listSharedFolders で解決してください。
scripts/removeFolderMember.ts	removeFolderMember	Single (dropbox)	共有フォルダーからメンバーを削除します（完了するまでポーリングします）。
scripts/createFileRequest.ts	createFileRequest	Single (dropbox)	フォルダーへの公開アップロードページを作成します。
scripts/listFileRequests.ts	listFileRequests	Single (dropbox)	アカウントのファイルリクエストを一覧表示します。
scripts/getCurrentAccount.ts	getCurrentAccount	Single (dropbox)	アカウントと、そのチーム／個人の名前空間 ID を特定します。
一部のスクリプトは、別のスクリプトで解決するのが最適な ID または URL を受け取ります。解決方法のヒントはフィールドの説明に記載されています（例：addFolderMember.shared_folder_id ← listSharedFolders、modifySharedLinkSettings.url ← listSharedLinks）。

曖昧さの解消と拒否

名前による項目の曖昧さの解消。 Dropbox では、項目はパスまたはIDで指定し、パスでは大文字と小文字が区別されないため、同じ名前に見える項目が複数存在することがあります。ユーザーが正確なパスではなく言葉で指定した項目に対して書き込み（移動／コピー／削除／共有）を行う前に、searchFiles または listFolder で項目を特定してください。

• 一致する項目が1つだけ → 操作を実行します。必要以上に確認しないでください。
• 一致する項目が2つ以上あり、候補を区別できない（例：異なるフォルダーにある report.pdf、または名前が重複する共有フォルダー）→ 操作を中止し、区別できるフィールド（フォルダーの場合は完全な path_display または shared_folder_id）を添えて候補を一覧表示し、どれを指しているかユーザーに尋ねてください。黙って選ばないでください。

ここで名前が重複しやすいエンティティの種類は、名前が重複するファイル／フォルダー（searchFiles／listFolder で特定し、path_display で区別）と、名前が重複する共有フォルダー（listSharedFolders で特定し、shared_folder_id で区別）です。

このコネクターが実行しない操作 — その旨を伝え、実行したふりをしないでください。 ユーザーが次の操作を依頼した場合、別のツールで代用して成功したと報告するのではなく、未対応であることを伝えてください。

• 1回の呼び出しで複数の項目を一括移動、コピー、または削除する操作。 一括処理ツールはありません。単一項目用ツール（moveFile／copyFile／deletePath）を自分で繰り返し呼び出すか、項目ごとに1回の呼び出しが必要であることをユーザーに伝えてください。
• バイナリ形式のドキュメント（PDF／画像／Office）をテキストとして読み取ること、OCR、またはドキュメント解析。 getFileContents が返すのは UTF-8 テキストのみです。それ以外のファイルでは is_text:false が返されるため、getTemporaryLink を使ってバイトデータを引き渡す必要があります。PDF の内容を読んだと主張しないでください。
• 個別のファイルリクエストの取得または編集、あるいは管理対象の共有としてフォルダー全体を共有する操作。 利用できるのは createFileRequest と listFileRequests のみです。ファイルリクエストの取得／更新ツールも、shareFolder ツールもありません。

認証

すべての形状で、認証情報ではなく1つの接続セレクター（[<resolver>:]<value> 形式の文字列）を使って認証情報を渡します。すべてのコネクターで zapier:<connection-id>（Zapier 管理の認証。Zapier の認証、再試行、ガバナンスのレイヤーを経由します）が利用できます。また、一部のコネクターでは1つ以上の直接トークン用リゾルバーも利用できます（名前と数はコネクターによって異なります）。推測せず、このコネクター独自のリゾルバーを確認してください。<resolver>: の接頭辞は省略可能です。値だけを指定した場合は、その値に対応する最初のリゾルバーが使用されます。UUID 形式の値だけを指定した場合は、必ず zapier: が使用されます。各スクリプトでは、必要な接続と、利用可能なリゾルバーが宣言されています。接続を渡す正確な構文と、このコネクターのリゾルバー一覧の確認方法は、形状によって異なります。上記で読み込んだリファレンスを参照してください。

すでに設定済みの情報を先に確認しますか？そのために環境変数の値を表示しないでください。env または env | grep <name> を実行すると名前とともに値も表示されるため、値が設定されている場合は有効な認証情報がトランスクリプトに漏れる可能性があります。名前だけを確認するには（env | cut -d= -f1 | grep -i <name>）、または既知の名前を直接テストしてください（[ -n "$VAR_NAME" ]）。

まだ接続がありませんか？いずれかを選び、取得する際は必ずリファレンスに記載された手順に従ってください。ユーザーが接続 ID やトークンを覚えているものとして、単にそれを尋ねてはいけません。

	読み込み
認証情報を直接渡す	references/use-without-zapier.md
Zapier 接続経由で認証情報を渡す	references/use-with-zapier.md

出力形式

すべてのスクリプトは、{ data, meta } エンベロープを返します。

• data — スクリプトの結果です（outputSchema が宣言する形状です。スクリプトの正確なスキーマを形状に応じて確認する方法については、上で読み込んだリファレンスを参照してください）。
• meta.outputDataValidation — data の検証結果です。
  • { skipped: false, droppedPaths: null } — 検証済みで、削除されたものはありません。
  • { skipped: false, droppedPaths: [...], instruction } — 検証済みですが、該当するパスは data から削除されました。これらは、スクリプトが API から返したものの、outputSchema では宣言されていないフィールドです。必要な場合は、出力検証をスキップして再実行してください。
  • { skipped: true } — 検証がバイパスされ、data は検証されていないスクリプトの生の出力です。

削除されたフィールドの確認／skipOutputDataValidation。 検証されていない生の結果を受け取るには、出力検証を無効にします（正確な構文は形状によって異なります。上で読み込んだリファレンスを参照してください）。入力検証は常に実行されます。

結果の絞り込み／filterOutputData。 大きな結果から必要なフィールドだけを取り出すには、data を後処理する jq 式を渡します（正確な構文は形状によって異なります）。jq は { data, meta } エンベロープではなく data のみを対象にするため、data を起点に記述してください（スクリプトの --help、または形状に応じた同等のコマンドを実行すると、出力スキーマを確認できます）。変換後の値が data に置き換わり、meta は保持されます。また、結果は出力スキーマに対して再検証されません。

リファレンス

該当する領域で作業する前に、対応するリファレンスファイルを読み込んでください。

リファレンス	対象	読み込むタイミング
references/dropbox-api-gotchas.md	Stone の .tag 共用体の形状、error_summary エラーモデル、読み取り時と書き込み時の「見つからない」の非対称性、パスの規則（ルートは "/" ではなく ""）、兄弟関係にある /continue エンドポイントを使ったカーソルページネーション、レート制限と名前空間の書き込みロック、アップロードセッションのフロー、共有リンクの復旧、namespace_id によるチームスペースの指定	Dropbox API を直接呼び出す前、または予期しない API エラーをデバッグする前