MCP

🚀 Supadata MCP 服務器

Supadata MCP 服務器是一個模型上下文協議（MCP）實現，它與 Supadata 集成，具備視頻和網頁抓取功能，能有效解決從視頻和網頁中提取信息的問題，為用戶提供便捷的內容獲取途徑。

✨ 主要特性

• 視頻文本提取：支持從 YouTube、TikTok、Twitter 以及文件 URL 中提取視頻文本。
• 網頁抓取、爬取與發現：可對網頁進行抓取、爬取，並發現新的 URL。
• 自動重試與速率限制：具備自動重試機制和速率限制功能，保障服務的穩定性。

你可以在 Smithery 或 MCP.so 的 playground 上體驗我們的 MCP 服務器。

📦 安裝指南

使用 npx 運行

env SUPADATA_API_KEY=your-api-key npx -y supadata-mcp

手動安裝

npm install -g supadata-mcp

在 Cursor 上運行

配置 Cursor 🖥️

注意：需要 Cursor 版本 0.45.6 及以上。 有關最新的配置說明，請參考 Cursor 官方關於配置 MCP 服務器的文檔：Cursor MCP 服務器配置指南。

在 Cursor v0.48.6 中配置 Supadata MCP

1. 打開 Cursor 設置。
2. 轉到“功能”>“MCP 服務器”。
3. 點擊“+ 添加新的全局 MCP 服務器”。
4. 輸入以下代碼：

