mult-fetch-mcp-server

mult-fetch-mcp-server

本项目实现了符合 MCP 规范的客户端和服务端，用于 AI 助手与外部工具之间的通信。

English | 中文文档

版本 2.0

使用 URL 调用 fetch 工具。默认格式为 Markdown，通过 HTTP 获取内容并提取易读文章。无需提供 startCursor。

format	返回内容
markdown	易读文章，以 Markdown 格式呈现（默认）
plaintext	易读文章，以纯文本格式呈现
html	HTML 标记
json	JSON 文档
txt	原始响应正文

普通网页会在一次响应中返回。默认预算为 maxChars 100000 和 maxBytes 1048576；截断时优先选择换行符或空格。正文较长时，响应会包含 nextCursor 和 chunkId。再次调用 fetch，并将 cursor 设为 nextCursor。

fetch_html、fetch_json、fetch_txt、fetch_markdown 和 fetch_plaintext 都是 fetch 的轻量别名，使用固定格式。

Cursor

将以下内容添加到 ~/.cursor/mcp.json，或项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "mult-fetch": {
      "command": "npx",
      "args": ["-y", "@lmcc-dev/mult-fetch-mcp-server"],
      "env": {
        "MCP_LANG": "en"
      }
    }
  }
}

Claude Desktop

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mult-fetch": {
      "command": "npx",
      "args": ["-y", "@lmcc-dev/mult-fetch-mcp-server"],
      "env": {
        "MCP_LANG": "en"
      }
    }
  }
}

保存后重启宿主。让它获取一个 URL。它应调用 fetch，而不提供 startCursor。

浏览器模式

默认 HTTP 抓取器不需要 Chrome 或 Puppeteer。常规安装无需它们（npm install --omit=optional 会跳过可选依赖包）。如需在无头浏览器中渲染页面，请安装可选依赖包并将 useBrowser 设为 true：

npm install puppeteer puppeteer-extra puppeteer-extra-plugin-stealth

autoDetectMode 默认值为 false，因此除非设置该标志，否则遇到 403 时不会启动浏览器。

安全性

每个请求（包括重定向）都会在发送前进行检查：

• 环回地址（127.0.0.0/8、::1、localhost）
• 私有网络（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）
• 链路本地地址和云元数据地址（169.254.0.0/16，包括 169.254.169.254，以及 IPv6 fe80::/10）
• 运营商级 NAT 100.64.0.0/10、文档专用地址范围，以及嵌入在 6to4、NAT64 或 IPv4 映射 IPv6 地址中的私有地址

直连会固定到通过检查的地址。默认超时时间为 30 秒，每个响应都会受到 maxChars 和 maxBytes 限制。浏览器模式采用相同的 URL 检查。只有在确实需要浏览器访问私有网络目标时，才设置 ALLOW_PRIVATE_NETWORK_REQUESTS=true。

项目结构

fetch-mcp/
├── src/                         # Source code directory
│   ├── lib/                     # Library files
│   │   ├── fetchers/            # Web fetching implementation
│   │   │   ├── browser/         # Browser-based fetching
│   │   │   │   ├── BrowserFetcher.ts      # Browser fetcher implementation
│   │   │   │   ├── BrowserInstance.ts     # Browser instance management
│   │   │   │   └── PageOperations.ts      # Page interaction operations
│   │   │   ├── node/            # Node.js-based fetching
│   │   │   └── common/          # Shared fetching utilities
│   │   ├── utils/               # Utility modules
│   │   │   ├── ChunkManager.ts        # Content chunking
│   │   │   ├── ContentProcessor.ts    # HTML to text conversion
│   │   │   ├── ContentExtractor.ts    # Intelligent content extraction
│   │   │   ├── ContentSizeManager.ts  # Content size limiting
│   │   │   └── ErrorHandler.ts        # Error handling
│   │   ├── server/              # Server-related modules
│   │   │   ├── index.ts         # Server entry
│   │   │   ├── browser.ts       # Browser management
│   │   │   ├── fetcher.ts       # Web fetching logic
│   │   │   ├── tools.ts         # Tool registration and handling
│   │   │   ├── resources.ts     # Resource handling
│   │   │   ├── prompts.ts       # Prompt templates
│   │   │   └── types.ts         # Server type definitions
│   │   ├── i18n/                # Internationalization support
│   │   └── types.ts             # Common type definitions
│   ├── client.ts                # MCP client implementation
│   └── mcp-server.ts            # MCP server main entry
├── index.ts                     # Server entry point
├── tests/                       # Test files
└── dist/                        # Compiled files

