Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
262 lines (189 loc) · 8.44 KB

CONTRIBUTING.md

File metadata and controls

262 lines (189 loc) · 8.44 KB
Raw

Contributing to OpenChrome

Thank you for your interest in contributing!

Getting Started

  1. Fork the repository
  2. Clone your fork
  3. Install dependencies: npm install
  4. Build the project: npm run build
  5. Run tests: npm test

Development Setup

Prerequisites

  • Node.js 18+
  • Google Chrome

Building

# Build everything
npm run build

# Build CLI only (with watch mode)
npm run dev

# Build source only
npm run build:src

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- session-manager.test.ts

Local Testing

# Start MCP server locally
node dist/cli/index.js serve --auto-launch

# Run doctor check
node dist/cli/index.js doctor

Code Style

  • Use TypeScript for all code
  • Follow existing code patterns
  • Use meaningful variable and function names
  • Add comments for complex logic
  • Keep functions focused and small

Commit Messages

Follow conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only
  • style: Formatting, missing semicolons, etc.
  • refactor: Code change that neither fixes a bug nor adds a feature
  • test: Adding missing tests
  • chore: Maintenance

Examples:

  • feat(session): add session timeout configuration
  • fix(cdp): handle reconnection on detach
  • docs(readme): update installation instructions

Pull Request Process

  1. Create a feature branch from main
  2. Make your changes
  3. Add tests if applicable
  4. Update documentation if needed
  5. Ensure all tests pass: npm test
  6. Submit a pull request

PR Checklist

  • Tests added/updated
  • Documentation updated
  • Builds successfully (npm run build)
  • All tests pass (npm test)
  • Commit messages follow convention

Architecture Overview

src/
├── mcp-server.ts          # MCP protocol server (stdio JSON-RPC)
├── session-manager.ts     # Browser session lifecycle
├── index.ts               # Main entry point
├── cdp/                   # Chrome DevTools Protocol layer
│   ├── client.ts          # CDP client wrapper
│   └── connection-pool.ts # Connection pooling
├── chrome/                # Chrome process management
│   ├── launcher.ts        # Auto-launch Chrome with debugging port
│   └── pool.ts            # Browser context pool
├── tools/                 # MCP tool implementations (36 tools)
│   ├── index.ts           # Tool registration
│   ├── navigation.ts      # navigate, page_reload
│   ├── computer.ts        # screenshot, click, keyboard, scroll
│   ├── read-page.ts       # Accessibility tree parsing
│   ├── find.ts            # Natural language element search
│   ├── form.ts            # form_input, fill_form
│   ├── orchestration.ts   # workflow_init, worker_create, etc.
│   └── ...                # Other tool modules
├── orchestration/         # Parallel workflow engine
├── hints/                 # Adaptive Guidance system
│   ├── hint-engine.ts     # Rule evaluation engine
│   └── rules/             # Error recovery, sequence detection, etc.
├── dashboard/             # Terminal dashboard (optional)
├── resources/             # MCP resources (usage guide)
├── config/                # Global configuration
├── types/                 # TypeScript type definitions
└── utils/                 # Shared utilities

cli/
├── index.ts               # CLI entry point (setup, serve, doctor, etc.)
└── update-check.ts        # Version update checker

Key Concepts

  1. CDP-based: Connects to Chrome via Chrome DevTools Protocol (port 9222)
  2. Session Isolation: Each Worker gets an isolated browser context (separate cookies, localStorage)
  3. MCP Protocol: Communicates with Claude Code via JSON-RPC over stdio
  4. Adaptive Guidance: Hint engine injects _hint fields into tool responses to prevent LLM mistakes
  5. Parallel Workflows: Orchestration engine manages multiple Workers for concurrent tasks

Testing Guidelines

Unit Tests

  • Test individual functions and classes
  • Mock CDP connections and Chrome APIs
  • Focus on business logic

Integration Tests

  • Test component interactions (e.g., multi-worker workflows)
  • Use realistic scenarios
  • Verify error handling and recovery

Stress Tests

  • Concurrent operations and race conditions
  • Large data handling
  • Error recovery under load

Contribution Areas

Looking for something to work on? Here are the key areas where contributions would make the biggest impact.

Multi-Client Compatibility

OpenChrome is a standard MCP server, but currently only tested with Claude Code. Help us verify and support other MCP clients. Codex CLI now has a dedicated setup/config preset, but runtime validation is still needed across real environments.

Client Status What's Needed
Claude Code Verified -
Cursor Untested Test all 36 tools, verify instructions field
Windsurf Untested Test all 36 tools, verify instructions field
Codex CLI Preset added, runtime validation needed Verify initialize, tools/list, and at least one browser-backed tool call using the documented Codex config
VS Code + MCP Untested Test basic tool flow

How to contribute: Pick a client, run the test suite against it, report what works and what doesn't. Adapt oc setup to support the client if needed.

Cross-Platform Support

Currently developed and tested on macOS. Windows and Linux need attention.

  • Windows: Chrome path detection, --remote-debugging-port launch, named pipes vs Unix sockets
  • Linux: Headless Chrome in CI environments, Wayland vs X11 screenshot handling
  • CI/CD: GitHub Actions workflow for automated testing across platforms

Performance Benchmarks

The README claims 80x speedup, but we need reproducible benchmarks.

  • Benchmark suite: Automated comparison vs Playwright MCP on standard tasks (navigate, screenshot, form fill)
  • Memory profiling: Measure actual memory usage with 5, 10, 20 Workers
  • Latency analysis: Tool-by-tool latency comparison with other MCP browser tools

Browser Support

Currently Chrome-only via CDP. Other browsers have similar protocols.

  • Edge: Shares CDP — should work with minimal changes (needs testing)
  • Firefox: Uses its own remote debugging protocol (significant work)
  • Safari: Limited Web Inspector protocol (research needed)

Adaptive Guidance Improvements

The hint engine (src/hints/) currently has 21 static rules. Areas to improve:

  • More error patterns: Catalog common LLM mistakes and add recovery hints
  • Client-specific hints: Different LLMs make different mistakes — adapt hints per client
  • Learned pattern sharing: Export/import learned patterns across users
  • Benchmark hint effectiveness: Measure how hints reduce retry loops and wasted tokens

Tool Enhancements

  • Accessibility testing: Tools for WCAG compliance checking
  • Visual regression: Screenshot diff between runs
  • Network HAR export: Export full network traffic as HAR files
  • Video recording: Record browser session as video/GIF
  • Multi-tab orchestration: Coordinate actions across tabs within a single Worker

Developer Experience

  • oc setup for other clients: Auto-configure for Cursor, Windsurf, etc.
  • oc benchmark: Built-in benchmark command
  • oc replay: Replay a recorded session for debugging
  • Plugin system: Allow users to register custom tools

Documentation

  • API reference: Auto-generated docs for all 36 tools with examples
  • Tutorials: Step-by-step guides (e.g., "Automate your CI dashboard")
  • Troubleshooting guide: Common issues and solutions per platform

Good First Issues

If you're new to the project, these are good starting points:

  • Add a new hint rule to src/hints/rules/ (follow existing patterns)
  • Test OpenChrome on a non-Claude MCP client and report results
  • Add Windows Chrome path detection in src/chrome/launcher.ts
  • Write an example script using OpenChrome tools
  • Improve error messages for common setup failures

Questions?

  • Open an issue for bugs or feature requests
  • Check existing issues before creating new ones

License

By contributing, you agree that your contributions will be licensed under the MIT License.