使用说明

🏆 Webcrawl MCP服务器-生产就绪实施🏆

███╗   ███╗ ██████╗██████╗     ██████╗ ███████╗███████╗
████╗ ████║██╔════╝██╔══██╗    ██╔══██╗██╔════╝██╔════╝
██╔████╔██║██║     ██████╔╝    ██████╔╝█████╗  █████╗  
██║╚██╔╝██║██║     ██╔═══╝     ██╔══██╗██╔══╝  ██╔══╝  
██║ ╚═╝ ██║╚██████╗██║         ██║  ██║███████╗██║     
╚═╝     ╚═╝ ╚═════╝╚═╝         ╚═╝  ╚═╝╚══════╝╚═╝     
     
   100% MCP COMPLIANT | ABORT CAPABLE ✅

A. 生产准备就绪 模型上下文协议（MCP）服务器，提供全面的网络爬行功能。具有智能内容提取、工具执行中止功能和完全符合MCP规范。

🎯 主要特点

✅ 100%符合MCP标准 -完全符合MCP规范v2024-11-05
🛑 中止功能 -优雅地取消长时间运行的操作
🧠 智能爬行 -具有相关性评分的智能内容提取
🔗 链接分析 -高级链接提取和分类
🗺️ 网站地图生成 -全面的网站结构映射
🔍 内容搜索 -页面内内容搜索和分析
🌐 网页搜索 -集成网络搜索功能
⏰ 实用工具 -日期/时间和通用功能

� 快速开始

使用Docker（推荐）

docker-compose up --build

地方发展

# Install dependencies
npm install
cd mcp-service && npm install

# Start development server
npm run dev

🛠️ 可用工具

工具	描述	主要功能
爬行	基本网络爬行	页面内容、元数据、链接
智能爬行	智能爬行	相关性评分、智能导航
extractLinks	链接提取	分类、过滤、分析
搜索	内容搜索	文本匹配、上下文提取
generate网站地图	网站地图创建	网站结构、层次结构映射
网络搜索	网络搜索	多引擎支持，结果过滤
getDateTime	日期/时间实用程序	时区支持，格式化

🛑 中止功能

所有工具都支持优雅取消：

# Start a tool execution
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"crawl","arguments":{"url":"https://example.com"}},"id":"tool-123"}'

# Abort the execution
curl -X POST http://localhost:3000/tools/abort/tool-123

📋 MCP协议支持

✅ 会话管理：使用完成会话生命周期 Mcp-Session-Id 标头
✅ 协议初始化：适当 initialize 和 notifications/initialized 握手
✅ 能力协商：完全支持协议版本协商
✅ 传输协议：现代可流式HTTP和SSE支持
✅ 标准方法: tools/list, tools/call, resources/list, resources/read
✅ 错误处理：正确执行所有JSON-RPC 2.0错误代码

🏗️ 建筑

mcp-service/
├── src/
│   ├── services/tools/         # Self-contained tool implementations
│   │   ├── BaseTool.ts         # Base class with abort functionality
│   │   ├── CrawlTool.ts        # Web crawling
│   │   ├── SmartCrawlTool.ts   # Intelligent crawling
│   │   ├── ExtractLinksTool.ts # Link extraction
│   │   ├── SearchInPageTool.ts # Page search
│   │   ├── SitemapTool.ts      # Sitemap generation
│   │   ├── WebSearchTool.ts    # Web search
│   │   └── DateTimeTool.ts     # Date/time utilities
│   ├── mcp/                    # MCP protocol implementation
│   ├── routes/                 # HTTP endpoints
│   ├── controllers/            # Request handlers
│   └── config/                 # Configuration management

🔧 配置

环境变量

# Copy template and configure
cp .env-template .env

# Key settings
PORT=3000                       # Server port
MCP_TRANSPORT=streamable-http   # Transport protocol
PUPPETEER_HEADLESS=true        # Browser mode
LOG_LEVEL=info                 # Logging level

开发vs生产

发展：放宽速率限制（1000个请求/分钟）
生产：使用更严格的限制保护默认值

🧪 测试

# Run MCP compliance tests
npm run test:mcp-compliance

# Run all tests
npm test

# Build project
npm run build


### Running Locally

