feat: RTL/i18n, AI translate+undo, no-refresh saves, settings perf

- RTL: force dir=rtl on LabelFilter, NotesViewToggle, LabelManagementDialog - i18n: add missing keys (notifications, privacy, edit/preview, AI translate/undo) - Settings pages: convert to Server Components (general, appearance) + loading skeleton - AI menu: add Translate option (10 languages) + Undo AI button in toolbar - Fix: saveInline uses REST API instead of Server Action → eliminates all implicit refreshes in list mode - Fix: NotesTabsView notes sync effect preserves selected note on content changes - Fix: auto-tag suggestions now filter already-assigned labels - Fix: color change in card view uses local state (no refresh) - Fix: nav links use <Link> for prefetching (Settings, Admin) - Fix: suppress duplicate label suggestions already on note - Route: add /api/ai/translate endpoint
2026-04-15 23:48:28 +02:00
parent 39671c6472
commit b6a548acd8
68 changed files with 5014 additions and 485 deletions
--- a/docs/guide-utilisateur-mcp.md
+++ b/docs/guide-utilisateur-mcp.md
@@ -0,0 +1,364 @@
+# Guide Utilisateur : MCP dans Keep Notes
+
+## Table des matières
+
+1. [Qu'est-ce que MCP ? (en termes simples)](#1-quest-ce-que-mcp--en-termes-simples)
+2. [Comment ça marche dans Keep Notes](#2-comment-ca-marche-dans-keep-notes)
+3. [Les clés API : à quoi ça sert](#3-les-cles-api--a-quoi-ca-sert)
+4. [Gérer ses clés API depuis l'interface](#4-gerer-ses-cles-api-depuis-linterface)
+5. [Configurer Claude Code](#5-configurer-claude-code)
+6. [Configurer Cursor](#6-configurer-cursor)
+7. [Configurer N8N](#7-configurer-n8n)
+8. [Questions fréquentes](#8-questions-frequentes)
+
+---
+
+## 1. Qu'est-ce que MCP ? (en termes simples)
+
+**MCP** = **Model Context Protocol** (Protocole de Contexte de Modèle).
+
+C'est un standard qui permet à des outils IA (comme Claude, Cursor, N8N) de **parler** à votre application Keep Notes.
+
+### Analogie simple
+
+Imaginez que Keep Notes est un restaurant. Normalement, pour lire le menu ou commander, vous devez ouvrir l'application web dans votre navigateur.
+
+MCP, c'est comme un **service de livraison** : il permet à d'autres applications de passer des commandes directement au restaurant, sans ouvrir le site web. Votre clé API, c'est votre **numéro de client** qui prouve que vous avez le droit de commander.
+
+### Concrètement, que permet MCP ?
+
+Avec MCP, vous pouvez depuis Claude Code, Cursor ou N8N :
+
+- **Lire** vos notes existantes
+- **Créer** de nouvelles notes
+- **Rechercher** dans vos notes (recherche sémantique IA)
+- **Organiser** vos notes dans des carnets
+- **Gérer** vos étiquettes
+- **Générer des titres** avec l'IA
+- Et 30+ autres actions
+
+### Les deux modes de connexion
+
+Votre serveur MCP Keep Notes peut fonctionner de deux façons :
+
+| Mode | Comment ça marche | Pour qui | Clé API nécessaire ? |
+|------|-------------------|----------|----------------------|
+| **Stdio** | L'outil IA lance directement le serveur MCP en arrière-plan | Claude Code, Cursor (local) | Non |
+| **HTTP** | Le serveur MCP tourne en continu sur le port 3001, les outils s'y connectent via le réseau | N8N, Cursor (distant), tout outil réseau | Oui |
+
+---
+
+## 2. Comment ça marche dans Keep Notes
+
+Votre projet Keep Notes contient **deux serveurs** qui partagent la même base de données :
+
+```
+Keep/
+├── keep-notes/          ← Application web (port 3000)
+│   └── prisma/dev.db    ← Base de données SQLite
+│
+└── mcp-server/          ← Serveur MCP (port 3001 en mode HTTP)
+    ├── index.js         ← Mode Stdio
+    ├── index-sse.js     ← Mode HTTP
+    └── tools.js         ← Les 37 outils disponibles
+```
+
+**Important** : Les deux serveurs accèdent à la **même base de données**. Quand vous créez une note via MCP, elle apparaît immédiatement dans l'interface web, et inversement.
+
+---
+
+## 3. Les clés API : à quoi ça sert
+
+Une **clé API** est un mot de passe secret qui permet à un outil externe de prouver son identité au serveur MCP.
+
+### Quand vous avez besoin d'une clé API
+
+- **Mode HTTP** (N8N, Cursor distant, etc.) : **OUI**, vous devez fournir votre clé API à chaque requête.
+- **Mode Stdio** (Claude Code, Cursor local) : **NON**, l'outil accède directement à la base de données.
+
+### Format d'une clé
+
+Les clés générées par Keep Notes ressemblent à ça :
+
+```
+mcp_sk_0f0fe746d34dabdf7370d06352a2fd5fabf5994d2a980a31
+```
+
+- Préfixe `mcp_sk_` (pour "MCP Secret Key")
+- Suivi de 48 caractères hexadécimaux
+
+### Securité
+
+- La clé brute n'est affichée **qu'une seule fois** au moment de sa création
+- En base de données, seul le **hash SHA-256** est stocké (comme un mot de passe)
+- Personne (même pas vous) ne peut retrouver la clé brute après fermeture de la fenêtre
+- Si vous perdez une clé, il faut la révoquer et en générer une nouvelle
+
+---
+
+## 4. Gérer ses clés API depuis l'interface
+
+### Accéder à la page MCP
+
+1. Ouvrez Keep Notes dans votre navigateur (`http://localhost:3000`)
+2. Cliquez sur **Paramètres** (icône engrenage)
+3. Dans le menu latéral, cliquez sur **MCP Settings** (icône clé)
+
+### Générer une nouvelle clé
+
+1. Cliquez sur le bouton **"Générer une nouvelle clé"**
+2. Donnez un nom à votre clé (ex: "Mon Claude Code", "N8N Prod")
+3. Cliquez sur **"Générer"**
+4. **Copiez immédiatement la clé** — elle ne sera plus jamais visible
+5. Cliquez sur **"Terminé"**
+
+### Gérer vos clés existantes
+
+Pour chaque clé, vous verrez :
+
+- Le **nom** que vous lui avez donné
+- La **date de création**
+- La **date de dernière utilisation**
+- Le **statut** : Active (verte) ou Révoquée (grise)
+
+#### Révoquer une clé
+
+La révocation **désactive** la clé sans la supprimer. L'outil qui l'utilisait perdra son accès.
+
+> Utile si vous pensez qu'une clé a été compromise mais voulez garder un historique.
+
+#### Supprimer une clé
+
+La suppression est **définitive**. La clé et son historique disparaissent.
+
+---
+
+## 5. Configurer Claude Code
+
+Claude Code est l'outil en ligne de commande de Claude (celui que vous utilisez actuellement).
+
+### Méthode recommandée : Mode Stdio (sans clé API)
+
+Avec le mode stdio, Claude Code lance le serveur MCP directement. Pas besoin de clé API car il accède à la base SQLite directement.
+
+#### Étape 1 : Ouvrir la configuration MCP
+
+Dans votre terminal Claude Code, tapez :
+
+```
+/mcp
+```
+
+#### Étape 2 : Ajouter le serveur
+
+Choisissez d'ajouter un nouveau serveur et collez cette configuration :
+
+```json
+{
+  "mcpServers": {
+    "keep-notes": {
+      "command": "node",
+      "args": ["/Users/sepehr/dev/Keep/mcp-server/index.js"],
+      "env": {
+        "DATABASE_URL": "file:/Users/sepehr/dev/Keep/keep-notes/prisma/dev.db",
+        "APP_BASE_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+#### Explication de chaque champ
+
+| Champ | Valeur | À quoi ça sert |
+|-------|--------|----------------|
+| `command` | `"node"` | Lance Node.js |
+| `args` | `["/chemin/vers/mcp-server/index.js"]` | Chemin vers le serveur MCP (mode stdio) |
+| `env.DATABASE_URL` | `"file:/chemin/vers/prisma/dev.db"` | Où trouver la base de données |
+| `env.APP_BASE_URL` | `"http://localhost:3000"` | URL de l'app web (pour les fonctions IA) |
+
+#### Étape 3 : Vérifier
+
+Redémarrez Claude Code. Tapez un message demandant d'utiliser un outil Keep Notes, par exemple :
+
+> "Liste mes notes Keep Notes"
+
+Claude Code devrait automatiquement détecter les outils MCP disponibles.
+
+### Méthode alternative : fichier de configuration
+
+Vous pouvez aussi éditer directement le fichier de config :
+
+```bash
+# Configuration globale (tous les projets)
+nano ~/.claude.json
+
+# OU configuration par projet
+nano /Users/sepehr/dev/Keep/.claude/settings.local.json
+```
+
+Ajoutez le bloc `mcpServers` dans le fichier JSON.
+
+---
+
+## 6. Configurer Cursor
+
+Cursor est un éditeur de code avec IA intégrée qui supporte MCP.
+
+### Mode local (Stdio — sans clé API)
+
+Ouvrez les paramètres MCP dans Cursor (`Settings` > `MCP`) et ajoutez :
+
+```json
+{
+  "mcpServers": {
+    "keep-notes": {
+      "command": "node",
+      "args": ["/Users/sepehr/dev/Keep/mcp-server/index.js"],
+      "env": {
+        "DATABASE_URL": "file:/Users/sepehr/dev/Keep/keep-notes/prisma/dev.db",
+        "APP_BASE_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+C'est **exactement la même config** que Claude Code en mode stdio.
+
+### Mode distant (HTTP — avec clé API)
+
+Si le serveur MCP tourne sur une autre machine ou si vous préférez le mode HTTP :
+
+#### 1. Démarrez le serveur MCP en mode HTTP
+
+```bash
+cd /Users/sepehr/dev/Keep/mcp-server
+node index-sse.js
+```
+
+Le serveur démarre sur `http://localhost:3001`.
+
+#### 2. Configurez Cursor
+
+```json
+{
+  "mcpServers": {
+    "keep-notes": {
+      "url": "http://localhost:3001/mcp",
+      "headers": {
+        "x-api-key": "mcp_sk_VOTRE_CLE_API_ICI"
+      }
+    }
+  }
+}
+```
+
+Remplacez `mcp_sk_VOTRE_CLE_API_ICI` par votre vraie clé (générée depuis `/settings/mcp`).
+
+---
+
+## 7. Configurer N8N
+
+N8N est un outil d'automatisation qui peut utiliser MCP pour interagir avec vos notes.
+
+### Prérequis
+
+1. Le serveur MCP doit tourner en mode HTTP :
+
+```bash
+cd /Users/sepehr/dev/Keep/mcp-server
+node index-sse.js
+```
+
+2. Vous devez avoir généré une clé API depuis `/settings/mcp`
+
+### Configuration dans N8N
+
+#### Étape 1 : Ajouter un nœud MCP Client
+
+Dans votre workflow N8N, ajoutez un nœud **"MCP Client"**.
+
+#### Étape 2 : Configurer la connexion
+
+| Paramètre | Valeur |
+|-----------|--------|
+| **Transport** | HTTP Streamable |
+| **URL** | `http://VOTRE_IP:3001/mcp` |
+| **Authentication** | API Key |
+| **Header** | `x-api-key` |
+| **Valeur** | `mcp_sk_VOTRE_CLE_API_ICI` |
+
+#### Trouver votre IP locale
+
+```bash
+# macOS
+ifconfig | grep "inet " | grep -v 127.0.0.1
+
+# Résultat typique : 192.168.1.XX
+```
+
+Utilisez cette IP (pas `localhost`) si N8N tourne sur une autre machine.
+
+#### Étape 3 : Utiliser un outil
+
+Après connexion, N8N charge la liste des 37 outils disponibles. Choisissez celui que vous voulez utiliser, par exemple :
+
+- `create_note` — Créer une note
+- `search_notes` — Rechercher des notes
+- `get_notes` — Lister les notes
+
+### Exemple de workflow
+
+**Workflow "Sauvegarder un article web en note"** :
+
+```
+Webhook (reçoit un article)
+    → MCP Client : create_note
+        title = article.title
+        content = article.body
+        labels = ["article", "web"]
+```
+
+---
+
+## 8. Questions fréquentes
+
+### J'ai perdu ma clé API, que faire ?
+
+Les clés ne sont jamais stockées en clair. Si vous avez perdu une clé :
+1. Allez dans `/settings/mcp`
+2. **Révoquez** l'ancienne clé
+3. **Générez** une nouvelle clé
+4. **Copiez-la** immédiatement
+5. Mettez à jour la config de votre outil (Claude Code, Cursor, N8N)
+
+### Peut-on utiliser MCP sans clé API ?
+
+**Oui**, en mode stdio. C'est le cas pour Claude Code et Cursor configurés en local. La clé API n'est nécessaire que pour le mode HTTP distant.
+
+### Le serveur MCP doit-il tourner en permanence ?
+
+- **Mode Stdio** : Non. L'outil (Claude Code/Cursor) lance le serveur automatiquement quand il en a besoin.
+- **Mode HTTP** : Oui. Le serveur doit tourner en continu (`node index-sse.js`) pour que N8N et les autres outils puissent s'y connecter.
+
+### Mes notes sont-elles en sécurité ?
+
+- Les clés API sont hashées (SHA-256) en base de données, comme des mots de passe
+- Le serveur MCP accède à la même base que l'app web — les permissions utilisateur sont respectées
+- En mode HTTP, le trafic peut être sécurisé avec HTTPS (configuration du reverse proxy)
+
+### Combien de clés API puis-je créer ?
+
+Pas de limite. Il est recommandé de créer une clé par outil (une pour Claude Code, une pour N8N, etc.) pour pouvoir les révoquer indépendamment.
+
+### Quels sont les 37 outils disponibles ?
+
+| Catégorie | Outils |
+|-----------|--------|
+| **Notes** | `create_note`, `get_note`, `get_notes`, `update_note`, `delete_note`, `search_notes`, `toggle_pin`, `toggle_archive`, `export_notes`, `import_notes`, `restore_note` |
+| **Carnets** | `create_notebook`, `get_notebooks`, `get_notebook`, `update_notebook`, `delete_notebook`, `reorder_notebooks` |
+| **Etiquettes** | `create_label`, `get_labels`, `update_label`, `delete_label` |
+| **IA** | `generate_title_suggestions`, `reformulate_text`, `generate_tags`, `fuse_notes`, `batch_organize`, `generate_notebook_summary`, etc. |
+| **Rappels** | `get_due_reminders` |
+| **Clés API** | `generate_api_key`, `list_api_keys`, `revoke_api_key` |