用途
mcp-page-capture 是一个 Model Context Protocol (MCP) 服务器，通过 Puppeteer 编排无头 Chromium，对任意 URL 进行像素级截图，并返回 MCP 兼容的元数据，供自动化工作流使用。它面向 Copilot/MCP 启用环境，可嵌入自动化流程或作为独立开发者工具运行。
主要能力
- 由 Puppeteer 与无头 Chromium 驱动的高保真截图，支持视口截图与整页截图。
- LLM 优化的 schema，暴露最少参数并提供合理默认值。
- 结构化 DOM 提取，可选 CSS 选择器，便于 AI 消费。
- 设备预设用于移动端模拟（iPhone、iPad、Android、桌面）。
- 六种简化步骤，便于 LLM 使用：viewport、wait、fill、click、scroll、screenshot。
- 智能默认：省略时自动截图，字段类型自动检测。
- 一致的参数命名：target 用于元素，for 用于等待，to 用于滚动，device 用于视口。
- 瞬态失败时自动重试并采用指数退避。
- 遥测钩子用于集中可观测性与监控。
- 可插拔存储后端（本地文件系统、S3、内存）。
- 结构化日志及防御性错误处理，便于运维可见性。
- 可通过 npm start、npm run dev 启动，或作为长期运行的 MCP 边车（sidecar）。
- 提供多平台 Docker 镜像（amd64、arm64）。
使用方式
MCP 传输启动一个 Node.js 服务器并注册 captureScreenshot 和 extractDom 工具。传入的工具调用会根据相关类型定义进行验证。Puppeteer 启动（或复用）Chromium 实例，导航至请求的 URL，并根据工具参数获取截图或序列化 DOM。服务器向调用方或下游工作流返回结构化内容（图像、文本、DOM 树、元数据）。
从源代码运行（开发时推荐）：
npm install
npm start
运行服务器：本地迭代时热重载运行 npm run dev。
Docker 构建与运行：
docker build -t mcp-page-capture .
docker run -p 3000:3000 mcp-page-capture
（Docker 提供一致环境，可作为边车/服务部署到 Kubernetes、ECS、Fly.io 等。）
IDE MCP 配置：可能需要使用 dist/cli.js 或 node 的完整路径，具体取决于工作目录和 Node.js 模块解析配置。
程序化使用：可将服务器嵌入另一个 Node.js 进程，导入包暴露的辅助函数。
六种步骤类型（恰好六种）
步骤顺序：自动修正！viewport 自动移到首位，screenshot 自动添加到末尾。
- viewport：设置视口或设备预设。
- wait：等待。参数 for 用于等待条件，如选择器或时长。
- fill：填充表单字段，自动检测字段类型并处理文本输入、下拉选择、复选框和单选按钮。
- click：点击元素，参数 target。
- scroll：滚动页面，参数 to（如 'bottom'）。
- screenshot：截图，可指定 fullPage 等。
复合模式（新版）：可自动展开为多个步骤的高层模式。
验证模式：使用 validate: true 在执行前检查步骤，返回验证分析，包括：错误（缺少必需参数）、警告（步骤顺序问题，例如 viewport 不在第一位）、建议（推荐改进，例如为 click 增加 waitFor）、步骤分析（每步状态与说明）。
工具调用示例
注意：如果未提供显式 screenshot 步骤，结尾会自动截图。fill 步骤自动检测字段类型并处理文本输入、下拉选择、复选框和单选按钮。
表单填充字段支持：
- selector（必需）：表单字段的 CSS 选择器。
- value（必需）：要设置的值。复选框使用 "true" 或 "false"。下拉/单选使用 value 属性。
- type（可选）：字段类型提示（text、select、checkbox、radio、textarea、password、email、number、tel、url、date、file）。未指定时自动检测。
- matchByText（可选）：对于 select 字段，按可见文本而非 value 属性匹配。
- delay（可选）：文本输入时击键之间的延迟（毫秒）。
- formSelector（可选）：表单容器的 CSS 选择器（用于限定字段选择器作用域）。
- submit（可选）：填写后是否提交表单（默认 false）。
- submitSelector（可选）：提交按钮的选择器。未指定时使用 form.submit() 或查找 [type="submit"]。
- waitForNavigation（可选）：提交后是否等待导航（默认 true）。
示例响应中 fields 数组的每个字段支持上述选项。
高级步骤（运行时可用，但不在 LLM schema 中暴露）
type、hover、cookie、storage、evaluate、keypress、focus、blur、clear、upload、submit。
旧参数支持：为向后兼容，部分旧参数在运行时可用，但不在 LLM schema 中暴露，使用时记录弃用警告。
视口预设
可用视口预设包括：desktop-fhd（1920x1080）、desktop-hd（1280x720）、desktop-4k（3840x2160）、macbook-pro-16、ipad-pro（12.9 英寸）、ipad-pro-landscape、ipad（10.2 英寸）、surface-pro、iphone-14-pro-max、iphone-14-pro、iphone-se（第三代）、pixel-7-pro、galaxy-s23-ultra。
重试与遥测
工具在瞬态失败时自动重试并采用指数退避。默认可重试条件：HTTP 状态码 500、502、503、504、408、429；网络错误 ETIMEDOUT、ECONNRESET、ENOTFOUND、ECONNREFUSED；DNS 解析失败。可自定义重试策略。
服务器发出结构化遥测事件：tool.invoked、tool.completed、tool.failed、navigation.started、navigation.completed、navigation.failed、retry.attempt、retry.succeeded、browser.launched、browser.closed、screenshot.captured、dom.extracted。可编程配置遥测钩子。
存储后端
截图可自动保存到可配置的存储后端：
- 本地文件系统。
- S3 兼容存储。 可在工具调用中使用存储。
适用场景
- 自动化工作流中的网页截图与 DOM 提取。
- 与 Copilot/MCP 启用环境集成。
- 作为独立开发者工具或长期运行的 MCP 边车。
- 需要移动端模拟、表单交互、结构化数据提取的 AI 友好场景。
限制
- 需要首次运行时下载 Chromium 包的权限，以及访问目标 URL 的网络连接。
- 需要复杂认证流程或用户手势的动态页面尚未自动化。
- 极长或无限滚动页面可能超出默认 Chromium 内存限制。
- S3 存储后端需要 AWS SDK 集成（包含占位实现）。
发布与贡献
发布自动化由 semantic-release 和 GitHub Actions 驱动。提交必须遵循 Conventional Commits 规范（feat:、fix:、chore:）以自动版本化。成功构建后发布到 npm。多平台镜像（linux/amd64、linux/arm64）自动构建并发布到 Docker Hub 和 GitHub Container Registry，标记语义版本、major、major.minor 和 latest。所需仓库密钥：NPM_TOKEN、DOCKER_USERNAME、DOCKER_PASSWORD；GITHUB_TOKEN 由 GitHub Actions 自动提供。
贡献方式：阅读 CONTRIBUTING.md，打开描述变更的 issue，提交包含 npm run build 输出及更新文档/测试的 PR。
作者/维护者：由 Saurabh Chase (@chasesaurabh) 维护。通过 issues 或 discussions 联系以协调路线图。
许可证：MIT License。
