BROWSER_MCP_GUIDE.md

# 🌐 Browser MCP Integration - PageChat

## Vue d'ensemble

Browser MCP ajoute des capacités d'automatisation web intelligentes à votre chat PageChat. Les utilisateurs peuvent maintenant contrôler un navigateur directement depuis le chat !

## 🎯 Fonctionnalités

### Navigation Web
- **Navigation automatique** vers n'importe quelle URL
- **Captures d'écran** haute qualité
- **Extraction de contenu** intelligente
- **Interaction avec les éléments** (clic, saisie)

### Commandes Disponibles

#### Navigation de base
```
/browse https://example.com     # Naviguer vers une URL
/web info                       # Infos de la page actuelle
/web screenshot                 # Capture d'écran
```

#### Extraction de contenu
```
/web text                       # Tout le texte de la page
/web text .article             # Texte d'un élément spécifique
/web search "mot-clé"          # Rechercher du texte
/web links                      # Extraire tous les liens
```

#### Interaction avec la page
```
/web click #button             # Cliquer sur un élément
/web fill #email=user@test.com # Remplir un champ
/web wait .loading            # Attendre qu'un élément apparaisse
```

#### Aide
```
/web help                      # Afficher toutes les commandes
```

## 🚀 Installation et Configuration

### 1. Dépendances installées
- `playwright` - Automatisation de navigateur
- `mcp` - Model Context Protocol
- `beautifulsoup4` - Parsing HTML
- `lxml` - Parser XML/HTML rapide

### 2. Démarrage
```bash
# Linux/Mac
chmod +x start_with_browser.sh
./start_with_browser.sh

# Windows
start_with_browser.bat
```

### 3. Test de fonctionnement
1. Ouvrir le chat PageChat
2. Taper : `/browse https://example.com`
3. Voir la réponse avec capture d'écran !

## 🎨 Exemples d'utilisation

### Exemple 1 : Recherche d'informations
```
Utilisateur: /browse https://news.ycombinator.com
Bot: ✅ Navigation réussie vers https://news.ycombinator.com
     Titre: Hacker News
     📸 Capture d'écran prise...

Utilisateur: /web text .titleline
Bot: 📝 Texte extrait:
     Show HN: My new project
     Ask HN: How do you handle...
     YC W25 batch companies...
```

### Exemple 2 : Automatisation de formulaire
```
Utilisateur: /browse https://example.com/contact
Bot: ✅ Navigation réussie...

Utilisateur: /web fill #name=John Doe
Bot: ✏️ Champ rempli: #name = 'John Doe'

Utilisateur: /web fill #email=john@example.com
Bot: ✏️ Champ rempli: #email = 'john@example.com'

Utilisateur: /web click #submit
Bot: 👆 Clic effectué sur: #submit
```

### Exemple 3 : Monitoring de page
```
Utilisateur: /browse https://status.github.com
Bot: ✅ Navigation réussie...

Utilisateur: /web search "incident"
Bot: 🔍 Recherche de 'incident': ❌ Non trouvé

Utilisateur: /web search "operational"
Bot: 🔍 Recherche de 'operational': ✅ Trouvé
```

## 🔧 Configuration Avancée

### Personnalisation du navigateur
Éditez `browser_mcp_server.py` :

```python
# Changer la résolution
viewport={'width': 1920, 'height': 1080}

# Mode non-headless (visible)
browser = await playwright.chromium.launch(headless=False)

# User agent personnalisé
user_agent='Mozilla/5.0 (Custom Browser Bot)'
```

### Sécurité
- Le navigateur tourne en mode **sandbox**
- **Pas d'accès filesystem** par défaut
- **Timeout automatique** sur les opérations longues
- **Limite de mémoire** configurée

## 🐛 Dépannage

### Problème : "❌ Impossible de démarrer Browser MCP"
**Solution :** Installer Playwright browsers
```bash
python -m playwright install chromium
```

### Problème : Timeout sur les pages lentes
**Solution :** Augmenter le timeout dans les commandes
```python
await browser_state.page.goto(url, timeout=30000)  # 30 secondes
```

### Problème : Élément non trouvé
**Solution :** Utiliser des sélecteurs CSS plus spécifiques
```
/web click button[type="submit"]     # Au lieu de #submit
/web fill input[name="email"]=...   # Au lieu de #email
```

## 🎯 Cas d'usage avancés

### 1. Monitoring de site web
```python
# Dans le chat
/browse https://mysite.com
/web search "error"
/web screenshot
```

### 2. Test d'interface utilisateur
```python
/browse https://myapp.com/login
/web fill #username=testuser
/web fill #password=testpass
/web click #login-btn
/web wait .dashboard
/web screenshot
```

### 3. Scraping de données
```python
/browse https://example.com/products
/web text .product-title
/web links
/web screenshot
```

## 🔄 Intégration avec HF Spaces

Le Browser MCP fonctionne également sur **Hugging Face Spaces** avec quelques adaptations :

### Dockerfile pour HF Spaces
```dockerfile
# Ajouter au Dockerfile existant
RUN playwright install chromium
RUN playwright install-deps
```

### Variables d'environnement
```bash
# Pour HF Spaces
PLAYWRIGHT_BROWSERS_PATH=/tmp/playwright
```

## 🎉 Conclusion

Browser MCP transforme votre chat en un **assistant web intelligent** capable de :
- 🌐 Naviguer sur n'importe quel site
- 📸 Capturer et analyser des pages
- 🤖 Automatiser des tâches répétitives
- 🔍 Extraire des informations précises

**Votre chat est maintenant un navigateur IA ! 🚀**