Zipline Mcp

Zipline MCP サーバー

Zipline と連携し、Zipline 互換ホストにファイルをアップロードするために特化した MCP（Model Context Protocol）サーバーです。このサーバーは、ファイルのアップロードと検証、アップロードコマンドの生成を行うツールを提供します。

機能

• Zipline インスタンスにファイルをアップロード
• アップロード前にファイルを検証
• アップロードコマンドをプレビュー
• アップロード後にダウンロード URL のみを取得
• Zipline サーバーに保存されているユーザーファイルを一覧表示・検索
• Zipline サーバー上のリモートフォルダーを一覧表示・管理
• 次のような複数のファイル形式をサポート：
  • テキスト／コード：txt、md、gpx、html、json、xml、csv、js、css、py、sh、yaml、yml
  • 画像：png、jpg、jpeg、gif、webp、svg、bmp、tiff、ico、heic、avif

インストール

グローバルインストール

npx で使用できるようにサーバーをグローバルにインストールするには：

npm install -g zipline-mcp

ローカルインストール

プロジェクトの依存関係としてサーバーをインストールするには：

npm install zipline-mcp

使用方法

npx を使う

サーバーをグローバルにインストールした場合は、直接実行できます：

npx zipline-mcp

MCP クライアントの設定への追加

このサーバーを MCP クライアント（Claude Desktop など）で使用するには、クライアントの設定ファイルに追加する必要があります。

MCP-Zipline 統合ガイド

クイックスタート設定

この最小限の設定を MCP クライアント（例：Claude Desktop）に追加します：

# YAML format
mcpServers:
  zipline:
    command: npx
    args: ['-y', 'zipline-mcp']
    environment:
      ZIPLINE_TOKEN: 'your-api-token-here'
      ZIPLINE_ENDPOINT: 'http://localhost:3000'

// JSON format
{
  "mcpServers": {
    "zipline": {
      "command": "npx",
      "args": ["-y", "zipline-mcp"],
      "environment": {
        "ZIPLINE_TOKEN": "your-api-token-here",
        "ZIPLINE_ENDPOINT": "http://localhost:3000"
      }
    }
  }
}

詳細な設定オプション

必須設定

• command：実行する実行ファイル（通常は "npx"）
• args："zipline-mcp" を含む配列
• environment.ZIPLINE_TOKEN：Zipline API トークン
• environment.ZIPLINE_ENDPOINT：Zipline サーバーの URL（デフォルトは "http://localhost:3000"）

任意の設定

• environment.ZIPLINE_FORMAT：ファイル名の形式。対応する値："random"、"uuid"、"date"、"name"、"gfycat"（"random-words" の別名）、"random-words"。デフォルトは "random" です。
• environment.ZIPLINE_ENDPOINT：Zipline サーバーのカスタム URL
• environment.ZIPLINE_DISABLE_SANDBOXING：tmp_file_manager ツールのユーザーごとのサンドボックス化を無効にします。"true" に設定するとサンドボックス化が無効になり、すべてのユーザーで共有の ~/.zipline_tmp ディレクトリを使用します。デフォルトは "false"（サンドボックス化が有効）です。
• environment.ALLOWED_EXTENSIONS：アップロードおよび検証で許可するファイル拡張子の一覧を上書きします。 カンマ区切りの一覧（例：.txt,.md,.pdf,.docx）を指定します。設定すると、デフォルトの許可拡張子一覧が置き換わります。デプロイ環境で対応するファイル形式を制限または拡張する場合に便利です。
• environment.ZIPLINE_ALLOWED_ROOTS：upload_file_to_zipline と validate_file が読み取り可能なディレクトリです。 カンマ区切りの絶対パス（例：/home/me/uploads,/var/zipline/inbox）を指定します。各パスとファイルは realpath で解決されます。シンボリックリンクは、そのリンク先がこれらのディレクトリ内にある場合のみ許可されます。存在しないパスは無視され、サーバーログに記録されます。そのパスによって読み取り可能な場所が追加されることはありません。未設定の場合、許可されるディレクトリはサーバーを実行しているユーザーのホームディレクトリのみです。

セキュリティのベストプラクティス

1. API トークンは設定ファイルではなく、環境変数に保存してください
2. Zipline サーバーへのすべての接続で HTTPS を使用してください
3. エージェントがアップロード元として使用するディレクトリを ZIPLINE_ALLOWED_ROOTS に設定してください。サーバーは、それ以外のすべてのパスを拒否します。これらのディレクトリ外を指すシンボリックリンクも拒否されます。
4. download_external_url は、リクエストごとおよびリダイレクトごとに DNS を解決します。ループバック、プライベート、リンクローカル、またはクラウドメタデータのアドレスが含まれる場合、ダウンロードは拒否されます。接続にはその DNS 解決で得られたアドレスを使用するため、後続の DNS 解決によって接続先が変更されることはありません。

よくある問題のトラブルシューティング

認証エラー

• 症状："Invalid authorization token" エラー
• 解決方法：
  • トークンが有効であることを確認する
  • ZIPLINE_TOKEN の値に誤字がないか確認する
  • トークンが環境変数経由で渡されていることを確認する

アーキテクチャの概要

Zipline MCP Server は、MCP クライアントと Zipline のファイルホスティングサービスの橋渡しをします。各コンポーネントの連携方法は次のとおりです。

graph LR
    A[MCP Client] --> B[MCP Server]
    B --> C[Zipline API]
    C --> D[(Zipline Storage)]

主なコンポーネント

1. MCP クライアント：ファイルのアップロードリクエストを開始します（例：Claude Desktop）
2. MCP サーバー：
   • ファイルをローカルで検証します
   • アップロードコマンドを生成します
   • Zipline での認証を処理します
3. Zipline API：アップロードリクエストを処理し、URL を返します
4. Zipline ストレージ：ファイルを永続的に保存するシステム

一般的なワークフロー

1. クライアントがファイルパスを MCP サーバーに送信します
2. サーバーがファイルの種類とサイズを検証します
3. サーバーが認証済みの API リクエストを構築します
4. Zipline がアップロードを処理し、URL を返します
5. サーバーが MCP クライアント向けにレスポンスを整形します

