Feature/computer use integration

.gitignore

@@ -44,3 +44,4 @@ temp/
 
 # Jest cache
 .jest/
+.claude/harness/

README.md

@@ -4,18 +4,22 @@
 [![npm downloads](https://img.shields.io/npm/dm/codex-mcp-server.svg)](https://www.npmjs.com/package/codex-mcp-server)
 [![license](https://img.shields.io/npm/l/codex-mcp-server.svg)](https://www.npmjs.com/package/codex-mcp-server)
 
-Bridge between Claude and OpenAI's Codex CLI — get AI-powered code analysis, generation, and review right in your editor.
+Bridge between Claude and OpenAI's Codex CLI — get AI-powered code analysis, generation, and review right in your editor. Also includes optional browser automation via Playwright.
 
 ```mermaid
 graph LR
     A[Claude Code] --> B[Codex MCP Server]
     B --> C[Codex CLI]
     C --> D[OpenAI API]
+    B --> E[Browser Use]
+    E --> F[Chromium]
 
     style A fill:#FF6B35
     style B fill:#4A90E2
     style C fill:#00D4AA
     style D fill:#FFA500
+    style E fill:#9B59B6
+    style F fill:#E74C3C
 ```
 
 ## Quick Start
@@ -54,6 +58,7 @@ Use review to check my uncommitted changes
 | `codex` | AI coding assistant with session support, model selection, and structured output metadata |
 | `review` | AI-powered code review for uncommitted changes, branches, or commits |
 | `websearch` | Web search using Codex CLI with customizable result count and search depth |
+| `browser_*` | 10 browser automation tools — launch, screenshot, click, type, scroll, drag, navigate ([setup](docs/browser-use.md)) |
 | `listSessions` | View active conversation sessions |
 | `ping` | Test server connection |
 | `help` | Get Codex CLI help |
@@ -90,8 +95,14 @@ Use codex to return structuredContent with threadId metadata when available
 **Web search:**
 ```
 Use websearch with query "TypeScript 5.8 new features"
-Use websearch with query "Rust vs Go performance 2025" and numResults 15
-Use websearch with query "React Server Components" and searchDepth "full"
+```
+
+**Browser Automation:**
+```
+Use browser_status to check if Playwright is available
+Use browser_launch with sessionId "web1" and url "https://example.com"
+Use browser_screenshot with sessionId "web1" to see the page
+Use browser_click with sessionId "web1", x 100, and y 200
 ```
 
 ## Requirements
@@ -105,6 +116,7 @@ Use websearch with query "React Server Components" and searchDepth "full"
 ## Documentation
 
 - **[API Reference](docs/api-reference.md)** — Full tool parameters and response formats
+- **[Browser Use](docs/browser-use.md)** — Playwright setup, tools, and troubleshooting
 - **[Session Management](docs/session-management.md)** — How conversations work
 - **[Codex CLI Integration](docs/codex-cli-integration.md)** — Version compatibility and CLI details
 

docs/api-reference.md

@@ -48,9 +48,20 @@ All tools include annotations that provide hints to MCP clients about tool behav
 |------|---------|---------------|-------------------|------------------|-----------------|
 | `codex` | Execute Codex CLI | `false` | `true` | `false` | `true` |
 | `review` | Code Review | `true` | `false` | `true` | `true` |
+| `websearch` | Web Search | `true` | `false` | `true` | `true` |
 | `ping` | Ping Server | `true` | `false` | `true` | `false` |
 | `help` | Get Help | `true` | `false` | `true` | `false` |
 | `listSessions` | List Sessions | `true` | `false` | `true` | `false` |
+| `browser_launch` | Launch Browser | `false` | `false` | `false` | `true` |
+| `browser_screenshot` | Browser Screenshot | `true` | `false` | `true` | `false` |
+| `browser_click` | Browser Click | `false` | `false` | `false` | `false` |
+| `browser_type` | Browser Type | `false` | `false` | `false` | `false` |
+| `browser_scroll` | Browser Scroll | `false` | `false` | `false` | `false` |
+| `browser_drag` | Browser Drag | `false` | `false` | `false` | `false` |
+| `browser_key` | Browser Key Press | `false` | `false` | `false` | `false` |
+| `browser_navigate` | Browser Navigate | `false` | `false` | `false` | `true` |
+| `browser_close` | Close Browser | `false` | `true` | `true` | `false` |
+| `browser_status` | Browser Status | `true` | `false` | `true` | `false` |
 
 ### Progress Notifications
 For long-running operations, the server sends `notifications/progress` messages when the client includes a `progressToken` in the request `_meta`.
@@ -439,4 +450,97 @@ Optional:
 ### Optional Configuration
 - **CODEX_HOME**: Custom directory for Codex CLI configuration
 - **Session Limits**: Configurable in server implementation (default: 100)
-- **TTL Settings**: Configurable session expiration (default: 24 hours)
+- **TTL Settings**: Configurable session expiration (default: 24 hours)
+
+## Browser Use Tools
+
+Cross-platform browser automation via Playwright. See [Browser Use](browser-use.md) for setup instructions.
+
+### `browser_status` — Health Check
+
+**Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`
+
+No parameters. Returns Playwright availability, active sessions, and any error.
+
+### `browser_launch` — Launch Browser
+
+**Annotations:** `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: true`
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sessionId` | string | yes | - | Unique session identifier |
+| `url` | string | no | - | URL to navigate to on launch |
+| `headless` | boolean | no | `true` | Run without visible window |
+| `viewportWidth` | integer | no | `1440` | Viewport width in pixels |
+| `viewportHeight` | integer | no | `900` | Viewport height in pixels |
+
+### `browser_screenshot` — Take Screenshot
+
+**Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sessionId` | string | yes | Browser session ID |
+
+Returns base64 PNG image, page URL, and page title.
+
+### `browser_click` — Click
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sessionId` | string | yes | - | Browser session ID |
+| `x` | number | yes | - | X coordinate (viewport-relative) |
+| `y` | number | yes | - | Y coordinate (viewport-relative) |
+| `button` | enum | no | `left` | `left`, `right`, or `middle` |
+| `clickCount` | integer | no | `1` | Number of clicks |
+
+### `browser_type` — Type Text
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sessionId` | string | yes | Browser session ID |
+| `text` | string | yes | Text to type into focused element |
+
+### `browser_scroll` — Scroll
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sessionId` | string | yes | - | Browser session ID |
+| `direction` | enum | yes | - | `up`, `down`, `left`, or `right` |
+| `amount` | integer | no | `300` | Scroll amount in pixels |
+
+### `browser_drag` — Drag
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sessionId` | string | yes | Browser session ID |
+| `fromX` | number | yes | Start X coordinate |
+| `fromY` | number | yes | Start Y coordinate |
+| `toX` | number | yes | End X coordinate |
+| `toY` | number | yes | End Y coordinate |
+
+### `browser_key` — Key Press
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sessionId` | string | yes | Browser session ID |
+| `key` | string | yes | Key or combo (`Enter`, `Control+a`, `Meta+s`) |
+
+Modifier keys are auto-normalized: `Cmd`/`Command` → `Meta`, `Ctrl` → `Control`, `Opt`/`Option` → `Alt`.
+
+### `browser_navigate` — Navigate
+
+**Annotations:** `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: true`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sessionId` | string | yes | Browser session ID |
+| `url` | string | yes | URL to navigate to |
+
+### `browser_close` — Close Session
+
+**Annotations:** `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: true`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sessionId` | string | yes | Browser session ID to close |

docs/browser-use.md

@@ -0,0 +1,127 @@
+# Browser Use
+
+Playwright-based browser automation. Launch a real Chromium browser, take screenshots, click, type, scroll, drag, and navigate — all via MCP tools.
+
+## Architecture
+
+```
+Claude Code
+  → codex-mcp-server
+    → BrowserUseBridge (singleton, lazy init)
+      → Playwright (peer dependency)
+        → Chromium instances
+```
+
+The bridge manages multiple concurrent browser sessions. Playwright is only imported on first use — no impact on codex/review startup when browser tools aren't used.
+
+## Setup
+
+```bash
+npm install playwright
+npx playwright install chromium
+```
+
+Playwright is a **peer dependency** — install it separately. The server works fine without it; browser tools will return a helpful error if Playwright isn't available.
+
+## Tools
+
+### `browser_status` — Health Check
+
+Works even without Playwright installed. Returns availability, active sessions, and any error.
+
+```json
+{ "sessionId": "my-session" }
+```
+
+### `browser_launch` — Launch Browser
+
+Creates a new browser session. Supports multiple concurrent sessions with unique IDs.
+
+```json
+{
+  "sessionId": "my-session",
+  "url": "https://example.com",
+  "headless": true,
+  "viewportWidth": 1440,
+  "viewportHeight": 900
+}
+```
+
+### `browser_screenshot` — Take Screenshot
+
+Returns base64 PNG image data along with the current page URL and title.
+
+```json
+{ "sessionId": "my-session" }
+```
+
+### `browser_click` — Click
+
+Click at viewport-relative pixel coordinates.
+
+```json
+{ "sessionId": "my-session", "x": 100, "y": 200, "button": "left", "clickCount": 1 }
+```
+
+### `browser_type` — Type Text
+
+Type literal text into the currently focused element. Click on an input field first.
+
+```json
+{ "sessionId": "my-session", "text": "hello world" }
+```
+
+### `browser_scroll` — Scroll
+
+Scroll the page in a direction by a pixel amount.
+
+```json
+{ "sessionId": "my-session", "direction": "down", "amount": 300 }
+```
+
+### `browser_drag` — Drag
+
+Drag from one coordinate to another (viewport-relative).
+
+```json
+{ "sessionId": "my-session", "fromX": 100, "fromY": 100, "toX": 300, "toY": 300 }
+```
+
+### `browser_key` — Key Press
+
+Press a key or key combination. Supports Playwright key names. Modifier keys are auto-normalized: `Cmd` → `Meta`, `Ctrl` → `Control`, `Opt` → `Alt`, etc.
+
+```json
+{ "sessionId": "my-session", "key": "Control+a" }
+{ "sessionId": "my-session", "key": "Cmd+s" }
+```
+
+### `browser_navigate` — Navigate
+
+Go to a URL in the current page.
+
+```json
+{ "sessionId": "my-session", "url": "https://example.com" }
+```
+
+### `browser_close` — Close Session
+
+Close a browser session and clean up resources.
+
+```json
+{ "sessionId": "my-session" }
+```
+
+## Troubleshooting
+
+**"Playwright is not installed"**
+Install it: `npm install playwright && npx playwright install chromium`
+
+**"Session already exists"**
+Use a different sessionId or close the existing session first with `browser_close`.
+
+**"No active browser session"**
+You must call `browser_launch` before using other browser tools.
+
+**Screenshots not loading**
+Check that the client supports `image` content type in MCP tool results. Claude Code supports this natively.

eslint.config.mjs

@@ -16,6 +16,12 @@ export default [
       globals: {
         console: 'readonly',
         process: 'readonly',
+        Buffer: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+        setImmediate: 'readonly',
       },
     },
     plugins: {

jest.config.mjs

@@ -28,4 +28,5 @@ export default {
     '**/__tests__/**/*.test.ts',
     '**/?(*.)+(spec|test).ts',
   ],
+  testPathIgnorePatterns: ['/node_modules/', '/trash/'],
 };