MCP 规范

Model Context Protocol（MCP）定义了两种主要的传输方式：

1. 标准输入/输出（Stdio）：客户端将 MCP 服务作为子进程启动，双方通过标准输入（stdin）和标准输出（stdout）进行通信。
2. 服务器发送事件（SSE）：用于在客户端和服务端之间传递消息。

本项目实现了标准输入/输出（Stdio）传输方式。

功能

• 基于官方 MCP SDK 实现
• 支持标准输入/输出（Stdio）传输
• 提供一个 fetch 工具，format 可设为 HTML、JSON、文本、Markdown 或纯文本
• 默认通过 HTTP 抓取，可选用无头浏览器渲染
• 单次响应内容窗口（maxChars / maxBytes）；正文被截断时，可选使用 cursor 继续获取
• 将详细的调试日志写入 stderr
• 双语国际化（英语和中文）
• 模块化设计，便于维护和扩展
• 智能内容提取：基于 Mozilla 的 Readability 库，可从网页中提取有意义的内容，同时过滤广告和导航元素
• 元数据支持：可提取网页标题、作者、发布日期和站点信息等元数据
• 智能内容检测：自动检测页面是否包含有意义的内容，过滤登录页、错误页和其他缺少实质内容的页面
• 浏览器自动化增强：支持页面滚动、Cookie 管理、等待选择器等高级浏览器交互

安装

通过 Smithery 安装

如需通过 Smithery 为 Claude Desktop 自动安装 Mult Fetch MCP Server：

npx -y @smithery/cli install @lmcc-dev/mult-fetch-mcp-server --client claude

本地安装

pnpm install

全局安装

pnpm add -g @lmcc-dev/mult-fetch-mcp-server

也可以通过 npx 直接运行（无需安装）：

npx @lmcc-dev/mult-fetch-mcp-server

与 Claude 集成

如需将此工具集成到 Claude 桌面端，需要添加服务配置：

配置文件位置

• MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

配置示例

方法 1：使用 npx（推荐）

此方法最简单，无需指定完整路径，适用于全局安装或通过 npx 直接使用：

{
  "mcpServers": {
    "mult-fetch-mcp-server": {
      "command": "npx",
      "args": ["@lmcc-dev/mult-fetch-mcp-server"],
      "env": {
        "MCP_LANG": "en"  // Set language to English, options: "zh" or "en"
      }
    }
  }
}

方法 2：指定完整路径

如果需要使用特定的安装位置，可以指定完整路径：

{
  "mcpServers": {
    "mult-fetch-mcp-server": {
      "command": "path-to/bin/node",
      "args": ["path-to/@lmcc-dev/mult-fetch-mcp-server/dist/index.js"],
      "env": {
        "MCP_LANG": "en"  // Set language to English, options: "zh" or "en"
      }
    }
  }
}

请将 path-to/bin/node 替换为系统中 Node.js 可执行文件的路径，并将 path-to/@lmcc-dev/mult-fetch-mcp-server 替换为此项目的实际路径。

使用示例

以下是在 Claude 桌面客户端中使用此工具的示例：

图片展示了 Claude 如何使用 fetch 工具获取网页内容，并根据你的指示进行处理。

使用方法

完成配置后，重启 Claude 桌面应用，即可在对话中使用以下工具：

• fetch：获取 URL。将 format 设为 html、markdown（默认）、plaintext、json 或 txt
• fetch_html、fetch_json、fetch_txt、fetch_markdown、fetch_plaintext：保留自 1.x 版本的 fetch 别名

构建

pnpm run build

运行服务