フォーマットのオプション

format パラメーターは、アップロードしたファイルを Zipline サーバー上でどのような名前にするかを指定します。次のフォーマットを利用できます。

random

サーバーの設定で定義された長さのランダムな文字列をファイル名として生成します。これがデフォルトのフォーマットです。

uuid

UUID に基づくファイル名を生成します（例：550e8400-e29b-41d4-a716-446655440000）。

date

現在の日付と時刻を、サーバーのデフォルトの日付フォーマットに従って使用します。日付のフォーマット処理はすべて Zipline サーバーが行います。

name

拡張子を除いた元のファイル名を使用します（例：document.txt は document になります）。

gfycat

random-words のエイリアスです。人が読みやすい「ランダムな単語」形式のファイル名を生成します。

random-words

ランダムな単語を使って、人が読みやすいファイル名を生成します（例：happy-purple-elephant）。

フォーマットの正規化と検証

• 大文字と小文字を区別しない：すべてのフォーマット値で大文字と小文字は区別されません（例：UUID、uuid、Uuid は同じ値として扱われます）。
• エイリアスの処理：gfycat は自動的に random-words にマッピングされます。
• エラー処理：無効なフォーマット値を指定すると、「Invalid format」エラーになります。
• デフォルトの動作：format パラメーターを省略すると、サーバーに設定されたデフォルトのフォーマット（通常は random）が使用されます。

例

# Use UUID format
upload_file_to_zipline(filePath: "document.txt", format: "uuid")

# Use human-readable format (via alias)
upload_file_to_zipline(filePath: "document.txt", format: "gfycat")

# Case-insensitive usage
upload_file_to_zipline(filePath: "document.txt", format: "RANDOM-WORDS")

拡張アップロードオプション

Zipline MCP Server は、ファイルのアップロードをより細かく制御できる追加の任意ヘッダーに対応しました。これらのヘッダーは、x-zipline-* ヘッダーとして Zipline サーバーに送信されます。

x-zipline-deletes-at

アップロードしたファイルを自動的に削除するタイミングを指定します。

フォーマット：

• 相対時間：「1d」（1 日）、「2h」（2 時間）、「30m」（30 分）のような文字列
• 絶対日時：「date=」プレフィックスを付けた ISO-8601 形式。例：「date=2025-12-31T23:59:59Z」

例：

// Delete after 24 hours
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  deletesAt: '1d',
});

// Delete at specific date
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  deletesAt: 'date=2025-12-31T23:59:59Z',
});

検証：

• 相対時間は正の値で、有効な単位（d、h、m）を使用する必要があります
• 絶対日時は ISO-8601 形式で、未来の日付を指定する必要があります
• 無効なフォーマットは、内容を示すエラーメッセージとともに拒否されます

x-zipline-password

アップロードしたファイルをパスワードで保護します。このヘッダーを指定すると、ファイルにアクセスする際にパスワードの入力が必要になります。

フォーマット：

• 空でない文字列

例：

uploadFile({
  filePath: 'secret.txt',
  format: 'random',
  password: 'my-secret-password',
});

検証：

• パスワードは空でない文字列である必要があります
• 空白文字だけのパスワードは拒否されます
• セキュリティ：パスワードがログに記録されたり、エラーメッセージに表示されたりすることはありません

x-zipline-max-views

ファイルが利用できなくなるまでに閲覧できる回数を制限します。閲覧に成功するたびにカウンターが減ります。

フォーマット：

• 0 以上の整数

例：

// Allow 10 views
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  maxViews: 10,
});

// Allow single view (disposable link)
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  maxViews: 1,
});

検証：

• 0 以上の整数である必要があります
• 負の数や整数以外の値は拒否されます
• カウンターが 0 になると、ファイルは削除対象になります

x-zipline-folder

アップロード先のフォルダー ID を指定します。指定するフォルダーは Zipline サーバー上に存在している必要があります。

フォーマット：

• 英数字の文字列（英字と数字のみ）

例：

uploadFile({
  filePath: 'document.txt',
  format: 'random',
  folder: 'myfolder123',
});

検証：

• 空でない英数字の文字列である必要があります
• 特殊文字と空白文字は拒否されます
• 指定したフォルダーが存在しない場合、アップロードは失敗します

複数のヘッダーの組み合わせ

複数のヘッダーを組み合わせることで、さらに詳細に制御できます。

uploadFile({
  filePath: 'document.txt',
  format: 'random',
  deletesAt: '7d', // Delete after 7 days
  password: 'secret123', // Password protect
  maxViews: 5, // Allow 5 views
  folder: 'shared', // Place in "shared" folder
});

エラー処理

アップロードリクエストをサーバーに送信する前に、すべてのヘッダーがローカルで検証されます。無効なヘッダーがある場合：

• アップロードは直ちに中止されます
• 内容を説明するエラーメッセージが返されます
• Zipline サーバーへの HTTP リクエストは行われません
• エラーメッセージには、修正が必要な内容が具体的に示されます

下位互換性

拡張ヘッダーはすべて任意です。これらのヘッダーを使用しない既存のコードは、これまでどおり動作します。この新機能は、これらのパラメーターを明示的に指定した場合にのみ有効になります。

利用可能なツール

このサーバーでは、次のツールを利用できます。

upload_file_to_zipline

ファイルを Zipline サーバーにアップロードし、詳細な成功メッセージを返します。

