huoshui-fetch

huoshui-fetch

专用的网页内容抓取与转换 MCP（Model Context Protocol）服务，提供抓取、转换和提取网页数据的工具。

功能

抓取工具

• fetch_url：从 URL 抓取内容，可自定义超时、重定向处理方式和 user-agent
• fetch_with_headers：使用自定义请求头抓取 URL，以支持经过身份验证的请求

转换工具

• html_to_markdown_tool：将 HTML 转换为简洁的 Markdown 格式
• html_to_text_tool：从 HTML 中提取纯文本
• clean_html_tool：移除脚本和样式，并清理 HTML
• json_to_markdown_tool：将 JSON 数据转换为易读的 Markdown

提取工具

• extract_article_tool：使用 readability 提取文章主体内容
• extract_links_tool：提取所有链接，并提供筛选选项
• extract_metadata_tool：提取页面元数据（标题、描述、OG 标签）
• extract_images_tool：提取图片，并按尺寸筛选
• extract_structured_data_tool：提取 JSON-LD 和微数据

安装

通过 MCP Registry 安装（推荐）

此服务已上架 Model Context Protocol Registry。使用你的 MCP 客户端安装。

mcp-name: io.github.huoshuiai42/huoshui-fetch

# Using uv (recommended)
uv sync

# Or install from GitHub
pip install git+https://github.com/yourusername/huoshui-fetch.git

使用方法

使用 uvx 运行（推荐用于临时使用）

# From the repository
uvx --from . huoshui-fetch

# From GitHub (once published)
uvx --from git+https://github.com/yourusername/huoshui-fetch.git huoshui-fetch

直接运行

# Using uv
uv run python -m huoshui_fetch

# Or if installed
python -m huoshui_fetch

服务通过标准输入/输出进行通信，非常适合与 Claude Desktop 和其他兼容 MCP 的客户端集成。

Claude Desktop 配置

添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "huoshui-fetch": {
      "command": "uvx",
      "args": ["--no-cache", "--from", ".", "huoshui-fetch"],
      "cwd": "/path/to/huoshui-fetch"
    }
  }
}

或者，如果从 GitHub 安装：

{
  "mcpServers": {
    "huoshui-fetch": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/huoshui-fetch.git",
        "huoshui-fetch"
      ]
    }
  }
}

使用示例

配置完成后，即可在 Claude Desktop 中使用这些工具：

// Fetch a webpage
fetch_url("https://example.com")

// Convert HTML to Markdown
html_to_markdown_tool("<h1>Hello</h1><p>World</p>")

// Extract article content
extract_article_tool(html_content, "https://example.com/article")

要求

• Python 3.11+
• 依赖项见 pyproject.toml

开发与发布

本项目包含用于构建和发布到 PyPI 的完整自动化流程。

自动化发布工作流

# Complete automated workflow (TestPyPI + PyPI)
uv run python scripts/publish.py --include-pypi

# TestPyPI only (recommended for testing)
uv run python scripts/publish.py

# Bump version and publish
uv run python scripts/publish.py --version-bump patch --include-pypi

单独命令

# Version management
uv run python scripts/version_manager.py --check
uv run python scripts/version_manager.py --bump patch

# Setup PyPI credentials (first time)
uv run python scripts/credentials_setup.py

# Build package
uv run python scripts/build.py

# Run comprehensive tests
uv run python scripts/test.py

# Upload to PyPI
uv run python scripts/upload.py

功能

• ✅ 版本管理：在所有文件间自动同步
• ✅ 质量检查：使用 Ruff 进行 lint 检查，使用 MyPy 进行类型检查
• ✅ 构建自动化：执行干净构建并进行验证
• ✅ 测试套件：全面测试软件包和功能
• ✅ 发布工作流：使用 uv publish 发布到 TestPyPI → PyPI（支持 .pypirc 文件）
• ✅ 错误恢复：内置错误处理和恢复选项

详细文档请参阅 PUBLISHING.md。

DXT 扩展

本项目支持 DXT（Desktop Extensions）格式，便于分发和安装。

构建 DXT 扩展：

python build_dxt.py

这会创建一个 huoshui-fetch-{version}.dxt 文件，可安装到兼容的 AI 桌面应用中。

许可证

MIT