1. Install dependencies:
   ```bash
   npm install

导航到mcp服务目录：
```
cd mcp-service
npm install
```
定义环境变量（请参见配置).

构建并启动服务器：

npm run build
npm start

# Or for development with auto-reload:
npm run dev
## 🌐 API Endpoints

端点	协议	描述
`POST /mcp`	MCP流式HTTP	推荐 -基于HTTP的现代JSON-RPC
`GET /mcp`	HTTP	服务器信息和连接详细信息
`POST /tools/abort/:toolId`	REST	中止工具执行
`GET /api/health`	REST	健康检查
`GET /api/version`	REST	版本信息

📝 使用示例

基本工具执行

# Execute crawl tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "crawl",
      "arguments": {
        "url": "https://example.com",
        "maxPages": 3
      }
    },
    "id": 1
  }'

带查询的智能爬行

# Execute smart crawl with relevance scoring
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "smartCrawl",
      "arguments": {
        "url": "https://example.com",
        "query": "pricing information",
        "maxPages": 5,
        "relevanceThreshold": 3
      }
    },
    "id": 2
  }'

中止工具执行

# Start tool execution
TOOL_ID=$(curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"generateSitemap","arguments":{"url":"https://large-site.com","maxPages":100}},"id":"sitemap-1"}' \
  | jq -r '.result.toolId')

# Abort if needed
curl -X POST http://localhost:3000/tools/abort/$TOOL_ID

📚 文档

文档	描述
MCP_API.md	完整的API参考和示例
工具_ABORT.md	刀具中止功能指南
概述.md	架构和设计概述
代码_结构.md	开发人员文档
贡献.md	贡献指南

🤝 贡献

我们欢迎捐款！请看贡献.md 作为指导方针。

📄 许可证

本项目遵循知识共享署名-非商业4.0国际许可协议（CC BY-NC 4.0）。这意味着您可以自由地：

分享 --以任何媒介或格式复制和重新分发材料
适应 --重新混合、转换和构建材料

根据以下条款：

归因 --你必须给予适当的信用
非商业用途 --您不得将该材料用于商业目的

请参阅许可证.md 文件以获取完整的许可证文本。

由以下材料制成❤️ 对于MCP社区 “name”：“smartCrawl”， “description”：“抓取网站并返回markdown格式的内容，可能会回答特定的查询。”， “parameterDescription”：“要爬网的URL、可选爬网参数和可选查询。”， “returnDescription”：“包含成功状态、原始URL、标记内容和可选错误消息的对象。”， “端点”：“/api/tools/smartCrawl” }, { “name”：“extractLinks”， “description”：“从网页中提取链接并对其进行分类。”， “parameterDescription”：“从中提取链接的URL。”， “returnDescription”：“包含内部和外部链接及其描述的对象。”， “endpoint”：“/api/tools/extractLinks” }, { “name”：“sitemapGenerator”， “description”：“通过抓取网站页面从网站生成站点地图。”， “parameterDescription”：“用于抓取站点地图生成的URL，可选深度和最大页面数。”， “returnDescription”：“包含生成的站点地图结构的对象。”， “端点”：“/api/tools/sitemapGenerator” }, { “name”：“searchInPage”， “description”：“在网页中搜索特定内容。”， “parameterDescription”：“要查找的URL和搜索词。”， “returnDescription”：“包含搜索结果和匹配项的对象。”， “端点”：“/api/tools/searchInPage” }, { “name”：“网络搜索”， “description”：“执行网络搜索并提取结果。”， “parameterDescription”：“搜索查询和最大结果数。”， “returnDescription”：“包含带有标题、描述和URL的搜索结果的对象。”， “端点”：“/api/tools/webSearch” }, { “name”：“dateTime”， “description”：“获取各种格式的当前日期和时间信息。”， “parameterDescription”：“可选时区参数。”， “returnDescription”：“包含多种格式的当前日期/时间的对象。”， “endpoint”：“/api/tools/dateTime” } ] }


### Direct Tool Execution

#### Crawl Tool
```bash
curl -X POST http://localhost:${PORT:-3000}/api/tools/crawl \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "maxPages": 3,
    "depth": 1,
    "strategy": "bfs",
    "captureScreenshots": true,
    "captureNetworkTraffic": false,
    "waitTime": 2000
  }'

智能抓取工具（Markdown输出）

curl -X POST http://localhost:${PORT:-3000}/api/tools/smartCrawl \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "query": "What is this site about?",
    "maxPages": 2,
    "depth": 1
  }'

提取链接工具

curl -X POST http://localhost:${PORT:-3000}/api/tools/extractLinks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'

网站地图生成器工具

curl -X POST http://localhost:${PORT:-3000}/api/tools/sitemapGenerator \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "maxPages": 10,
    "depth": 2
  }'

