309 lines
11 KiB
Markdown
309 lines
11 KiB
Markdown
# Chrome MCP Server Architecture 🏗️
|
|
|
|
This document provides a detailed technical overview of the Chrome MCP Server architecture, design decisions, and implementation details.
|
|
|
|
## 📋 Table of Contents
|
|
|
|
- [Overview](#overview)
|
|
- [System Architecture](#system-architecture)
|
|
- [Component Details](#component-details)
|
|
- [Data Flow](#data-flow)
|
|
- [AI Integration](#ai-integration)
|
|
- [Performance Optimizations](#performance-optimizations)
|
|
- [Security Considerations](#security-considerations)
|
|
|
|
## 🎯 Overview
|
|
|
|
Chrome MCP Server is a sophisticated browser automation platform that bridges AI assistants with Chrome browser capabilities through the Model Context Protocol (MCP). The architecture is designed for:
|
|
|
|
- **High Performance**: SIMD-optimized AI operations and efficient native messaging
|
|
- **Extensibility**: Modular tool system for easy feature additions
|
|
- **Reliability**: Robust error handling and graceful degradation
|
|
- **Security**: Sandboxed execution and permission-based access control
|
|
|
|
## 🏗️ System Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "AI Assistant Layer"
|
|
A[Claude Desktop]
|
|
B[Custom MCP Client]
|
|
C[Other AI Tools]
|
|
end
|
|
|
|
subgraph "MCP Protocol Layer"
|
|
D[HTTP/SSE Transport]
|
|
E[MCP Server Instance]
|
|
F[Tool Registry]
|
|
end
|
|
|
|
subgraph "Native Server Layer"
|
|
G[Fastify HTTP Server]
|
|
H[Native Messaging Host]
|
|
I[Session Management]
|
|
end
|
|
|
|
subgraph "Chrome Extension Layer"
|
|
J[Background Script]
|
|
K[Content Scripts]
|
|
L[Popup Interface]
|
|
M[Offscreen Documents]
|
|
end
|
|
|
|
subgraph "Browser APIs Layer"
|
|
N[Chrome APIs]
|
|
O[Web APIs]
|
|
P[Native Messaging]
|
|
end
|
|
|
|
subgraph "AI Processing Layer"
|
|
Q[Semantic Engine]
|
|
R[Vector Database]
|
|
S[SIMD Math Engine]
|
|
T[Web Workers]
|
|
end
|
|
|
|
A --> D
|
|
B --> D
|
|
C --> D
|
|
D --> E
|
|
E --> F
|
|
F --> G
|
|
G --> H
|
|
H --> P
|
|
P --> J
|
|
J --> K
|
|
J --> L
|
|
J --> M
|
|
J --> N
|
|
J --> O
|
|
J --> Q
|
|
Q --> R
|
|
Q --> S
|
|
Q --> T
|
|
```
|
|
|
|
## 🔧 Component Details
|
|
|
|
### 1. Native Server (`app/native-server/`)
|
|
|
|
**Purpose**: MCP protocol implementation and native messaging bridge
|
|
|
|
**Key Components**:
|
|
|
|
- **Fastify HTTP Server**: Handles MCP protocol over HTTP/SSE
|
|
- **Native Messaging Host**: Communicates with Chrome extension
|
|
- **Session Management**: Manages multiple MCP client sessions
|
|
- **Tool Registry**: Routes tool calls to Chrome extension
|
|
|
|
**Technologies**:
|
|
|
|
- TypeScript + Fastify
|
|
- MCP SDK (@modelcontextprotocol/sdk)
|
|
- Native messaging protocol
|
|
|
|
### 2. Chrome Extension (`app/chrome-extension/`)
|
|
|
|
**Purpose**: Browser automation and AI-powered content analysis
|
|
|
|
**Key Components**:
|
|
|
|
- **Background Script**: Main orchestrator and tool executor
|
|
- **Content Scripts**: Page interaction and content extraction
|
|
- **Popup Interface**: User configuration and status display
|
|
- **Offscreen Documents**: AI model processing in isolated context
|
|
|
|
**Technologies**:
|
|
|
|
- WXT Framework + Vue 3
|
|
- Chrome Extension APIs
|
|
- WebAssembly + SIMD
|
|
- Transformers.js
|
|
|
|
### 3. Shared Packages (`packages/`)
|
|
|
|
#### 3.1 Shared Types (`packages/shared/`)
|
|
|
|
- Tool schemas and type definitions
|
|
- Common interfaces and utilities
|
|
- MCP protocol types
|
|
|
|
#### 3.2 WASM SIMD (`packages/wasm-simd/`)
|
|
|
|
- Rust-based SIMD-optimized math functions
|
|
- WebAssembly compilation with Emscripten
|
|
- 4-8x performance improvement for vector operations
|
|
|
|
## 🔄 Data Flow
|
|
|
|
### Tool Execution Flow
|
|
|
|
```
|
|
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ ┌──────────────┐
|
|
│ AI Assistant│ │ Native Server│ │ Chrome Extension│ │ Browser APIs │
|
|
└─────┬───────┘ └──────┬───────┘ └─────────┬───────┘ └──────┬───────┘
|
|
│ │ │ │
|
|
│ 1. Tool Call │ │ │
|
|
├──────────────────►│ │ │
|
|
│ │ 2. Native Message │ │
|
|
│ ├─────────────────────►│ │
|
|
│ │ │ 3. Execute Tool │
|
|
│ │ ├──────────────────►│
|
|
│ │ │ 4. API Response │
|
|
│ │ │◄──────────────────┤
|
|
│ │ 5. Tool Result │ │
|
|
│ │◄─────────────────────┤ │
|
|
│ 6. MCP Response │ │ │
|
|
│◄──────────────────┤ │ │
|
|
```
|
|
|
|
### AI Processing Flow
|
|
|
|
```
|
|
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ ┌──────────────┐
|
|
│ Content │ │ Text Chunker │ │ Semantic Engine │ │ Vector DB │
|
|
│ Extraction │ │ │ │ │ │ │
|
|
└─────┬───────┘ └──────┬───────┘ └─────────┬───────┘ └──────┬───────┘
|
|
│ │ │ │
|
|
│ 1. Raw Content │ │ │
|
|
├──────────────────►│ │ │
|
|
│ │ 2. Text Chunks │ │
|
|
│ ├─────────────────────►│ │
|
|
│ │ │ 3. Embeddings │
|
|
│ │ ├──────────────────►│
|
|
│ │ │ │
|
|
│ │ 4. Search Query │ │
|
|
│ ├─────────────────────►│ │
|
|
│ │ │ 5. Query Vector │
|
|
│ │ ├──────────────────►│
|
|
│ │ │ 6. Similar Docs │
|
|
│ │ │◄──────────────────┤
|
|
│ │ 7. Search Results │ │
|
|
│ │◄─────────────────────┤ │
|
|
```
|
|
|
|
## 🧠 AI Integration
|
|
|
|
### Semantic Similarity Engine
|
|
|
|
**Architecture**:
|
|
|
|
- **Model Support**: BGE-small-en-v1.5, E5-small-v2, Universal Sentence Encoder
|
|
- **Execution Context**: Web Workers for non-blocking processing
|
|
- **Optimization**: SIMD acceleration for vector operations
|
|
- **Caching**: LRU cache for embeddings and tokenization
|
|
|
|
**Performance Optimizations**:
|
|
|
|
```typescript
|
|
// SIMD-accelerated cosine similarity
|
|
const similarity = await simdMath.cosineSimilarity(vecA, vecB);
|
|
|
|
// Batch processing for efficiency
|
|
const similarities = await simdMath.batchSimilarity(vectors, query, dimension);
|
|
|
|
// Memory-efficient matrix operations
|
|
const matrix = await simdMath.similarityMatrix(vectorsA, vectorsB, dimension);
|
|
```
|
|
|
|
### Vector Database (hnswlib-wasm)
|
|
|
|
**Features**:
|
|
|
|
- **Algorithm**: Hierarchical Navigable Small World (HNSW)
|
|
- **Implementation**: WebAssembly for near-native performance
|
|
- **Persistence**: IndexedDB storage with automatic cleanup
|
|
- **Scalability**: Handles 10,000+ documents efficiently
|
|
|
|
**Configuration**:
|
|
|
|
```typescript
|
|
const config: VectorDatabaseConfig = {
|
|
dimension: 384, // Model embedding dimension
|
|
maxElements: 10000, // Maximum documents
|
|
efConstruction: 200, // Build-time accuracy
|
|
M: 16, // Connectivity parameter
|
|
efSearch: 100, // Search-time accuracy
|
|
enableAutoCleanup: true, // Automatic old data removal
|
|
maxRetentionDays: 30, // Data retention period
|
|
};
|
|
```
|
|
|
|
## ⚡ Performance Optimizations
|
|
|
|
### 1. SIMD Acceleration
|
|
|
|
**Rust Implementation**:
|
|
|
|
```rust
|
|
use wide::f32x4;
|
|
|
|
fn cosine_similarity_simd(&self, vec_a: &[f32], vec_b: &[f32]) -> f32 {
|
|
let len = vec_a.len();
|
|
let simd_lanes = 4;
|
|
let simd_len = len - (len % simd_lanes);
|
|
|
|
let mut dot_sum_simd = f32x4::ZERO;
|
|
let mut norm_a_sum_simd = f32x4::ZERO;
|
|
let mut norm_b_sum_simd = f32x4::ZERO;
|
|
|
|
for i in (0..simd_len).step_by(simd_lanes) {
|
|
let a_chunk = f32x4::new(vec_a[i..i+4].try_into().unwrap());
|
|
let b_chunk = f32x4::new(vec_b[i..i+4].try_into().unwrap());
|
|
|
|
dot_sum_simd = a_chunk.mul_add(b_chunk, dot_sum_simd);
|
|
norm_a_sum_simd = a_chunk.mul_add(a_chunk, norm_a_sum_simd);
|
|
norm_b_sum_simd = b_chunk.mul_add(b_chunk, norm_b_sum_simd);
|
|
}
|
|
|
|
// Calculate final similarity
|
|
let dot_product = dot_sum_simd.reduce_add();
|
|
let norm_a = norm_a_sum_simd.reduce_add().sqrt();
|
|
let norm_b = norm_b_sum_simd.reduce_add().sqrt();
|
|
|
|
dot_product / (norm_a * norm_b)
|
|
}
|
|
```
|
|
|
|
### 2. Memory Management
|
|
|
|
**Strategies**:
|
|
|
|
- **Object Pooling**: Reuse Float32Array buffers
|
|
- **Lazy Loading**: Load AI models on-demand
|
|
- **Cache Management**: LRU eviction for embeddings
|
|
- **Garbage Collection**: Explicit cleanup of large objects
|
|
|
|
### 3. Concurrent Processing
|
|
|
|
**Web Workers**:
|
|
|
|
- **AI Processing**: Separate worker for model inference
|
|
- **Content Indexing**: Background indexing of tab content
|
|
- **Network Capture**: Parallel request processing
|
|
|
|
## 🔧 Extension Points
|
|
|
|
### Adding New Tools
|
|
|
|
1. **Define Schema** in `packages/shared/src/tools.ts`
|
|
2. **Implement Tool** extending `BaseBrowserToolExecutor`
|
|
3. **Register Tool** in tool index
|
|
4. **Add Tests** for functionality
|
|
|
|
### Custom AI Models
|
|
|
|
1. **Model Integration** in `SemanticSimilarityEngine`
|
|
2. **Worker Support** for processing
|
|
3. **Configuration** in model presets
|
|
4. **Performance Testing** with benchmarks
|
|
|
|
### Protocol Extensions
|
|
|
|
1. **MCP Extensions** for custom capabilities
|
|
2. **Transport Layers** for different communication methods
|
|
3. **Authentication** for secure connections
|
|
4. **Monitoring** for performance metrics
|
|
|
|
This architecture enables Chrome MCP Server to deliver high-performance browser automation with advanced AI capabilities while maintaining security and extensibility.
|