Keep/mcp-server/START-SSE.md

# Guide de Démarrage - Serveur MCP Keep Notes (Mode SSE)

## 🚀 Démarrage Rapide du Serveur SSE

### Option 1: Script PowerShell (Recommandée pour Windows)

```powershell
# Exécuter depuis le dossier mcp-server
.\start-sse.ps1
```

**Ce script fait:**
- ✅ Vérifie que Prisma est généré
- ✅ Vérifie que Keep Notes est en cours d'exécution (port 3000)
- ✅ Génère Prisma si nécessaire
- ✅ Messages d'erreur clairs
- ✅ Démarre le serveur MCP sur le port 3001

### Option 2: Commande directe

```bash
cd mcp-server
npm run start:sse
```

Ou directement:

```bash
node index-sse.js
```

---

## ✅ Prérequis

### 1. Node.js installé

```bash
node --version
# Doit retourner v18 ou supérieur
```

### 2. Dépendances installées

```bash
cd mcp-server
npm install
```

### 3. Client Prisma généré

```bash
npx prisma generate
```

### 4. Keep Notes en cours d'exécution

Le serveur SSE nécessite que Keep Notes soit démarré sur le port 3000.

```bash
# Dans un autre terminal
cd keep-notes
npm run dev
```

### 5. Port 3001 disponible

Le serveur SSE utilise le port 3001. Vérifiez qu'il n'est pas déjà utilisé:

```bash
# Windows (PowerShell)
netstat -ano | findstr "3001"

# Mac/Linux
lsof -i :3001
```

---

## 🎯 Utilisation avec N8N

### Configuration N8N pour MCP SSE

Le serveur SSE est parfait pour N8N sur une machine distante!

#### Étape 1: Trouver votre IP

**Windows:**
```powershell
ipconfig
```
Cherchez "IPv4 Address" (ex: 192.168.1.100)

**Mac/Linux:**
```bash
ifconfig
# ou
ip addr show
```

#### Étape 2: Configurer N8N

Dans N8N, allez dans **Settings** → **MCP Access** et ajoutez:

```json
{
  "name": "keep-notes",
  "transport": "sse",
  "url": "http://192.168.1.100:3001/sse"
}
```

Remplacez `192.168.1.100` par votre IP réelle.

#### Étape 3: Activer les workflows

1. Importez les workflows N8N (voir `N8N-SETUP.md`)
2. Activez chaque workflow (bouton play)
3. Les workflows peuvent maintenant appeler les outils MCP

---

## 🛠️ Outils Disponibles (19 au total)

### Notes (9 outils)

| # | Outil | Description |
|---|--------|-------------|
| 1 | create_note | Créer une nouvelle note (support complet) |
| 2 | get_notes | Récupérer toutes les notes (supporte filtres) |
| 3 | get_note | Récupérer une note par ID |
| 4 | update_note | Mettre à jour une note |
| 5 | delete_note | Supprimer une note |
| 6 | search_notes | Rechercher des notes |
| 7 | get_labels | Récupérer les labels (méthode legacy) |
| 8 | toggle_pin | Épingler/désépingler une note |
| 9 | toggle_archive | Archiver/désarchiver une note |

### Notebooks (5 outils)

| # | Outil | Description |
|---|--------|-------------|
| 10 | create_notebook | Créer un nouveau notebook |
| 11 | get_notebooks | Récupérer tous les notebooks |
| 12 | get_notebook | Récupérer un notebook avec ses notes |
| 13 | update_notebook | Mettre à jour un notebook |
| 14 | delete_notebook | Supprimer un notebook |

### Labels (5 outils)

| # | Outil | Description |
|---|--------|-------------|
| 15 | create_label | Créer un nouveau label |
| 16 | get_labels_detailed | Récupérer les labels avec détails |
| 17 | update_label | Mettre à jour un label |
| 18 | delete_label | Supprimer un label |

---

## 📊 Tests de Vérification

### Test 1: Health Check

```bash
curl http://localhost:3001/
```

**Réponse attendue:**
```json
{
  "name": "Keep Notes MCP SSE Server",
  "version": "2.0.0",
  "status": "running",
  "endpoints": {
    "sse": "/sse",
    "message": "/message"
  }
}
```

### Test 2: SSE Connection

```bash
curl -N http://localhost:3001/sse
```

### Test 3: Appeler un outil (get_notes)

