使用说明

mcp-web 翻译成中文是“MCP网络（或MCP网页）”。不过，这里的“MCP”是一个缩写，具体含义需要根据上下文来确定。在没有特定上下文的情况下，“MCP”可能代表多个概念，如“Machine Control Protocol”（机器控制协议）、“Multi-Cloud Platform”（多云平台）等。因此，完整的翻译可能需要根据具体语境来调整。如果“MCP”在此处是一个特定项目或系统的名称，那么“MCP网络（或MCP网页）”可能就是最直接的翻译

用于智能网页摘要的MCP服务器

一个功能强大的模型上下文协议（MCP）服务器，提供智能URL摘要功能，包括内容提取、智能分块以及基于大型语言模型（LLM）的摘要生成。

特点

🚀 表示火箭或快速前进的符号，常用于表达速度、进步或创新。 快速且稳健的获取使用httpx作为主要工具，对JavaScript密集型网站采用Playwright作为备用方案
📁 文件夹 文件系统支持总结本地文件（Markdown、代码、文档）及网页URL
🎯（目标） 智能内容提取基于trafilatura的内容提取（主要用于提取主要内容）
📊（表格） 智能分块具有可配置重叠的层次化和语义化文本分割
🤖 表示机器人或机器人形象。 大型语言模型（LLM）摘要生成针对长文档的流式输出映射-归约策略
🏠 表示“房子”或“家”。 本地LLM支持Ollama、LM Studio、LocalAI 或云服务提供商（OpenAI、Anthropic）
💾 代表“软盘”或“存储设备”。 持久缓存基于磁盘的缓存，支持TTL（生存时间）和LRU（最近最少使用）驱逐策略
🔒（锁形符号，常用于表示安全、保密或锁定状态） 安全第一路径验证、目录白名单设置以及OWASP LLM（大型语言模型）前十大合规性
📈 这个符号通常表示“上升趋势”或“增长”，在图表中常用来表示数据或价格的上升。 指标与日志记录通过结构化日志记录实现全面可观测性
🔗（这个符号在中文里通常没有直接的对应翻译，它在中文网络语境中常被用作链接或超链接的象征，可以简单翻译为“链接”或根据上下文具体描述其含义，如“这是一个链接”） 链接追踪可选的递归链接跟踪，以获取更深入的上下文
📝 Markdown 输出格式良好的摘要，附有引文和元数据
🧪 翻译为中文是“🧪（实验或化学相关的符号，具体含义需结合上下文，如‘实验’或‘化学实验’等）”。不过，通常这个符号本身在中文里没有直接对应的词汇，它更多地被用作一个表示实验或化学相关情境的符号。如果非要给出一个贴近的翻译，可以是“实验/化学实验的符号”或根据具体语境翻译为相应的词汇。 综合测试单元测试、集成测试、安全测试、黄金测试（或称为标准测试）和基准测试

状态： 积极开发 | 版本： 0.2.0 | 测试覆盖率： 85%左右 | 许可证： 麻省理工学院（MIT）

现实世界中的例子

输入： 总结Python的asyncio文档

result = await summarize_urls(
    urls=["https://docs.python.org/3/library/asyncio.html"],
    query="How do I create and manage concurrent async tasks?"
)

输出：

摘要：Python asyncio - 并发任务管理

来源： https://docs.python.org/3/library/asyncio.html 的中文翻译可以是：“Python 3 官方文档之 asyncio 模块”。不过，通常我们不会直接翻译网址，而是直接使用原网址或提供中文描述来指代该文档。在这里，我给出了一个可能的中文表述，以帮助理解该网址指向的内容

要点

创建任务：

使用 asyncio.create_task() 并发调度协程

任务是围绕协程的封装，用于并发运行它们

asyncio.gather() 并发运行多个可等待对象并收集结果

任务管理：

asyncio.wait() 以实现对任务完成的精细控制

asyncio.TaskGroup() (Python 3.11+) 用于结构化并发

任务可以使用（相应方法/工具）取消 .cancel() 并已与……核对过 .done()

最佳实践：