页面搜索工具

curl -X POST http://localhost:${PORT:-3000}/api/tools/searchInPage \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "searchTerm": "contact information"
  }'

网络搜索工具

curl -X POST http://localhost:${PORT:-3000}/api/tools/webSearch \
  -H "Content-Type: application/json" \
  -d '{
    "query": "MCP protocol specification",
    "maxResults": 5
  }'

日期时间工具

curl -X POST http://localhost:${PORT:-3000}/api/tools/dateTime \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "UTC"
  }'

环境变量

PORT （默认值：3000）：MCP服务器的端口。
NODE_ENV （默认：开发）：环境模式（开发或生产）。
MCP_NAME, MCP_VERSION, MCP_DESCRIPTION：MCP服务器标识。
CRAWL_DEFAULT_MAX_PAGES （默认值：10）：默认抓取的最大页面数。
CRAWL_DEFAULT_DEPTH （默认值：3）：默认爬网深度。
CRAWL_DEFAULT_STRATEGY （默认值：bfs）：默认爬网策略（bfs|dfs|bestFirst）。
CRAWL_DEFAULT_WAIT_TIME （默认值：1000）：请求之间的默认等待时间（毫秒）。
LOG_LEVEL （默认值：info）：日志记录级别（debug | info | warn | error）。
CACHE_TTL （默认值：3600）：缓存TTL（秒）。
MAX_REQUEST_SIZE （默认值：10mb）：最大HTTP有效负载大小。
CORS_ORIGINS （默认值：*）：允许CORS的来源。
RATE_LIMIT_WINDOW （默认值：900000）：速率限制窗口，单位为毫秒（15分钟）。
RATE_LIMIT_MAX_REQUESTS （默认值：100）：每个速率限制窗口的最大请求数。
PUPPETEER_EXECUTABLE_PATH （可选）：Puppeteer的Chrome/Chromium可执行文件的自定义路径。
PUPPETEER_SKIP_DOWNLOAD （默认值：false）：在安装过程中跳过Chromium的自动下载。

配置

所有配置都集中在 src/config 目录，其中包含用于系统不同方面的单独模块：

appConfig.ts：核心应用程序设置
mcpConfig.ts：MCP服务器特定设置
securityConfig.ts：安全相关设置
crawlConfig.ts：Web爬网默认参数

关键组件

服务器：整合Express和MCP功能的统一服务器实施。
路线：在API和MCP端点的单独文件中组织。
SimpleMcpServer：实现MCP发现和工具调用逻辑。
控制器: toolController 和 resourceController 用于处理业务逻辑。
工具：扩展BaseTool抽象类的自包含工具实现：
- 爬行工具：具有内容提取功能的基本网络爬行
- SmartCrawlTool：具有markdown输出和查询支持的智能爬行
- 提取链接工具：从网页中提取链接并对其进行分类
- 网站地图工具：从抓取的内容生成站点地图
- 搜索输入工具：在网页中搜索特定内容
- 网络搜索工具：具有结果提取的Web搜索功能
- DateTimeTool：日期和时间实用程序函数
配置：具有模块特定设置的集中配置系统。
MCP传输：支持现代流式HTTP和传统SSE传输方法。
工具架构：每个工具都包括自己的浏览器管理、爬行逻辑和错误处理，以实现完全的自我控制。

Web爬行功能

MCP服务器包括一套全面的自包含爬行工具，每个工具都具有集成的浏览器管理和专门的功能：

基于工具的体系结构

独立设计：每个工具都管理自己的Puppeteer浏览器实例和爬行逻辑
BaseTool抽象类：所有工具共享的通用功能，具有标准化的错误处理
独立经营：工具在没有共享服务依赖的情况下运行，以提高可靠性

可用工具

爬行工具

基本Web爬行：从网页中提取文本内容和表格
多种策略：BFS、DFS和最佳优先爬行方法
电脑屏幕截图工具：可选的全屏截图功能
内容提取：智能可见文本提取跳过隐藏元素

SmartCrawlTool

Markdown输出：使用自定义格式规则进行HTML到Markdown的转换
基于查询的爬行：基于特定查询的重点内容提取
智能内容检测：增强不同内容类型的相关性评分
结构化输出：格式良好的标记，带有适当的标题和章节

提取链接工具

链接分类：分离内部和外部链接提取
链接分析：提取链接文本、URL和描述
全面覆盖：查找页面内容中的所有可点击链接

网站地图工具

