模型上下文協議 (MCP) 整合

PreviewFile.dev 提供 MCP 伺服器，使 AI 代理和助手能夠以程式化方式上傳附件並生成安全的預覽 URL。這允許與 Claude、Cursor、Cherry Studio、Windsurf、Chatbox AI 等 MCP 相容客戶端無縫整合。

快速開始

MCP 端點

https://previewfile.dev/api/v1/mcp

傳輸協議: HTTP 串流傳輸 (MCP 規範修訂版 2025-06-18)

認證方式

所有 MCP 請求都需要使用 API 金鑰進行認證。您可以在 控制台設定 取得 API 金鑰。

支援的認證方式

設定範例

{
  "mcpServers": {
    "previewfile": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-client-http",
        "https://previewfile.dev/api/v1/mcp"
      ],
      "env": {
        "MCP_BEARER_TOKEN": "your-api-key-here"
      }
    }
  }
}

可用工具

PreviewFile MCP 伺服器提供 2 個工具 用於檔案上傳和預覽生成：

工具概覽

previewfile_upload_from_url

透過提供 URL 上傳檔案。伺服器取得檔案並建立預覽工作階段。這是從現有檔案建立預覽連結的主要方法。

參數：

回應範例：

{
  "shortUrl": "a1b2c3d4",
  "previewUrl": "https://previewfile.dev/p/a1b2c3d4",
  "expireAt": "2026-01-28T10:30:00Z",
  "status": "READY",
  "fileName": "report.pdf",
  "fileSize": 245678,
  "mimeType": "application/pdf"
}

previewfile_request_upload_url

請求預簽名 URL 以將檔案直接上傳到儲存空間。當您需要上傳無法透過 URL 存取的檔案時使用。

參數：

回應範例：

{
  "uploadUrl": "https://storage.previewfile.dev/upload/...",
  "tempKey": "tmp/space123/abc123.pdf",
  "expiresIn": 3600
}

收到預簽名 URL 後，使用 HTTP PUT 將檔案直接上傳到傳回的 uploadUrl。

建議提示詞

以下是一些幫助您開始使用 PreviewFile MCP 伺服器的自然語言提示詞：

URL 轉預覽提示詞

"將這個 S3 URL 轉換為安全預覽連結：https://bucket.s3.amazonaws.com/doc.pdf"

"為這個檔案 URL 建立一個 2 小時有效期的預覽"

"為這個外部文件生成帶浮水印的預覽連結"

"為這份合約 URL 建立一個檢視後即過期的一次性預覽連結"

"禁止下載方式上傳這個 URL 的檔案：https://example.com/report.pdf"

直接上傳提示詞

"取得一個預簽名 URL，以便我上傳大型影片檔案"

"我需要上傳一個 50MB 的簡報 - 給我一個上傳 URL"

使用場景

1. AI 輔助文件分享

讓您的 AI 程式設計助手在討論文件時自動生成安全預覽連結：

使用者：「分享這份 S3 文件給團隊，不要暴露我們的儲存桶 URL」
AI：*使用 previewfile_upload_from_url 取得並生成安全連結*
    「這是您的安全預覽連結：https://previewfile.dev/p/abc123
     連結 1 小時後過期。原始 URL 已隱藏。」

2. 安全的外部檔案分享

將任何可存取的 URL 轉換為安全的限時預覽：

使用者：「為這份客戶報告建立預覽連結：https://pdfobject.com/pdf/sample.pdf」
AI：*使用 previewfile_upload_from_url 並設定 noDownload=true*
    「預覽連結已建立：https://previewfile.dev/p/xyz789
     下載已停用。1 小時後過期。」

3. 帶浮水印的文件分發

分享帶有追蹤浮水印的機密文件：

使用者：「分享這份合約給供應商，但要新增浮水印」
AI：*使用 previewfile_upload_from_url 並設定 watermark 參數*
    「已建立帶「供應商審閱」浮水印的預覽連結：https://previewfile.dev/p/abc456
     浮水印將顯示在所有頁面上。」

4. 一次性安全連結

為敏感內容建立自毀預覽連結：

使用者：「為這份機密文件建立一次性連結」
AI：*使用 previewfile_upload_from_url 並設定 oneTime=true*
    「一次性預覽連結已建立：https://previewfile.dev/p/wire123
     連結在首次存取後立即過期。」

預簽名上傳工作流程

對於無法透過 URL 存取的檔案，使用預簽名上傳工作流程：

{
  "fileName": "large-video.mp4",
  "mimeType": "video/mp4",
  "sizeBytes": 52428800,
  "fileHash": "a1b2c3d4e5f6..."
}

curl -X PUT "${uploadUrl}" \
  -H "Content-Type: video/mp4" \
  --data-binary @large-video.mp4

安全功能

MCP 伺服器繼承了所有 PreviewFile 安全功能：

錯誤處理

MCP 伺服器傳回帶有清晰訊息的結構化錯誤：

{
  "error": "TTL exceeds plan limit. Maximum allowed: 1440 minutes."
}

常見錯誤

速率限制

MCP 請求計入您的 API 速率限制：

疑難排解

連線問題

問題：AI 客戶端無法連線到 MCP 伺服器

解決方案：

1. 驗證您的 API 金鑰正確且有效
2. 檢查端點 URL：https://previewfile.dev/api/v1/mcp
3. 確保您的客戶端支援 HTTP 串流傳輸
4. 檢查網路/防火牆限制

上傳失敗

問題：檔案上傳失敗或逾時

解決方案：

1. 對於大檔案，使用預簽名上傳工作流程
2. 驗證 base64 編碼正確（無 data URL 前綴）
3. 檢查檔案大小是否在 500MB 限制內
4. 確保 MIME 類型與實際檔案內容相符

認證錯誤

問題：「Authentication required」錯誤

解決方案：

1. 從 控制台設定 生成新的 API 金鑰
2. 驗證金鑰傳遞正確：
   • Bearer 權杖：Authorization: Bearer <key>
   • 請求標頭：x-api-key: <key>
3. 檢查金鑰是否已被撤銷

常見問題

不使用 API 金鑰可以使用 MCP 嗎？

不可以，所有 MCP 操作都需要認證。請從 控制台設定 取得您的 API 金鑰。

最大檔案大小是多少？

每個檔案 500MB。

上傳的檔案是永久的嗎？

不是，所有檔案根據設定的 TTL 自動過期。最大保留時間取決於您的方案。

可以透過 MCP 列出所有預覽嗎？

目前，請使用 控制台 或 REST API 列出預覽。MCP 專注於上傳和單一預覽操作。

檔案去重是自動的嗎？

是的，具有相同 SHA-256 雜湊的檔案只儲存一次，節省儲存空間和頻寬。

後續步驟

• 📖 檢視 REST API 文件 了解更多端點
• 🔒 閱讀 安全策略 了解資料保護詳情
• 💰 造訪 定價頁面 比較方案
• 🎨 查看 支援的格式 了解檔案相容性

需要幫助？ 聯絡我們：[email protected]