pnpm run server
# or
node dist/index.js
# if globally installed, you can run directly
@lmcc-dev/mult-fetch-mcp-server
# or use npx
npx @lmcc-dev/mult-fetch-mcp-server

客户端演示工具

注意：以下 client.js 功能仅供演示和测试使用。与 Claude 或其他 AI 助手搭配使用时，MCP 服务由 AI 驱动，并会自动管理分块过程。

命令行客户端

项目包含一个命令行客户端，用于测试和开发：

pnpm run client <method> <params_json>
# example
pnpm run client fetch_html '{"url": "https://example.com", "debug": true}'

演示客户端分块控制参数

使用命令行客户端测试时，可以使用以下参数演示内容分块功能：

• --all-chunks：命令行标志，用于按顺序自动获取所有分块（仅用于演示）
• --max-chunks：命令行标志，用于限制要获取的最大分块数（可选，默认值为 10）

实时输出演示

client.js 演示工具支持实时输出：

node dist/src/client.js fetch_html '{"url":"https://example.com", "startCursor": 0, "contentSizeLimit": 500}' --all-chunks --debug

演示客户端将按顺序自动获取所有分块并立即显示，展示如何实时处理大量内容。

运行测试

# Run MCP functionality tests
npm run test:mcp

# Run mini4k.com website tests
npm run test:mini4k

# Run direct client call tests
npm run test:direct

语言设置

此项目支持中文和英文双语国际化。你可以通过环境变量设置语言：

使用环境变量

设置 MCP_LANG 环境变量以控制语言：

# Set to English
export MCP_LANG=en
npm run server

# Set to Chinese
export MCP_LANG=zh
npm run server

# Windows system
set MCP_LANG=zh
npm run server

使用环境变量可确保所有相关进程（包括 MCP 服务）使用相同的语言设置。

默认语言

默认情况下，系统将按以下优先级选择语言：

1. MCP_LANG 环境变量
2. 操作系统语言（如果以 "zh" 开头，则使用中文）
3. 英文（作为最终回退选项）

调试

此项目遵循 MCP 协议规范，默认不输出任何日志，以避免干扰 JSON-RPC 通信。调试信息通过调用参数控制：

使用 debug 参数

调用工具时，将 debug: true 参数设为开启：

{
  "url": "https://example.com",
  "debug": true
}

调试消息会按以下格式发送到标准错误流（stderr）：

[MCP-SERVER] MCP server starting...
[CLIENT] Fetching URL: https://example.com

调试日志文件

启用调试模式后，所有调试消息也会写入以下位置的日志文件：

~/.mult-fetch-mcp-server/debug.log

可通过 MCP 资源 API 访问此日志文件：

// Access the debug log file
const result = await client.readResource({ uri: "file:///logs/debug" });
console.log(result.contents[0].text);

// Clear the debug log file
const clearResult = await client.readResource({ uri: "file:///logs/clear" });
console.log(clearResult.contents[0].text);

代理设置

此工具支持多种代理设置配置方式：

1. 使用 proxy 参数

最直接的方式是在请求参数中指定代理：

{
  "url": "https://example.com",
  "proxy": "http://your-proxy-server:port",
  "debug": true
}

2. 使用环境变量

此工具会自动检测并使用标准环境变量中的代理设置：

# Set proxy environment variables
export HTTP_PROXY=http://your-proxy-server:port
export HTTPS_PROXY=http://your-proxy-server:port

# Run the server
npm run server

3. 检测系统代理

此工具会尝试根据你的操作系统检测系统代理设置：

• Windows：使用 set 命令读取环境变量中的代理设置
• macOS/Linux：使用 env 命令读取环境变量中的代理设置

4. 代理故障排除

如果代理检测遇到问题：

1. 使用 debug: true 参数查看代理检测的详细日志
2. 使用 proxy 参数显式指定代理
3. 确保代理 URL 格式正确：http://host:port 或 https://host:port
4. 对于需要浏览器功能的网站，设置 useBrowser: true 以使用浏览器模式

5. 浏览器模式和代理

使用浏览器模式（useBrowser: true）时，工具将：

