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