MCP-Server-Template

🏆 Webcrawl MCP 服务 - 可用于生产环境的实现 🏆

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

这是一个可用于生产环境的 Model Context Protocol（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

🛠️ 可用工具

工具	描述	主要功能
crawl	基础网页爬取	页面内容、元数据、链接
smartCrawl	智能爬取	相关性评分、智能导航
extractLinks	链接提取	分类、筛选、分析
searchInPage	内容搜索	文本匹配、上下文提取
generateSitemap	网站地图创建	网站结构、层级映射
webSearch	网页搜索	支持多个搜索引擎、结果筛选
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 握手
• ✅ 能力协商：全面支持协议版本协商
• ✅ 传输协议：支持现代 Streamable 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

开发环境与生产环境

• 开发环境：宽松的速率限制（每分钟 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

2. 切换到 mcp-service 目录：

   cd mcp-service
   npm install
   

3. 定义环境变量（参见配置）。
4. 构建并启动服务：

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

Endpoint	Protocol	Description
POST /mcp	MCP Streamable HTTP	Recommended - Modern JSON-RPC over HTTP
GET /mcp	HTTP	Server info and connection details
POST /tools/abort/:toolId	REST	Abort tool execution
GET /api/health	REST	Health check
GET /api/version	REST	Version information

📝 Usage Examples

Basic Tool Execution

# 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 参考和示例
TOOL_ABORT.md	工具中止功能指南
OVERVIEW.md	架构和设计概览
CODE_STRUCTURE.md	开发者文档
CONTRIBUTING.md	贡献指南

🤝 参与贡献

欢迎参与贡献！请参阅 CONTRIBUTING.md 了解指南。

📄 许可证

本项目采用 Creative Commons Attribution-NonCommercial 4.0 International License（CC BY-NC 4.0）授权。这意味着你可以：

• 分享 — 以任何媒介或格式复制和重新分发材料
• 改编 — 混编、转换材料，并以此为基础进行创作

须遵守以下条款：

• 署名 — 你必须给予适当署名
• 非商业性使用 — 你不得将材料用于商业目的

完整许可文本请参阅 LICENSE.md 文件。

---

