# Changelog of Puppeteer MCP (`meysamazing/puppeteer-mcp`) Actor

- **URL**: https://apify.com/meysamazing/puppeteer-mcp/changelog.md
- **Full Actor documentation**: https://apify.com/meysamazing/puppeteer-mcp.md

## Changelog

All notable changes to the Puppeteer MCP Actor will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

### [1.5.2](https://github.com/meysam81/puppeteer-mcp/compare/v1.5.1...v1.5.2) (2025-12-09)

#### Bug Fixes

- **docs:** update sse to http transport ([1850522](https://github.com/meysam81/puppeteer-mcp/commit/18505222baf008b3f8af6d0a194cd33d5b1fa41d))

### [1.5.1](https://github.com/meysam81/puppeteer-mcp/compare/v1.5.0...v1.5.1) (2025-12-09)

#### Bug Fixes

- address broken navigation and reliability issues ([#86](https://github.com/meysam81/puppeteer-mcp/issues/86)) ([959a941](https://github.com/meysam81/puppeteer-mcp/commit/959a941c65703c6cc7bff800ae5da39549b4b97b))

### [1.5.0](https://github.com/meysam81/puppeteer-mcp/compare/v1.4.7...v1.5.0) (2025-12-09)

#### Features

- **monetization:** add PPE pricing configuration for Apify marketplace ([#85](https://github.com/meysam81/puppeteer-mcp/issues/85)) ([1dd8331](https://github.com/meysam81/puppeteer-mcp/commit/1dd83311e36c4f7a11484698062fd7c57c6df6b8))

#### Bug Fixes

- do not include image if the request did not ask for it ([3d3994d](https://github.com/meysam81/puppeteer-mcp/commit/3d3994dcf3da0a8b7035a71b2b98a446d536bb5d))

### [1.4.7](https://github.com/meysam81/puppeteer-mcp/compare/v1.4.6...v1.4.7) (2025-12-09)

#### Bug Fixes

- **deps:** update dependency @anthropic-ai/sdk to ^0.71.0 ([#40](https://github.com/meysam81/puppeteer-mcp/issues/40)) ([1081534](https://github.com/meysam81/puppeteer-mcp/commit/1081534573803246d486499758c42e8b527b4584))
- **deps:** update dependency express to v5 ([#41](https://github.com/meysam81/puppeteer-mcp/issues/41)) ([436c09c](https://github.com/meysam81/puppeteer-mcp/commit/436c09c32f0621f1760edc99173485c7f348fda4))
- **deps:** update dependency pino to v10 ([#42](https://github.com/meysam81/puppeteer-mcp/issues/42)) ([72e6f4c](https://github.com/meysam81/puppeteer-mcp/commit/72e6f4c7bc09ea337b9c652d29af5648bdec0f5d))
- shutdown after 2min of inactivity ([4caeedc](https://github.com/meysam81/puppeteer-mcp/commit/4caeedc982a59e924638f38aa46d01513eb43662))

### [1.4.6](https://github.com/meysam81/puppeteer-mcp/compare/v1.4.5...v1.4.6) (2025-12-09)

#### Bug Fixes

- **docs:** remove the redundant TOC ([e09814d](https://github.com/meysam81/puppeteer-mcp/commit/e09814d4ec12fe6283a058e4afb1f529f8bcb946))

### [1.4.5](https://github.com/meysam81/puppeteer-mcp/compare/v1.4.4...v1.4.5) (2025-12-09)

#### Features

- add apify readiness probe ([a494970](https://github.com/meysam81/puppeteer-mcp/commit/a494970d5db8fe436b91b720505ba4ed7b17e94d))
- add comprehensive benchmark suite for PPE pricing validation ([#80](https://github.com/meysam81/puppeteer-mcp/issues/80)) ([c7c107c](https://github.com/meysam81/puppeteer-mcp/commit/c7c107ccb8ee0a764280795eb33d7f860ab71890))
- add security features and fix navigation bugs ([#79](https://github.com/meysam81/puppeteer-mcp/issues/79)) ([a0a4461](https://github.com/meysam81/puppeteer-mcp/commit/a0a446143a531659e3fa12bf63c22784ec9e7d08))

#### Bug Fixes

- address the storage validation issue ([d19ed45](https://github.com/meysam81/puppeteer-mcp/commit/d19ed45717ddd8610c692c0bc253652977f344fc))
- send json in health ([4641eb8](https://github.com/meysam81/puppeteer-mcp/commit/4641eb88ecff82640526a255500c551cf2ba2e73))

### [1.4.4](https://github.com/meysam81/puppeteer-mcp/compare/v1.4.3...v1.4.4) (2025-12-08)

#### Bug Fixes

- allow the override from apify port env var ([b7d4f13](https://github.com/meysam81/puppeteer-mcp/commit/b7d4f1378253d0296a50102d563ddb6e46b84963))

### [1.4.3](https://github.com/meysam81/puppeteer-mcp/compare/v1.4.2...v1.4.3) (2025-12-08)

#### Bug Fixes

- add SSE transport protocol support to MCP server ([#72](https://github.com/meysam81/puppeteer-mcp/issues/72)) ([e2f78e3](https://github.com/meysam81/puppeteer-mcp/commit/e2f78e32df4f0408249d2280ff1039f62b56b527))
- **dev:** lint with prettier ([3f527ac](https://github.com/meysam81/puppeteer-mcp/commit/3f527ac46c1c13dd0ab137d68222efcbc6d9c608))

### [1.4.2](https://github.com/meysam81/puppeteer-mcp/compare/v1.4.1...v1.4.2) (2025-12-07)

#### Bug Fixes

- cast to partial config to avoid compiler error ([8e73651](https://github.com/meysam81/puppeteer-mcp/commit/8e73651709612714b8f6f338dcbaf42825bd9479))
- make compiler happy ([15b6f6a](https://github.com/meysam81/puppeteer-mcp/commit/15b6f6ab7b31405d9323ded8becab4bb0b22c1f2))

### [1.4.1](https://github.com/meysam81/puppeteer-mcp/compare/v1.4.0...v1.4.1) (2025-12-07)

#### Bug Fixes

- add event handler for actor shutdown ([2fd5d62](https://github.com/meysam81/puppeteer-mcp/commit/2fd5d62f2f97702ac32b4390ba4d51932ed4d7de))
- add prefix to utils import ([8d610da](https://github.com/meysam81/puppeteer-mcp/commit/8d610da43df6d9c8e1cc5157da42bae7136137e0))
- adhere to MCP protocol standard ([cd49c11](https://github.com/meysam81/puppeteer-mcp/commit/cd49c1125f6271d7186e9d3c05be24129c7a29a4))
- comply to MCP protocol in response payload ([36c3e48](https://github.com/meysam81/puppeteer-mcp/commit/36c3e48fbda99a142c2e18442a9f93fc32256443))

### [1.4.0](https://github.com/meysam81/puppeteer-mcp/compare/v1.3.4...v1.4.0) (2025-12-07)

#### ⚠ BREAKING CHANGES

- Config fields renamed from *Dataset* to *Storage*
  - screenshotDatasetThreshold -> screenshotStorageThreshold
  - contentDatasetThreshold -> contentStorageThreshold
  - alwaysStoreScreenshotsInDataset -> alwaysStoreScreenshots
  - alwaysStoreContentInDataset -> alwaysStoreContent

#### Features

- add community CTA messages at startup and shutdown ([#65](https://github.com/meysam81/puppeteer-mcp/issues/65)) ([d2688d0](https://github.com/meysam81/puppeteer-mcp/commit/d2688d0f5387f8d29982eb450b0eab2e44011f80))
- add proxy support with Apify Proxy and custom proxy URLs ([#64](https://github.com/meysam81/puppeteer-mcp/issues/64)) ([3b20914](https://github.com/meysam81/puppeteer-mcp/commit/3b209140cd0269762e7fdc9072aae949beb37f37))
- add standardized output schema with dataset views ([#68](https://github.com/meysam81/puppeteer-mcp/issues/68)) ([e979ec8](https://github.com/meysam81/puppeteer-mcp/commit/e979ec87a327c02ea3c4838c6a084e3202195b72))
- optimize storage with KeyValueStore and compression ([#63](https://github.com/meysam81/puppeteer-mcp/issues/63)) ([7f8c133](https://github.com/meysam81/puppeteer-mcp/commit/7f8c133099f00a87827dfe4d3fd47964af05a69b))

#### Bug Fixes

- correct readme path and add memory constraints in actor.json ([#67](https://github.com/meysam81/puppeteer-mcp/issues/67)) ([b7659ce](https://github.com/meysam81/puppeteer-mcp/commit/b7659ce9f1b723745becfe13aa386a8b3e54f0a7))

#### Miscellaneous Chores

- release v1.4.0 ([b24243e](https://github.com/meysam81/puppeteer-mcp/commit/b24243edc6c83c042ec3ba95cfa239b6b5f31e02))

### [1.3.4](https://github.com/meysam81/puppeteer-mcp/compare/v1.3.3...v1.3.4) (2025-12-06)

#### Bug Fixes

- correct dataset URL construction with token support ([#61](https://github.com/meysam81/puppeteer-mcp/issues/61)) ([18c66ab](https://github.com/meysam81/puppeteer-mcp/commit/18c66ab5198b4aff657a5c81799a7b64ba6820ea))

### [1.3.3](https://github.com/meysam81/puppeteer-mcp/compare/v1.3.2...v1.3.3) (2025-12-06)

#### Bug Fixes

- run with bun ([cb32def](https://github.com/meysam81/puppeteer-mcp/commit/cb32def726c6a1aadaf666b2d6a7a987d63a56db))

### [1.3.2](https://github.com/meysam81/puppeteer-mcp/compare/v1.3.1...v1.3.2) (2025-12-06)

#### Bug Fixes

- add xvfb for non-headless mode ([11e80a5](https://github.com/meysam81/puppeteer-mcp/commit/11e80a5a3fd3413ce02ee0bf9a7d051c60887683))
- **CI:** remove docker from GHA ([667db0b](https://github.com/meysam81/puppeteer-mcp/commit/667db0bf7f7708149ccbff60d11ab121b8253341))
- install xauth for gui access ([cdadd15](https://github.com/meysam81/puppeteer-mcp/commit/cdadd1565f0e6421090c939f523cc5a68a7f99ab))
- let apify handle runtime ([e6c7180](https://github.com/meysam81/puppeteer-mcp/commit/e6c7180c29187402c78f6de1f3c411628a308a61))

### [1.3.1](https://github.com/meysam81/puppeteer-mcp/compare/v1.3.0...v1.3.1) (2025-12-06)

#### Bug Fixes

- read version inside the code ([ea6119d](https://github.com/meysam81/puppeteer-mcp/commit/ea6119d6512284e9315a99e6831eb93079927ad1))
- use platform-agnostic config keys ([8c9ec4d](https://github.com/meysam81/puppeteer-mcp/commit/8c9ec4dffe9100575c8d6b847537705a1a27d122))

### [1.3.0](https://github.com/meysam81/puppeteer-mcp/compare/v1.2.3...v1.3.0) (2025-12-04)

#### ⚠ BREAKING CHANGES

- Tool parameters now include optional sessionId field.
- Complete rewrite of the Puppeteer MCP Actor from Go to TypeScript

#### Features

- add handler for notifications/initialized MCP method ([#52](https://github.com/meysam81/puppeteer-mcp/issues/52)) ([091f683](https://github.com/meysam81/puppeteer-mcp/commit/091f683620ffe765b82182d89dbfe99e95daa152))
- add session persistence and 10 new browser tools for reliable web browsing ([#47](https://github.com/meysam81/puppeteer-mcp/issues/47)) ([90795c6](https://github.com/meysam81/puppeteer-mcp/commit/90795c661051844c02605c74f529ec1cd1dd8593))
- allow taking screenshots in various formats ([171be14](https://github.com/meysam81/puppeteer-mcp/commit/171be1468b39c2d9cf3572da764021ca826bcb3d))
- prepare Apify actor for production release ([#51](https://github.com/meysam81/puppeteer-mcp/issues/51)) ([298802a](https://github.com/meysam81/puppeteer-mcp/commit/298802ae9d8ddf66dcfd8ff8f624d0dba34b88a2))
- rewrite codebase from Go to TypeScript/JavaScript ([#39](https://github.com/meysam81/puppeteer-mcp/issues/39)) ([ecc9ebd](https://github.com/meysam81/puppeteer-mcp/commit/ecc9ebd440c96b88b6b1ea0c37ec8e1097e61633))

#### Bug Fixes

- **CI:** update workflow after go to ts migration ([#46](https://github.com/meysam81/puppeteer-mcp/issues/46)) ([37ff698](https://github.com/meysam81/puppeteer-mcp/commit/37ff6987397ed1896a228a019bd62f0721047182))
- **deps:** update module github.com/rs/zerolog to v1.34.0 ([#34](https://github.com/meysam81/puppeteer-mcp/issues/34)) ([eae9d25](https://github.com/meysam81/puppeteer-mcp/commit/eae9d25ccbe321502ae61ec9a1af89b1018a979d))
- **dev:** do not track envrc ([ffa0ee1](https://github.com/meysam81/puppeteer-mcp/commit/ffa0ee19862a3dccab26eb6776f776fabc7c52e0))
- document MCP project tools and API ([#49](https://github.com/meysam81/puppeteer-mcp/issues/49)) ([14ff939](https://github.com/meysam81/puppeteer-mcp/commit/14ff9396da533ab69a1c8fa744ae88573ec3e5ff))
- standardize tool output to json format ([#50](https://github.com/meysam81/puppeteer-mcp/issues/50)) ([038ff44](https://github.com/meysam81/puppeteer-mcp/commit/038ff44946b2c4f3931a7d06712fb3e893a3dc44))

#### Miscellaneous Chores

- release v1.3.0 ([3cfe97d](https://github.com/meysam81/puppeteer-mcp/commit/3cfe97da587a1fcee9d72307d90e7f3f0106875b))

### [1.2.3](https://github.com/meysam81/puppeteer-mcp/compare/v1.2.2...v1.2.3) (2025-11-24)

#### Bug Fixes

- listen to apify-specified port on standby mode ([12eb63c](https://github.com/meysam81/puppeteer-mcp/commit/12eb63c6f3dcde139fa646b462ede9dcd2d29bd2))

### [1.2.2](https://github.com/meysam81/puppeteer-mcp/compare/v1.2.1...v1.2.2) (2025-11-24)

#### Bug Fixes

- **CI:** do not change actor definition ([3cfae77](https://github.com/meysam81/puppeteer-mcp/commit/3cfae77234a1803a703d08a16f16b649a2358fa4))

### [1.2.1](https://github.com/meysam81/puppeteer-mcp/compare/v1.2.0...v1.2.1) (2025-11-24)

#### Bug Fixes

- add verbose and useful logging ([8cd7290](https://github.com/meysam81/puppeteer-mcp/commit/8cd7290018b48fb1c94afdde73824650829d0eb5))
- **doc:** lint ([d865807](https://github.com/meysam81/puppeteer-mcp/commit/d8658078f2b284fa7718d62459188b7ec5c093c2))

### [1.2.0](https://github.com/meysam81/puppeteer-mcp/compare/v1.1.0...v1.2.0) (2025-11-24)

#### Features

- **docs:** Simplify README for end-user focus ([#30](https://github.com/meysam81/puppeteer-mcp/issues/30)) ([8fe9f7c](https://github.com/meysam81/puppeteer-mcp/commit/8fe9f7c8c444822c267e78043671f622aa8f4b31))
- **security:** implement least privilege with limited permissions ([#31](https://github.com/meysam81/puppeteer-mcp/issues/31)) ([25d17af](https://github.com/meysam81/puppeteer-mcp/commit/25d17aff0d96dfaf83840c400bacefe88267ee87))

#### Bug Fixes

- **CI:** use version flag ([1013c80](https://github.com/meysam81/puppeteer-mcp/commit/1013c80f7456cb44b8153ce2bdd61ecc7bb93631))

### [1.1.0](https://github.com/meysam81/puppeteer-mcp/compare/v0.1.1...v1.1.0) (2025-11-24)

#### ⚠ BREAKING CHANGES

- Documented major architectural shift from single-page reuse to browser pooling implementation.

#### Features

- **dev:** optimize browser with pooling ([187fc53](https://github.com/meysam81/puppeteer-mcp/commit/187fc5380a9c2b8d1e9b890cb1c286ef964358f8))

#### Bug Fixes

- **CI:** pass the docker build ([b6fb298](https://github.com/meysam81/puppeteer-mcp/commit/b6fb29842c54783b8a67d3e7de3021c1c7edc7a1))
- **dev:** add my custom tooling ([9326358](https://github.com/meysam81/puppeteer-mcp/commit/932635801f3c10b914a987ad0fefa2edbcaa3c0a))
- **dev:** do not track ignore dir ([2675fe5](https://github.com/meysam81/puppeteer-mcp/commit/2675fe5a1898a6a3dfbac6a2482763e950431b34))

#### Documentation

- update CLAUDE.md with browser pooling architecture ([#27](https://github.com/meysam81/puppeteer-mcp/issues/27)) ([2c388ce](https://github.com/meysam81/puppeteer-mcp/commit/2c388ce1d657dff6272ef90638f148acd877d1a1))

### [0.1.1](https://github.com/meysam81/puppeteer-mcp/compare/v0.1.0...v0.1.1) (2025-11-14)

#### Bug Fixes

- **CI:** release to apify with MAJOR.MINOR ([#13](https://github.com/meysam81/puppeteer-mcp/issues/13)) ([6044128](https://github.com/meysam81/puppeteer-mcp/commit/60441284d04b1938b55879d362825d95f610bac6))

### 0.1.0 (2025-11-14)

#### Features

- add comprehensive CI/CD workflow ([#5](https://github.com/meysam81/puppeteer-mcp/issues/5)) ([f1bacc7](https://github.com/meysam81/puppeteer-mcp/commit/f1bacc75e2291fd0e788f0daa98187c9d17f0bce))
- Initial implementation of Puppeteer MCP Actor for Apify Store ([#1](https://github.com/meysam81/puppeteer-mcp/issues/1)) ([219508f](https://github.com/meysam81/puppeteer-mcp/commit/219508f570b43dd242c971d7f2eb802607dca071))
- optimize Dockerfile with comprehensive caching strategies ([#11](https://github.com/meysam81/puppeteer-mcp/issues/11)) ([db5a25c](https://github.com/meysam81/puppeteer-mcp/commit/db5a25c0b694ad3c40ffde76e00cc2a28737ef9e))
- push edge docker to ghcr.io ([#10](https://github.com/meysam81/puppeteer-mcp/issues/10)) ([d3af725](https://github.com/meysam81/puppeteer-mcp/commit/d3af725bf04e09615c4a85c64c3637860e7d849a))

#### Bug Fixes

- correct jsonschema tag format for required fields ([#4](https://github.com/meysam81/puppeteer-mcp/issues/4)) ([8ada1d2](https://github.com/meysam81/puppeteer-mcp/commit/8ada1d265aae2ff40d0d5fcd81286e7f917165d9))
- correct MCP tool parameter struct tags format ([#12](https://github.com/meysam81/puppeteer-mcp/issues/12)) ([a08dfd9](https://github.com/meysam81/puppeteer-mcp/commit/a08dfd96a432cfb6f0533524d6dadc80ad85efed))
- syntax error ([#3](https://github.com/meysam81/puppeteer-mcp/issues/3)) ([42fb2a4](https://github.com/meysam81/puppeteer-mcp/commit/42fb2a48e67ea78e6106f8876abd5478c6974946))

#### Miscellaneous Chores

- **deps:** update dependency go to v1.25.4 ([#7](https://github.com/meysam81/puppeteer-mcp/issues/7)) ([07eda00](https://github.com/meysam81/puppeteer-mcp/commit/07eda001f0be11b24ecb142ed5df539960bfe52e))

### \[Unreleased]

#### Fixed

- Fixed memory leak where `MustPage()` created new browser pages on every navigation
- Fixed health check in Dockerfile by ensuring wget is available in runtime image
- Fixed variable shadowing in screenshot function that prevented proper error handling

#### Changed

- BrowserManager now maintains a single page instance that is reused across all tool calls
- All browser automation tools now use the managed page instance instead of creating new pages
- Improved page lifecycle management with proper cleanup on shutdown

### [1.0.0] - 2025-11-13

#### Added

- Initial release of Puppeteer MCP Actor
- Model Context Protocol (MCP) server implementation using official Go SDK
- Rod browser automation integration for high-performance web control
- 7 comprehensive browser automation tools:
  - `navigate` - URL navigation with wait conditions
  - `click` - Element interaction via CSS selectors
  - `type` - Text input with configurable delays
  - `screenshot` - Page and element screenshot capture
  - `evaluate` - JavaScript execution in page context
  - `waitForSelector` - Smart element waiting
  - `extract` - Data extraction from page elements
- Streamable HTTP/SSE transport for AI assistant connections
- Configurable input schema for Actor customization
- Docker containerization with Chrome/Chromium
- Comprehensive error handling and logging
- Headless and headed browser mode support
- Graceful shutdown handling
- Health check endpoint
- Production-ready Dockerfile with multi-stage build
- Detailed README with examples and use cases
- Apify platform integration

#### Technical Details

- Built with Go 1.23
- MCP Go SDK v0.8.0
- Rod v0.116.2
- Debian Bookworm base image
- Non-root container execution for security
- Optimized for Apify platform deployment

#### Documentation

- Comprehensive README with 2000+ words
- SEO-optimized content for Apify Store
- Integration examples for Claude, Python, and cURL
- Architecture documentation
- Troubleshooting guide
- Security best practices

[1.0.0]: https://github.com/meysam81/puppeteer-mcp/releases/tag/v1.0.0