@agimon-ai/browse-tool 0.2.4 → 0.2.6

package/README.md

@@ -56,14 +56,29 @@ Add to your Claude Code configuration (`.mcp.json`):
 browse-tool mcp-serve [options]
 
 Options:
-  -t, --type <type>      Transport type: stdio (default: "stdio")
+  -t, --type <type>      Transport type: stdio, streamable-http (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)
+  --host <host>          Default host for HTTP services (default: "localhost")
+  --port <port>          Port for streamable HTTP transport (default: "3201")
   -p, --profile <name>   Default profile name for browser sessions
   --custom-tools <path>  Expose tools from a folder containing tools.yaml
+  --snippets-dir <path>  Directory used by browser_run_code to save and load reusable snippets
 ```
 
+### Streamable HTTP Transport
+
+For clients that can connect over MCP streamable HTTP, start `mcp-serve` with:
+
+```bash
+browse-tool mcp-serve --type streamable-http --host 127.0.0.1 --port 3201
+```
+
+This exposes the MCP endpoint at `http://127.0.0.1:3201/mcp` and keeps the existing browse-tool HTTP service for browser execution on its own port.
+
+Streamable HTTP clients can pin a profile for the whole MCP session by sending `x-profile: <profile-name>` on the initialize request. When a profile is pre-selected this way, `browser_launch` always uses it and `browser_list_profiles` only returns that profile when it exists.
+
 ## Custom Tools
 
 Custom tools are loaded from a folder containing:
@@ -186,6 +201,13 @@ browse-tool exec-custom-tool \
 | `browser_resize_page` | Resize the browser viewport |
 | `browser_emulate` | Emulate device, geolocation, or network conditions |
 
+### Code Tools (2)
+
+| Tool | Description |
+|------|-------------|
+| `browser_run_code` | Execute inline code against `{ page, context, browser }`, optionally save it as a reusable snippet |
+| `browser_list_snippets` | List saved snippets by name, description, and snippetPath |
+
 ### Testing/Tracing Tools (3)
 
 | Tool | Description |
@@ -203,63 +225,47 @@ browse-tool exec-custom-tool \
 | `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';
+## Saved Snippets
 
-export async function run({ page, context, browser, pauseCheck }: AutomationFixtures) {
-  // Navigate to a page
-  await page.goto('https://example.com');
+If you start `mcp-serve` or `http-serve` with `--snippets-dir <path>`, `browser_run_code` can persist inline snippets and later execute them again by `snippetPath`.
 
-  // Create a pause checkpoint for LLM intervention
-  await pauseCheck('after-navigation', 'Page loaded, ready for inspection');
+Save an inline snippet:
 
-  // 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');
+```json
+{
+  "tool": "browser_run_code",
+  "arguments": {
+    "pageId": "page-1",
+    "code": "return await page.title();",
+    "saveAs": {
+      "name": "Get Page Title",
+      "description": "Return the current page title"
+    }
+  }
 }
 ```
 
-### 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 |
+List saved snippets:
 
-### Using pauseCheck
+```json
+{
+  "tool": "browser_list_snippets",
+  "arguments": {}
+}
+```
 
-The `pauseCheck` function allows the automation to pause at specific points, giving the LLM control to inspect the page, interact manually, and then resume:
+Run a saved snippet:
 
-```typescript
-await pauseCheck(stepName: string, reason?: string): Promise<void>
+```json
+{
+  "tool": "browser_run_code",
+  "arguments": {
+    "pageId": "page-1",
+    "snippetPath": "get-page-title.ts"
+  }
+}
 ```
 
-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.
@@ -277,20 +283,6 @@ Profiles allow you to persist browser state (cookies, localStorage, etc.) across
 }
 ```
 
-### Use a Profile with Automation
-
-```json
-{
-  "tool": "run_automation",
-  "arguments": {
-    "scriptPath": "/path/to/script.ts",
-    "browserOptions": {
-      "profile": "my-profile"
-    }
-  }
-}
-```
-
 ### Save Profile State
 
 ```json
@@ -303,47 +295,6 @@ Profiles allow you to persist browser state (cookies, localStorage, etc.) across
 }
 ```
 
-## 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
@@ -429,7 +380,7 @@ browse-tool/
 │   │   ├── ProfileService.ts     # Profile management
 │   │   └── SessionService.ts     # Session tracking
 │   ├── tools/           # MCP tool implementations
-│   ├── transports/      # Transport handlers (stdio)
+│   ├── transports/      # Transport handlers (stdio, streamable HTTP)
 │   └── types/           # TypeScript type definitions
 ├── tests/
 │   ├── services/        # Service unit tests