diff --git a/docs/contributing.mdx b/docs/contributing.mdx index 282b07e5b..d1f860bed 100644 --- a/docs/contributing.mdx +++ b/docs/contributing.mdx @@ -1,530 +1,267 @@ --- title: "Contributing to BrowserOS" -description: "Let's build the best open-source browser!" -icon: "code-branch" +description: "Guide to contributing to BrowserOS" --- -Hey there! Thanks for your interest in BrowserOS. Whether you're fixing bugs, adding features, improving docs, or just poking around the code, we're glad you're here. +BrowserOS has two main parts you can contribute to: -BrowserOS is a monorepo with two main parts: -- **Agent** - The Chrome extension with AI features (TypeScript/React) -- **Browser** - The custom Chromium build (C++/Python) +- **Agent** β€” The AI features, UI, and browser automation (TypeScript/React) +- **Browser** β€” The custom Chromium build (C++/Python) -Most folks start with the agent since it's way easier to set up and iterate on. +Most contributors work on the Agent since it's much easier to set up. -## 1. Quick Links +## Quick Links - - - Star, fork, and contribute to our codebase - - - Join our community for discussions and support - - - Report bugs or suggest new features - - +- [GitHub Repository](https://github.com/BrowserOS-ai/BrowserOS) +- [Discord Community](https://discord.gg/YKwjt5vuKr) +- [Report Issues](https://github.com/BrowserOS-ai/BrowserOS/issues) -## 2. Ways to Contribute +## Ways to Contribute -You can contribute to BrowserOS in many ways! Whether you want to build features or help out in other ways, we appreciate all contributions. +**Report bugs** β€” [Open an issue](https://github.com/browseros-ai/BrowserOS/issues/new) with steps to reproduce, expected vs actual behavior, and screenshots. - - - Found a bug? [Open an issue](https://github.com/browseros-ai/BrowserOS/issues/new) with: - - Clear description - - Steps to reproduce - - Expected vs actual behavior - - Screenshots/videos - - Environment details (OS, browser version, BrowserOS version) - +**Suggest features** β€” Share ideas on [GitHub](https://github.com/browseros-ai/BrowserOS/issues/99) or [Discord](https://discord.gg/YKwjt5vuKr). - - Have an idea? [Share it here](https://github.com/browseros-ai/BrowserOS/issues/99) or chat with us on [Discord](https://discord.gg/YKwjt5vuKr). - +**Improve docs** β€” Docs live in `docs/` and use Mintlify. Edit pages and update `docs/docs.json` for navigation. - - We use Mintlify for our documentation. All docs live in the docs/ directory. +--- - - Add new documentation pages or update existing ones under docs/ - - Help clarify instructions; add examples, tutorials, or guides - - After adding or editing a page, update docs/docs.json to include your new or changed file in the navigation +## Path 1: Agent Development - If you have questions about the docs system, ask in Discord! - - +The Agent is a monorepo with 3 components: -## 3. Pick Your Path +| Component | Path | What it does | +|-----------|------|--------------| +| **Agent UI** | `apps/agent` | Chrome extension β€” chat interface, settings, side panel | +| **Server** | `apps/server` | Bun server β€” agent loop, MCP tools, API endpoints | +| **Controller** | `apps/controller-ext` | Chrome extension β€” bridges `chrome.*` APIs to the server | -If you want to contribute to development, here are two paths you can take: +### Architecture - - - **What you'll work on:** - - AI agent features & tools - - UI/UX improvements - - Browser automation - - Testing & docs +BrowserOS Agent architecture diagram - **What you need:** - - Node.js 18+ - - ~500MB disk space - - 10 minutes to set up +### Setup - **Skills:** TypeScript, React, Chrome APIs - - - **What you'll work on:** - - Chromium patches - - Build system - - Platform features - - Core browser stuff +```bash +# Clone the repo +git clone https://github.com/YOUR-USERNAME/BrowserOS.git +cd BrowserOS/packages/browseros-agent - **What you need:** - - ~100GB disk space - - 16GB+ RAM (recommended) - - 3+ hours for first build +# Install dependencies +bun install - **Skills:** C++, Python, Chromium internals - - +# Copy environment files +cp apps/server/.env.example apps/server/.env.development +cp apps/agent/.env.example apps/agent/.env.development +``` -### 3.1 Agent Development +### Running Locally -The agent is a Chrome extension that provides AI-powered automation. Most contributors work here. +```bash +# Terminal 1: Start the server +bun run start:server - +# Terminal 2: Start the agent extension (dev mode) +bun run start:agent +``` -#### Quick Setup +Then load the extension in BrowserOS: +1. Go to `chrome://extensions/` +2. Enable **Developer mode** +3. Click **Load unpacked** and select the `apps/agent/dist/` folder - - - ```bash - cd packages/browseros-agent - ``` - +### Commands - - ```bash - yarn install - ``` - +| Command | Description | +|---------|-------------| +| `bun run start:server` | Start the server | +| `bun run start:agent` | Start agent extension (dev mode) | +| `bun run build:server` | Build server for production | +| `bun run build:agent` | Build agent extension | +| `bun run build:ext` | Build controller extension | +| `bun run test` | Run tests | +| `bun run lint` | Check with Biome | +| `bun run typecheck` | TypeScript check | - - ```bash - cp .env.example .env - ``` - Edit `.env` and add your `LITELLM_API_KEY` - +--- - - ```bash - yarn build:dev # One-time build - ``` - - +## Path 2: Browser Development -#### Load in BrowserOS +Only go down this path if you're working on Chromium-level features like patches to the browser itself. - - - Navigate to `chrome://extensions/` - +**Requirements:** +- ~100GB disk space +- 16GB+ RAM recommended +- 3+ hours for first build - - Toggle **Developer mode** in the top right - - - - Click **Load unpacked** and select `packages/browseros-agent/dist/` - - - - Press the Agent icon from the extensions toolbar to open the agent panel - - - - -For detailed setup, architecture, and code standards, see the [Agent Contributing Guide](https://github.com/BrowserOS-ai/BrowserOS/blob/main/packages/browseros-agent/CONTRIBUTING.md). - - - - -### 3.2 Browser Development - -Building the custom Chromium browser requires significant disk space and time. Only go down this path if you're working on browser-level features like patches to Chromium itself. - - - -#### Prerequisites +### Prerequisites - - macOS (tested on M4 Max) - - Xcode and Command Line Tools + - macOS with Xcode and Command Line Tools - Python 3.12+ - [UV](https://docs.astral.sh/uv/) (Python package manager) - Git - - ~100GB of free disk space (for Chromium source) - - ~16GB RAM (recommended) - Ubuntu 20.04+ or similar - build-essential package - Python 3.12+ - - [UV](https://docs.astral.sh/uv/) (Python package manager) + - [UV](https://docs.astral.sh/uv/) - Git - - ~100GB of free disk space - - ~16GB RAM (recommended) - Windows 10/11 - Visual Studio 2022 with C++ workload - Python 3.12+ - - [UV](https://docs.astral.sh/uv/) (Python package manager) + - [UV](https://docs.astral.sh/uv/) - Git - - ~100GB of free disk space - - ~16GB RAM minimum -#### Build Instructions +### Build Instructions - - - Follow the official Chromium guide for your platform to clone the source code: +**1. Clone Chromium source** - **[Chromium: Get the Code](https://www.chromium.org/developers/how-tos/get-the-code/)** +Follow the official [Chromium: Get the Code](https://www.chromium.org/developers/how-tos/get-the-code/) guide. This sets up `depot_tools` and fetches ~100GB of source code. - This sets up `depot_tools` and fetches the Chromium source tree (~100GB). +Note the path where you clone it (e.g., `~/chromium/src`). - - Take note of the path where you clone Chromium (e.g., `~/chromium/src`). You'll need this path for the build commands. - - +**2. Install UV and dependencies** - - Install UV if you haven't already, then install the build system dependencies: +```bash +# Install UV +curl -LsSf https://astral.sh/uv/install.sh | sh +# Navigate to build system +cd packages/browseros + +# Install dependencies +uv sync +``` + +**3. Build debug version** + +```bash +uv run browseros build \ + --chromium-src \ + --setup \ + --prep \ + --build \ + --build-type debug +``` + +The `--setup` and `--prep` flags are only needed for the first build. After that, just use `--build` for incremental builds: + +```bash +uv run browseros build --chromium-src --build --build-type debug +``` + +**4. Run BrowserOS** + + + ```bash - # Install UV (if not installed) - curl -LsSf https://astral.sh/uv/install.sh | sh - - # Navigate to the build system directory - cd packages/browseros - - # Install all dependencies - uv sync + /out/Default_arm64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev \ + --enable-logging=stderr \ + --use-mock-keychain \ + --user-data-dir=/tmp/test-profile ``` - - - - Run the build command with your Chromium source path: - + + ```bash - uv run browseros build \ - --chromium-src \ - --setup \ - --prep \ - --build \ - --build-type debug + /out/Default_x64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev \ + --enable-logging=stderr \ + --use-mock-keychain \ + --user-data-dir=/tmp/test-profile ``` - - Replace `` with the actual path to your Chromium source directory (e.g., `~/chromium/src`). - - - The `--setup` and `--prep` flags are only needed for the first build. After that, you can just use `--build` for incremental builds. - - - - - For a production-optimized build: - + + ```bash - uv run browseros build \ - --chromium-src \ - --setup \ - --prep \ - --build \ - --build-type release + \out\Default_x64\BrowserOS Dev.exe \ + --enable-logging=stderr \ + --user-data-dir=%TEMP%\test-profile ``` + + + ```bash + /out/Default_x64/browseros \ + --enable-logging=stderr \ + --user-data-dir=/tmp/test-profile + ``` + + - - Release builds take longer to compile but produce faster, smaller binaries. - - - - - After the build completes, you'll find BrowserOS Dev in the output directory. - - - - ```bash - /out/Default_arm64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev \ - --enable-logging=stderr \ - --use-mock-keychain \ - --user-data-dir=/tmp/test-profile - ``` - - - ```bash - /out/Default_x64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev \ - --enable-logging=stderr \ - --use-mock-keychain \ - --user-data-dir=/tmp/test-profile - ``` - - - ```bash - \out\Default_x64\BrowserOS Dev.exe \ - --enable-logging=stderr \ - --user-data-dir=%TEMP%\test-profile - ``` - - - ```bash - /out/Default_x64/browseros \ - --enable-logging=stderr \ - --user-data-dir=/tmp/test-profile - ``` - - - - - The `--user-data-dir` flag creates an isolated profile, keeping your development browser separate from any existing profiles. - - - - -#### Build Flags Reference +### Build Flags | Flag | Description | |------|-------------| -| `--chromium-src` | Path to your Chromium source directory (required) | -| `--setup` | Run setup phase (clean, git setup) | -| `--prep` | Run prep phase (resources, patches, configure) | +| `--chromium-src` | Path to Chromium source directory | +| `--setup` | Run setup phase (first build only) | +| `--prep` | Run prep phase (first build only) | | `--build` | Run the compile phase | -| `--build-type` | Build type: `debug` or `release` | -| `--sign` | Sign the build (platform-specific) | +| `--build-type` | `debug` or `release` | +| `--sign` | Sign the build | | `--package` | Package for distribution | - -For incremental builds after your first build, you only need `--build`: -```bash -uv run browseros build --chromium-src --build --build-type debug -``` - +### Troubleshooting -#### Troubleshooting +**Build fails with missing dependencies** β€” Make sure you followed all steps from the Chromium build guide for your platform. - - - Make sure you've followed all prerequisite steps from the Chromium build guide - - Ensure Xcode is up to date (macOS) - - Verify all required packages are installed (Linux) - - Check Visual Studio installation (Windows) - +**Out of disk space** β€” Chromium needs ~100GB. Check with `df -h`. - - Chromium requires significant disk space (~100GB). Ensure you have enough free space before starting the build. You can use `df -h` on Unix systems or check Disk Management on Windows. - +**Build takes too long** β€” Use ccache, more CPU cores, or stick to debug builds. - - - Use ccache to speed up rebuilds - - Consider using a machine with more CPU cores - - Build only the components you need for development - - Use debug builds for faster compilation times - - - - Make sure UV is installed and in your PATH: - ```bash - curl -LsSf https://astral.sh/uv/install.sh | sh - source ~/.bashrc # or restart your terminal - ``` - - - - -## 4. Making Your First Contribution - -Open a PR on GitHub with: -- **Clear title** in conventional commit format -- **Description** explaining what changed and why -- **Screenshots/videos** for UI changes -- **Link to related issues** (e.g., "Fixes #123") - -### Sign the CLA - -On your first PR, our bot will ask you to sign the Contributor License Agreement: - - - - Read the [CLA document](https://github.com/BrowserOS-ai/BrowserOS/blob/main/CLA.md) - - - - Comment on your PR: - ``` - I have read the CLA Document and I hereby sign the CLA - ``` - - - - The bot will record your signature (one-time thing) - - - -## 5. Code Standards - -### TypeScript (Agent) - -- **Strict typing** - Always declare types, avoid `any` -- **Zod schemas** - Use Zod instead of TypeScript interfaces -- **Path aliases** - Use `@/lib` not relative paths like `../` -- **Naming:** - - Classes: `PascalCase` - - Functions/variables: `camelCase` - - Constants: `UPPERCASE` - - Private methods: prefix with `_` - -**Example:** - -```typescript -import { z } from 'zod' - -// Good: Zod schema with inline comments -export const ToolInputSchema = z.object({ - action: z.enum(['click', 'type']), // Action to perform - target: z.string().min(1), // Element selector - timeout: z.number().default(5000) // Timeout in ms -}) - -export type ToolInput = z.infer -``` - -### React (Agent UI) - -- **Styling:** Tailwind CSS only (no SCSS or CSS modules) -- **Hooks:** Only at top level -- **Props:** Define with Zod schemas -- **Testing:** Vitest (not Jest) - -### General Guidelines - -- Keep functions short (\<20 lines ideally) -- Write tests for new features -- Use descriptive variable names -- Handle errors gracefully - - -claude.md file can be found at below: -- Agent: [packages/browseros-agent/CLAUDE.md](https://github.com/BrowserOS-ai/BrowserOS/blob/main/packages/browseros-agent/CLAUDE.md) - - -## 6. Project Structure - -``` -monorepo/ -β”œβ”€β”€ packages/ -β”‚ β”œβ”€β”€ browseros/ # Chromium build system -β”‚ β”‚ β”œβ”€β”€ build/ # Python build scripts -β”‚ β”‚ β”œβ”€β”€ chromium_patches/ # Patches to Chromium source -β”‚ β”‚ └── resources/ # Icons, configs -β”‚ β”‚ -β”‚ └── browseros-agent/ # Chrome extension -β”‚ β”œβ”€β”€ src/ -β”‚ β”‚ β”œβ”€β”€ lib/ # Core agent logic -β”‚ β”‚ β”œβ”€β”€ sidepanel/ # Side panel UI -β”‚ β”‚ β”œβ”€β”€ newtab/ # New tab page -β”‚ β”‚ └── background/ # Extension background -β”‚ └── docs/ # Architecture docs -β”‚ -β”œβ”€β”€ docs/ # General documentation -└── CONTRIBUTING.md # Contributing guide -``` - -## 7. Development Workflow - - - - Fork the repository on GitHub and clone it locally: - ```bash - git clone https://github.com/YOUR-USERNAME/BrowserOS.git - cd BrowserOS - ``` - - - - Create a new branch for your feature or fix: - ```bash - git checkout -b feature/your-feature-name - ``` - - - - Make your changes and test them thoroughly. Follow our coding standards and ensure all tests pass. - - - - Commit your changes with a descriptive message: - ```bash - git add . - git commit -m "feat: add new feature description" - git push origin feature/your-feature-name - ``` - - - - Open a pull request on GitHub with a clear description of your changes and why they're needed. - - - -## 8. Support - -Stuck? Need clarification? We're here to help. - - - - Real-time chat and support - - - Bug reports and features - - - General questions - - - - -## 9. License - -By contributing, you agree that your contributions will be licensed under AGPL-3.0. +**UV command not found** β€” Restart your terminal after installing UV. --- -Built with ❀️ from San Francisco +## Making Your First PR + +1. **Fork** the repository on GitHub +2. **Clone** your fork locally +3. **Create a branch**: `git checkout -b feature/your-feature` +4. **Make changes** and test them +5. **Commit**: `git commit -m "feat: add your feature"` +6. **Push**: `git push origin feature/your-feature` +7. **Open a PR** with a clear description + +### Sign the CLA + +On your first PR, our bot will ask you to sign the Contributor License Agreement. Just comment: + +``` +I have read the CLA Document and I hereby sign the CLA +``` + +--- + +## Code Standards + +**TypeScript:** +- Use strict typing, avoid `any` +- Use Zod schemas instead of TypeScript interfaces +- Use path aliases (`@/lib`) not relative paths (`../`) +- Naming: `PascalCase` for classes, `camelCase` for functions + +**React:** +- Tailwind CSS only (no SCSS or CSS modules) +- Hooks at top level only +- Test with Vitest + +**General:** +- Keep functions short (under 20 lines) +- Write tests for new features +- Handle errors gracefully + +--- + +## Getting Help + +- **Discord** β€” [discord.gg/YKwjt5vuKr](https://discord.gg/YKwjt5vuKr) +- **GitHub Issues** β€” [github.com/BrowserOS-ai/BrowserOS/issues](https://github.com/BrowserOS-ai/BrowserOS/issues) +- **GitHub Discussions** β€” [github.com/BrowserOS-ai/BrowserOS/discussions](https://github.com/BrowserOS-ai/BrowserOS/discussions) + +--- + +By contributing, you agree that your contributions will be licensed under AGPL-3.0. diff --git a/docs/docs.json b/docs/docs.json index 649c2919f..db7ac529c 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -21,10 +21,16 @@ { "group": "Core Features", "pages": [ - "features/llm-chat-hub", "features/bring-your-own-llm", + "features/llm-chat-hub", + "features/scheduled-tasks", + "features/use-with-claude-code" "features/ad-blocking", - "features/use-with-claude-code", + ] + }, + { + "group": "Integrations", + "pages": [ "integrations/n8n" ] }, diff --git a/docs/features/scheduled-tasks.mdx b/docs/features/scheduled-tasks.mdx new file mode 100644 index 000000000..b903ececc --- /dev/null +++ b/docs/features/scheduled-tasks.mdx @@ -0,0 +1,59 @@ +--- +title: "Scheduled Tasks" +description: "Run the BrowserOS agent automatically on a schedule" +--- + +Scheduled Tasks let you run the BrowserOS agent automaticallyβ€”daily, every few hours, or every few minutes. You get the full power of the agent running on autopilot. + +## Creating a Scheduled Task + +1. Go to **Settings β†’ Scheduled Tasks** +2. Click **Create Task** +3. Fill in the details: + - **Name** β€” A friendly name for your task + - **Prompt** β€” What you want the agent to do + - **Schedule** β€” Daily at a specific time, every N hours, or every N minutes +4. Click **Create** + +Create scheduled task dialog + +## Example Use Cases + +**Morning briefing** +> Every morning at 8am, check my Google Calendar and send me a summary of today's events. For each meeting, do a quick Google search on the attendees and include their LinkedIn summary. + +**LinkedIn automation** +> Every day, go to LinkedIn and accept up to 25 pending connection requests. + +**Price monitoring** +> Check the price of this Amazon item every hour. If it drops below $50, place the order. + +## Viewing Results + +When a scheduled task runs, you can see the results in two places: + +- **New Tab page** β€” Results show up right on your new tab +- **Settings β†’ Scheduled Tasks** β€” View the full run history for each task + +Scheduled task results + +Click **View** on any task run to see the full output: + +Scheduled task output showing a daily news briefing + +## How It Works + +Scheduled tasks run in a background window, so they don't interrupt whatever you're working on. You won't even notice them running. + + +BrowserOS needs to be open for scheduled tasks to run. If your laptop was closed or BrowserOS wasn't running at the scheduled time, the task will run as soon as you open BrowserOS again. + + +## Pro Tip: Complex Prompts with MCPs + +Your scheduled task prompts can be as complex as you want. If you connect MCP servers (like Google Calendar, Slack, Notion, or Gmail), you can create powerful automated workflows. + +For example: +> Check my Google Calendar for tomorrow's meetings, then post a summary to my Slack channel, and create a Notion page with prep notes for each meeting. + +See [Connect to MCPs](/features/connect-mcps) to set up your integrations. diff --git a/docs/features/use-with-claude-code.mdx b/docs/features/use-with-claude-code.mdx new file mode 100644 index 000000000..e9af6c5fa --- /dev/null +++ b/docs/features/use-with-claude-code.mdx @@ -0,0 +1,144 @@ +--- +title: "Use BrowserOS with Claude Code" +description: "Control your browser from Claude Code, Gemini CLI, or any MCP client" +--- + +BrowserOS is the best browser for AI coding agents. It comes with a built-in MCP server that lets Claude Code control your browser β€” open tabs, extract page content, fill forms, take screenshots, and automate any web task. + + +Unlike Chrome DevTools MCP which requires setting up debug profiles and running separate servers, BrowserOS MCP works out of the box. Just copy the URL from settings and connect. + + +## Why Use BrowserOS with Claude Code? + + + + Claude tests your web app, reads console errors, and fixes the code β€” all in one loop. + + + Extract your LinkedIn profile, tweets, or any authenticated page content. + + + Fill forms, navigate multi-step workflows, and automate repetitive browser tasks. + + + Full browser control: tabs, navigation, clicks, typing, screenshots, bookmarks, and history. + + + +## Getting Started + + + + Navigate to `chrome://browseros/mcp` or click **Settings** β†’ **BrowserOS as MCP** in the sidebar. + + + Copy the Server URL shown on the page (e.g., `http://127.0.0.1:9239/mcp`). + + BrowserOS MCP settings page showing Server URL + + + Use the tabs below to connect your preferred client. + + + + + + Add BrowserOS to Claude Code: + ```bash + claude mcp add --transport http browseros --scope user + # Example: claude mcp add --transport http browseros http://127.0.0.1:9239/mcp --scope user + ``` + + Start Claude Code and try it: + ```bash + claude + > Open amazon.com in BrowserOS + ``` + + + Run `claude --dangerously-skip-permissions` to skip confirmation prompts for each browser action. + + + To remove later: + ```bash + claude mcp remove browseros --scope user + ``` + + + Add BrowserOS to Gemini CLI: + ```bash + gemini mcp add local-server --transport http --scope user + # Example: gemini mcp add local-server http://127.0.0.1:9239/mcp --transport http --scope user + ``` + + + Add BrowserOS to OpenAI Codex CLI: + ```bash + codex mcp add browseros --transport http + # Example: codex mcp add browseros http://127.0.0.1:9239/mcp --transport http + ``` + + + Open your Claude Desktop config file: + ``` + ~/Library/Application Support/Claude/claude_desktop_config.json + ``` + + Add BrowserOS: + ```json + { + "mcpServers": { + "browserOS": { + "command": "npx", + "args": ["mcp-remote", "http://127.0.0.1:9239/mcp"] + } + } + } + ``` + + Restart Claude Desktop to connect. + + + +## Example Prompts + +Once connected, try these prompts in Claude Code: + +``` +Open my LinkedIn profile in BrowserOS and extract my work experience as JSON +``` + +``` +In BrowserOS, go to localhost:3000, click the login button, and check for console errors +``` + +``` +Take a screenshot of the current page in BrowserOS and save it to screenshots/ +``` + +``` +Search my BrowserOS history for "invoice" and list the recent matches +``` + +## Available Tools + +BrowserOS exposes 31 tools to MCP clients: + +| Category | Tools | +|----------|-------| +| **Tabs** | open, close, switch, list, group, ungroup | +| **Navigation** | navigate, scroll up/down, scroll to element | +| **Interaction** | click, type, clear input, send keys | +| **Content** | get page content, get interactive elements, execute JavaScript | +| **Screenshots** | capture page, capture with pointer overlay | +| **Bookmarks** | list, create, remove | +| **History** | search, get recent | + +## Demo Videos + +### Agentic coding workflow +[![Frontend dev demo](https://img.youtube.com/vi/vcSxzIIkg_0/0.jpg)](https://youtu.be/vcSxzIIkg_0) + +### Browser automation with Claude Code +[![Agentic tasks demo](https://img.youtube.com/vi/rPFx_Btajj0/0.jpg)](https://youtu.be/rPFx_Btajj0) diff --git a/docs/images/contributing--architecture.png b/docs/images/contributing--architecture.png new file mode 100644 index 000000000..9531e9b34 --- /dev/null +++ b/docs/images/contributing--architecture.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:59c78fa8b3696cc7e6799e90e6d744646a65ca4209b9e3fdddb2ab0e1e344029 +size 873000 diff --git a/docs/images/features--browseros-mcp-settings.png b/docs/images/features--browseros-mcp-settings.png new file mode 100644 index 000000000..12e228263 --- /dev/null +++ b/docs/images/features--browseros-mcp-settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4b56bf0f3b9d029f2f020a4a255250c7c85b97eea9d98b4402f46fe350d0ea6b +size 4448586 diff --git a/docs/images/features--scheduled-tasks-create.png b/docs/images/features--scheduled-tasks-create.png new file mode 100644 index 000000000..e86178b39 --- /dev/null +++ b/docs/images/features--scheduled-tasks-create.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:62047e65722bb8864fc25d16a03a76f9b3ba7fb5d79d39dc834b5d3fc78252dc +size 2626804 diff --git a/docs/images/features--scheduled-tasks-output.png b/docs/images/features--scheduled-tasks-output.png new file mode 100644 index 000000000..e4ec5d58e --- /dev/null +++ b/docs/images/features--scheduled-tasks-output.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:85605f45061b62f3f0da7ba464cae3e36939c0d90655c44982c54379c24b452f +size 3886284 diff --git a/docs/images/features--scheduled-tasks-results.png b/docs/images/features--scheduled-tasks-results.png new file mode 100644 index 000000000..e0463706c --- /dev/null +++ b/docs/images/features--scheduled-tasks-results.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e80726cdcc6136055e62ab804d876bd4338e97f16ce70de719a9ba932e47022f +size 2643981 diff --git a/docs/integrations/n8n.mdx b/docs/integrations/n8n.mdx index 7465d8507..9113c0a6f 100644 --- a/docs/integrations/n8n.mdx +++ b/docs/integrations/n8n.mdx @@ -1,101 +1,70 @@ --- title: "n8n Integration" -description: "Connect BrowserOS MCP to n8n for AI-powered browser automation workflows" -icon: "workflow" +description: "Build AI workflows that control your browser" --- -Build AI workflows that automate browser tasks using n8n and BrowserOS MCP. +Connect BrowserOS to n8n to build automated workflows. Your n8n AI agents can control the browserβ€”open pages, click buttons, extract data, and fill forms. + +## What You Can Build + +- **Lead enrichment** β€” Pull a list of LinkedIn URLs from a spreadsheet and scrape each profile +- **Price monitoring** β€” Check product prices hourly and send a Slack alert when they drop +- **Form automation** β€” Auto-fill job applications using data from your CRM +- **Data extraction** β€” Scrape authenticated pages that require login ## Prerequisites -- Node.js and npm installed ([nodejs.org](https://nodejs.org)) -- BrowserOS running with MCP server enabled -- LLM API key (OpenAI, Claude, etc.) +Before you start: +- BrowserOS running with MCP server enabled (Settings β†’ BrowserOS as MCP) +- n8n running locally (`npx n8n` or install globally with `npm install -g n8n`) ## Setup -### Step 1: Install and Run n8n +### 1. Install the MCP community node -Run n8n locally: +In n8n, go to **Settings β†’ Community Nodes** and install `n8n-nodes-mcp`: -```bash -npx n8n -``` +Installing n8n-nodes-mcp community node -Access n8n at `http://localhost:5678` and complete the initial setup by creating an account. +### 2. Create a workflow - - For global installation: `npm install n8n -g`, then run `n8n` anytime. - +Build a workflow with these nodes: -### Step 2: Install MCP Community Node - -Go to **Settings β†’ Community Nodes** and install `n8n-nodes-mcp`: - - - ![Install n8n-nodes-mcp community node](/images/n8n-node.png) - - -### Step 3: Create Workflow - -Create a new workflow with: - -1. Add a **Chat Trigger** node (this receives user messages) +1. Add a **Chat Trigger** node (receives your messages) 2. Add an **AI Agent** node and connect it to the trigger -3. Under the AI Agent, click **Chat Model** and add your LLM (e.g., OpenAI Chat Model) -4. Under the AI Agent, click **Tool** β†’ search "mcp" β†’ select **MCP Client Tool** +3. Add a **Chat Model** under the AI Agent (e.g., OpenAI, Claude) +4. Add an **MCP Client Tool** under the AI Agent - - ![Workflow with AI Agent and MCP Client](/images/n8n-step3-workflow.png) - +n8n workflow with AI Agent and MCP Client -### Step 4: Configure AI Agent Prompt +### 3. Configure the AI Agent -In the AI Agent node, set **Source for Prompt (User Message)** to **Connected Chat Trigger Node**. +In the AI Agent node, set **Source for Prompt** to **Connected Chat Trigger Node**. - - ![Configure AI Agent prompt](/images/n8n-step4-agent-prompt.png) - +AI Agent prompt configuration -### Step 5: Configure MCP Client +### 4. Connect to BrowserOS -Click on the **MCP Client** node and configure: +Click on the MCP Client node and configure: -1. **Endpoint**: Copy your MCP URL from BrowserOS (e.g., `http://127.0.0.1:9228/mcp`) -2. **Server Transport**: `HTTP Streamable` +- **Endpoint**: Your BrowserOS MCP URL (find it in Settings β†’ BrowserOS as MCP) +- **Server Transport**: `HTTP Streamable` - - Find your MCP URL in BrowserOS under **Settings β†’ MCP**. - +MCP Client configuration with BrowserOS URL - - ![Configure MCP Client node](/images/n8n-step5-mcp-client.png) - +### 5. Test it -### Step 6: Test Workflow - -Save the workflow, click **Open chat**, and send a message: +Save the workflow, click **Open chat**, and try: ``` -open google.com on browserOS +open google.com in BrowserOS ``` - - ![Test the workflow](/images/n8n-step6-test.png) - +Testing the workflow ## Troubleshooting - - Connection issues? Verify: - - - BrowserOS is running - - MCP server is enabled in BrowserOS settings - - Port number matches your BrowserOS MCP configuration - - -## Resources - - - Learn more about BrowserOS MCP - \ No newline at end of file +If the connection fails: +- Make sure BrowserOS is running +- Check that MCP server is enabled in BrowserOS settings +- Verify the port number matches your BrowserOS MCP URL diff --git a/packages/browseros-agent b/packages/browseros-agent index 552558e2f..e4830f485 160000 --- a/packages/browseros-agent +++ b/packages/browseros-agent @@ -1 +1 @@ -Subproject commit 552558e2fdb18a0d981875e8a41b5aae6d8b0b1e +Subproject commit e4830f485a854b40296c9794d936ba1b316d89f1