1. 首先尝试使用明确指定的代理（如果提供）
2. 然后尝试使用系统代理设置
3. 如果未找到代理，则不使用代理继续执行

浏览器模式尤其适用于实施反爬措施或需要执行 JavaScript 的网站。

参数处理

本项目通过以下方式处理参数：

• debug：通过调用参数传入，每个请求都可以单独控制是否启用调试输出
• MCP_LANG：从环境变量中读取，用于控制整个服务的语言设置

用法

创建客户端

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import path from 'path';
import { fileURLToPath } from 'url';

// Get the directory path of the current file
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Create client transport layer
const transport = new StdioClientTransport({
  command: 'node',
  args: [path.resolve(__dirname, 'dist/index.js')],
  stderr: 'inherit',
  env: {
    ...process.env  // Pass all environment variables, including MCP_LANG
  }
});

// Create client
const client = new Client({
  name: "example-client",
  version: "1.0.0"
});

// Connect to transport layer
await client.connect(transport);

// Use client
const result = await client.callTool({
  name: 'fetch_html',
  arguments: {
    url: 'https://example.com',
    debug: true  // Control debug output through parameters
  }
});

if (result.isError) {
  console.error('Fetch failed:', result.content[0].text);
} else {
  console.log('Fetch successful!');
  console.log('Content preview:', result.content[0].text.substring(0, 500));
}

支持的工具

• fetch：获取 URL。format 可以是 html、markdown（默认）、plaintext、json 或 txt
• fetch_html、fetch_json、fetch_txt、fetch_markdown、fetch_plaintext：fetch 的 1.x 版别名

资源支持

服务支持 resources/list 和 resources/read 方法，但当前实现中未定义任何资源。资源系统旨在提供对项目文件和文档的访问，但此功能尚未完全实现。

资源用法示例

// Example: List available resources
const resourcesResult = await client.listResources({});
console.log('Available resources:', resourcesResult);

// Note: Currently this will return empty lists for resources and resourceTemplates

支持的提示词模板

服务提供以下提示词模板：

• fetch-website：获取网站内容，支持不同格式和浏览器模式
• extract-content：从网站提取特定内容，支持 CSS 选择器和数据类型指定
• debug-fetch：调试网站抓取问题，分析可能的原因并提供解决方案

提示词模板用法

1. 使用 prompts/list 获取可用提示词模板列表
2. 使用 prompts/get 获取特定提示词模板的内容

// Example: List available prompt templates
const promptsResult = await client.listPrompts({});
console.log('Available prompts:', promptsResult);

// Example: Get website content prompt
const fetchPrompt = await client.getPrompt({
  name: "fetch-website",
  arguments: {
    url: "https://example.com",
    format: "html",
    useBrowser: "false"
  }
});
console.log('Fetch website prompt:', fetchPrompt);

// Example: Debug website fetching issues
const debugPrompt = await client.getPrompt({
  name: "debug-fetch",
  arguments: {
    url: "https://example.com",
    error: "Connection timeout"
  }
});
console.log('Debug fetch prompt:', debugPrompt);

参数选项

每个工具都支持以下参数：

基本参数

• url：要获取的 URL（必填）
• headers：自定义请求标头（可选，默认值为 {}）
• proxy：代理服务 URL，格式为 http://host:port 或 https://host:port（可选）

网络控制参数

• timeout：超时时间，单位为毫秒（可选，默认值为 30000）
• maxRedirects：允许跟随的最大重定向次数（可选，默认值为 10）
• noDelay：是否禁用请求之间的随机延迟（可选，默认值为 false）
• useSystemProxy：是否使用系统代理（可选，默认值为 true）

内容窗口

• maxChars：此响应中的最大字符数（可选，默认值为 100000）。截断时优先在换行符或空格处进行。
• maxBytes：此响应中的最大 UTF-8 字节数（可选，默认值为 1048576）。
• cursor：来自 nextCursor 的续传令牌。首次调用时省略。设置后，服务不会重新获取 URL。
• enableContentSplitting：设为 false 时，超出大小限制的内容将被截断，且不返回游标（可选，默认值为 true）。
• contentSizeLimit：旧版字节分块大小。未设置 maxChars 或 maxBytes 时，将使用 1.x 字节分块器。
• startCursor：旧版字节偏移量。非必需。仅与 1.x 的 chunkId 搭配使用。