网站地图生成：从抓取的内容创建结构化站点地图
层次结构：按深度和关系组织页面
可配置深度：控制站点地图生成的爬行深度

搜索输入工具

内容搜索：在网页中查找特定术语或短语
上下文提取：为搜索匹配提供周围环境
相关性评分：按相关性对搜索结果进行排名

网络搜索工具

Web搜索集成：执行网络搜索并提取结果
结果处理：从搜索结果中提取标题、描述和URL
可配置的结果：控制返回的结果数量

DateTimeTool

时间实用程序：多种格式的当前日期/时间
时区支持：转换不同时区的时间
格式选项：各种日期/时间格式输出

共享浏览器管理功能

稳健的错误处理：通过适当的错误处理和回退机制改进了浏览器初始化
自定义Chrome路径：通过以下方式支持自定义Chrome/Chromium可执行路径 PUPPETEER_EXECUTABLE_PATH
资源管理：每个工具中的自动浏览器清理和连接管理
独立实例：每个工具都管理自己的浏览器实例，以实现更好的隔离

内容提取（跨工具）

文本提取：智能可见文本提取，跳过隐藏元素和脚本
Markdown转换：HTML到Markdown的转换，带有表和代码块的自定义规则
表格提取：支持字幕的HTML表格的结构化提取
电脑屏幕截图工具：可选的全屏截图功能
链接处理：提取并分类内部链接和外部链接

爬行策略

广度优先搜索（BFS）：系统探索的默认策略
深度优先搜索（DFS）：优先考虑网站结构中的深层路径
最佳优先搜索：简单的基于启发式的爬行（首先是较短的路径）

高级选项

网络流量监控：爬行期间可选跟踪HTTP请求
多页面爬行：支持通过深度控制抓取多个页面
等待时间配置：页面加载之间的可配置延迟
电脑屏幕截图工具：保存到临时目录的可选全屏截图

差错恢复

浏览器启动回退：浏览器初始化的多种策略
连接恢复：断开连接的浏览器的自动重新连接处理
URL验证：强大的URL解析和验证，具有错误处理功能
超时管理：可配置超时，防止挂在慢速页面上

定制

在中添加新路线 routes 目录。
通过修改扩展MCP功能 SimpleMcpServer 或者添加新的控制器。
通过扩展来创建新工具 BaseTool 抽象类 services/tools 目录。
每个工具都是独立的，可以独立开发。
通过中的环境变量调整性能和安全性 config 目录。

架构图

graph LR
  Client --> Server
  Server --> Router["Routes (API/MCP)"]
  Router --> |SSE| SimpleMcpServer
  Router --> |Streamable HTTP| SimpleMcpServer
  Router --> ApiControllers
  SimpleMcpServer --> Controllers
  Controllers --> Tools["Self-Contained Tools"]
  Tools --> |BaseTool| CrawlTool
  Tools --> |BaseTool| SmartCrawlTool
  Tools --> |BaseTool| ExtractLinksTool
  Tools --> |BaseTool| SitemapTool
  Tools --> |BaseTool| SearchInPageTool
  Tools --> |BaseTool| WebSearchTool
  Tools --> |BaseTool| DateTimeTool

参考文献

概述：高层架构和概念概述。
编码结构：源文件的详细说明。
MCP API参考：端点规范和JSON-RPC方法。
模型上下文协议SDK：官方SDK文档。
MCP传输模型：SSE与流式HTTP的详细信息。

使用说明

🏆 Webcrawl MCP服务器-生产就绪实施🏆

🎯 主要特点

� 快速开始

使用Docker（推荐）

地方发展

🛠️ 可用工具

🛑 中止功能

📋 MCP协议支持

🏗️ 建筑

🔧 配置

环境变量

开发vs生产

🧪 测试

📝 使用示例

基本工具执行

带查询的智能爬行

中止工具执行

📚 文档

🤝 贡献

📄 许可证

智能抓取工具（Markdown输出）

提取链接工具

网站地图生成器工具

页面搜索工具

网络搜索工具

日期时间工具

环境变量

配置

关键组件

Web爬行功能

基于工具的体系结构

可用工具

爬行工具

SmartCrawlTool

提取链接工具

网站地图工具

搜索输入工具

网络搜索工具

DateTimeTool

共享浏览器管理功能

内容提取（跨工具）

爬行策略

高级选项

差错恢复

定制

架构图

参考文献

相关 MCP

网页内容抓取服务

网页内容抓取服务器

网页研究服务器

网页内容获取工具

谷歌自定义搜索及网页内容提取服务

网页内容抓取服务