refactor(mcp): improve bridge mode initialization and test organization

- Improve error handling in base-tools.ts for bridge mode initialization
  - Add specific detection for bridge mode URL requirement errors
  - Provide friendly logging messages instead of generic failure messages
  - Clarify that deferred initialization is expected behavior

- Improve comments in web-tools.ts
  - Remove misleading "deferred until first tool use" comment
  - Add clear explanations for bridge vs puppeteer mode behavior
  - Clarify that bridge mode requires URL while puppeteer can auto-start

- Move tests from @midscene/mcp to @midscene/web-mcp
  - Relocate utils and puppeteer tests to correct package location
  - Update mcp package.json to remove obsolete test scripts
  - All 22 tests passing in new location

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: quanru

packages/mcp/package.json

@@ -21,7 +21,6 @@
     "dev": "npm run build:watch",
     "build:watch": "rslib build --watch",
     "mcp-playground": "npx @modelcontextprotocol/inspector node ./dist/index.js",
-    "test": "vitest run",
     "inspect": "node scripts/inspect.mjs"
   },
   "dependencies": {
@@ -37,8 +36,7 @@
     "@modelcontextprotocol/sdk": "1.10.2",
     "@rslib/core": "^0.11.2",
     "@types/node": "^18.0.0",
-    "typescript": "^5.8.3",
-    "vitest": "3.0.5"
+    "typescript": "^5.8.3"
   },
   "license": "MIT"
 }

packages/shared/src/mcp/base-tools.ts

@@ -63,7 +63,13 @@ export abstract class BaseMidsceneTools implements IMidsceneTools {
       );
     } catch (error) {
       // Layer 2: Create temporary device instance to read actionSpace
-      debug('Failed to get action space from agent, using temporary device');
+      // This is expected behavior for bridge mode without URL or unconnected devices
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      if (errorMessage.includes('requires a URL') || errorMessage.includes('web_connect')) {
+        debug('Bridge mode detected - agent will be initialized on first web_connect call');
+      } else {
+        debug('Agent not available yet, using temporary device for action space');
+      }
       const tempDevice = this.createTemporaryDevice();
       actionSpace = tempDevice.actionSpace();
       debug(

packages/web-mcp/src/web-tools.ts

@@ -60,9 +60,8 @@ export class WebMidsceneTools extends BaseMidsceneTools {
     if (this.agent) return this.agent;
 
     // Choose bridge or puppeteer mode
-    // In bridge mode, we need a URL to connect to
-    // If no URL provided, agent creation will be deferred until first tool use
     if (!this.puppeteerMode) {
+      // Bridge mode requires a URL to connect to browser
       if (!openNewTabWithUrl) {
         throw new Error(
           'Bridge mode requires a URL. Use web_connect tool to connect to a page first.',
@@ -72,6 +71,7 @@ export class WebMidsceneTools extends BaseMidsceneTools {
         openNewTabWithUrl,
       )) as unknown as BaseAgent;
     } else {
+      // Puppeteer mode can auto-start with default page
       this.agent = (await this.initPuppeteerAgent(
         openNewTabWithUrl,
       )) as unknown as BaseAgent;

packages/mcp/tests/puppeteer.test.ts renamed to packages/web-mcp/tests/puppeteer.test.ts

@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.json",
+  "include": [".", "../src/**/*", "../vitest.setup.ts"],
+  "compilerOptions": {
+    "types": ["vitest/globals", "node"]
+  }
+}