Breaking Change in v0.46.0: browseros-cli v0.2.2 incompatible with new MCP tools (tool names changed)

[maceatwork]

Issue Type

Agent Issue

Operating System

macOS

Description of the bug

Summary

BrowserOS v0.46.0 introduced a breaking change to the MCP tools that renders browseros-cli v0.2.2 completely non-functional. The CLI still attempts to use the old tool names (e.g., list_pages, get_active_page, take_snapshot) which no longer exist in the new MCP server (v0.0.119), resulting in "Tool not found" errors for all CLI commands.

Root Cause

In v0.46.0, the MCP tools were "rebuilt from the ground up" (per release notes), changing from 53 tools to 16 tools with completely different names:

OLD Tools (v0.45.x and earlier) - 53 tools:

• list_pages, get_active_page, navigate_page, take_snapshot, perform_action, extract_content, etc.

NEW Tools (v0.46.0) - 16 tools:

• tabs, navigate, snapshot, act, read, grep, screenshot, pdf, wait, windows, evaluate, run, diff, tab_groups, download, upload

The Problem:

• browseros-cli v0.2.2 (latest available) still uses OLD tool names

• BrowserOS Server v0.0.119 only has NEW tool names registered

• Result: Every CLI command fails with "Tool not found" errors

Impact

All browseros-cli commands are broken:

• browseros-cli pages → "Tool list_pages not found"

• browseros-cli active → "Tool get_active_page not found"

• browseros-cli snap → "Tool get_active_page not found"

• browseros-cli nav → "Tool navigate_page not found"

• All other commands fail similarly

This affects all users who rely on the CLI for browser automation, as well as AI agents that use the CLI.

What Still Works

✅ CDP (Chrome DevTools Protocol) on port 9014 - fully functional
✅ New MCP tools - work perfectly when called directly
✅ BrowserOS browser - works normally
✅ Health/status endpoints - respond correctly

Workarounds

1. Use CDP directly: curl http://127.0.0.1:9014/json/list

2. Use new MCP tools directly (if your agent supports them)

3. Wait for browseros-cli v0.3.0+ with updated tool names

Requested Fix

1. Release browseros-cli v0.3.0+ that uses the new tool names

2. Update documentation to reflect the breaking change

3. Provide migration guide for users transitioning from old to new tools

4. Consider backward compatibility or deprecation warnings in future releases

Steps to Reproduce

Environment Setup

• OS: macOS (Apple Silicon M-series)

• BrowserOS App: v0.46.0 (latest, Chromium 148.0.7948.97)

• BrowserOS Server: v0.0.119

• browseros-cli: v0.2.2 (latest available)

• Installation: Fresh install via official CDN

Steps to Reproduce

Step 1: Install/Update BrowserOS

1. Download BrowserOS v0.46.0 from https://github.com/BrowserOS-ai/BrowserOS/releases

2. Install the app and launch it

3. Verify server is running: curl http://127.0.0.1:9200/health

   • Expected: {"status":"ok","cdpConnected":true}

Step 2: Install browseros-cli

1. Install CLI: curl -fsSL https://cdn.browseros.com/install.sh | sh

2. Verify version: browseros-cli --version

   • Output: browseros-cli version 0.2.2

3. Initialize: browseros-cli init

4. Check health: browseros-cli health

   • Expected: Server OK, CDP connected

Step 3: Test CLI Commands (ALL FAIL)

# Test 1: List pages
browseros-cli pages
# Actual: Error: MCP error -32602: Tool list_pages not found

# Test 2: Get active page
browseros-cli active
# Actual: Error: no active page: MCP error -32602: Tool get_active_page not found

# Test 3: Take snapshot
browseros-cli snap
# Actual: Error: no active page: MCP error -32602: Tool get_active_page not found

# Test 4: Navigate
browseros-cli nav https://example.com
# Actual: Error: MCP error -32602: Tool navigate_page not found

# Test 5: Screenshot
browseros-cli ss
# Actual: Error: no active page: MCP error -32602: Tool get_active_page not found

Step 4: Verify CDP Works (Workaround)

# CDP endpoint works perfectly
curl -s http://127.0.0.1:9014/json/list | jq '.[] | {id, title, url}'
# Returns: Full list of open tabs with IDs, titles, and URLs

