@agimon-ai/browse-tool 0.2.0

package/LICENSE

@@ -0,0 +1,52 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             AgiFlow
+Licensed Work:        @agimon-ai/public-packages
+                      The Licensed Work is (c) 2026 AgiFlow.
+Additional Use Grant: None
+Change Date:          2030-03-06
+Change License:       Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

package/README.md

@@ -0,0 +1,375 @@
+# browse-tool
+
+MCP (Model Context Protocol) server for browser automation using Playwright. Provides comprehensive browser control, profile management, and LLM-driven automation capabilities.
+
+## Features
+
+- 37 browser automation tools for complete browser control
+- Multi-browser support (Chromium, Firefox, WebKit)
+- Profile management for persistent browser sessions
+- Page registry for managing multiple tabs/windows
+- LLM-controlled automation with pause/resume flow
+- Session management for organized browser operations
+
+## Installation
+
+```bash
+pnpm install
+```
+
+## Development
+
+```bash
+pnpm dev
+```
+
+## Build
+
+```bash
+pnpm build
+```
+
+## Test
+
+```bash
+pnpm test
+```
+
+## Usage with Claude Code
+
+Add to your Claude Code configuration (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "browse-tool": {
+      "command": "npx",
+      "args": ["browse-tool", "mcp-serve"]
+    }
+  }
+}
+```
+
+### CLI Options
+
+```bash
+browse-tool mcp-serve [options]
+
+Options:
+  -t, --type <type>      Transport type: stdio (default: "stdio")
+  -b, --browser <type>   Default browser: chromium, firefox, webkit (default: "chromium")
+  --headless             Run browsers in headless mode
+  --no-headless          Run browsers in headed mode (visible window)
+  -p, --profile <name>   Default profile name for browser sessions
+```
+
+## Tool Reference
+
+### Input Tools (8)
+
+| Tool | Description |
+|------|-------------|
+| `browser_click` | Click on an element |
+| `browser_fill` | Fill a form field with text (clears first) |
+| `browser_type` | Type text into an element (appends) |
+| `browser_hover` | Hover over an element |
+| `browser_select` | Select an option from a dropdown |
+| `browser_drag` | Drag from one element to another |
+| `browser_press_key` | Press a keyboard key |
+| `browser_upload_file` | Upload a file to a file input |
+
+### Navigation Tools (5)
+
+| Tool | Description |
+|------|-------------|
+| `browser_navigate` | Navigate to a URL |
+| `browser_go_back` | Go back in browser history |
+| `browser_go_forward` | Go forward in browser history |
+| `browser_reload` | Reload the current page |
+| `browser_wait_for` | Wait for an element or condition |
+
+### Snapshot Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `browser_screenshot` | Take a screenshot |
+| `browser_pdf` | Generate PDF of the page |
+| `browser_snapshot` | Get accessibility tree snapshot |
+
+### Tab/Page Management Tools (4)
+
+| Tool | Description |
+|------|-------------|
+| `browser_list_pages` | List all open pages |
+| `browser_select_page` | Switch to a specific page |
+| `browser_new_page` | Open a new page |
+| `browser_close_page` | Close a page |
+
+### Dialog/Network/Console Tools (7)
+
+| Tool | Description |
+|------|-------------|
+| `browser_handle_dialog` | Handle JavaScript dialogs (alert, confirm, prompt) |
+| `browser_list_network_requests` | List captured network requests |
+| `browser_get_network_request` | Get details of a specific network request |
+| `browser_list_console_messages` | List console messages |
+| `browser_evaluate_script` | Execute JavaScript in the page |
+| `browser_resize_page` | Resize the browser viewport |
+| `browser_emulate` | Emulate device, geolocation, or network conditions |
+
+### Testing/Tracing Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `browser_expect` | Assert conditions on elements |
+| `browser_start_trace` | Start Playwright tracing |
+| `browser_stop_trace` | Stop tracing and save trace file |
+
+### Profile Management Tools (4)
+
+| Tool | Description |
+|------|-------------|
+| `browser_list_profiles` | List all saved profiles |
+| `browser_create_profile` | Create a new browser profile |
+| `browser_delete_profile` | Delete a profile |
+| `browser_save_profile_state` | Save current browser state to profile |
+
+### Automation Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `run_automation` | Run an automation script with optional pause |
+| `resume_automation` | Resume a paused automation |
+| `get_automation_status` | Get automation session status |
+
+## Automation Script Format
+
+Automation scripts are TypeScript/JavaScript modules that export a `run` function:
+
+```typescript
+import type { AutomationFixtures } from 'browse-tool';
+
+export async function run({ page, context, browser, pauseCheck }: AutomationFixtures) {
+  // Navigate to a page
+  await page.goto('https://example.com');
+
+  // Create a pause checkpoint for LLM intervention
+  await pauseCheck('after-navigation', 'Page loaded, ready for inspection');
+
+  // Continue with automation
+  await page.click('#login-button');
+
+  // Another pause point
+  await pauseCheck('after-login-click', 'Login button clicked');
+
+  // Fill form
+  await page.fill('#username', 'testuser');
+  await page.fill('#password', 'password123');
+}
+```
+
+### Fixtures Available
+
+| Fixture | Type | Description |
+|---------|------|-------------|
+| `page` | `Page` | Playwright Page instance |
+| `context` | `BrowserContext` | Playwright BrowserContext |
+| `browser` | `Browser` | Playwright Browser instance |
+| `pauseCheck` | `Function` | Create pause checkpoints for LLM control |
+
+### Using pauseCheck
+
+The `pauseCheck` function allows the automation to pause at specific points, giving the LLM control to inspect the page, interact manually, and then resume:
+
+```typescript
+await pauseCheck(stepName: string, reason?: string): Promise<void>
+```
+
+When paused:
+1. The automation waits for `resume_automation` to be called
+2. All browser tools remain available for LLM interaction
+3. The LLM can inspect page state, take screenshots, etc.
+4. Once resumed, automation continues from where it paused
+
+## Profile Management
+
+Profiles allow you to persist browser state (cookies, localStorage, etc.) across sessions.
+
+### Create a Profile
+
+```json
+{
+  "tool": "browser_create_profile",
+  "arguments": {
+    "name": "my-profile",
+    "browser": "chromium",
+    "headless": false
+  }
+}
+```
+
+### Use a Profile with Automation
+
+```json
+{
+  "tool": "run_automation",
+  "arguments": {
+    "scriptPath": "/path/to/script.ts",
+    "browserOptions": {
+      "profile": "my-profile"
+    }
+  }
+}
+```
+
+### Save Profile State
+
+```json
+{
+  "tool": "browser_save_profile_state",
+  "arguments": {
+    "sessionId": "automation-1",
+    "profileName": "my-profile"
+  }
+}
+```
+
+## LLM-Controlled Automation Flow
+
+The unique feature of browse-tool is the ability to run automation scripts with LLM intervention points:
+
+1. **Start Automation with Pause**
+   ```json
+   {
+     "tool": "run_automation",
+     "arguments": {
+       "scriptPath": "/path/to/script.ts",
+       "pauseAtStart": true
+     }
+   }
+   ```
+
+2. **Automation Pauses** - Returns `automationId` and `pageIds`
+
+3. **LLM Interacts** - Use browser tools (`browser_click`, `browser_fill`, etc.) on the paused pages
+
+4. **Resume Automation**
+   ```json
+   {
+     "tool": "resume_automation",
+     "arguments": {
+       "automationId": "automation-1"
+     }
+   }
+   ```
+
+5. **Script Continues** - Until next `pauseCheck` or completion
+
+6. **Check Status**
+   ```json
+   {
+     "tool": "get_automation_status",
+     "arguments": {
+       "automationId": "automation-1"
+     }
+   }
+   ```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PLAYWRIGHT_PROFILES_DIR` | `~/.browse-tool/profiles` | Directory for storing browser profiles |
+| `PLAYWRIGHT_REGISTRY_DIR` | `.agiflow/registry` | Directory for HTTP server registry |
+| `PLAYWRIGHT_PIDS_DIR` | `.pids` | Directory for tracking server PIDs |
+| `NODE_ENV` | `development` | Runtime environment (`development`, `production`) |
+
+### CLI Flags vs Environment Variables
+
+CLI flags take precedence over environment variables. For example, `--profiles-dir /custom/path` overrides `PLAYWRIGHT_PROFILES_DIR`.
+
+## Error Handling
+
+### Common Failure Modes
+
+| Failure | Cause | Recovery |
+|---------|-------|----------|
+| Browser launch failure | Missing browser binary or incompatible version | Run `npx playwright install chromium` to install browsers |
+| Navigation timeout | Page took too long to load | Increase timeout via `browser_wait_for` or check network connectivity |
+| Element not found | Selector did not match any element | Use `browser_snapshot` to inspect the current DOM tree |
+| Profile not found | Referenced profile does not exist | Use `browser_list_profiles` to list available profiles |
+| Session expired | Browser context was closed or crashed | Launch a new browser session with `browser_navigate` |
+| Spec bundler build error | Syntax errors or unresolvable imports in spec file | Check the spec file for errors; see `SpecBundlerBuildError.recovery` |
+| Spec bundler CLI error | `bun` not installed or not in PATH | Install bun: `curl -fsSL https://bun.sh/install \| bash` |
+
+### Error Codes
+
+All structured errors include a `code` field for programmatic handling and a `recovery` field with suggested resolution steps.
+
+## Spec Bundler
+
+The `SpecBundlerService` bundles Playwright spec files before execution, replacing `@playwright/test` imports with a lightweight stub module so specs can run inside the MCP server.
+
+### Runtime Requirements
+
+- **Bun runtime** (preferred): When the MCP server runs under Bun, `Bun.build()` is used directly.
+- **Node.js runtime** (fallback): When running under Node.js, the service spawns `bun` as a CLI subprocess. Ensure `bun` is installed and accessible in `PATH`:
+  ```bash
+  curl -fsSL https://bun.sh/install | bash
+  # or
+  npm i -g bun
+  ```
+
+### Programmatic Usage
+
+```typescript
+import { SpecBundlerService } from 'browse-tool';
+
+const bundler = new SpecBundlerService();
+const { outputPath, cleanup } = await bundler.bundle('/path/to/my-spec.ts');
+try {
+  // Use the bundled output at outputPath
+} finally {
+  await cleanup();
+}
+```
+
+### Error Handling
+
+| Error Class | Code | When |
+|-------------|------|------|
+| `SpecBundlerBuildError` | `SPEC_BUNDLER_BUILD_FAILED` | Bundler reports syntax or resolution errors |
+| `SpecBundlerNoOutputError` | `SPEC_BUNDLER_NO_OUTPUT` | Bundling produces no output file |
+| `SpecBundlerCliError` | `SPEC_BUNDLER_CLI_FAILED` | `bun` CLI subprocess fails to execute |
+
+## Architecture
+
+```
+browse-tool/
+├── src/
+│   ├── commands/        # CLI commands (mcp-serve)
+│   ├── container/       # InversifyJS IoC container
+│   ├── server/          # MCP server factory
+│   ├── services/        # Core services
+│   │   ├── AutomationRunner.ts   # Script execution
+│   │   ├── BrowserService.ts     # Browser lifecycle
+│   │   ├── PageRegistry.ts       # Page tracking
+│   │   ├── PauseController.ts    # Pause/resume flow
+│   │   ├── ProfileService.ts     # Profile management
+│   │   └── SessionService.ts     # Session tracking
+│   ├── tools/           # MCP tool implementations
+│   ├── transports/      # Transport handlers (stdio)
+│   └── types/           # TypeScript type definitions
+├── tests/
+│   ├── services/        # Service unit tests
+│   ├── tools/           # Tool unit tests
+│   ├── integration/     # Integration tests
+│   └── fixtures/        # Test fixtures
+└── README.md
+```
+
+## License
+
+MIT