• filePath：アップロードするファイルのパスです。このパスは ZIPLINE_ALLOWED_ROOTS 内に解決される必要があります（この変数が未設定の場合はホームディレクトリが対象です）。サーバーはシンボリックリンクを解決した後の実際のパスを読み取ります。対応する拡張子：txt、md、gpx、html、json、xml、csv、js、css、py、sh、yaml、yml、png、jpg、jpeg、gif、webp、svg、bmp、tiff、ico、heic、avif。バイナリ形式は、ファイルの内容からその形式を特定できる場合にのみ受け付けられます。旧形式の Word、Excel、PowerPoint ファイルは、バイト列が Compound File Binary コンテナーである場合に受け付けられます。AVI は、バイト列が AVI コンテナー（video/vnd.avi）の場合に受け付けられます。Matroska はバイト列が Matroska（video/matroska）の場合に、WebM はバイト列が WebM の場合に受け付けられます。Matroska または WebM ファイルが EBML ヘッダーで始まり、ドキュメントタイプが先頭から 4100 バイトを超えた位置にある場合、サーバーはタイプを特定するまでそのファイルの読み取りを続けます。拡張子だけでは不十分です。テキスト形式は、バイト列に NUL が含まれない場合にのみ受け付けられます。NUL バイトがあっても、シークレットスキャンは省略されません。
• originalName：（任意）ダウンロード時に保持する元のファイル名です。このパラメーターは x-zipline-original-name ヘッダーとして Zipline サーバーに送信されます。元のファイル名はファイルの保存時ではなく、ダウンロード時に使用されます。空でない文字列であり、パス区切り文字を含まない必要があります。

ユーザー向けプロンプトの例：

• 「/path/to/document.pdf を Zipline にアップロードしてください」
• 「/home/user/images/photo.jpg にあるファイルをアップロードし、元の名前を保持してください」
• 「/path/to/data.csv を元の名前 sales-data.csv でアップロードしたいです」
• 「ファイル /path/to/script.py を Zipline にアップロードしてください」
• 「/path/to/report.docx をアップロードしてもらえますか？」

validate_file

ファイルが存在し、アップロードに適しているかどうかを確認します。

• filePath：検証するファイルのパスです。アップロードと同じ ZIPLINE_ALLOWED_ROOTS の規則が適用されます。シンボリックリンクを解決した後の実際のパスが、許可されたディレクトリ内にある必要があります。対応する拡張子：txt、md、gpx、html、json、xml、csv、js、css、py、sh、yaml、yml、png、jpg、jpeg、gif、webp、svg、bmp、tiff、ico、heic、avif。Compound File、AVI、Matroska、WebM のケースを含め、アップロードと同じ内容の規則が適用されます。拡張子が一致していても、形式を特定できない非テキストの内容は、信頼されずに拒否されます。

ユーザー向けプロンプトの例：

• 「/path/to/document.pdf がアップロード可能か確認してください」
• 「/home/user/images/photo.jpg にあるファイルを検証してください」
• 「/path/to/data.csv は Zipline にアップロードできますか？」
• 「/path/to/script.py を検証してもらえますか？」
• 「/path/to/report.docx をアップロードできるか確認してください」

list_user_files

Zipline サーバーに以前アップロードしたファイルの一覧表示と検索を行います。このツールを使用して、get_user_file、update_user_file、delete_user_file ツールで使用できるファイル ID を検索できます。ファイル名がわかっている場合は、get_user_file を使ってファイル ID を取得することもできます。

• page：（任意）ページネーション用のページ番号（デフォルト：1）
• perPage：（任意）ページあたりの項目数（デフォルト：20）
• searchField：（任意）検索対象のフィールド（例：「name」、「originalName」、「type」）
• searchQuery：（任意）検索クエリ文字列
• filter：（任意）ファイルの種類などで絞り込み
• sort：（任意）並べ替えに使うフィールド（例：「createdAt」、「size」、「name」）
• order：（任意）並べ替え順（「asc」または「desc」、デフォルト：「desc」）

ユーザー向けのプロンプト例：

• 「Zipline 上のすべてのファイルを一覧表示して」
• 「アップロードしたファイルの最初のページを表示して」
• 「名前に 'document' が含まれるファイルを検索して」
• 「アップロードした PDF ファイルをすべて探して」
• 「作成日順に、最新のものからファイルを一覧表示して」
• 「1 ページあたり 10 件で、2 ページ目を表示して」
• 「元のファイル名に 'report' が含まれるファイルを検索して」
• 「サイズ順に、最も大きいものからファイルを一覧表示して」
• 「アップロードした画像ファイルをすべて探して」

tmp_file_manager

ユーザーごとに分離された、最小限のサンドボックス型ファイル管理機能です。各ユーザーには、そのユーザーの ZIPLINE_TOKEN に基づく専用のサンドボックスディレクトリが割り当てられます。使用できるのはファイル名のみです（サブディレクトリやパストラバーサルは使用できません）。すべての操作は、ユーザーのサンドボックス内に厳密に制限されます。

• command：次のいずれか：
  • LIST — ユーザーのサンドボックス内にあるすべてのファイルを一覧表示します
  • CREATE <filename> — ファイルを作成または上書きします（content を指定することもできます）
  • OPEN <filename> または READ <filename> — ファイルの内容を読み取ります（最大 1MB）
  • PATH <filename> — サンドボックス内にあるファイルの絶対パスを取得します
  • DELETE <filename> — サンドボックスからファイルを削除します
• content：（任意）CREATE に指定する文字列の内容

例：

• LIST
• CREATE notes.txt（内容の指定は任意）
• OPEN notes.txt
• READ notes.txt
• PATH notes.txt
• DELETE notes.txt

ユーザー向けのプロンプト例：

• 「サンドボックス内のすべてのファイルを一覧表示して」
• 「'Meeting notes from today' という内容で 'notes.txt' という名前のファイルを作成して」
• 「'config.json' の内容を読み取って」
• 「'data.csv' の絶対パスを取得して」
• 「'temp.txt' を削除して」
• 「一時ディレクトリ内のすべてのファイルを表示して」
• 「内容を入力して、新しいファイル 'draft.md' を作成して」
• 「'settings.json' ファイルを開いて読み取って」
• 「'output.txt' の完全なパスは？」
• 「'old_file.txt' をサンドボックスから削除して」

サンドボックス設定：

• ユーザーごとのサンドボックスは、デフォルトで有効です
• サンドボックスを無効にして、すべてのユーザーで共有する ~/.zipline_tmp ディレクトリを使用するには、環境で ZIPLINE_DISABLE_SANDBOXING=true を設定します
• サンドボックスを無効にすると、セッションロックと TTL によるクリーンアップも無効になります