为 MCP 社区倾心打造 ❤️ "name": "smartCrawl", "description": "抓取网站并返回 Markdown 格式的内容，还可回答特定查询。", "parameterDescription": "要抓取的 URL、可选的抓取参数，以及可选的查询。", "returnDescription": "包含成功状态、原始 URL、Markdown 内容和可选错误消息的对象。", "endpoint": "/api/tools/smartCrawl" }, { "name": "extractLinks", "description": "从网页中提取链接并进行分类。", "parameterDescription": "要从中提取链接的 URL。", "returnDescription": "包含内部和外部链接及其描述的对象。", "endpoint": "/api/tools/extractLinks" }, { "name": "sitemapGenerator", "description": "通过抓取网站页面生成站点地图。", "parameterDescription": "用于生成站点地图的抓取 URL，可选深度和 maxPages。", "returnDescription": "包含生成的站点地图结构的对象。", "endpoint": "/api/tools/sitemapGenerator" }, { "name": "searchInPage", "description": "在网页中搜索特定内容。", "parameterDescription": "要搜索的 URL 和搜索词。", "returnDescription": "包含搜索结果和匹配项的对象。", "endpoint": "/api/tools/searchInPage" }, { "name": "webSearch", "description": "执行网页搜索并提取结果。", "parameterDescription": "搜索查询和最大结果数。", "returnDescription": "包含搜索结果（标题、描述和 URL）的对象。", "endpoint": "/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（默认值：development）：环境模式（development 或 production）。
• 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）：请求之间的默认等待时间，单位为 ms。
• 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：网页爬取默认参数

核心组件

• 服务端：集成 Express 和 MCP 功能的统一服务端实现。
• 路由：将 API 和 MCP 端点整理在不同文件中。
• SimpleMcpServer：实现 MCP 发现和工具调用逻辑。
• 控制器：用于处理业务逻辑的 toolController 和 resourceController。
• 工具：独立的工具实现，扩展 BaseTool 抽象类：
  • CrawlTool：基础网页爬取和内容提取
  • SmartCrawlTool：支持 Markdown 输出和查询的智能爬取
  • ExtractLinksTool：从网页中提取链接并进行分类
  • SitemapTool：根据爬取内容生成站点地图
  • SearchInPageTool：在网页中搜索特定内容
  • WebSearchTool：网页搜索功能并提取结果
  • DateTimeTool：日期和时间实用功能
• 配置：集中的配置系统，包含模块专属设置。
• MCP 传输：同时支持现代 Streamable HTTP 和旧版 SSE 传输方式。
• 工具架构：每个工具都包含自己的浏览器管理、爬取逻辑和错误处理，实现完全独立运行。

网页爬取功能

此 MCP 服务包含一套全面且独立的爬取工具，每个工具都集成了浏览器管理并提供专门功能：

基于工具的架构

• 独立设计：每个工具都管理自己的 Puppeteer 浏览器实例和爬取逻辑
• BaseTool 抽象类：为所有工具提供共享的通用功能和标准化错误处理
• 独立运行：工具无需依赖共享服务即可运行，从而提高可靠性

可用工具

CrawlTool

• 基础网页爬取：从网页中提取文本内容和表格
• 多种策略：BFS、DFS 和最佳优先爬取方式
• 截图捕获：可选的整页截图功能
• 内容提取：智能提取可见文本并跳过隐藏元素

SmartCrawlTool

• Markdown 输出：按照自定义格式规则将 HTML 转换为 Markdown
• 基于查询的爬取：根据特定查询提取相关内容
• 智能内容检测：针对不同内容类型提升相关性评分
• 结构化输出：格式规范的 Markdown，包含恰当的标题和分节

ExtractLinksTool

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

SitemapTool

• 生成站点地图：根据爬取的内容创建结构化站点地图
• 层级结构：按深度和关联关系组织页面
• 深度可配置：控制生成站点地图时的爬取深度

SearchInPageTool

• 内容搜索：在网页中查找特定词语或短语
• 上下文提取：提供搜索匹配项的周边上下文
• 相关性评分：按相关性排列搜索结果

WebSearchTool

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

DateTimeTool

• 时间实用工具：以多种格式获取当前日期和时间
• 时区支持：跨不同时区转换时间
• 格式选项：提供多种日期和时间格式

浏览器管理通用功能

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

内容提取（适用于所有工具）

• 文本提取：智能提取可见文本，同时跳过隐藏元素和脚本
• Markdown 转换：将 HTML 转换为 Markdown，并为表格和代码块应用自定义规则
• 表格提取：结构化提取 HTML 表格，并支持标题
• 截图捕获：可选的整页截图功能
• 链接处理：提取并分类内部链接和外部链接

爬取策略

• 广度优先搜索（BFS）：用于系统化探索的默认策略
• 深度优先搜索（DFS）：优先探索网站结构中更深层的路径
• 最佳优先搜索：基于简单启发式规则进行爬取（优先选择较短路径）

高级选项

• 网络流量监控：可选跟踪爬取期间的 HTTP 请求
• 多页面爬取：支持控制深度并爬取多个页面
• 等待时间配置：可配置页面加载之间的延迟
• 截图捕获：可选将整页截图保存到临时目录

错误恢复能力

• 浏览器启动回退机制：提供多种浏览器初始化策略
• 连接恢复：自动处理已断开浏览器的重新连接
• URL 验证：可靠地解析和验证 URL，并进行错误处理
• 超时管理：可配置超时时间，避免因页面加载缓慢而一直等待

自定义

• 在 routes 目录中添加新路由。
• 修改 SimpleMcpServer 或添加新控制器，以扩展 MCP 功能。
• 在 services/tools 目录中扩展抽象类 BaseTool，以创建新工具。
• 每个工具都是独立的，可以单独开发。
• 通过 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 方法。
• Model Context Protocol SDK：官方 SDK 文档。
• MCP 传输模型：SSE 与 Streamable HTTP 的详细说明。