11 KiB
11 KiB
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
- System Architecture
- Component Details
- Data Flow
- AI Integration
- Performance Optimizations
- 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
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:
// 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:
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:
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
- Define Schema in
packages/shared/src/tools.ts - Implement Tool extending
BaseBrowserToolExecutor - Register Tool in tool index
- Add Tests for functionality
Custom AI Models
- Model Integration in
SemanticSimilarityEngine - Worker Support for processing
- Configuration in model presets
- Performance Testing with benchmarks
Protocol Extensions
- MCP Extensions for custom capabilities
- Transport Layers for different communication methods
- Authentication for secure connections
- 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.