Watercrawl MCP

🚀 WaterCrawl MCP

WaterCrawl MCP 是一個為 WaterCrawl 構建的模型上下文協議（MCP）服務器，它基於 FastMCP 開發。該軟件包通過標準化接口為 AI 系統提供網頁爬取、數據抓取和搜索功能。

🚀 快速開始

使用 npx 快速啟動（無需安裝）

可以使用 npx 直接運行 WaterCrawl MCP，無需進行安裝：

npx @watercrawl/mcp --api-key YOUR_API_KEY

與 AI 助手配合使用

Codeium/Windsurf

無需安裝該軟件包，即可將其配置到 Codeium 或 Windsurf 中：

{
  "mcpServers": {
    "watercrawl": {
      "command": "npx",
      "args": [
        "@watercrawl/mcp",
        "--api-key",
        "YOUR_API_KEY",
        "--base-url",
        "https://app.watercrawl.dev"
      ]
    }
  }
}

Claude Desktop

以 SSE 模式運行 WaterCrawl MCP：

npx @watercrawl/mcp sse --port 3000 --endpoint /sse --api-key YOUR_API_KEY

然後將 Claude Desktop 配置為連接到你的 SSE 服務器。

命令行選項

• -b, --base-url <url>：WaterCrawl API 的基礎 URL（默認值：https://app.watercrawl.dev）
• -k, --api-key <key>：必需參數，你的 WaterCrawl API 密鑰
• -h, --help：顯示幫助信息
• -V, --version：顯示版本信息

SSE 模式的額外選項：

• -p, --port <number>：SSE 服務器的端口號（默認值：3000）
• -e, --endpoint <path>：SSE 端點路徑（默認值：/sse）

🛠️ 開發與貢獻

項目結構

wc-mcp/
├── src/                   # 源代碼
│   ├── cli/               # 命令行界面
│   ├── config/            # 配置管理
│   ├── mcp/               # MCP 實現
│   ├── services/          # WaterCrawl API 服務
│   └── tools/             # MCP 工具實現
├── tests/                 # 測試套件
├── dist/                  # 編譯後的 JavaScript
├── tsconfig.json          # TypeScript 配置
├── package.json           # npm 包配置
└── README.md              # 本文件

開發環境設置

1. 克隆倉庫並安裝依賴：

git clone https://github.com/watercrawl/watercrawl-mcp
cd watercrawl-mcp
npm install

2. 構建項目：

npm run build

3. 為本地開發鏈接該軟件包：

npm link @watercrawl/mcp

貢獻指南

1. 分叉倉庫
2. 創建功能分支（git checkout -b feature/your-feature）
3. 提交更改（git commit -m 'Add your feature'）
4. 推送到分支（git push origin feature/your-feature）
5. 打開拉取請求

📦 安裝（npx 的替代方案）

全局安裝

npm install -g @watercrawl/mcp

本地安裝

npm install @watercrawl/mcp

⚙️ 配置

可以使用環境變量或命令行參數來配置 WaterCrawl MCP。

環境變量

創建一個 .env 文件或設置環境變量：

WATERCRAWL_BASE_URL=https://app.watercrawl.dev
WATERCRAWL_API_KEY=YOUR_API_KEY
SSE_PORT=3000                  # 可選，用於 SSE 模式
SSE_ENDPOINT=/sse              # 可選，用於 SSE 模式

💻 使用示例

1. scrape-url

從 URL 抓取內容，並可進行自定義配置：

{
  "url": "https://example.com",
  "pageOptions": {
    "exclude_tags": ["script", "style"],
    "include_tags": ["p", "h1", "h2"],
    "wait_time": 1000,
    "only_main_content": true,
    "include_html": false,
    "include_links": true,
    "timeout": 15000,
    "accept_cookies_selector": ".cookies-accept-button",
    "locale": "en-US",
    "extra_headers": {
      "User-Agent": "Custom User Agent"
    },
    "actions": [
      {"type": "screenshot"},
      {"type": "pdf"}
    ]
  },
  "sync": true,
  "download": true
}

2. search

使用 WaterCrawl 進行網絡搜索：

{
  "query": "artificial intelligence latest developments",
  "searchOptions": {
    "language": "en",
    "country": "us",
    "time_range": "recent",
    "search_type": "web",
    "depth": "deep"
  },
  "resultLimit": 5,
  "sync": true,
  "download": true
}

3. download-sitemap

從爬取請求中以不同格式下載站點地圖：

{
  "crawlRequestId": "uuid-of-crawl-request",
  "format": "json" // 或 "graph" 或 "markdown"
}

4. manage-crawl

管理爬取請求：列出、獲取詳情、停止或下載結果：

{
  "action": "list", // 或 "get", "stop", "download"
  "crawlRequestId": "uuid-of-crawl-request", // 用於 get、stop 和 download 操作
  "page": 1,
  "pageSize": 10
}

5. manage-search

管理搜索請求：列出、獲取詳情或停止正在運行的搜索：

{
  "action": "list", // 或 "get", "stop"
  "searchRequestId": "uuid-of-search-request", // 用於 get 和 stop 操作
  "page": 1,
  "pageSize": 10,
  "download": true
}

6. monitor-request

即時監控爬取或搜索請求，並可控制超時時間：

{
  "type": "crawl", // 或 "search"
  "requestId": "uuid-of-request",
  "timeout": 30, // 單位：秒
  "download": true
}

📄 許可證

ISC