Harbor

AI capabilities for the web, on your terms.

Harbor is a Firefox browser extension with a native Node.js bridge that brings AI models and MCP (Model Context Protocol) tools to web applications — with user consent and local-first privacy.

┌──────────────────┐                              ┌──────────────────┐
│ Firefox Extension│  ◄── stdin/stdout JSON ──►  │ Node.js Bridge   │
│   (sidebar UI)   │                              │  (auto-started)  │
└──────────────────┘                              └────────┬─────────┘
                                                           │
                                    ┌──────────────────────┼──────────────────────┐
                                    │                      │                      │
                              ┌─────▼─────┐         ┌──────▼──────┐        ┌──────▼──────┐
                              │ LLM       │         │ MCP Servers │        │ MCP Servers │
                              │ (Ollama)  │         │  (stdio)    │        │  (Docker)   │
                              └───────────┘         └─────────────┘        └─────────────┘

✨ Features

• Local LLM Integration — Use Ollama, llamafile, or other local models
• MCP Server Management — Install, run, and manage MCP servers from a curated directory
• JS AI Provider — Exposes window.ai and window.agent APIs to web pages
• Permission System — Per-origin capability grants with user consent
• Docker Isolation — Optional containerized execution for MCP servers

---

📚 Documentation

Choose the guide that matches your needs:

For Users

Document	Description
User Guide	Install Harbor, set up LLMs, manage MCP servers

For Developers Building Apps with Harbor

Document	Description
Developer Guide	Full API reference for window.ai and window.agent
JS AI Provider API	Detailed API with examples and TypeScript types
Demo Code	Working examples of Harbor integration

For AI Agents

Document	Description
LLMS.txt	Compact, token-efficient reference for AI coding assistants

For Harbor Contributors

Document	Description
Contributing Guide	Build, test, and contribute to Harbor
Architecture	System design and component overview
MCP Host	MCP execution environment internals
Testing Plan	Test coverage and QA procedures

---

🚀 Quick Start

Prerequisites

• Firefox 109+
• Node.js 18+ (for development)
• Ollama or llamafile (for LLM)

Installation

Option 1: macOS Installer

# Download and run Harbor-x.x.x.pkg
# Restart Firefox after installation

Option 2: Build from Source

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

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

# Build bridge (including submodule)
cd bridge-ts/src/any-llm-ts && npm install && npm run build && cd ../..
npm install && npm run build && cd ..

# Install native messaging manifest
cd bridge-ts/scripts && ./install_native_manifest_macos.sh && cd ../..

# Load extension in Firefox
# Go to: about:debugging#/runtime/this-firefox
# Click "Load Temporary Add-on" → select extension/dist/manifest.json

Verify Installation

1. Click the Harbor sidebar icon in Firefox
2. You should see "Connected" status
3. Click "Detect" under LLM settings to find your local model

---

🎯 How It Works

Web Page Integration:

// Check if Harbor is available
if (window.agent) {
  // Request permissions
  await window.agent.requestPermissions({
    scopes: ['model:prompt', 'mcp:tools.list', 'mcp:tools.call'],
    reason: 'Enable AI features'
  });

  // Use AI text generation
  const session = await window.ai.createTextSession();
  const response = await session.prompt('Hello!');

  // Run agent tasks with tools
  for await (const event of window.agent.run({ task: 'Search my files' })) {
    console.log(event);
  }
}

Permission Scopes:

Scope	Description
model:prompt	Basic text generation
model:tools	AI with tool calling
mcp:tools.list	List available MCP tools
mcp:tools.call	Execute MCP tools
browser:activeTab.read	Read active tab content

---

🗂 Project Structure

harbor/
├── extension/          # Firefox Extension (TypeScript, Vite)
├── bridge-ts/          # Node.js Native Messaging Bridge
│   ├── src/
│   │   ├── host/       # MCP execution environment
│   │   ├── mcp/        # MCP protocol client
│   │   ├── chat/       # Chat orchestration
│   │   ├── llm/        # LLM providers
│   │   ├── installer/  # Server installation
│   │   └── catalog/    # Server directory
│   └── scripts/        # Native manifest installers
├── demo/               # Example web pages
├── docs/               # Documentation
└── installer/          # Distributable packages

---

🛠 Development

# Watch mode (bridge)
cd bridge-ts && npm run dev

# Watch mode (extension)
cd extension && npm run dev

# Run tests
cd bridge-ts && npm test
cd extension && npm test

See Contributing Guide for detailed development instructions.

---

📊 Roadmap

• Native messaging bridge
• MCP server management
• LLM integration (Ollama, llamafile)
• Chat orchestration with tool calling
• JS AI Provider (window.ai, window.agent)
• Permission system
• v1.0 Production release
• Windows/Linux installers
• Chrome extension support

---

📄 License

MIT