Align MCP browser pools with durable API contracts

[IlyaasK]

Summary

• align browser-pool validation with merged API limits and defaults
• add durable update clear semantics for profile, proxy, extensions, Chrome policy, and start URL
• return authoritative resolved profile and extension IDs in compact responses
• keep create and update semantics distinct for empty values

Why

The MCP tool lagged the durable browser-pool API contract. Agents could not reliably pause filling, clear configuration, or see the IDs the API actually resolved.

Implementation

The registered MCP surface now enforces integer fill rates, timeout bounds of 10 through 259200 seconds, and update-only empty sentinels. Tests exercise the registered tool rather than exporting implementation helpers.

Verification

• bun test (90 tests)
• bunx tsc --noEmit
• Prettier and git diff --check
• registered-tool scenario tests for create, update, validation, omission, clears, and resolved IDs
• targeted Stryker runs killed all 46 core PATCH mutants; the expanded boundary run killed 45/51, with survivors limited to schema-blocked duplicate validation and description strings
• crap4ts: create 6.0, update 13.0, shared config 13.0

---

Note

Medium Risk
Changes MCP tool input mapping and API payloads for pool create/update (clears, bounds, responses); incorrect mapping could send wrong clears or reject valid agent requests, but scope is limited to browser-pool tooling with strong test coverage.

Overview
Aligns the manage_browser_pools MCP tool with the durable browser-pool API so create/update behavior, validation, and responses match what agents need.

Create vs update: Empty start_url and clear_profile / clear_extensions are update-only; create rejects them. Updates can clear profile, extensions, proxy (proxy_id: ""), start_url, and Chrome policy ({}) via explicit sentinels, with guards against mixing clears with set profile/extension fields.

Validation: Integer fill_rate_per_minute (min 0) and timeout_seconds bounded 10–259200; start_url schema allows "" on update. Pool summaries expose profile_id and extension_ids from the API instead of nested profile/extension objects.

Refactor: buildBrowserSharedConfig extracts shared profile/extensions/viewport building; create still uses buildBrowserCreateConfig for start_url. Kernel client test mocks move to kernel-client.test-fixtures; new contract tests cover the registered tool.

^{Reviewed by Cursor Bugbot for commit 08f762c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
mcp	Ready	Preview	Aug 7, 2026 6:34pm

[masnwilliams]

the contract fixes are needed and the behavior looks correct, but i think these two maintainability issues should be addressed before merging. the main concern is keeping PATCH-only clear semantics out of the shared create path; the second is ensuring the new shared test mock is actually isolated between suites.

[masnwilliams]

both requested changes are addressed: create serialization is strict again with PATCH clears owned by the update path, and the shared Kernel client factory is restored after the browser-pool suite. re-ran the full test suite, typecheck, changed-file formatting, and the cross-suite leak reproduction; all pass.