```bash
curl -X POST http://localhost:3001/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_notes",
      "arguments": {}
    },
    "id": 1
  }'
```

### Test 4: Créer une note

```powershell
$body = @{
    jsonrpc = "2.0"
    method = "tools/call"
    params = @{
        name = "create_note"
        arguments = @{
            content = "Test depuis MCP SSE"
            title = "SSE Test"
            color = "green"
        }
    }
    id = 1
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Method POST -Uri "http://localhost:3001/message" `
  -Body $body -ContentType "application/json"
```

---

## 🔧 Configuration Avancée

### Changer le port

Modifier `index-sse.js`:

```javascript
const PORT = process.env.PORT || 3002;
```

Ou utiliser une variable d'environnement:

```powershell
$env:PORT=3002; node index-sse.js
```

### Sécurisation avec API Key

Ajouter de l'authentification dans `index-sse.js`:

```javascript
app.use((req, res, next) => {
  const apiKey = req.headers['x-api-key'];
  if (apiKey !== process.env.MCP_API_KEY) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
});
```

---

## 🛑 Arrêter le Serveur

Appuyez sur **Ctrl+C** dans le terminal.

Le serveur fermera proprement:
- Arrêtera toutes les connexions SSE
- Déconnectera Prisma de la base de données
- Affichera un message de confirmation

---

## 📚 Documentation Complémentaire

- [README-SSE.md](./README-SSE.md) - Documentation détaillée des outils
- [README.md](./README.md) - Documentation principale du serveur MCP
- [N8N-SETUP.md](./N8N-SETUP.md) - Guide d'installation des workflows N8N
- [N8N-WORKFLOWS.md](./N8N-WORKFLOWS.md) - Description des workflows N8N

---

## 🔍 Dépannage

### Erreur: "Port 3001 already in use"

**Solution 1:** Changer le port dans `index-sse.js`:
```javascript
const PORT = process.env.PORT || 3002;
```

**Solution 2:** Trouver et tuer le processus:
```powershell
Get-Process node | Where-Object {$_.Path -like "*index-sse*"}
Stop-Process -Id $process.Id
```

### Erreur: "Cannot connect from N8N"

**Checklist:**
1. ✅ Serveur SSE en cours d'exécution (`http://localhost:3001` fonctionne)
2. ✅ Firewall autorise le port 3001
3. ✅ Utilisation de l'IP correcte (pas `localhost` depuis N8N distant)
4. ✅ N8N peut atteindre votre réseau
5. ✅ Utilisation de `http://` (pas `https://`)

**Test depuis N8N:**
```bash
curl http://YOUR_IP:3001/
```

### Erreur: "Prisma Client not initialized"

**Solution:**
```bash
cd mcp-server
npx prisma generate
```

### SSE Connection Drops

C'est normal! SSE maintient une connexion persistante. Si elle chute:
- Le client doit se reconnecter automatiquement
- Vérifier la stabilité du réseau
- Vérifier les paramètres firewall/proxy

---

## 🌐 Architecture SSE vs stdio

| Fonctionnalité | SSE (index-sse.js) | stdio (index.js) |
|---------------|----------------------|-------------------|
| **Transport** | HTTP/SSE | Process local |
| **Accès distant** | ✅ Oui | ❌ Non |
| **Port** | 3001 | N/A |
| **Utilisation N8N** | ✅ Parfait | ❌ Impossible |
| **Utilisation Cursor** | ✅ Possible | ✅ Parfait |
| **Setup** | Moyen | Simple |
| **Latence** | Faible | Très faible |
| **Outils** | 19 | 19 |

**Recommandation:**
- **SSE** pour N8N sur machine distante ✅
- **stdio** pour Cursor sur la même machine ✅

---

## 🎉 Démarrage Rapide (Récapitulatif)

```bash
# 1. Démarrer Keep Notes (terminal 1)
cd keep-notes
npm run dev

# 2. Démarrer le serveur MCP SSE (terminal 2)
cd mcp-server
.\start-sse.ps1

# 3. Configurer N8N avec: http://YOUR_IP:3001/sse
# 4. Importer et activer les workflows N8N
# 5. Utiliser les outils MCP dans vos workflows!
```

---

**Version:** 2.0.0
**Dernière mise à jour:** 18 janvier 2026
**Status:** ✅ Production Ready