AI导哈

网页文档阅读器

一个基于Model Context Protocol (MCP)的服务器，使Amazon Q能够智能导航和提取网页文档内容。

  • by Lumos-Labs-HQ
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Lumos-Labs-HQ/amazon-q-MCP

使用说明

🌐 Amazon Q Web文档阅读器

用于智能Web内容提取的MCP服务器

A Model Context Protocol (MCP) server that enables Amazon Q to intelligently navigate and extract documentation from websites.
Amazon Q uses Claude 4.5 to make smart decisions about which pages to visit and what content to extract.

特性 • 安装 • 设置 • 用法 • 工具

✨ 特性

  • 🧠 智能导航 -Amazon Q（Claude 4.5）决定访问哪些文档页面
  • 🧹 清洁内容提取 -删除导航、广告、脚本和其他非内容元素
  • 📝 多种输出格式 -支持Markdown和纯文本输出
  • 💻 代码块提取 -从文档中具体提取代码示例
  • 📊 页面结构分析 -提取标题层次结构和目录
  • 🔗 链接发现 -查找和筛选文档链接
  • 📚 批处理 -一次阅读多个文档页面

🎯 运作原理

User: "I'm having issues with Razorpay routes"
      Documentation: https://razorpay.com/docs

Amazon Q (Claude 4.5):
  1. Reads main docs page
  2. Sees links: ["Payments", "Routes", "Webhooks", ...]
  3. Intelligently decides: "Routes link is relevant!"
  4. Navigates to Routes documentation
  5. Extracts content and solves your problem

All navigation decisions = Amazon Q's Claude brain 🧠
MCP Server = Clean content extraction tool 🛠️

📦 安装

先决条件

步骤1：克隆存储库

git clone https://github.com/yourusername/amazon-q-web_search.git
cd amazon-q-web_search

步骤2：安装依赖项

使用紫外线（推荐）：

uv sync

使用pip：

pip install -e .

🔧 使用Amazon Q进行设置

步骤1：找到您的MCP配置文件

Amazon Q在以下位置查找MCP服务器配置：

  • Linux/WSL: ~/.aws/amazonq/mcp.json
  • macOS: ~/.aws/amazonq/mcp.json
  • 视窗: %USERPROFILE%\.aws\amazonq\mcp.json

步骤2：创建/编辑配置文件

如果目录不存在，请创建该目录：

mkdir -p ~/.aws/amazonq

编辑或创建 ~/.aws/amazonq/mcp.json:

对于Linux/WSL：

{
  "mcpServers": {
    "doc_reader": {
      "command": "/full/path/to/amazon-q-web_search/.venv/bin/python",
      "args": ["/full/path/to/amazon-q-web_search/main.py"]
    }
  }
}

对于macOS：

{
  "mcpServers": {
    "doc_reader": {
      "command": "/full/path/to/amazon-q-web_search/.venv/bin/python",
      "args": ["/full/path/to/amazon-q-web_search/main.py"]
    }
  }
}

对于Windows：

{
  "mcpServers": {
    "doc_reader": {
      "command": "C:\\full\\path\\to\\amazon-q-web_search\\.venv\\Scripts\\python.exe",
      "args": ["C:\\full\\path\\to\\amazon-q-web_search\\main.py"]
    }
  }
}

💡 提示： 替换 /full/path/to/ 使用克隆存储库的实际路径。

步骤3：验证安装

  1. 启动Amazon Q CLI：

    q chat

  2. 检查MCP服务器是否已加载：

    /mcp

    您应该看到：

    doc_reader
  - read_web_documentation
  - get_documentation_links
  - get_page_structure
  - extract_code_examples
  - read_multiple_docs

  3. 如果未加载：

    • 检查中的文件路径 mcp.json 是正确的
    • 重新启动Amazon Q CLI
    • 检查日志： q chat logdump

🚀 用法

基础示例

在Amazon Q CLI中，只需询问文档：

I'm having issues with Razorpay routes. Can you help me understand how they work?
Documentation: https://razorpay.com/docs/

亚马逊Q将：

  1. ✅ 阅读主文档页面
  2. ✅ 提取所有可用链接
  3. ✅ 智能识别“路由”链接
  4. ✅ 导航到路线文档
  5. ✅ 为您提供准确的信息