ユーザーごとのサンドボックス（有効な場合）：

• 各ユーザーには、~/.zipline_tmp/users/{hash} に固有のサンドボックスディレクトリが割り当てられます。hash はユーザーの ZIPLINE_TOKEN の SHA-256 ハッシュです
• セキュリティのため、サンドボックスは権限 0700 で自動的に作成されます
• すべてのファイル操作は、ユーザーのサンドボックス内に分離されます
• 24 時間を超えたサンドボックスは自動的にクリーンアップされます

セッションロック（サンドボックスが有効な場合）：

• 操作中は各ユーザーのサンドボックスがロックされ、同時アクセスを防ぎます
• ロックは 30 分後に自動的に期限切れになります
• 複数のクライアントが同じサンドボックスにアクセスした際の競合状態を防止します

安全性：

• 使用できるのはファイル名のみです（/、\、..、絶対パスは使用できません）
• ユーザーのサンドボックス外へのアクセスは明示的なエラーとともに拒否されます
• 1MB を超えるファイルは読み取れません
• サブディレクトリはサポートされていません
• サンドボックスが有効な場合、各ユーザーのサンドボックスは他のユーザーから分離されます

download_external_url

新しいツール download_external_url が追加されました。このツールを使うと、MCP サーバー（したがってモデル）は外部の HTTP(S) URL を呼び出し元のサンドボックスにダウンロードし、保存したファイルの絶対ファイルシステムパスを返します。

• ツール名：download_external_url
• 目的：外部の HTTP(S) リソースをユーザーごとのサンドボックスにダウンロードし、ファイルの保存先の絶対パスを返します。
• 入力スキーマ：
  • url（文字列）— 必須 — ダウンロードする HTTP または HTTPS の URL
  • timeoutMs（数値）— 任意 — リクエストのタイムアウト（ミリ秒、デフォルト：30000）
  • maxFileSizeBytes（数値）— 任意 — 許可する最大ファイルサイズ（バイト、デフォルト：100 _ 1024 _ 1024 = 100 MB）
• 動作：
  • 指定された URL を検証し、http: と https: のスキームのみを許可します。
  • AbortController を使用して、設定されたタイムアウトを適用します。
  • Content-Length ヘッダーがある場合はその値を確認し、設定された最大サイズを超えるサイズが宣言されているダウンロードを拒否します。
  • ファイルをユーザーのサンドボックスディレクトリ（tmp_file_manager ツールが使用するものと同じサンドボックス）にダウンロードし、絶対パスを返します。例：/home/user/.zipline_tmp/users/<hash>/file.ext。
  • リモートリソースからファイル名が提供されない場合は、安全で決定的な名前を使用します。
  • 失敗時にはサンドボックスに不完全なファイルが残らないよう、部分ファイルを削除します。
  • 可観測性のため、既存のサンドボックスロギング機能を使って構造化ログを出力します。

使用例（MCP ツール呼び出し）

• 入力例： { "url": "https://example.com/files/document.pdf", "timeoutMs": 30000, "maxFileSizeBytes": 104857600 }
• 成功時の応答内容の例： "✅ DOWNLOAD COMPLETE\n\nLocal path: /home/user/.zipline_tmp/users/abc123/document.pdf"

セキュリティと安全性に関する考慮事項

• http と https のみを受け付けます。それ以外のスキーム（ftp、file など）は拒否されます。
• リダイレクト後も含め、接続のたびにサーバーがホスト名を解決し、いずれかのアドレスがループバック、プライベート、リンクローカル、またはクラウドメタデータのアドレス（例：127.0.0.1、10.0.0.0/8、169.254.169.254）の場合はダウンロードを拒否します。
• ソケットは、その名前解決で返されたアドレスに接続します。元のホスト名は Host ヘッダーおよび TLS サーバー名として送信されます。確認後に DNS が変更されても、接続先が変わることはありません。
• デフォルトのファイルサイズ上限は 100 MB です。maxFileSizeBytes で上書きできますが、慎重に設定してください。
• ダウンローダーはリダイレクトをたどりますが、リダイレクトループを防ぐため、コードで最大回数を適用します。各リダイレクト先も再度名前解決して検証します。
• リモートサーバーがエラーステータスを返す場合、応答本文の先頭 1 MiB のみを保持します。ダウンロードが成功した場合は、引き続き maxFileSizeBytes（デフォルト 100 MB）が適用されます。
• すべてのダウンロードはユーザーごとのサンドボックス内に保存されます。ファイル名は tmp_file_manager と同じルールに従って検証・サニタイズされます（パス区切り文字、ドットセグメント、絶対パスは使用できません）。
• 可観測性のため、サーバーはサニタイズしたパス（ユーザー部分はマスク）とともにダウンロードのアクティビティを記録します。トークンなどの秘密情報は決して記録されません。
• サーバーがダウンロードできる場所を制限するためにドメイン許可リストが必要な場合は、本番環境でこのツールを有効にする前に、MCP サーバーの設定レベルでホスト名の許可リストを追加することを検討してください。

ユーザー向けプロンプトの例：

• 「'https://example.com/document.pdf' から PDF をダウンロードして、サンドボックスに保存してください」
• 「タイムアウトを 60 秒にして、'https://example.com/data.csv' をダウンロードしてください」
• 「最大ファイルサイズを 50MB にして、'https://example.com/image.jpg' から画像をダウンロードしてください」
• 「'https://example.com/report.pdf' からファイルをダウンロードして、サンドボックスに保存してください」
• 「'https://example.com/config.json' をダウンロードしてもらえますか？」
• 「タイムアウトを 45 秒に設定して、'https://example.com/archive.zip' をダウンロードしてください」
• 「最大サイズを 10MB にして、'https://example.com/data.json' をダウンロードする必要があります」

list_user_files

新しいツール list_user_files が追加されました。Zipline サーバーに以前アップロードしたファイルを一覧表示して検索できます。

