xcrawl-mcp 1.0.4 → 1.0.5

package/README.md

@@ -5,9 +5,9 @@ Model Context Protocol (MCP) server for XCrawl. It exposes scraping, search, map
 ## Table of Contents
 
 - [Prerequisites](#prerequisites)
+- [Remote Hosted URL](#remote-hosted-url)
 - [Quick Start (Stdio)](#quick-start-stdio)
 - [Claude Desktop Configuration](#claude-desktop-configuration)
-- [Cloudflare Workers Deployment](#cloudflare-workers-deployment)
 - [Authentication](#authentication)
 - [Available Tools](#available-tools)
 - [Request Defaults](#request-defaults)
@@ -20,21 +20,42 @@ Model Context Protocol (MCP) server for XCrawl. It exposes scraping, search, map
 
 - Node.js 18+
 - XCrawl API key from [xcrawl.com](https://xcrawl.com)
-- Cloudflare account (only for Workers deployment)
+
+## Remote Hosted URL
+
+Use the hosted MCP endpoint:
+
+```text
+https://mcp.xcrawl.com/{XCRAWL_API_KEY}/mcp
+```
+
+You can pass the API key in the URL path:
+
+```text
+https://mcp.xcrawl.com/{XCRAWL_API_KEY}/mcp
+```
+
+Or via headers. Supported methods:
+
+```text
+Authorization: Bearer {XCRAWL_API_KEY}
+x-api-key: {XCRAWL_API_KEY}
+x-xcrawl-api-key: {XCRAWL_API_KEY}
+```
 
 ## Quick Start (Stdio)
 
 Run directly with `npx`:
 
 ```bash
-XCRAWL_API_KEY=your-api-key npx -y xcrawl-mcp
+XCRAWL_API_KEY=YOUR_API_KEY npx -y xcrawl-mcp
 ```
 
 Or install globally:
 
 ```bash
 npm install -g xcrawl-mcp
-XCRAWL_API_KEY=your-api-key xcrawl-mcp
+XCRAWL_API_KEY=YOUR_API_KEY xcrawl-mcp
 ```
 
 ## Claude Desktop Configuration
@@ -43,6 +64,20 @@ Add to Claude Desktop config:
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
+Use the hosted MCP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "xcrawl": {
+      "url": "https://mcp.xcrawl.com/{XCRAWL_API_KEY}/mcp"
+    }
+  }
+}
+```
+
+Or run locally:
+
 ```json
 {
   "mcpServers": {
@@ -50,26 +85,13 @@ Add to Claude Desktop config:
       "command": "npx",
       "args": ["-y", "xcrawl-mcp"],
       "env": {
-        "XCRAWL_API_KEY": "your-api-key"
+        "XCRAWL_API_KEY": "YOUR_API_KEY"
       }
     }
   }
 }
 ```
 
-## Cloudflare Workers Deployment
-
-```bash
-git clone <your-repo>
-cd xcrawl-mcp
-npm install
-npm run deploy
-```
-
-After deployment:
-- `https://xcrawl-mcp.<your-account>.workers.dev/mcp`
-- `https://xcrawl-mcp.<your-account>.workers.dev/health`
-
 ## Authentication
 
 ### Stdio mode
@@ -77,12 +99,13 @@ After deployment:
 Use environment variable:
 - `XCRAWL_API_KEY` (required)
 
-### Workers mode
+### Hosted / Workers mode
 
-Pass API key in request headers (priority order):
-1. `Authorization: Bearer <api-key>`
-2. `x-api-key: <api-key>`
-3. `x-xcrawl-api-key: <api-key>`
+Pass API key using one of these methods:
+1. URL path: `https://mcp.xcrawl.com/{XCRAWL_API_KEY}/mcp`
+2. `Authorization: Bearer {XCRAWL_API_KEY}`
+3. `x-api-key: {XCRAWL_API_KEY}`
+4. `x-xcrawl-api-key: {XCRAWL_API_KEY}`
 
 ## Available Tools
 
@@ -94,6 +117,7 @@ Pass API key in request headers (priority order):
 | `xcrawl_map` | Discover URLs from a site |
 | `xcrawl_crawl` | Async multi-page crawl |
 | `xcrawl_check_crawl_status` | Check async crawl status |
+| `xcrawl_key_status` | Check whether the current API key is valid and has remaining credits |
 
 ### `xcrawl_scrape`
 
@@ -186,6 +210,28 @@ Possible values: `pending`, `crawling`, `completed`, `failed`.
 
 Possible values: `pending`, `crawling`, `completed`, `failed`.
 
+### `xcrawl_key_status`
+
+```json
+{}
+```
+
+Returns key validity and current credit status, including:
+
+- `status`
+- `valid`
+- `authorized`
+- `has_credits`
+- `is_expired`
+- `can_use_tools`
+- `remain_credits`
+- `consumed_credits`
+- `today_credits`
+- `total_credits`
+- `package_title`
+- `next_reset_at`
+- `expired_at`
+
 ## Request Defaults
 
 Common defaults:
@@ -208,6 +254,23 @@ Defaults may vary by API version.
 | `output.json.json_schema` | - | Optional |
 | `webhook.events` | `["started","completed","failed"]` | Optional callback events |
 
+## Preflight Checks
+
+Before executing high-cost tools, the MCP server now performs a key and credits preflight check.
+
+Current tools with preflight checks:
+
+- `xcrawl_scrape`
+- `xcrawl_search`
+- `xcrawl_map`
+- `xcrawl_crawl`
+
+The preflight check verifies:
+
+- the current API key is valid
+- the current API key is authorized
+- the account still has remaining credits
+
 ## Error Format
 
 Errors are returned in MCP format:
@@ -229,7 +292,7 @@ Errors are returned in MCP format:
 ```bash
 npm install
 npm run build
-XCRAWL_API_KEY=your-key npm run start:stdio:dev
+XCRAWL_API_KEY=YOUR_API_KEY npm run start:stdio:dev
 
 npm run dev
 curl http://localhost:8787/health

package/XCRAWL_MCP_/344/270/255/346/226/207/346/226/207/346/241/243.md

@@ -0,0 +1,393 @@
+# XCrawl MCP Server
+
+> 通过 Model Context Protocol 使用 XCrawl API
+
+XCrawl MCP Server 让您可以在支持 MCP 的客户端中直接调用 XCrawl 的网页抓取、搜索、发现与批量爬取能力。
+
+## 功能特性
+
+- 网页抓取与爬取
+- 搜索与发现
+- 结构化提取
+- 状态与额度检查
+- 流式 HTTP
+- 本地命令运行
+
+## 安装
+
+您可以使用我们的云端托管 URL，或在本地运行服务器。XCrawl API Key 可从 `https://dash.xcrawl.com/api-key` 获取。
+
+### 云端托管 URL
+
+```text
+https://mcp.xcrawl.com/{XCRAWL_API_KEY}/mcp
+```
+
+### 使用 npx 运行
+
+```bash
+XCRAWL_API_KEY=YOUR_API_KEY npx -y xcrawl-mcp
+```
+
+### 手动安装
+
+```bash
+npm install -g xcrawl-mcp
+```
+
+### 在 Cursor 中使用
+
+如需查看最新的配置方式，也可以参考 Cursor 官方文档：
+[Cursor MCP Server Configuration Guide](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers)
+
+在 Cursor **v0.48.6** 中：
+
+1. 打开 Cursor 设置。
+2. 进入 `Features > MCP Servers`。
+3. 点击 `+ Add new global MCP server`。
+4. 加入以下配置：
+
+```json
+{
+  "mcpServers": {
+    "xcrawl": {
+      "url": "https://mcp.xcrawl.com/{XCRAWL_API_KEY}/mcp"
+    }
+  }
+}
+```
+
+如果当前版本或环境不支持 HTTP 方式，可使用本地 `npx`：
+
+```json
+{
+  "mcpServers": {
+    "xcrawl": {
+      "command": "npx",
+      "args": ["-y", "xcrawl-mcp"],
+      "env": {
+        "XCRAWL_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+在 Cursor **v0.45.6** 中：
+
+1. 打开 Cursor 设置。
+2. 进入 `Features > MCP Servers`。
+3. 点击 `+ Add New MCP Server`。
+4. 填入以下内容：
+
+- Name: `xcrawl`
+- Type: `command`
+- Command: `env XCRAWL_API_KEY=YOUR_API_KEY npx -y xcrawl-mcp`
+
+如果您在 Windows 上遇到问题，也可以尝试：
+
+```text
+cmd /c "set XCRAWL_API_KEY=YOUR_API_KEY && npx -y xcrawl-mcp"
+```
+
+添加完成后，刷新 MCP Server 列表即可看到 XCrawl 工具。
+
+### 在 VS Code 中使用
+
+在 VS Code 中按 `Ctrl + Shift + P`，输入并打开 `Preferences: Open User Settings (JSON)`，然后加入以下配置：
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "xcrawl": {
+        "url": "https://mcp.xcrawl.com/{XCRAWL_API_KEY}/mcp"
+      }
+    }
+  }
+}
+```
+
+如果希望在当前工作区共享配置，也可以写入 `.vscode/mcp.json` 或客户端要求的 MCP 配置文件。
+
+如果当前 VS Code MCP 环境不支持 HTTP 方式，可使用本地 `npx`：
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "xcrawl": {
+        "command": "npx",
+        "args": ["-y", "xcrawl-mcp"],
+        "env": {
+          "XCRAWL_API_KEY": "YOUR_API_KEY"
+        }
+      }
+    }
+  }
+}
+```
+
+保存后，刷新 MCP 服务列表或重启 VS Code。
+
+**注意：** 部分用户反馈，在 VS Code 中直接添加 MCP Server 时，可能会因为 JSON schema 校验问题而加载失败。这一问题会影响多个 MCP 工具，XCrawl 也可能受到影响。
+
+**临时解决方案：** 可以先关闭 VS Code 的 JSON 验证，再尝试加载 MCP Server。
+
+参考链接：
+- [microsoft/vscode#155379](https://github.com/microsoft/vscode/issues/155379)
+- [directus/directus#25906 (comment)](https://github.com/directus/directus/issues/25906#issuecomment-3369169513)
+
+XCrawl MCP Server 本身仍可正常工作；这一问题主要发生在通过 VS Code 的 MCP Server 列表直接添加时。后续如果 VS Code 更新了相关 schema 校验，我们会补充更明确的说明。
+
+### 在 Claude Desktop 中使用
+
+打开 Claude Desktop 配置文件：
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+加入以下配置：
+
+```json
+{
+  "mcpServers": {
+    "xcrawl": {
+      "url": "https://mcp.xcrawl.com/{XCRAWL_API_KEY}/mcp"
+    }
+  }
+}
+```
+
+如果您收到“无法连接到 MCP 服务器”之类的错误，可能是当前 Claude Desktop 版本不支持 HTTP 方式。可以改用本地 `npx` 方式，这需要先安装 [**Node.js**](https://nodejs.org/)。
+
+```json
+{
+  "mcpServers": {
+    "xcrawl": {
+      "command": "npx",
+      "args": ["-y", "xcrawl-mcp"],
+      "env": {
+        "XCRAWL_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+如果出现 `spawn npx ENOENT` 错误，通常表示 Node.js 尚未安装，或未加入系统 PATH。请从 [nodejs.org](https://nodejs.org) 安装 Node.js（LTS 版本），然后完全重启 Claude Desktop。在 Windows 上，也可以在命令提示符中运行 `where npx`，并将返回的完整路径，例如 `C:\\Program Files\\nodejs\\npx.cmd`，填入 `command`。
+
+### 在 Claude Code 中使用
+
+在终端中运行：
+
+```bash
+claude mcp add xcrawl --url https://mcp.xcrawl.com/{XCRAWL_API_KEY}/mcp
+```
+
+如果当前环境不支持 HTTP 方式，可使用本地命令方式：
+
+```bash
+claude mcp add xcrawl -e XCRAWL_API_KEY=YOUR_API_KEY -- npx -y xcrawl-mcp
+```
+
+### 在 Windsurf 中使用
+
+打开 Windsurf 设置，进入 `Tools > Configure > View raw config`，然后加入以下配置：
+
+```json
+{
+  "mcpServers": {
+    "xcrawl": {
+      "serverUrl": "https://mcp.xcrawl.com/{XCRAWL_API_KEY}/mcp"
+    }
+  }
+}
+```
+
+如果当前环境不支持 HTTP 方式，可使用本地 `npx`：
+
+```json
+{
+  "mcpServers": {
+    "xcrawl": {
+      "command": "npx",
+      "args": ["-y", "xcrawl-mcp"],
+      "env": {
+        "XCRAWL_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### 在 Google Antigravity 中使用
+
+Google Antigravity 支持在 Agent 界面中直接配置 MCP Server。
+
+1. 打开编辑器中的 Agent 侧边栏，或进入 Agent Manager。
+2. 点击 `...`，选择 `MCP Servers`。
+3. 选择 `View raw config`，打开本地 `mcp_config.json`。
+4. 加入以下配置：
+
+```json
+{
+  "mcpServers": {
+    "xcrawl": {
+      "command": "npx",
+      "args": ["-y", "xcrawl-mcp"],
+      "env": {
+        "XCRAWL_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+5. 保存后，在 Antigravity 的 MCP 界面点击 `Refresh`，即可看到 XCrawl 工具。
+
+## 可用工具
+
+### 1. 抓取工具 `xcrawl_scrape`
+
+抓取单个网页内容，支持多种输出格式。
+详细参数请参考：<https://docs.xcrawl.com/doc/features/scrape/>
+
+```json
+{
+  "name": "xcrawl_scrape",
+  "arguments": {
+    "url": "https://example.com",
+    "output": {
+      "formats": ["markdown", "screenshot"]
+    }
+  }
+}
+```
+
+### 2. 搜索工具 `xcrawl_search`
+
+用于根据关键词、地区、语言等参数获取搜索结果，并支持高级 Google SERP 参数。
+详情请参考：<https://docs.xcrawl.com/doc/features/search/>
+
+```json
+{
+  "name": "xcrawl_search",
+  "arguments": {
+    "query": "latest AI news",
+    "location": "New York",
+    "language": "en",
+    "limit": 10,
+    "serp_options": {
+      "tbs": "qdr:w",
+      "safe": 1
+    }
+  }
+}
+```
+
+### 3. 发现工具 `xcrawl_map`
+
+用于快速获取站点内的 URL 列表。
+详情请参考：<https://docs.xcrawl.com/doc/features/map/>
+
+```json
+{
+  "name": "xcrawl_map",
+  "arguments": {
+    "url": "https://example.com",
+    "filter": "blog/.*",
+    "limit": 1000,
+    "include_subdomains": true,
+    "ignore_query_parameters": true
+  }
+}
+```
+
+### 4. 批量爬取工具 `xcrawl_crawl`
+
+用于按规则批量抓取站点页面。XCrawl 会根据指定的 URL 在站内发现所有链接并依次抓取。
+详情请参考：<https://docs.xcrawl.com/doc/features/crawl/>
+
+```json
+{
+  "name": "xcrawl_crawl",
+  "arguments": {
+    "url": "https://example.com",
+    "output": {
+      "formats": ["markdown"]
+    }
+  }
+}
+```
+
+### 5. 状态检查工具 `xcrawl_key_status`
+
+检查当前运行时 API Key 是否有效、是否已授权、是否还有可用积分，以及当前是否允许继续调用工具。
+
+```json
+{
+  "name": "xcrawl_key_status",
+  "arguments": {}
+}
+```
+
+### 6. 检查抓取状态 `xcrawl_check_status`
+
+查询异步抓取任务状态。
+
+```json
+{
+  "name": "xcrawl_check_status",
+  "arguments": {
+    "scrape_id": "abc-123-def-456"
+  }
+}
+```
+
+### 7. 检查批量爬取状态 `xcrawl_check_crawl_status`
+
+查询异步批量爬取任务状态。
+
+```json
+{
+  "name": "xcrawl_check_crawl_status",
+  "arguments": {
+    "crawl_id": "xyz-789-abc-012"
+  }
+}
+```
+
+## 错误处理
+
+错误按 MCP 工具格式返回，例如：
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "Error: XCrawl API error: 401 Unauthorized - Invalid API key"
+    }
+  ],
+  "isError": true
+}
+```
+
+## 健康检查
+
+可通过以下地址做健康检查：
+
+```bash
+curl https://mcp.xcrawl.com/health
+```
+
+成功时返回：
+
+```text
+OK
+```
+
+## 许可证
+
+MIT

package/dist/core/status.d.ts

@@ -0,0 +1,6 @@
+import type { XCrawlKeyStatusResponse } from "../types.js";
+export declare function fetchXCrawlKeyStatus(apiKey: string): Promise<XCrawlKeyStatusResponse>;
+export declare function formatKeyStatusResponse(response: XCrawlKeyStatusResponse): string;
+export declare function requiresCreditPreflight(toolName: string): boolean;
+export declare function assertXCrawlToolPreflight(apiKey: string, toolName: string): Promise<void>;
+//# sourceMappingURL=status.d.ts.map

package/dist/core/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/core/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAA6C,MAAM,aAAa,CAAC;AAiFtG,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAsD3F;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,CAEjF;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,wBAAsB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/F"}