{
  "mcpServers": {
    "supadata-mcp": {
      "command": "npx",
      "args": ["-y", "supadata-mcp"],
      "env": {
        "SUPADATA_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}

在 Cursor v0.45.6 中配置 Supadata MCP

1. 打開 Cursor 設置。
2. 轉到“功能”>“MCP 服務器”。
3. 點擊“+ 添加新的 MCP 服務器”。
4. 輸入以下信息：
   • 名稱：“supadata-mcp”（或你喜歡的名稱）
   • 類型：“命令”
   • 命令：env SUPADATA_API_KEY=your-api-key npx -y supadata-mcp

如果你使用的是 Windows 系統且遇到問題，可以嘗試 cmd /c "set SUPADATA_API_KEY=your-api-key && npx -y supadata-mcp"。

將 your-api-key 替換為你的 Supadata API 密鑰。如果你還沒有，可以在 https://www.supadata.dev/app/api-keys 創建賬戶並獲取。

添加後，刷新 MCP 服務器列表以查看新工具。Composer 代理會在合適的時候自動使用 Supadata MCP，但你也可以通過描述網頁抓取需求來明確請求使用。通過 Command + L（Mac）訪問 Composer，在提交按鈕旁邊選擇“代理”，然後輸入你的查詢。

在 Windsurf 上運行

將以下內容添加到你的 ./codeium/windsurf/model_config.json 文件中：

{
  "mcpServers": {
    "supadata-mcp": {
      "command": "npx",
      "args": ["-y", "supadata-mcp"],
      "env": {
        "SUPADATA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

通過 Smithery 安裝

要通過 Smithery 為 Claude Desktop 自動安裝 Supadata，請運行以下命令：

npx -y @smithery/cli install @supadata-ai/mcp --client claude

在 VS Code 上運行

一鍵安裝

點擊以下安裝按鈕之一：

手動安裝

將以下 JSON 塊添加到 VS Code 的用戶設置（JSON）文件中。你可以通過按下 Ctrl + Shift + P 並輸入 Preferences: Open User Settings (JSON) 來打開該文件。

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Supadata API Key",
        "password": true
      }
    ],
    "servers": {
      "supadata": {
        "command": "npx",
        "args": ["-y", "supadata-mcp"],
        "env": {
          "SUPADATA_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

你也可以選擇將其添加到工作區中名為 .vscode/mcp.json 的文件中，這樣可以與他人共享配置：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Supadata API Key",
      "password": true
    }
  ],
  "servers": {
    "supadata": {
      "command": "npx",
      "args": ["-y", "supadata-mcp"],
      "env": {
        "SUPADATA_API_KEY": "${input:apiKey}"
      }
    }
  }
}

📚 詳細文檔

環境變量

• SUPADATA_API_KEY：你的 Supadata API 密鑰

與 Claude Desktop 配合使用

將以下內容添加到你的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "supadata-mcp": {
      "command": "npx",
      "args": ["-y", "supadata-mcp"],
      "env": {
        "SUPADATA_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

系統配置

服務器包含多個可通過環境變量設置的配置參數。如果未進行配置，以下是默認值：

const CONFIG = {
  retry: {
    maxAttempts: 3, // 速率限制請求的重試次數
    initialDelay: 1000, // 首次重試前的初始延遲（毫秒）
    maxDelay: 10000, // 重試之間的最大延遲（毫秒）
    backoffFactor: 2, // 指數退避的乘數
  },
};

速率限制和批量處理

服務器利用 Supadata 內置的速率限制和批量處理功能：

• 自動處理速率限制，採用指數退避策略
• 高效並行處理批量操作
• 智能請求排隊和節流
• 對臨時錯誤進行自動重試

🔧 技術細節

如何選擇工具

使用以下指南為你的任務選擇合適的工具：

• 如果你需要視頻內容的文本記錄：使用 transcript
• 如果你知道確切的 URL：
  • 單個 URL：使用 scrape
  • 多個 URL：使用 batch_scrape
• 如果你需要發現網站上的 URL：使用 map
• 如果你想分析整個網站或部分內容：使用 crawl（有限制！）

快速參考表

可用工具

1. 文本提取工具 (supadata_transcript)

從支持的視頻平臺和文件 URL 中提取文本記錄。

• 適用場景：分析視頻內容並從 YouTube、TikTok、Twitter 和文件 URL 中提取文本記錄。
• 不推薦場景：非視頻內容（網頁使用 scrape 工具）
• 常見錯誤：對普通網頁使用 transcript 工具（應使用 scrape 工具）
• 提示示例：

"從這個 YouTube 視頻獲取文本記錄：https://youtube.com/watch?v=example"

• 使用示例：

{
  "name": "supadata_transcript",
  "arguments": {
    "url": "https://youtube.com/watch?v=example",
    "lang": "en",
    "text": false,
    "mode": "auto"
  }
}

• 返回結果：
  • 文本或格式化輸出的文本記錄內容
  • 異步處理：用於檢查狀態的作業 ID

2. 檢查文本提取狀態 (supadata_check_transcript_status)

檢查文本提取作業的狀態。

{
  "name": "supadata_check_transcript_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

• 返回結果：包含文本提取作業狀態、完成進度和結果的響應。

3. 抓取工具 (supadata_scrape)

使用高級選項從單個 URL 抓取內容。

• 適用場景：當你確切知道包含信息的頁面時，提取單頁內容。
• 不推薦場景：從多個頁面提取內容（已知 URL 使用 batch_scrape，先發現 URL 使用 map + batch_scrape，全面提取使用 crawl）
• 常見錯誤：對 URL 列表使用 scrape 工具（應使用 batch_scrape 工具）
• 提示示例：

"獲取 https://example.com 頁面的內容。"

• 使用示例：

{
  "name": "supadata_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["markdown"],
    "onlyMainContent": true,
    "waitFor": 1000,
    "timeout": 30000,
    "mobile": false,
    "includeTags": ["article", "main"],
    "excludeTags": ["nav", "footer"],
    "skipTlsVerification": false
  }
}

• 返回結果：指定格式的 Markdown、HTML 或其他內容。

4. 映射工具 (supadata_map)

映射網站以發現網站上所有索引的 URL。

• 適用場景：在決定抓取內容之前發現網站上的 URL，查找網站的特定部分。
• 不推薦場景：當你已經知道確切的 URL 時（使用 scrape 或 batch_scrape），當你需要頁面內容時（映射後使用 scrape）
• 常見錯誤：使用 crawl 發現 URL 而不是 map
• 提示示例：

"列出 example.com 上的所有 URL。"

• 使用示例：

{
  "name": "supadata_map",
  "arguments": {
    "url": "https://example.com"
  }
}

• 返回結果：網站上發現的 URL 數組。

5. 爬取工具 (supadata_crawl)

在網站上啟動異步爬取作業並從所有頁面提取內容。

• 適用場景：當你需要全面覆蓋時，從多個相關頁面提取內容。
• 不推薦場景：從單個頁面提取內容（使用 scrape），當存在令牌限制時（使用 map + batch_scrape），當你需要快速結果時（爬取可能較慢）
• 警告：爬取響應可能非常大，可能會超過令牌限制。限制爬取深度和頁面數量，或使用 map + batch_scrape 以獲得更好的控制。
• 常見錯誤：設置 limit 或 maxDepth 過高（導致令牌溢出），對單個頁面使用 crawl（應使用 scrape）
• 提示示例：

"從 example.com/blog 的前兩層獲取所有博客文章。"

• 使用示例：

{
  "name": "supadata_crawl",
  "arguments": {
    "url": "https://example.com/blog/*",
    "maxDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}

• 返回結果：包含用於檢查狀態的操作 ID 的響應：

{
  "content": [
    {
      "type": "text",
      "text": "Started crawl for: https://example.com/* with job ID: 550e8400-e29b-41d4-a716-446655440000. Use supadata_check_crawl_status to check progress."
    }
  ],
  "isError": false
}

6. 檢查爬取狀態 (supadata_check_crawl_status)

檢查爬取作業的狀態。

{
  "name": "supadata_check_crawl_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

• 返回結果：包含爬取作業狀態、完成進度和結果詳細信息的響應。

日誌系統

服務器包含全面的日誌記錄：

• 操作狀態和進度
• 性能指標
• 信用使用監控
• 速率限制跟蹤
• 錯誤情況

示例日誌消息：

[INFO] Supadata MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[INFO] Batch operation queued with ID: batch_1
[WARNING] Credit usage has reached warning threshold
[ERROR] Rate limit exceeded, retrying in 2s...

錯誤處理

服務器提供強大的錯誤處理功能：

• 對臨時錯誤進行自動重試
• 採用退避策略處理速率限制
• 詳細的錯誤消息
• 信用使用警告
• 網絡彈性

示例錯誤響應：

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
    }
  ],
  "isError": true
}

開發

# 安裝依賴
npm install

# 構建
npm run build

# 運行測試
npm test

貢獻代碼

1. 分叉倉庫
2. 創建你的功能分支
3. 運行測試：npm test
4. 提交拉取請求

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。