• ツール名：list_user_files
• 目的：ページネーション、フィルタリング、並べ替え、検索に対応し、Zipline サーバーに保存されているユーザーファイルを一覧表示して検索します。
• 入力スキーマ：
  • page（number）— 任意 — ページネーションのページ番号（デフォルト：1）
  • perPage（number）— 任意 — 1ページあたりの項目数（デフォルト：20）
  • searchField（string）— 任意 — 検索対象のフィールド（例：「name」、「originalName」、「type」）
  • searchQuery（string）— 任意 — 検索クエリ文字列
  • filter（string）— 任意 — ファイルの種類またはその他の条件でフィルタリング
  • sort（string）— 任意 — 並べ替え対象のフィールド（例：「createdAt」、「size」、「name」）
  • order（string）— 任意 — 並べ替え順（「asc」または「desc」、デフォルト：「desc」）
• 動作：
  • 指定したパラメーターで Zipline API からファイルを取得します
  • 多数のファイルを処理できるよう、ページネーションに対応しています
  • searchField と searchQuery を使って、特定のフィールド内を検索できます
  • 結果のフィルタリングと並べ替えに対応しています
  • ファイル情報とページネーションのメタデータを含む、構造化された応答を返します

使用例（MCP ツール呼び出し）

• 入力例：

  {
    "page": 1,
    "perPage": 10,
    "searchField": "name",
    "searchQuery": "document",
    "sort": "createdAt",
    "order": "desc"
  }
  

• 成功時の応答内容の例：

  📁 USER FILES (Page 1 of 3)
  
  1. ⭐ document.pdf
     🆔 ID: file123
     📅 Created: 1/15/2025
     📊 Size: 1.2 MB
     🏷️ Type: application/pdf
     👁️ Views: 5
     🔗 URL: https://zipline.example.com/u/file123
  
  2. image.png
     🆔 ID: img456
     📅 Created: 1/14/2025
     📊 Size: 2.1 MB
     🏷️ Type: image/png
     👁️ Views: 12
     🔗 URL: https://zipline.example.com/u/img456
  
  3. data.csv
     🆔 ID: csv789
     📅 Created: 1/13/2025
     📊 Size: 500.0 KB
     🏷️ Type: text/csv
     👁️ Views: 3
     🔗 URL: https://zipline.example.com/u/csv789
  
  Total files: 25 | Showing: 3
  

  注： 応答内の URL は、ZIPLINE_ENDPOINT の設定にかかわらず適切な形式になるよう正規化されます。末尾のスラッシュを処理し、一貫した URL の構築を保証します。

ファイルモデル

このツールは、次の構造でファイルを返します。

• id：ファイルの一意の識別子（get_user_file、update_user_file、delete_user_file などの操作に使用）
• name：サーバーに保存されているファイル名
• originalName：アップロード時の元のファイル名
• size：ファイルサイズ（バイト単位）
• type：ファイルの MIME タイプ
• url：ファイルにアクセスするための直接 URL
• createdAt：ファイルのアップロード日時（ISO 8601 形式）
• expiresAt：ファイルの有効期限（該当する場合）
• maxViews：最大閲覧数（該当する場合）
• views：現在の閲覧数

検索とフィルタリングのオプション

このツールは、強力な検索機能とフィルタリング機能を提供します。

• 検索：searchField と searchQuery を使って、特定のフィールド内を検索します
  • 対応する検索フィールド：「name」、「originalName」、「type」
  • 大文字と小文字を区別せず、部分一致にも対応しています
• フィルター：filter パラメーターを使って、ファイルの種類またはその他の条件でフィルタリングします
• 並べ替え：sort と order を使って、任意のフィールドで結果を並べ替えます
  • 対応する並べ替えフィールド：「createdAt」、「size」、「name」、「views」
  • 並べ替え順には「asc」（昇順）または「desc」（降順）を指定できます

インテグレーター向けの注記

• このツールは MCP サーバーによってエクスポートされ、MCP クライアントまたはモデルからプログラムで呼び出せます。
• 実装は src/userFiles.ts にあり、MCP への登録は src/index.ts にあります。
• ページネーション、検索、フィルタリング、並べ替え、エラー処理を検証するテストが src/userFiles.test.ts に追加されました。

get_user_file

ツールに関する情報：get_user_file。Zipline サーバーに保存されている特定のファイルの詳細情報を取得できます。このツールで必要となるファイル ID は、list_user_files またはファイル名を使って確認してください。

• ツール名：get_user_file
• 目的：Zipline サーバーに保存されている特定のファイルの詳細情報を取得します
• 入力スキーマ：
  • id（string）— 必須 — 情報を取得するファイル ID。list_user_files ツールから取得してください。
• 動作：
  • ファイル ID を使用して Zipline API からファイル情報を取得します
  • サイズ、種類、閲覧数、お気に入りの状態などを含む包括的なファイルメタデータを返します
  • ファイル ID に含まれる特殊文字の URL エンコードを処理します

使用例（MCP ツールの呼び出し）

• 入力例：

  {
    "id": "file123"
  }
  

• 成功時のレスポンス内容の例：

  📁 FILE INFORMATION
  
  📁 document.pdf
  🆔 ID: file123
  📅 Created: 1/15/2025
  📊 Size: 1.2 MB
  🏷️ Type: application/pdf
  👁️ Views: 5
  🔗 URL: http://localhost:3000/u/file123
  
  📄 Original Name: my-document.pdf
  🏷️ Tags: tag1, tag2
  📁 Folder ID: folder123
  

  注： レスポンス内の URL は、ZIPLINE_ENDPOINT の設定にかかわらず適切な形式になるよう正規化されます。末尾のスラッシュを処理し、一貫した URL の構築を行います。

ユーザー向けプロンプトの例：

• 「ID が 'abc123' のファイルの詳細情報を取得して」
• 「ファイル 'document.pdf' の詳細を表示して」
• 「ファイル 'xyz789' のメタデータを確認したい」
• 「'my-image.jpg' という名前のファイルのプロパティは？」
• 「ID が 'file123' のファイルの情報を取得して」

update_user_file

ツールに関する情報：update_user_file。Zipline サーバーに保存されている特定のファイルのプロパティを更新できます。このツールで必要となるファイル ID は、list_user_files またはファイル名を使って確認してください。

