Contributing to Harbor

This guide is for developers who want to contribute to Harbor itself. If you're looking to build applications using Harbor, see Developer Guide instead.

Getting Started
Project Structure
Development Workflow
Testing
Code Style
Pull Request Process

Getting Started

Prerequisites

Rust (latest stable, for the native bridge)
Node.js 18+ (with npm, for the extension)
Firefox 109+ or Chrome 120+ (for testing the extension)
Python 3.9+ with uvx (for Python MCP servers)
Docker (optional, for isolated server execution)
Git (with submodule support)

Initial Setup

# Clone with submodules
git clone --recurse-submodules https://github.com/r/harbor.git
cd harbor

# If you already cloned without submodules:
git submodule update --init --recursive

Full Build

# Build the Rust bridge
cd bridge-rs
cargo build --release
cd ..

# Build the extension
cd extension
npm install
npm run build
cd ..

# Install native messaging manifest
cd bridge-rs
./install.sh
cd ..

Load Extension for Testing

Open Firefox and go to about:debugging#/runtime/this-firefox
Click "Load Temporary Add-on..."
Select extension/dist/manifest.json
The Harbor sidebar icon should appear

Project Structure

harbor/
├── extension/              # Harbor Extension - Infrastructure (TypeScript + esbuild)
│   ├── src/
│   │   ├── background.ts   # Native messaging, server management
│   │   ├── sidebar.ts      # Main sidebar UI
│   │   ├── js-runtime/     # In-browser JS MCP runtime
│   │   ├── wasm/           # In-browser WASM MCP runtime
│   │   ├── llm/            # LLM provider abstraction
│   │   ├── mcp/            # MCP protocol & host
│   │   └── policy/         # Feature flags
│   └── dist/               # Built output
│
├── web-agents-api/         # Web Agents API Extension - Implements window.ai/agent
│   ├── src/
│   │   ├── background.ts   # Cross-extension messaging to Harbor
│   │   ├── injected.ts     # window.ai and window.agent implementation
│   │   ├── content-script.ts  # Script injection
│   │   └── policy/         # Permission system
│   └── dist/               # Built output
│
├── bridge-rs/              # Rust Native Messaging Bridge
│   ├── src/
│   │   ├── main.rs         # Entry point
│   │   ├── native_messaging.rs  # Stdin/stdout JSON framing
│   │   ├── rpc/            # RPC method handlers
│   │   ├── llm/            # LLM provider configuration
│   │   ├── js/             # QuickJS runtime for JS MCP servers
│   │   ├── oauth/          # OAuth flow handling
│   │   └── fs/             # Filesystem utilities
│   └── any-llm-rust/       # Multi-provider LLM library (submodule)
│
├── demo/                   # Demo web pages
│   ├── web-agents/         # Web Agent API demos
│   └── web-agent-control/  # Browser interaction demos
│
├── mcp-servers/            # MCP server examples and templates
│   ├── builtin/            # Built-in servers (echo, time)
│   ├── examples/           # Example implementations
│   └── templates/          # Starter templates
│
├── docs/                   # Documentation
│   ├── USER_GUIDE.md       # End-user guide
│   ├── DEVELOPER_GUIDE.md  # API reference for app developers
│   ├── LLMS.txt            # AI agent reference
│   ├── JS_AI_PROVIDER_API.md
│   ├── MCP_HOST.md
│   └── TESTING_YOUR_APP.md # Testing apps that use the API
│
├── installer/              # Distributable packages
│   └── macos/              # macOS .pkg builder
│
├── ARCHITECTURE.md         # System architecture
├── CONTRIBUTING.md         # This file
└── README.md               # Project overview

Key Components

Component	Path	Description
Web Agent API	`web-agents-api/src/injected.ts`	window.ai/window.agent implementation
Permission System	`web-agents-api/src/policy/`	Origin permission grants
Harbor Client	`web-agents-api/src/harbor-client.ts`	Cross-extension messaging to Harbor
Native Messaging	`bridge-rs/src/native_messaging.rs`	Stdin/stdout JSON framing
RPC Handlers	`bridge-rs/src/rpc/`	All bridge message types
LLM Config	`bridge-rs/src/llm/`	LLM provider configuration
QuickJS Runtime	`bridge-rs/src/js/`	Sandboxed JS MCP server execution
OAuth	`bridge-rs/src/oauth/`	OAuth flow handling
MCP Host	`extension/src/mcp/`	MCP server management

Development Workflow

Watch Mode

For active development:

# Terminal 1: Build bridge (rerun after changes)
cd bridge-rs
cargo build --release

# Terminal 2: Watch extension
cd extension
npm run dev

After each rebuild:

Bridge: Changes take effect on next extension reload
Extension: Go to about:debugging and click "Reload" on the Harbor extension

Debugging

Extension (Browser Console):

Cmd+Shift+J (Mac) or Ctrl+Shift+J

Bridge (Logs): The bridge logs to a file. Check:

macOS: ~/Library/Caches/harbor-bridge.log
Linux: ~/.cache/harbor-bridge.log

For development, you can run the bridge manually:

cd bridge-rs
echo '{"type":"hello","request_id":"1"}' | cargo run