总是等待任务，否则它们将被垃圾回收

使用超时设置 asyncio.wait_for() 防止程序挂起

处理异常时使用 try/except 或者检查 .exception()

演出

任务为I/O密集型操作提供了真正的并发性

使用信号量来限制并发操作

更喜欢 gather() 用于简单的并行执行

使用Ollama通过llama3.2:3b生成的摘要 | 提取工具：trafilatura | 分块方式：自适应（512个标记）

为何这很重要： 无需阅读15,000多字的文档，您可以在几秒钟内获得简洁、实用的答案。

文件系统支持示例

输入： 总结本地项目文档

result = await summarize_urls(
    urls=[
        "file:///home/user/project/README.md",
        "/home/user/project/docs/ARCHITECTURE.md",
        "/home/user/project/CONTRIBUTING.md"
    ],
    query="How do I contribute to this project?"
)

输出：

摘要：项目贡献指南

来源： README.md，ARCHITECTURE.md，CONTRIBUTING.md

入门指南/开始使用

克隆仓库并将其分支保存到本地

安装依赖项，使用 uv sync (Python 3.10+)

使用开发容器以确保环境一致性

开发工作流程

遵循常规的提交格式

跑 task test 在提交拉取请求（PR）之前

确保代码检查（linting）通过 task lint

为新功能添加测试（要求覆盖率≥85%）

架构概述

模块化流程：获取器 → 提取器 → 分块器 → 摘要器

以安全为先的设计，包含路径验证和白名单机制

支持本地大型语言模型（Ollama）和云服务提供商

从本地文件生成的摘要 | 质量与网页URL相同

为何这很重要： 无需手动阅读，即可快速了解项目结构、贡献指南及架构，所有信息均来自本地文档。

快速入门

选项1：开发容器（推荐）

最简单的方法是使用带有 Docker 的 VS Code 开发容器来入门：

# Prerequisites: Docker and VS Code with Dev Containers extension
# 1. Clone the repository
git clone https://github.com/geehexx/mcp-web.git
cd mcp-web

# 2. Open in VS Code
code .

# 3. When prompted, click "Reopen in Container"
# Or: Press F1 → "Dev Containers: Reopen in Container"

你将获得：

✅ Python 3.10、uv 及所有依赖项已预安装
✅ Playwright 浏览器已准备好使用
✅ 已配置预提交钩子
✅ 已安装VS Code扩展（Python、Ruff、Mypy、Task）
✅ 所有开发者之间保持一致的环境

该容器在首次启动时会自动运行设置。请参阅开发容器详情如下。

选项2：手动安装

# Clone the repository
git clone https://github.com/geehexx/mcp-web.git
cd mcp-web

# Install uv (modern Python package manager)
# macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install Taskfile (recommended)
# macOS: brew install go-task/tap/go-task
# Linux: snap install task --classic
# Or see: https://taskfile.dev/installation/

# Setup complete environment (recommended)
task dev:setup

# Or manual installation with uv
uv sync --all-extras
uv run playwright install chromium

配置

默认本地大型语言模型（Ollama）

# Install Ollama: https://ollama.com
# Start: ollama serve
# Pull model: ollama pull llama3.2:3b

export MCP_WEB_SUMMARIZER_PROVIDER=ollama
export MCP_WEB_SUMMARIZER_MODEL=llama3.2:3b

# Or use task commands
task llm:ollama:pull # Pull recommended models
task llm:ollama:start # Start Ollama server

见 docs/guides/LOCAL_LLM_GUIDE.md 翻译为中文是：docs/guides/本地大型语言模型指南.md 用于完成本地LLM（大型语言模型）的设置。

云端大型语言模型（OpenAI）

export OPENAI_API_KEY="sk-..."
export MCP_WEB_SUMMARIZER_PROVIDER=openai
export MCP_WEB_SUMMARIZER_MODEL=gpt-4o-mini

仅在需要托管OpenAI的品质/延迟特性时设置这些。

其他设置

# Cache settings
export MCP_WEB_CACHE_DIR="~/.cache/mcp-web"
export MCP_WEB_CACHE_TTL=604800 # 7 days