• ツール名：update_user_file
• 目的：Zipline サーバーに保存されている特定のファイルのプロパティを更新します
• 入力スキーマ：
  • id（string）— 必須 — 更新するファイル ID。list_user_files ツールから取得してください。
  • favorite（boolean）— 任意 — お気に入りに設定または解除します
  • maxViews（number）— 任意 — 許可する閲覧数の上限（>= 0）
  • password（string | null）— 任意 — パスワードを設定（string）または削除（null）します
  • originalName（string）— 任意 — 元のファイル名を設定または更新します
  • type（string）— 任意 — ファイルの MIME タイプを設定または更新します
  • tags（string[]）— 任意 — このファイルに設定するタグ ID の配列
  • name（string）— 任意 — ファイル名を変更します
• 動作：
  • Zipline API に PATCH リクエストを送信してファイルのプロパティを更新します
  • 明示的に指定されたフィールドのみを更新します（未定義のフィールドは無視されます）
  • string または null を渡すことで、パスワードの設定または削除に対応します
  • 更新後のファイル情報を返します

使用例（MCP ツールの呼び出し）

• 入力例：

  {
    "id": "file123",
    "favorite": true,
    "maxViews": 10,
    "password": "secret123"
  }
  

• 成功時のレスポンス内容の例：

  ✅ FILE UPDATED SUCCESSFULLY!
  
  ⭐🔒 document.pdf
  🆔 ID: file123
  📅 Created: 1/15/2025
  📊 Size: 1.2 MB
  🏷️ Type: application/pdf
  👁️ Views: 5/10
  
  📄 Original Name: my-document.pdf
  🏷️ Tags: tag1, tag2
  📁 Folder ID: folder123
  

  注： レスポンスに URL フィールドは含まれません。URL を含む更新後のファイル情報を取得するには、get_user_file ツールを使用してください。

ユーザー向けプロンプトの例：

• 「ファイル 'abc123' をお気に入りに設定して」
• 「ファイル 'document.pdf' の閲覧数の上限を 10 に設定して」
• 「ファイル 'xyz789' にパスワード 'secret123' を設定して」
• 「ファイル 'file123' のパスワードを削除して」
• 「ファイル 'abc123' の元の名前を 'my-updated-document.pdf' に変更して」
• 「ファイル 'xyz789' の名前を 'new-name.pdf' に変更して」
• 「ファイル 'file123' の MIME タイプを 'application/pdf' に設定して」
• 「ファイル 'abc123' にタグ ['tag1', 'tag2'] を追加して」
• 「ファイル 'xyz789' をお気に入りに設定し、maxViews を 5、パスワードを 'secure' にして」

delete_user_file

新しいツール delete_user_file が追加されました。Zipline サーバーに保存されている特定のファイルを削除できます。このツールで必要なファイル ID を見つけるには、list_user_files またはファイル名を使用してください。

• ツール名：delete_user_file
• 目的：Zipline サーバーに保存されている特定のファイルを削除します
• 入力スキーマ：
  • id（string）— 必須 — 削除するファイル ID。list_user_files ツールで取得します。
• 動作：
  • Zipline API に DELETE リクエストを送信してファイルを削除します
  • 削除したファイル情報を返します（確認用）
  • ファイル ID 内の特殊文字を URL エンコードします

使用例（MCP ツール呼び出し）

• 入力例：

  {
    "id": "uniqueid123"
  }
  

• 成功時のレスポンス内容の例：

  ✅ FILE DELETED SUCCESSFULLY!
  
  ⭐🔒 document.pdf
  🆔 ID: uniqueid123
  📅 Created: 1/15/2025
  📊 Size: 1.2 MB
  🏷️ Type: application/pdf
  👁️ Views: 5/10
  
  📄 Original Name: my-document.pdf
  🏷️ Tags: tag1, tag2
  📁 Folder ID: folder123
  

  注： ファイルは削除済みのため、レスポンスに URL フィールドは含まれません。

ユーザー向けプロンプトの例：

• 「ID が 'abc123' のファイルを削除してください」
• 「'document.pdf' をサーバーから削除してください」
• 「'my-image.jpg' という名前のファイルを削除してください」
• 「ファイル 'xyz789' を完全に削除してください」
• 「ID が 'file123' のファイルを削除したいです」

remote_folder_manager

新しいツール remote_folder_manager が追加されました。Zipline サーバー上のリモートフォルダーを一覧表示および管理できます。

• ツール名：remote_folder_manager
• 目的：Zipline サーバー上のリモートフォルダーを一覧表示および管理します
• 入力スキーマ：
  • command（string）— 必須 — 実行するコマンド。次のコマンドに対応しています：
    • LIST — Zipline サーバー上のすべてのフォルダーを詳細情報付きで一覧表示します
    • ADD <name> — 指定した名前で新しいフォルダーを作成します
    • EDIT <id> — 指定した ID の既存のフォルダーを編集します
    • INFO <id> — ID を指定して特定のフォルダーの詳細情報を取得します
    • DELETE <id> — 指定した ID の既存のフォルダーを削除します
  • id（string）— 任意 — 編集するフォルダー ID（EDIT コマンドでは必須）
  • name（string）— 任意 — フォルダー名（ADD コマンドでは必須、EDIT コマンドでは任意）
  • isPublic（boolean）— 任意 — フォルダーを公開するかどうか（デフォルト：false、ADD コマンドおよび EDIT コマンド用）
  • allowUploads（boolean）— 任意 — フォルダーへのアップロードを許可するかどうか（EDIT コマンド用）
  • fileId（string）— 任意 — フォルダーに追加するファイル ID（EDIT コマンド用）
  • files（string[]）— 任意 — フォルダーに含めるファイル ID の配列（ADD コマンド用）
  • id（string）— 任意 — 情報を取得するフォルダー ID（INFO コマンドでは必須）