MCP Server Logs:

# View logs for a running server
# In the sidebar, click server name → "Logs"

Data Locations

During development, Harbor stores data in ~/.harbor/:

File	Purpose
`harbor.db`	Server configurations (SQLite)
`catalog.db`	Catalog cache (SQLite)
`installed_servers.json`	Installed servers
`secrets/credentials.json`	API keys
`sessions/*.json`	Chat sessions

To reset all state:

rm -rf ~/.harbor

Testing

Test Suites

Package	Command	Coverage
Bridge	`cd bridge-rs && cargo test`	RPC, LLM, JS runtime
Extension	`cd extension && npm test`	Provider injection

Running Tests

# Run Rust bridge tests
cd bridge-rs
cargo test

# Run extension tests
cd extension
npm test

Manual QA

Run through key flows as needed: server installation and connection, permission prompts, tool invocation, rate limiting. See tests/README.md for E2E and manual test setup.

Code Style

Rust

Follow standard Rust conventions
Use cargo fmt for formatting
Use cargo clippy for linting
Document public APIs with doc comments

TypeScript

Use strict TypeScript (strict: true in tsconfig)
Prefer interface over type for object shapes
Use explicit return types on exported functions
Document public APIs with JSDoc comments

Logging and Debug Statements

The codebase contains console.log statements used for debugging during development. For production releases:

Debug flags: Files with const DEBUG = true/false should have DEBUG set to false before release
Console logging: Console statements are intentionally left in place for debugging. They appear in the browser's extension console and don't affect end users
Bridge logging: The Rust bridge uses the tracing crate and logs to ~/.cache/harbor-bridge.log

When adding new debugging output, prefer using the existing DEBUG flag pattern:

const DEBUG = false;  // Set to true for development
if (DEBUG) console.log('Debug info:', data);

Naming Conventions

Type	Convention	Example
Rust files	`snake_case.rs`	`native_messaging.rs`
TS files	`kebab-case.ts`	`tool-registry.ts`
Rust structs	`PascalCase`	`LlmConfig`
TS classes	`PascalCase`	`McpHost`
Functions	`snake_case` (Rust) / `camelCase` (TS)	`list_tools()` / `listTools()`

Commit Messages

Use conventional commits:

feat: add tool router for intelligent server selection
fix: handle server crash during tool call
docs: update developer guide with new APIs
test: add integration tests for permissions
chore: upgrade dependencies

Pull Request Process

Before Submitting

Run tests:

cd bridge-rs && cargo test
cd extension && npm test

Format and lint:

cd bridge-rs && cargo fmt && cargo clippy

Test manually:
- Load the extension in Firefox
- Verify your changes work as expected
- Check the Browser Console for errors
Update documentation if you're changing:
- APIs → Update DEVELOPER_GUIDE.md and LLMS.txt
- Architecture → Update ARCHITECTURE.md
- User-facing features → Update USER_GUIDE.md

PR Template

## Description
<!-- What does this PR do? -->

## Testing
<!-- How did you test this? -->

## Checklist
- [ ] Tests pass (`cargo test`, `npm test`)
- [ ] Code formatted (`cargo fmt`)
- [ ] Extension loads without errors
- [ ] Documentation updated (if applicable)

Review Process

Open a PR against main
Wait for CI checks to pass
Request review
Address feedback
Merge when approved

Common Tasks

Adding a New RPC Message Type

Define the message type in bridge-rs/src/rpc/mod.rs
Add handler function
Add response handling in extension/src/background.ts
Update documentation in README.md or DEVELOPER_GUIDE.md

Adding a New LLM Provider

Add provider implementation in bridge-rs/any-llm-rust/src/providers/
Register in the provider registry
Update detection logic in bridge-rs/src/llm/

Release Checklist

Before a release:

Getting Help

Architecture questions: Check ARCHITECTURE.md first
API questions: Check DEVELOPER_GUIDE.md
Test questions: Check tests/README.md; for testing your own app that uses the API, see docs/TESTING_YOUR_APP.md
File issues: For bugs or feature requests

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to Harbor

Table of Contents

Getting Started

Prerequisites

Initial Setup

Full Build

Load Extension for Testing

Project Structure

Key Components

Development Workflow

Watch Mode

Debugging

Data Locations

Testing

Test Suites

Running Tests

Manual QA

Code Style

Rust

TypeScript

Logging and Debug Statements

Naming Conventions

Commit Messages

Pull Request Process

Before Submitting

PR Template

Review Process

Common Tasks

Adding a New RPC Message Type

Adding a New LLM Provider

Release Checklist

Getting Help

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to Harbor

Table of Contents

Getting Started

Prerequisites

Initial Setup

Full Build

Load Extension for Testing

Project Structure

Key Components

Development Workflow

Watch Mode

Debugging

Data Locations

Testing

Test Suites

Running Tests

Manual QA

Code Style

Rust

TypeScript

Logging and Debug Statements

Naming Conventions

Commit Messages

Pull Request Process

Before Submitting

PR Template

Review Process

Common Tasks

Adding a New RPC Message Type

Adding a New LLM Provider

Release Checklist

Getting Help