# Fetcher settings
export MCP_WEB_FETCHER_TIMEOUT=30
export MCP_WEB_FETCHER_MAX_CONCURRENT=5

# Summarizer settings
export MCP_WEB_SUMMARIZER_TEMPERATURE=0.3
export MCP_WEB_SUMMARIZER_MAX_TOKENS=2048

用法

作为MCP服务器

在您的MCP客户端配置（例如，Claude Desktop）中添加：

{
 "mcpServers": {
 "mcp-web": {
 "command": "python",
 "args": ["-m", "mcp_web.mcp_server"]
 }
 }
}

程序化使用

from mcp_web import create_server, load_config

# Create server
config = load_config()
mcp = create_server(config)

# Use the pipeline directly
from mcp_web.mcp_server import WebSummarizationPipeline

pipeline = WebSummarizationPipeline(config)

# Summarize URLs
async for chunk in pipeline.summarize_urls(
 urls=["https://example.com"],
 query="What are the key features?",
):
 print(chunk, end="")

工具

`summarize_urls`

从一个或多个URL中提取内容并进行总结，可选地指定查询焦点。

参数：

urls （列表[字符串]，必需）：要总结的URL列表
query （字符串，可选）：用于确定摘要重点的问题或主题
follow_links (布尔值，默认为False)：跟随相关的出站链接
max_depth (int, default=1): 最大链接追踪深度

示例：

result = await summarize_urls(
 urls=["https://docs.python.org/3/library/asyncio.html"],
 query="How do I create async tasks?",
 follow_links=True
)

`get_cache_stats`

获取缓存和指标统计数据。

返回值： 包含缓存大小、命中率和处理指标的字典

`clear_cache`

清除整个缓存。

`prune_cache`

删除过期的缓存条目。

建筑学

管道流量

URLs → Fetch (httpx/Playwright) → Extract (trafilatura) →
Chunk (hierarchical/semantic) → Summarize (LLM map-reduce) →
Markdown Output (streaming)

关键设计决策

DD-001httpx 作为主要工具，Playwright 作为备用以增强鲁棒性
DD-002用……进行抽纱编织 favor_recall=True 为了最大限度地提取内容
DD-003层次化+语义分块保留文档结构
DD-004512个标记的块，每块之间有50个标记的重叠，以平衡上下文信息
DD-006Map-reduce摘要处理可任意长度的文档
DD-0077天磁盘缓存，采用LRU（最近最少使用）淘汰策略
DD-008OpenAI GPT-4o-mini 默认（可配置）
DD-009流式输出以提升用户体验

看 docs/架构/ARCHITECTURE.md（注：这里的“architecture”根据上下文翻译为“架构”，同时保持文件名的原样，因为文件名通常不需要翻译）以获取完整的设计文档。

项目结构

mcp-web/
├── src/mcp_web/
│ ├── mcp_server.py # MCP tool entry point & orchestration
│ ├── fetcher.py # URL fetching (httpx + Playwright)
│ ├── extractor.py # Content extraction (trafilatura)
│ ├── chunker.py # Text chunking strategies
│ ├── summarizer.py # LLM summarization (map-reduce)
│ ├── cache.py # Disk cache manager
│ ├── metrics.py # Logging & metrics collection
│ ├── config.py # Configuration management
│ └── utils.py # Token counting, formatting
├── tests/ # Unit & integration tests
├── docs/ # Architecture & API documentation
├── examples/ # Example usage scripts
└── pyproject.toml # Dependencies & project metadata

开发容器

此项目包含一个完整的VS Code开发容器配置，以确保开发环境的一致性和可重复性。

使用开发容器快速入门

安装前提条件：

在容器中打开：

git clone https://github.com/geehexx/mcp-web.git
cd mcp-web
code .
# Press F1 → "Dev Containers: Reopen in Container"

等待设置：
- 容器构建（首次约2-5分钟）
- 依赖项会自动通过以下方式安装： post-create.sh
- Playwright 浏览器下载
- 预提交钩子配置