• 動作：
  • LIST の場合：Zipline API からフォルダーを取得し、ID、名前、公開状態、作成／更新日時、ファイル数など、フォルダーの詳細情報を含む構造化されたレスポンスを返します
  • ADD の場合：指定した名前と任意のパラメーターを使って新しいフォルダーを作成します
  • EDIT の場合：指定した ID の既存のフォルダーを任意のパラメーターで変更します
    • fileId が指定されている場合：指定したファイルをフォルダーに追加します
    • name、isPublic、または allowUploads が指定されている場合：フォルダーのプロパティを更新します
  • INFO の場合：ID に基づいて特定のフォルダーの詳細情報を取得します。すべてのフォルダーのプロパティが含まれます
  • DELETE の場合：指定した ID の既存のフォルダーを完全に削除し、削除したフォルダーの情報を返します
  • 利用可能なすべてのフィールドを含む、包括的なフォルダー情報を返します
  • 入力パラメーターを検証し、明確なエラーメッセージを表示します
  • INFO コマンドでは、有効なフォルダー ID が必要です（フォルダー名は指定できません）

使用例（MCP ツール呼び出し）

LIST コマンドの例：

• 入力例：

  {
    "command": "LIST"
  }
  

• 成功時のレスポンス内容の例：

  📁 REMOTE FOLDERS
  
  1. Documents
     🆔 ID: folder123
     🔒 Private
     📅 Created: 2025-01-15T10:30:45.123Z
     📝 Updated: 2025-01-20T14:45:30.456Z
     📄 Files: 5
  
  2. Images
     🆔 ID: folder456
     🔒 Public
     📅 Created: 2025-01-10T09:15:22.789Z
     📝 Updated: 2025-01-18T16:20:11.012Z
     📄 Files: 12
  
  3. Public
     🆔 ID: No ID
     🔒 Public
     📅 Created: 2025-01-05T08:00:00.000Z
     📝 Updated: 2025-01-05T08:00:00.000Z
     📄 Files: 0
  
  Total folders: 3
  

ADD コマンドの例：

• 入力例（パラメーターを使用）：

  {
    "command": "ADD",
    "name": "My New Folder",
    "isPublic": false
  }
  

• 入力例（コマンド引数を使用）：

  {
    "command": "ADD My New Folder"
  }
  

• 成功時のレスポンス内容の例：

  ✅ FOLDER CREATED SUCCESSFULLY!
  
  📁 My New Folder
     🆔 ID: folder789
     🔒 Private
     📄 Files: 0
  

  注： Zipline サーバーで ID が割り当てられていない場合、フォルダーに ID がないことがあります。この場合もツールは適切に処理し、ID のないフォルダーには「No ID」と表示します。

EDIT コマンドの例：

• 入力例（フォルダーのプロパティを更新）：

{
  "command": "EDIT",
  "id": "folder123",
  "name": "Updated Folder Name",
  "isPublic": true,
  "allowUploads": true
}

• 入力例（フォルダーにファイルを追加する場合）：

{
  "command": "EDIT",
  "id": "folder123",
  "fileId": "file456"
}

• 成功時のレスポンス内容の例（プロパティを更新する場合）：

✅ FOLDER UPDATED SUCCESSFULLY!

📁 Updated Folder Name
   🆔 ID: folder123
   🔒 Public
   📤 Uploads Allowed
   📄 Files: 3

• 成功時のレスポンス内容の例（ファイルを追加する場合）：

✅ FILE ADDED TO FOLDER SUCCESSFULLY!

📁 Documents
   🆔 ID: folder123
   🔒 Private
   📄 Files: 4

注意： EDIT コマンドは、次の 2 つのモードで動作します。

1. プロパティの編集：name、isPublic、または allowUploads が指定されている場合、PATCH リクエストでフォルダーのプロパティが更新されます。
2. ファイルの追加：fileId が指定されている場合、PUT リクエストで指定されたファイルがフォルダーに追加されます。

これらのモードは、個別に使用することも、1 つのコマンド内で組み合わせて使用することもできます。

INFO コマンドの例：

• 入力例：

  {
    "command": "INFO",
    "id": "folder123"
  }
  

• 成功時のレスポンス内容の例：

  📁 FOLDER INFORMATION
  
  📁 Documents
     🆔 ID: folder123
     🔒 Private
     📅 Created: 2025-01-15T10:30:45.123Z
     📝 Updated: 2025-01-20T14:45:30.456Z
     📄 Files: 5
     📋 Files (IDs): file123, file456, file789, fileabc, filexyz
  

  注意： INFO コマンドには、フォルダー名ではなく有効なフォルダー ID が必要です。情報を取得するフォルダーの ID を調べるには、LIST コマンドを使用してください。

DELETE コマンドの例：

• 入力例：

{
  "command": "DELETE",
  "id": "folder123"
}

• 成功時のレスポンス内容の例：

✅ FOLDER DELETED SUCCESSFULLY!

📁 Documents
   🆔 ID: folder123
   🔒 Private
   📅 Created: 2025-01-15T10:30:45.123Z
   📝 Updated: 2025-01-20T14:45:30.456Z
   📄 Files: 5

注意： DELETE コマンドには、フォルダー名ではなく有効なフォルダー ID が必要です。削除するフォルダーの ID を調べるには、LIST コマンドを使用してください。フォルダーの削除は完全に行われ、元に戻すことはできません。

フォルダーモデル

このツールは、次の構造でフォルダーを返します。

• id：フォルダーの一意の識別子（省略可能。すべてのフォルダーに存在するとは限りません）
• name：フォルダー名
• public：フォルダーが公開されているかどうか（true/false）
• createdAt：フォルダーが作成された日時（ISO 8601 形式）
• updatedAt：フォルダーが最後に更新された日時（ISO 8601 形式）
• files：フォルダーに含まれるファイル ID の配列

インテグレーター向けの注意事項

• このツールは MCP サーバーによってエクスポートされ、MCP クライアントまたはモデルからプログラムで呼び出すことができます。
• 実装は src/remoteFolders.ts にあり、MCP への登録は src/index.ts にあります。
• LIST コマンドと ADD コマンドの成功ケース、ページネーション、エラー処理、エッジケースを検証するテストが src/remoteFolders.test.ts に追加されています。

