A Fast Website Reader MCP

@just-every/mcp-read-website-fast

为 AI Agent 快速、高效地提取网页内容，转换为简洁的 Markdown。

概述

现有的 MCP 网页爬虫速度慢，且消耗大量 token。这会拖慢开发进度，而且大模型需要解析整个网页，因此提供的结果并不完整。

这个 MCP 包会在本地获取网页、剔除无关内容，并将内容转换为简洁的 Markdown，同时保留链接。它专为 Claude Code、IDE 和大模型处理流水线设计，尽可能减少 token 占用。只需极少的依赖，即可在本地爬取网站。

注意： 此包现在使用 @just-every/crawl 实现核心爬取和 Markdown 转换功能。

功能

• 快速启动：使用官方 MCP SDK，并通过延迟加载优化性能
• 内容提取：使用 Mozilla Readability（与 Firefox 阅读视图相同）
• HTML 转 Markdown：使用 Turndown，并支持 GFM
• 智能缓存：使用 SHA-256 哈希处理 URL
• 礼貌爬取：支持 robots.txt 和速率限制
• 并发抓取：支持配置爬取深度
• 流式优先设计：降低内存占用
• 保留链接：便于构建知识图谱
• 可选分块：便于后续处理

安装

Claude Code

claude mcp add read-website-fast -s user -- npx -y @just-every/mcp-read-website-fast

VS Code

code --add-mcp '{"name":"read-website-fast","command":"npx","args":["-y","@just-every/mcp-read-website-fast"]}'

Cursor

cursor://anysphere.cursor-deeplink/mcp/install?name=read-website-fast&config=eyJyZWFkLXdlYnNpdGUtZmFzdCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqdXN0LWV2ZXJ5L21jcC1yZWFkLXdlYnNpdGUtZmFzdCJdfX0=

JetBrains IDE

设置 → 工具 → AI 助手 → Model Context Protocol (MCP) → 添加

选择“As JSON”并粘贴：

{"command":"npx","args":["-y","@just-every/mcp-read-website-fast"]}

或者，在聊天窗口中输入 /add 并填写相同的 JSON——两种方式都可以一步完成服务配置。 

原始 JSON（适用于任何 MCP 客户端）

{
  "mcpServers": {
    "read-website-fast": {
      "command": "npx",
      "args": ["-y", "@just-every/mcp-read-website-fast"]
    }
  }
}

将其放入客户端的 mcp.json（例如 .vscode/mcp.json、~/.cursor/mcp.json 或 Claude 的 .mcp.json）。

功能

• 快速启动：使用官方 MCP SDK，并通过延迟加载优化性能
• 内容提取：使用 Mozilla Readability（与 Firefox 阅读视图相同）
• HTML 转 Markdown：使用 Turndown，并支持 GFM
• 智能缓存：使用 SHA-256 哈希处理 URL
• 礼貌爬取：支持 robots.txt 和速率限制
• 并发抓取：支持配置爬取深度
• 流式优先设计：降低内存占用
• 保留链接：便于构建知识图谱
• 可选分块：便于后续处理

可用工具

• read_website - 获取网页并将其转换为简洁的 Markdown
  • 参数：
    • url（必填）：要获取的 HTTP/HTTPS URL
    • pages（可选）：爬取的最大页面数（默认值：1，最大值：100）

可用资源

• read-website-fast://status - 获取缓存统计信息
• read-website-fast://clear-cache - 清除缓存目录

开发用法

安装

npm install
npm run build

获取单个页面

npm run dev fetch https://example.com/article

按深度爬取

npm run dev fetch https://example.com --depth 2 --concurrency 5

输出格式

# Markdown only (default)
npm run dev fetch https://example.com

# JSON output with metadata
npm run dev fetch https://example.com --output json

# Both URL and markdown
npm run dev fetch https://example.com --output both

CLI 选项

• -p, --pages <number> - 爬取的最大页面数（默认值：1）
• -c, --concurrency <number> - 最大并发请求数（默认值：3）
• --no-robots - 忽略 robots.txt
• --all-origins - 允许跨源爬取
• -u, --user-agent <string> - 自定义用户代理
• --cache-dir <path> - 缓存目录（默认值：.cache）
• -t, --timeout <ms> - 请求超时时间，单位为毫秒（默认值：30000）
• -o, --output <format> - 输出格式：json、markdown 或 both（默认值：markdown）

清除缓存

npm run dev clear-cache

自动重启功能

MCP 服务默认具备自动重启功能，以提高可靠性：

• 如果服务崩溃，会自动重启
• 处理未捕获的异常和 Promise 拒绝
• 实现指数退避（1 分钟内最多尝试 10 次）
• 记录所有重启尝试，以便监控
• 妥善处理关闭信号（SIGINT、SIGTERM）

如需在开发/调试时禁用自动重启：

# Run directly without restart wrapper
npm run serve:dev

架构

mcp/
├── src/
│   ├── crawler/        # URL fetching, queue management, robots.txt
│   ├── parser/         # DOM parsing, Readability, Turndown conversion
│   ├── cache/          # Disk-based caching with SHA-256 keys
│   ├── utils/          # Logger, chunker utilities
│   ├── index.ts        # CLI entry point
│   ├── serve.ts        # MCP server entry point
│   └── serve-restart.ts # Auto-restart wrapper

开发

# Run in development mode
npm run dev fetch https://example.com

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 提交 pull request

故障排除

缓存问题

npm run dev clear-cache

超时错误

• 使用 -t 标志增加超时时间
• 检查网络连接
• 确认 URL 可访问

未提取到内容

• 某些网站会阻止自动访问
• 尝试使用自定义 user agent，添加 -u 标志
• 检查网站是否需要 JavaScript（不支持）

许可证

MIT