A Model Context Protocol server for browser automation using Puppeteer with Linux display server support
This MCP server exposes 7 browser automation tools with visible schemas and basic descriptions. However, critical issues undermine quality: (1) Parameter descriptions are inconsistent and often missing for complex parameters like width/height defaults. (2) Output schemas are completely undocumented, the tool implementations return structured responses (console logs, screenshot data, navigation results) but the server provides NO schema documentation for what these returns contain. (3) Error handling is absent, no guidance on what happens when selectors fail, navigation times out, or JavaScript execution errors. (4) Descriptions lack WHEN to use each tool and prerequisites, e.g., puppeteer_evaluate doesn't explain it requires an active page. (5) The puppeteer_evaluate tool is high-risk (WRITE classification) but has no warning about side effects or irreversibility. (6) No input validation hints in descriptions, e.g., CSS selectors are not constrained or validated. (7) Tool names are verb-noun formatted (good), but descriptions are uniformly terse (10-52 chars) and lack actionability. Based on rubric baseline (average tool description should be 194 chars), these are 80% too short. Across the 7 tools, 5 have descriptions under 50 chars, which violates the rule: 'If descriptions are under 20 characters, description score CANNOT exceed 40.' While all descriptions here exceed 20 chars, most cluster near minimum viable length.
Click an element on the page
Execute JavaScript in the browser console
Fill out an input field
Hover an element on the page
Navigate to a URL
Take a screenshot of the current page or a specific element
Select an element on the page with Select tag
Output schemas completely undocumented. Tools return structured data (e.g., handleToolCall returns {content: [{type, text}], isError}) but no schema is provided to the LLM. LLMs cannot predict what data fields to expect in responses, making downstream tool chaining and data extraction error-prone.
Descriptions are uniformly terse (10-52 chars vs. baseline 194 chars). No guidance on WHEN to call each tool, prerequisites, or dependencies. Example: 'Click an element on the page' does not explain what happens if selector fails, whether click triggers navigation, or if the element must be visible first.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 47 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 40 | - | v1 |
No error handling guidance. Tools can fail (selector not found, navigation timeout, JavaScript error) but handleToolCall provides no recovery hints. An LLM receives an error but cannot determine: Is this retryable? Should I modify the selector? Call a different tool? Pattern: recovery-guide absent.
puppeteer_evaluate (high-risk, WRITE) lacks side-effect warnings. Description 'Execute JavaScript in the browser console' does not warn that arbitrary JS can modify DOM, trigger requests, or cause irreversible changes. LLMs will use this casually without understanding consequences.
Parameter constraints undocumented. 'selector' parameters accept CSS selector strings but no description specifies format, escaping rules, or examples. 'width' and 'height' have defaults (800, 600) but no min/max bounds, an LLM could pass width=999999 or width=-1.
No dependencies or prerequisites documented. Tools assume an active browser and page exist (managed by ensureBrowser() at runtime) but descriptions do not explain: Must navigate first? Are page interactions sequential or concurrent? What happens if browser launch fails?
puppeteer_screenshot parameter 'width' and 'height' descriptions mention defaults ('default: 800', 'default: 600') but implementation uses nullish coalesce (??), if width/height are optional, this should be explicit in the schema (not required) and description should clarify viewport vs. screenshot dimensions.