MCP大师木偶师
claude mcp add mcp-master-puppeteer -- npx -y github:flrngel/mcp-master-puppeteer#main使用Puppeteer实现浏览器自动化的高级MCP（模型上下文协议）服务器，针对最小的令牌使用进行了优化，同时在需要时提供全面的数据。
特性
🎯 代币优化回报
每个工具的设计都是为了在保持实用性的同时最大限度地减少令牌的使用：
- 默认最小值：除非要求，否则只返回基本数据
- 无重复内容：从不同时返回markdown和HTML
- 智能默认值：针对代理决策进行了优化
- 可选丰富：使用标志请求其他数据
🚀 关键设计原则
- 代币效率优先：响应大小减少60-70%
- 智能选择性退货：仅包括有助于决策的数据
- 无冗余：消除了重复数据和不必要的元数据
- 渐进增强：从最小开始，根据需要添加细节
📊 可用工具
1.木偶_导航_分析
导航到URL并返回页面状态、标题以及可选的内容/元数据。默认内容格式为“无”，以获得最快的响应。
选项：
{
url: string; // Required: URL to navigate to
waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2"; // Default: "networkidle0"
timeout?: number; // Navigation timeout in ms (default: 30000)
contentFormat?: "markdown" | "html" | "plain-text"; // Default: "markdown"
includeMetadata?: boolean; // Include page metadata (default: false)
includePerformance?: boolean; // Include performance metrics (default: false)
}退货：
{
navigationInfo: {
originalUrl: string;
finalUrl: string;
statusCode: number;
statusText: string;
redirectChain: string[];
navigationTimeMs: number;
};
// Always included - minimal essential data
url: string; // Final URL after redirects
statusCode: number;
title: string;
content?: string; // Omitted if contentFormat is "none"
contentFormat: ContentFormat;
// Optional - only if there are errors
errors?: PageError[];
// Optional - only if includeMetadata is true
metadata?: {
redirectChain?: string[];
description?: string;
openGraph?: Record;
twitterCard?: Record;
};
// Optional - only if includePerformance is true
performance?: {
loadTimeMs: number;
resourceCounts: {
total: number;
images: number;
scripts: number;
stylesheets: number;
};
};
}2.木偶师\_ creenshot_plus
拍摄针对LLM处理进行优化的屏幕截图，自动调整大小以保持在尺寸限制范围内。自动调整到Claude.ai的限制：单张图像为8000×8000，多张图像为2000×2000。
选项：
{
name: string; // Required: Name for the screenshot(s)
breakpoints?: number[]; // Viewport widths (default: [375, 768, 1280])
selector?: string; // CSS selector for element screenshot
fullPage?: boolean; // Capture full page height (default: true)
format?: "png" | "jpeg" | "webp"; // Image format (default: "jpeg")
quality?: number; // JPEG/WebP quality 0-100 (default: 80)
actions?: PageAction[]; // Actions to perform before screenshot
resizeForLLM?: boolean; // Resize to stay under max dimension (default: true)
maxDimension?: number; // Max width or height. Default: 8000 (single), 2000 (multiple)
resizeStrategy?: "cut" | "resize"; // How to handle oversized images (default: "cut")
}退货：
{
screenshots: Array;
// Optional - only if there are errors
errors?: PageError[];
}3.木偶师_提取_内容
使用格式选项和详细元数据从页面中提取结构化内容。
选项：
{
selector?: string; // CSS selector to extract from (default: full page)
includeHidden?: boolean; // Include hidden elements (default: false)
outputFormat?: "markdown" | "html" | "plain-text" | "structured-json"; // Default: "markdown"
includeAnalysis?: boolean; // Include detailed structure analysis (default: false)
}退货：
{
// Always included
content: string; // In requested format
contentFormat: ContentFormat;
wordCount: number;
// Optional - only if includeAnalysis is true
analysis?: {
headings: Array;
links: Array;
images: Array;
tables: number; // Just count
lists: {
ordered: number;
unordered: number;
};
};
}4.木偶师_get_page_info
获取全面的页面元数据、SEO评估、可访问性指标和性能指标。
选项：
{
sections?: Array; // Default: ["seo"]
}退货：
{
pageIdentification: {
currentUrl: string;
canonicalUrl?: string;
title: string;
language?: string;
charset?: string;
lastModified?: string;
};
metadataAnalysis: {
metaTags: {
basic: {
description?: string;
keywords?: string;
author?: string;
robots?: string;
viewport?: string;
};
openGraph: Record;
twitterCard: Record;
dublin: Record;
other: Record;
};
structuredData: {
hasJsonLd: boolean;
hasMicrodata: boolean;
hasRDFa: boolean;
schemas: string[];
};
};
seoAssessment: {
titleAnalysis: {
exists: boolean;
content: string;
lengthCharacters: number;
isOptimal: boolean; // 30-60 chars
issues: string[];
};
descriptionAnalysis: {
exists: boolean;
content?: string;
lengthCharacters: number;
isOptimal: boolean; // 120-160 chars
issues: string[];
};
headingStructure: {
hasH1: boolean;
h1Count: number;
h1Content: string[];
totalHeadings: number;
isHierarchical: boolean;
issues: string[];
};
canonicalStatus: {
hasCanonical: boolean;
canonicalUrl?: string;
isSelfReferencing: boolean;
issues: string[];
};
crawlability: {
isIndexable: boolean;
robotsDirectives: string[];
sitemapReference?: string;
};
};
accessibilityMetrics: {
documentStructure: {
hasProperDoctype: boolean;
hasLangAttribute: boolean;
declaredLanguage?: string;
hasTitle: boolean;
};
landmarks: {
hasMain: boolean;
hasNav: boolean;
hasHeader: boolean;
hasFooter: boolean;
hasAside: boolean;
landmarkRoles: string[];
skipLinks: boolean;
};
headingAnalysis: {
properHierarchy: boolean;
headingLevels: number[];
missingLevels: number[];
};
imageAccessibility: {
totalImages: number;
imagesWithAlt: number;
imagesWithEmptyAlt: number;
decorativeImages: number;
altTextCoveragePercent: number;
missingAltImages: number;
};
formAccessibility: {
totalForms: number;
formsWithLabels: number;
inputsWithoutLabels: number;
ariaUsage: boolean;
};
};
performanceIndicators: {
pageWeight: {
htmlSizeBytes: number;
totalResourcesBytes?: number;
imageOptimization: "good" | "needs-improvement" | "poor";
};
resourceCounts: {
totalRequests: number;
images: number;
scripts: number;
stylesheets: number;
fonts: number;
other: number;
};
criticalMetrics?: {
hasViewportMeta: boolean;
hasFaviconDefined: boolean;
usesHTTPS: boolean;
hasServiceWorker: boolean;
};
};
pageStructureOutline: string;
}5.木偶师_分析_形式
使用详细的字段信息和目的检测分析页面上的所有表单。
选项：
// No options - analyzes all forms on the current page退货：
{
formCount: number;
forms: FormInfo[]; // Basic form information
summary: {
totalInputs: number;
inputTypes: Record;
requiredFields: number;
hasFileUpload: boolean;
hasPasswordField: boolean;
formPurposes: string[]; // Detected purposes
};
}6.木偶戏互动
按顺序执行多个页面交互，并获得详细结果。
选项：
{
actions: Array;
stopOnError?: boolean; // Stop on first error (default: false)
}退货：
{
results: Array;
finalState: {
url: string;
title: string;
};
// Optional - only if there are errors
errors?: PageError[];
}7.木偶戏（简单）
单击页面上的元素。
选项：
{
selector: string; // Required: CSS selector
}8.木偶戏（简单）
填写输入字段。
选项：
{
selector: string; // Required: CSS selector
value: string; // Required: Value to fill
}常见类型
页面错误
{
type: "javascript" | "console" | "network" | "security";
level: "error" | "warning" | "info";
message: string;
source?: string;
line?: number;
column?: number;
timestamp: string;
url?: string;
statusCode?: number;
}错误摘要
{
totalErrors: number;
totalWarnings: number;
totalLogs: number;
hasJavaScriptErrors: boolean;
hasNetworkErrors: boolean;
hasConsoleLogs: boolean;
}安装
npm install mcp-master-puppeteer
# Or run directly
npx mcp-master-puppeteer配置
添加到MCP设置中：
{
"mcpServers": {
"puppeteer": {
"command": "mcp-master-puppeteer",
"args": [],
"env": {
"PUPPETEER_ARGS": "{\"headless\": false}"
}
}
}
}使用示例
使用智能默认值导航
// Default: no content extraction for fastest response
await puppeteer_navigate_analyze({
url: "https://example.com"
});
// Returns:
// {
// url: "https://example.com",
// statusCode: 200,
// title: "Example Domain",
// contentFormat: "none",
// metadata: {
// description: "Example Domain for use in examples"
// }
// }
// With content extraction
await puppeteer_navigate_analyze({
url: "https://example.com",
contentFormat: "markdown"
});
// Returns with content field populated
// Truly minimal response
await puppeteer_navigate_analyze({
url: "https://example.com",
includeMetadata: false
});
// Returns only: url, statusCode, title, contentFormat高效提取内容
// Structured JSON includes analysis by default
await puppeteer_extract_content({
outputFormat: "structured-json"
});
// Returns:
// {
// content: "{...json with headings, paragraphs...}",
// contentFormat: "structured-json",
// wordCount: 150,
// analysis: { // Included automatically for structured-json
// headings: [...],
// links: [...],
// images: [...]
// }
// }
// Markdown without analysis
await puppeteer_extract_content({
outputFormat: "markdown",
includeAnalysis: false // Default for non-structured formats
});针对LLM优化的捕获屏幕截图
// Default: resized for LLM processing
await puppeteer_screenshot_plus({
name: "homepage",
breakpoints: [375, 768, 1280],
format: "jpeg",
quality: 85
});
// Multiple screenshots: auto-resized to 2000×2000 max
// Single screenshot with custom limit
await puppeteer_screenshot_plus({
name: "homepage",
breakpoints: [1920], // Single breakpoint = 8000×8000 max by default
resizeForLLM: true,
maxDimension: 4096 // Custom max dimension
});
// Disable resizing for full quality
await puppeteer_screenshot_plus({
name: "homepage",
breakpoints: [1920],
resizeForLLM: false // Keep original size
});
// Use cut strategy (default) - crops image to fit
await puppeteer_screenshot_plus({
name: "cropped",
breakpoints: [1920],
maxDimension: 800,
resizeStrategy: "cut" // Crops to 800x800 max
});
// Use resize strategy - scales down viewport
await puppeteer_screenshot_plus({
name: "scaled",
breakpoints: [1920],
maxDimension: 800,
resizeStrategy: "resize" // Scales viewport to fit within 800px
});分析页面进行SEO
await puppeteer_get_page_info();
// Returns comprehensive analysis:
// - SEO assessment with specific issues
// - Accessibility metrics with scores
// - Performance indicators
// - Structured data detection
// - Complete meta tag analysis以最小回报执行操作
await puppeteer_batch_interact({
actions: [
{ type: "type", selector: "#search", text: "puppeteer" },
{ type: "click", selector: "#search-button" },
{ type: "waitForSelector", selector: ".results", timeout: 5000 }
]
});
// Returns:
// - Success/failure for each action
// - Page changes only if navigation occurred
// - Final URL and title
// - Errors only if present令牌优化详细信息
之前vs之后
navigation分析之前：平均响应约2500个令牌 导航分析之后：约600个令牌（默认为基本元数据），约400个令牌（最小值）
关键优化：
- 智能默认设置：包括基本元数据，完整细节可选择加入
- 已删除处理统计数据（原始SizeBytes，reductionPercent）
- 消除了内容重复（请求降价时没有原始HTML）
- 默认情况下只有基本元数据（描述、ogImage）
- 性能指标仅可选择
- 错误仅在存在时才包括在内
提取前内容：平均约1800个代币 提取内容后：约300个令牌（最小值），约600个令牌（带分析）
screenshotPlus之前：每张截图约1200个令牌 screenshotPlus之后：每张截图约150个令牌
屏幕截图大小调整
自动调整屏幕截图大小以符合Claude.ai限制：
- 单个图像：最大8000×8000像素
- 多个图像：每张图像最大2000×2000像素
- 调整大小时保持纵横比
- 可定制
maxDimension参数
调整策略：
- “剪切”（默认）：裁剪图像以适应最大尺寸，保持原始视口大小
- “调整大小”：缩小视口以适应最大尺寸，从而产生更小的文件大小
“剪切”策略是首选，因为它保持了原始页面布局，同时确保图像符合LLM限制。当您需要整个页面内容可见但比例缩小时，“调整大小”策略非常有用。
何时使用选项
默认行为：
navigateAnalyze：包括基本元数据（描述、ogImage）extractContent：包括对结构化json格式的分析getPageInfo：返回SEO和元数据部分
覆盖默认值：
includeMetadata: false：用于真正的最小导航includePerformance: true：用于调试性能问题includeAnalysis: false：禁用结构化json分析sections: ['seo']：将getPageInfo限制在特定部分
发展
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Test enhanced features
npx tsx tests/test-manual-enhanced.ts环境变量
PUPPETEER_ARGS-Puppeter启动选项的JSON字符串PUPPETEER_HEADLESS-在headful模式下设置为“false”（默认值：“true”，无头运行）DOCKER_CONTAINER-启用与Docker兼容的浏览器参数
许可证
麻省理工学院