分块管理

• chunkId：响应被截断时，随 nextCursor 返回的文档 ID。

将 cursor 传回 fetch 以读取下一段内容。此流程不使用 startCursor。

模式控制参数

• useBrowser：是否使用浏览器模式（可选，默认值为 false）
• useNodeFetch：是否强制使用 Node.js 模式（可选，默认值为 false，与 useBrowser 互斥）
• autoDetectMode：遇到 403 或挑战页面时在浏览器中重试（可选，默认值为 false）。需要安装可选的 Puppeteer 软件包。

浏览器模式专用参数

• waitForSelector：浏览器模式下等待的选择器（可选，默认值为 'body'）
• waitForTimeout：浏览器模式下的等待超时时间，单位为毫秒（可选，默认值为 5000）
• scrollToBottom：是否在浏览器模式下滚动到页面底部（可选，默认值为 false）
• saveCookies：是否在浏览器模式下保存 Cookie（可选，默认值为 true）
• closeBrowser：是否关闭浏览器实例（可选，默认值为 false）

内容提取参数

• extractContent：转换前是否使用 Readability（可选）。markdown 和 plaintext 的默认值为 true，html、json 和 txt 的默认值为 false。
• includeMetadata：是否在提取的内容中包含元数据（可选，默认值为 false，仅在 extractContent 为 true 时有效）
• fallbackToOriginal：提取失败时是否回退到原始内容（可选，默认值为 true，仅在 extractContent 为 true 时有效）

调试参数

• debug：是否启用调试输出（可选，默认值为 false）

内容提取功能

使用内容提取功能获取网页的核心内容，过滤导航栏、广告、侧边栏和其他干扰元素：

{
  "url": "https://example.com/article",
  "extractContent": true,
  "includeMetadata": true
}

如果有可用元数据，提取的内容将包含以下信息：

• 标题
• 署名（作者）
• 站点名称
• 摘要
• 内容长度
• Readability 标志（isReaderable）

特殊用法

内容提取示例

仅从文章网页中提取有意义的内容：

{
  "url": "https://example.com/news/article",
  "extractContent": true,
  "includeMetadata": true
}

对于可能无法成功提取内容的网站，可以使用 fallbackToOriginal 确保获取到一些内容：

{
  "url": "https://example.com/complex-layout",
  "extractContent": true,
  "fallbackToOriginal": true
}

不执行抓取而关闭浏览器

若要关闭浏览器实例而不执行任何抓取操作：

{
  "url": "about:blank",
  "closeBrowser": true
}

代理优先级

代理按以下顺序确定：

1. 命令行中指定的代理
2. 请求中的 proxy 参数
3. 环境变量（如果 useSystemProxy 为 true）
4. Git 配置（如果 useSystemProxy 为 true）

如果设置了 proxy，useSystemProxy 将自动设为 false。

调试输出

设置 debug: true 时，日志将输出到 stderr，并带有以下前缀：

• [MCP-SERVER]：来自 MCP 服务的日志
• [NODE-FETCH]：来自 Node.js 抓取器的日志
• [BROWSER-FETCH]：来自浏览器抓取器的日志
• [CLIENT]：来自客户端的日志
• [TOOLS]：来自工具实现的日志
• [FETCHER]：来自主抓取器接口的日志
• [CONTENT]：与内容处理相关的日志
• [CONTENT-PROCESSOR]：来自 HTML 内容处理器的日志
• [CONTENT-SIZE]：与内容大小管理相关的日志
• [CHUNK-MANAGER]：与内容分块操作相关的日志
• [ERROR-HANDLER]：与错误处理相关的日志
• [BROWSER-MANAGER]：来自浏览器实例管理器的日志
• [CONTENT-EXTRACTOR]：来自内容提取器的日志

许可证

MIT

---

由 lmcc-dev 更新