Step 5: Verify New MCP Tools Work

The new MCP tools (tabs, navigate, snapshot, act, read, etc.) work perfectly when called directly by AI agents that support them. The issue is ONLY with browseros-cli using old tool names.

Expected Behavior

All browseros-cli commands should work with BrowserOS v0.46.0, either by:

1. CLI being updated to use new tool names, OR

2. Server maintaining backward compatibility with old tool names

Actual Behavior

All browseros-cli commands fail with "Tool not found" errors because the CLI uses old tool names that no longer exist in the MCP server.

Screenshots / Videos

No response

BrowserOS Version

v0.46.0 (Chromium 148.0.7948.97) with Server v0.0.119

Additional Context

Technical Evidence

1. Server Health Check (Working)

$ curl http://127.0.0.1:9200/health
{"status":"ok","cdpConnected":true}

2. CDP Endpoint (Working)

$ curl -s http://127.0.0.1:9014/json/list
[
  {
    "id": "314979D6...",
    "type": "page",
    "title": "Example Domain",
    "url": "https://example.com",
    "webSocketDebuggerUrl": "ws://127.0.0.1:9014/devtools/page/..."
  }
]

3. CLI Commands (All Failing)

$ browseros-cli pages
Error: MCP error -32602: Tool list_pages not found

$ browseros-cli active
Error: no active page: MCP error -32602: Tool get_active_page not found

$ browseros-cli snap
Error: no active page: MCP error -32602: Tool get_active_page not found

4. Binary Analysis

Examining the browseros-cli binary shows it contains references to OLD tool names:

$ strings $(which browseros-cli) | grep -E "list_pages|get_active_page|navigate_page"
list_pages
get_active_page
navigate_page
take_snapshot
perform_action
# ... etc (all old tool names)

But the MCP server only has NEW tool names registered:

• tabs (not list_pages)

• navigate (not navigate_page)

• snapshot (not take_snapshot)

• act (not perform_action)

5. Release Notes Confirmation

From BrowserOS v0.46.0 release notes:

"New MCP tools — We rebuilt the browser tool surface from the ground up — a tighter, more reliable set of tools for agents to drive the browser."

This confirms the breaking change was intentional, but the CLI was not updated to match.

Impact on AI Agents

This breaking change affects multiple AI agents that rely on browseros-cli:

• Qwen (via MCP tools) - Works with new tools

• OpenCode - Uses browseros-cli - BROKEN

• Hermes - Uses browseros-cli - BROKEN

• Other agents - Likely BROKEN if using CLI

Documentation Issue

The official documentation at https://docs.browseros.com/features/use-with-claude-code still shows the OLD tool names (53 tools), not the new ones (16 tools). This creates confusion for users trying to understand what tools are available.

Suggested Solutions

Immediate Fix:

1. Release browseros-cli v0.3.0+ with updated tool names

2. Update documentation to show new tool names

3. Add migration guide for users

Long-term Improvements:

1. Semantic versioning: Breaking changes should increment major version (v1.0.0, not v0.46.0)

2. Deprecation warnings: Keep old tools working for 1-2 versions with deprecation warnings

3. Backward compatibility layer: Support both old and new tool names during transition

4. Automated testing: Test CLI against server before release to catch incompatibilities

Workaround for Users

Until the CLI is updated, users can:

1. Use CDP directly: curl http://127.0.0.1:9014/json/list

2. Use new MCP tools if their agent supports them

3. Downgrade BrowserOS to v0.45.x (if available)

System Information

• OS: macOS 15.5 (Sequoia)

• Architecture: Apple Silicon (arm64)

• Node.js: v22.22.3

• browseros-cli location: /Users/martin/.browseros/bin/browseros-cli

• BrowserOS config: ~/.config/browseros-cli/config.yaml

• Server ports: 9200 (MCP), 9014 (CDP), 9300 (Extension)

Related Issues

This issue likely affects all users who:

• Updated to BrowserOS v0.46.0

• Use browseros-cli for automation

• Rely on AI agents that use the CLI

Priority

HIGH - This completely breaks the CLI, which is a primary interface for many users and AI agents.

[shadowfax92]

Thanks for reporting! We re-wrote our entire MCP APIs. will update our the CLI.