ユーザー向けプロンプトの例：

• 「Zipline サーバー上のすべてのフォルダーを一覧表示して」
• 「利用可能なフォルダーを表示して」
• 「サーバー上にはどんなフォルダーがある？」
• 「すべてのリモートフォルダーを一覧表示して」
• 「Documents という名前の新しいフォルダーを作成して」
• 「Images というフォルダーを Zipline サーバーに追加して」
• 「Shared Files という名前の公開フォルダーを作成して」
• 「Projects という名前の新しいフォルダーを追加して」
• 「Archive という名前のフォルダーを作成して、非公開にして」
• 「フォルダー 'folder123' の名前を 'New Documents' に変更して」
• 「フォルダー 'folder456' を更新して、公開し、アップロードを許可して」
• 「ファイル 'file789' をフォルダー 'folder123' に追加して」
• 「フォルダー 'folder789' を非公開にして、アップロードを無効にして」
• 「フォルダー 'folder456' の名前を 'Archive' に変更して、公開して」
• 「フォルダー 'folder123' の詳細情報を取得して」
• 「ID が 'folder789' のフォルダーの詳細をすべて表示して」
• 「フォルダー 'folder456' のプロパティは何？」
• 「Documents という名前のフォルダーの情報を取得して（最初に LIST を使って ID を取得して）」
• 「ID が 'folder123' のフォルダーを削除して」
• 「Old Documents という名前のフォルダーをサーバーから削除して」
• 「ID が 'folder456' のフォルダーを削除して」
• 「フォルダー 'folder789' を完全に削除して」
• 「ID が 'folder123' のフォルダーを削除したい」

サンドボックスのパス解決

tmp_file_manager ツールは、安全なパス解決メカニズムを使用して、すべてのファイル操作がサンドボックスの境界内で行われるようにします。これは、次のセキュリティ保証を提供する resolveSandboxPath 関数によって実装されています。

パスの検証：

• ファイル名の検証：パス・トラバーサル攻撃を防ぐため、すべてのファイル名を検証します
• 絶対パスへの解決：相対ファイル名をサンドボックス内の絶対パスに変換します
• 境界の適用：解決されたパスがサンドボックスディレクトリの外に出ないようにします
• エラー処理：違反があった場合、明確なエラーメッセージとともに SandboxPathError をスローします

セキュリティ機能：

• 入力のサニタイズ：パス区切り文字（/、\）、ドットセグメント（..）、または絶対パスを含むファイル名を拒否します
• パスの正規化：シンボリックリンク攻撃を防ぐため、パスを正規形に解決します
• 包含の検証：最終的に解決されたパスがサンドボックスの境界内にあることを検証します
• 監査ログ：セキュリティ監視のため、すべてのサンドボックス操作をサニタイズ済みのパスとともに記録します

実装の詳細：

// Example of secure path resolution
function resolveSandboxPath(filename: string): string {
  const userSandbox = getUserSandbox();

  // Validate filename first
  const validationError = validateFilename(filename);
  if (validationError) {
    throw new SandboxPathError(validationError);
  }

  const resolved = path.resolve(userSandbox, filename);

  // Security: Ensure resolved path is within sandbox
  if (!resolved.startsWith(userSandbox)) {
    throw new SandboxPathError(`Path traversal attempt: ${filename}`);
  }

  return resolved;
}

エラーの例：

• CREATE ../evil.txt → エラー：ファイル名にパス区切り文字、ドットセグメント、または空の値を含めることはできません。~/.zipline_tmp 内のファイル名のみ使用できます。
• OPEN /etc/passwd → エラー：ファイル名にパス区切り文字、ドットセグメント、または空の値を含めることはできません。~/.zipline_tmp 内のファイル名のみ使用できます。
• READ ../../system/file → エラー：パス・トラバーサルの試行：../../system/file

ログ記録と監査：

セキュリティ上機密性の高い情報をサニタイズしたうえで、すべてのサンドボックス操作を記録します。

[2025-01-15T10:30:45.123Z] SANDBOX_OPERATION: FILE_CREATED - notes.txt - Path: /home/user/.zipline_tmp/users/[HASH] - Size: 42 bytes

ユーザー固有のパスは [HASH] でマスクされます。これにより、ログ内のトークン漏えいを防ぎながら、追跡可能性を維持します。

開発

前提条件

• Node.js（v18 以降）
• npm または yarn

セットアップ

1. リポジトリをクローンします。

git clone https://github.com/dorogoy/zipline-mcp.git
cd zipline-mcp

2. 依存関係をインストールします。

npm install

スクリプト

• npm run build：TypeScript プロジェクトをビルドします。
• npm run start：ビルド済みのサーバーを実行します。
• npm run dev：tsx を使用して開発モードでサーバーを実行します。
• npm run test：ウォッチモードでテストを実行します。
• npm run test:run：テストを一度実行します。
• npm run lint：ESLint を使用してコードベースをリントします。
• npm run lint:fix：可能な場合、リントエラーを自動修正します。
• npm run format：Prettier でコードベースをフォーマットします。
• npm run format:check：コードベースがフォーマット済みかどうかを確認します。

リント

ローカルでのリント実行

リントエラーを確認するには：

npm run lint

修正可能な問題を自動修正するには：

npm run lint:fix

または、Makefile を使用します。

make lint

CI でのリント

• リントはすべてのプルリクエストと各リリースの前に自動実行されます。
• リントエラーがある場合、CI は失敗します。
• PR のマージにはリントが必須です。

リント結果の解釈

• エラーはターミナルまたは CI ログに表示されます。
• npm run lint:fix を使用するか、表示された内容に従ってコードを編集し、ローカルでエラーを修正します。
• 警告によって CI がブロックされることはありませんが、コード品質のために対処する必要があります。

Makefile

利便性のために Makefile が用意されています。

make install      # Install dependencies
make build       # Build the project
make test        # Run tests
make lint        # Lint the code
make format      # Format the code
make clean       # Clean build artifacts
make publish     # Publish to npm

ライセンス

MIT