开始开发：

task test:fast    # Run tests
task lint         # Check code quality
task --list       # See all commands

包含内容

基础环境：

Debian 12 基础镜像
Python 3.10（通过 uv 安装）
Node.js（用于文档工具）
Git，curl，build-essential（构建必需品）

Python 工具：

uv（快速包管理器）
使用 pytest-xdist 进行并行测试
ruff（代码清理与格式化）
mypy（类型检查）
bandit，semgrep（安全工具）

VS Code 集成：

带有Pylance的Python扩展
粗体扩展（保存时格式化）
Mypy 类型检查器
任务运行程序集成
Markdown 代码检查
Git 集成（GitLens）
Docker 扩展

剧作家：

预装的Chromium浏览器
所有系统依赖项已配置
准备好进行集成测试

配置文件

.devcontainer/Dockerfile - 容器镜像定义
.devcontainer/devcontainer.json - VS Code 设置和扩展
.devcontainer/post-create.sh - 自动化设置脚本

定制化

添加 VS Code 扩展：

编辑 .devcontainer/devcontainer.json:

"extensions": [
  "ms-python.python",
  "your-extension-id"
]

修改Python版本：

编辑 .devcontainer/devcontainer.json：

"args": {
  "PYTHON_VERSION": "3.11"
}

添加系统依赖项：

编辑 .devcontainer/Dockerfile：

RUN apt-get update && apt-get install -y \
    your-package-here

故障排除

容器无法构建：

检查Docker是否正在运行： docker ps
清除 Docker 缓存： docker system prune -a
不使用缓存重建：F1 → “开发容器：重建容器”

扩展功能无法正常工作：

重新加载窗口：F1 → “开发者：重新加载窗口”
重新安装扩展：F1 → “开发容器：重建容器”

性能问题：

在Docker Desktop设置中分配更多资源
在Windows上使用WSL 2后端
启用 BuildKit： export DOCKER_BUILDKIT=1

看见 VS Code 开发容器文档了解更多详情。

发展

使用Taskfile（推荐）

# Show all available tasks
task --list

# Complete setup
task dev:setup

# Run tests
task test # All tests except live
task test:fast # Unit + security + golden
task test:coverage # With coverage report
task test:parallel # Parallel execution

# Code quality
task lint # All linting
task format # Auto-format code
task security # Security scans
task analyze # Complete analysis

# CI simulation
task ci # Full CI pipeline
task ci:fast # Quick check

见 `docs/guides/TASKFILE_GUIDE.md` 翻译为中文是：`文档/指南/TASKFILE指南.md` 以供完整任务参考。

运行测试

# With Taskfile
task test # Recommended
task test:unit
task test:security
task test:golden # With local/cloud LLM

# Or with pytest directly
pytest -m "not live"
pytest -m unit
pytest -m golden

代码质量

# With Taskfile (recommended)
task lint
task format
task security

# Or directly
ruff check src/ tests/
ruff format src/ tests/
mypy src/
bandit -r src/

贡献

为仓库创建分支（或“克隆仓库”）
创建一个特性分支（git checkout -b feature/amazing-feature)
在测试中进行更改
运行代码检查和测试
提交您的更改（git commit -m 'Add amazing feature')
推送到分支（git push origin feature/amazing-feature）
提交一个拉取请求（或合并请求）

配置参考

见文档/架构/ARCHITECTURE.md#配置策略以获取完整的配置选项。

关键设置

设置	默认值	描述
`FETCHER_TIMEOUT`	30	HTTP请求超时（秒）
`FETCHER_MAX_CONCURRENT`	5	最大并行获取数
`CHUNKER_CHUNK_SIZE`	512	每个块的目标标记数
`CHUNKER_OVERLAP`	50	块（标记）之间的重叠
`SUMMARIZER_MODEL`	llama3.2:3b	要使用的LLM模型
`SUMMARIZER_TEMPERATURE`	0.3	大语言模型（LLM）温度参数
`CACHE_TTL`	604800	缓存TTL（7天）
`CACHE_MAX_SIZE`	1GB	最大缓存大小