更多示例

Python文档：

Can you explain Python asyncio event loops?
Documentation: https://docs.python.org/3/library/asyncio.html

FastAPI教程：

How do I create a basic FastAPI application?
Documentation: https://fastapi.tiangolo.com/

AWS Lambda：

How do I create a Lambda function with Python?
Documentation: https://docs.aws.amazon.com/lambda/

🛠 可用工具

Amazon Q智能地链接这些工具来浏览文档：

1. read_web_documentation

从网页中提取干净的文档内容。

参数：

  • url （必填）：文档页面的URL
  • output_format （可选）： "markdown" （默认）或 "text"

退货： 提取带有标题和元数据的文档内容

2. get_documentation_links

使用可选筛选从文档页面中提取所有链接。

参数：

  • url （必填）：文档页面的URL
  • filter_pattern （可选）：过滤链接的模式（例如。， "api", "guide")

退货： 页面上找到的链接列表

3. get_page_structure

从文档页面中提取标题结构和目录。

参数：

  • url （必填）：文档页面的URL

退货： 页面标题的层次结构

4. extract_code_examples

从文档页面中提取所有代码块。

参数：

  • url （必填）：文档页面的URL

退货： 使用检测到的语言找到的所有代码块

5. read_multiple_docs

读取多个文档页面并组合其内容。

参数：

  • urls （必填）：文档URL列表（最多10个）

退货： 所有页面的组合内容

📁 项目结构

amazon-q-web_search/
├── main.py              # Entry point
├── pyproject.toml       # Project configuration
├── README.md            # This file
├── run_mcp.sh           # Startup script (Linux/macOS)
└── src/
    ├── __init__.py      # Package initialization
    ├── server.py        # MCP server initialization
    ├── config.py        # Configuration constants
    ├── fetcher.py       # HTTP fetching logic
    ├── extractor.py     # HTML content extraction
    ├── formatters.py    # Output formatting
    └── tools.py         # MCP tool definitions

⚙️ 配置

编辑 src/config.py 要自定义行为：

设置 默认值 说明
HTTP_TIMEOUT 30.0s 请求超时（秒）
MAX_CONTENT_LENGTH 10MB 最大内容大小（字节）
USER_AGENT 自定义 HTTP用户代理字符串
REMOVE_TAGS 提取过程中要删除的各种 HTML标签
CONTENT_SELECTORS 各种 查找主要内容的选择器

🐛 故障排除

MCP服务器未加载

检查配置：

cat ~/.aws/amazonq/mcp.json

验证路径是否正确：

  • 使用绝对路径，而不是相对路径
  • 检查Python可执行文件是否存在
  • 检查main.py是否存在

手动测试服务器：

cd /path/to/amazon-q-web_search
.venv/bin/python main.py

查看亚马逊Q日志：

q chat logdump

服务器启动，但工具不起作用

验证是否安装了依赖项：

cd /path/to/amazon-q-web_search
.venv/bin/python -c "import httpx, bs4, markdownify; print('OK')"

重新安装依赖关系：

uv sync --reinstall

连接超时

增加设置中的超时时间：

q settings mcp.initTimeout 60000

📚 依赖项

包装 用途
httpx 用于获取网页的异步HTTP客户端
美容组4 HTML解析和导航
lxml 文件 快速XML/HTML解析器
标记化 HTML到Markdown的转换
主控程序 模型上下文协议SDK

⚠️ 局限性

限制 值
最大内容大小 每页10MB
每批最大URL数 10
请求超时 30秒
内容类型 仅限HTML

🤝 贡献

欢迎投稿！请随时提交拉取请求。

  1. 复刻仓库
  2. 创建功能分支(git checkout -b feature/AmazingFeature)
  3. 提交您的更改(git commit -m 'Add some AmazingFeature')
  4. 推到分支(git push origin feature/AmazingFeature)
  5. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

💬 支持

  • 📫 打开一个 问题 用于错误报告或功能请求
  • ⭐ 如果你觉得这个仓库有用，就把它标上！
Built with ❤️ for Amazon Q Developer

相关 MCP