演出

基准（或标准）

单一URL~5-10秒（使用缓存）
多个URL（5个）~15-30秒（并行获取）
大文档（10k+个标记）~30-60秒（映射-归约）

优化技巧

为重复查询启用缓存
调整 chunk_size 基于内容类型
使用 llama3.2:3b 用于成本效益高的摘要（默认）
限制 max_depth 用于链接追踪
定期清理缓存

故障排除

常见问题

“没有名为 'playwright' 的模块”

跑 pip install playwright && playwright install chromium

“OPENAI_API_KEY 未设置”

导出您的API密钥： export OPENAI_API_KEY="sk-..."

“缓存权限被拒绝”

检查 ~/.cache/mcp-web 权限或设置自定义 CACHE_DIR

“提取返回空内容”

该网站可能大量使用JavaScript；抓取器将自动回退到Playwright
有些网站会屏蔽爬虫；请检查 robots.txt

调试模式

启用调试日志记录：

export MCP_WEB_METRICS_LOG_LEVEL="DEBUG"
python -m mcp_web.mcp_server

路线图

v0.2.0（当前版本）

[x] 本地大型语言模型（LLM）支持（Ollama、LM Studio、LocalAI）
[x] 综合测试基础设施
[x] 安全测试（OWASP LLM 顶级 10 项）
[x] 用于提升工具化的Taskfile
[x] 带有确定性验证的黄金测试

v0.3.0（版本0.3.0）

[ ] 对扫描文档的PDF OCR支持
[ ] 多语言翻译
[ ] 与Anthropic Claude的集成
[ ] 用于语义搜索的向量嵌入

v0.4.0（版本号，可直接译为“版本0.4.0”或保持原样，视语境而定）

[ ] 每个域的提取规则
[ ] 图像/图表提取
[ ] 增量式摘要生成
[ ] Prometheus指标导出

看 docs/架构/ARCHITECTURE.md#未来增强功能以获取完整路线图。

许可证

MIT 许可证 - 详见许可证详情请参阅文件。

致谢

模型上下文协议由Anthropic（公司/机构）开发
“Trafilatura”在中文中可以翻译为“拉丝工艺”或“拉丝加工”。这个词汇通常用于描述通过拉伸材料（如金属或塑料）来使其变细或成型的过程。用于内容提取
httpx 用于异步HTTP
剧作家用于浏览器自动化
tiktoken 用于计算令牌数量

支持

📚 书籍或学习材料的象征文档
🐛 蝉（或“虫子”，根据上下文可具体翻译）问题追踪器
💬 讨论

使用说明

用于智能网页摘要的MCP服务器

特点

现实世界中的例子

摘要：Python asyncio - 并发任务管理

要点

文件系统支持示例

摘要：项目贡献指南

入门指南/开始使用

开发工作流程

架构概述

快速入门

选项1：开发容器（推荐）

选项2：手动安装

配置

默认本地大型语言模型（Ollama）

云端大型语言模型（OpenAI）

其他设置

用法

作为MCP服务器

程序化使用

工具

summarize_urls

get_cache_stats

clear_cache

prune_cache

建筑学

管道流量

关键设计决策

项目结构

开发容器

使用开发容器快速入门

包含内容

配置文件

定制化

故障排除

发展

使用Taskfile（推荐）

运行测试

代码质量

贡献

配置参考

关键设置

演出

基准（或标准）

优化技巧

故障排除

常见问题

“没有名为 'playwright' 的模块”

“OPENAI_API_KEY 未设置”

“缓存权限被拒绝”

“提取返回空内容”

调试模式

路线图

v0.2.0（当前版本）

v0.3.0（版本0.3.0）

v0.4.0（版本号，可直接译为“版本0.4.0”或保持原样，视语境而定）

许可证

致谢

支持

相关 MCP

网页内容抓取服务

网页内容抓取服务器

网页研究服务器

网页内容获取工具

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

网页内容抓取服务

`summarize_urls`

`get_cache_stats`

`clear_cache`

`prune_cache`