docs: rewrite GUIDE.md with accurate code analysis, add English translation

Major corrections based on thorough code verification: - MCP tools: 9 -> 37 (added notebooks, labels, AI, reminders, API keys) - MCP transport: SSE -> HTTP Streamable (SSE is legacy redirect) - MCP endpoint: /sse -> /mcp as primary - MCP version: 1.0.0 -> 3.1.0 - i18n: FR/EN -> 15 languages - Added missing features: Agents, Workflows, Chat, Canvas/Lab, Memory Echo, Note Sharing, Markdown/LaTeX, RSS, Batch Organization - Fixed Dockerfile image: node:22-bullseye -> node:22-bullseye-slim - Fixed AI fallback chain documentation - Added user settings pages table - Added auto email mode (Resend + SMTP fallback) - Added GUIDE.en.md (English translation)
2026-04-20 23:07:58 +02:00
parent ffb2465b78
commit 3b7bbdda8c
2 changed files with 993 additions and 52 deletions
--- a/GUIDE.md
+++ b/GUIDE.md
@@ -19,38 +19,59 @@

 ## Presentation

-**Memento** est une application de prise de notes intelligente, inspiree de Google Keep, construite avec Next.js 16, TypeScript, Tailwind CSS 4, Prisma et PostgreSQL.
+**Memento** est une application de prise de notes intelligente, inspiree de Google Keep, construite avec Next.js 16, React 19, TypeScript, Tailwind CSS 4, Prisma ORM 5 et PostgreSQL 16.

 ### Fonctionnalites principales

- **Notes texte et checklists** avec couleurs personnalisees (10 themes pastel)
+**Notes et organisation :**
+- **Notes texte, checklists et Markdown** (avec support LaTeX/KaTeX)
 - **Grille masonry responsive** avec drag-and-drop
 - **Upload d'images** avec preservation de la taille originale
 - **Notebooks et labels contextuels** pour organiser les notes
+- **Partage de notes** avec permissions
+- **Corbeille** et **archive**
+
+**IA et automatisation :**
 - **Recherche semantique** (embeddings IA) + recherche plein texte
- **Generation automatique de tags** via IA
- **Suggestions de titre** par IA
- **Systeme de rappels** avec notifications
+- **Generation automatique de tags** et suggestions de titre via IA
+- **Agents IA** configurables avec instructions personnalisees
+- **Chat IA** avec conversations persistees
+- **Memory Echo** - decouverte de connexions entre notes
+- **Organisation automatique par batch** et labels intelligents
+- **Workflows visuels** - automate de creation de workflows (noeuds, triggers)
+- **Resume de notebooks** genere par IA
+
+**Productivite :**
+- **Systeme de rappels** avec notifications et recurrence
 - **Mode sombre/clair** avec preference systeme
- **Authentification** NextAuth.js (credentials, inscription, reset mot de passe)
- **Panneau admin** pour configurer les providers IA, SMTP, etc.
- **Serveur MCP** pour integrer avec Claude Desktop, N8N, ou tout client MCP
- **Support i18n** (FR/EN)
 - **Export/import de donnees** (JSON)
 - **PWA** (Progressive Web App)
+- **Support i18n** - 15 langues (FR, EN, AR, DE, ES, FA, HI, IT, JA, KO, NL, PL, PT, RU, ZH)
+
+**Outils avances :**
+- **Canvas/Lab** - tableau blanc avec dessin (Excalidraw/tldraw)
+- **Flux RSS** - integration de feeds RSS
+- **Serveur MCP** - 37 outils pour integrer avec Claude Desktop, N8N, ou tout client MCP
+
+**Administration :**
+- **Authentification** NextAuth.js v5 (credentials, inscription, reset mot de passe)
+- **Panneau admin** pour configurer les providers IA, SMTP, etc.
+- **Gestion des cles API** MCP
+- **Pages settings** : profil, apparence, donnees, MCP, IA

 ### Stack technique

 | Composant | Technologie |
 |-----------|-------------|
-| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS 4 |
-| UI | shadcn/ui, Lucide React |
+| Frontend | Next.js 16.1, React 19.2, TypeScript 5, Tailwind CSS 4 |
+| UI | shadcn/ui, Lucide React, Radix UI |
 | Backend | Next.js Server Actions, API Routes |
-| Base de donnees | PostgreSQL 16 via Prisma ORM 5 |
+| Base de donnees | PostgreSQL 16 via Prisma ORM 5.22 |
 | Authentification | NextAuth.js v5 |
-| IA | Vercel AI SDK (OpenAI, Ollama, custom) |
-| MCP | @modelcontextprotocol/sdk |
+| IA | Vercel AI SDK (OpenAI, Ollama, Custom OpenAI-compatible) |
+| MCP | @modelcontextprotocol/sdk v3.1 |
 | Email | Nodemailer (SMTP) ou Resend |
+| Canvas | Excalidraw / tldraw |
 | Docker | Docker Compose (postgres + memento-note + mcp-server + ollama) |

 ---
@@ -61,44 +82,55 @@
 Momento/
 ├── docker-compose.yml           # Orchestration multi-conteneurs
 ├── .env.docker.example          # Template config Docker
+├── GUIDE.md                     # Ce guide (FR)
+├── GUIDE.en.md                  # English guide
 ├── LICENSE                      # Apache 2.0 + Commons Clause
 ├── memento-note/                # Application Next.js
 │   ├── app/                     # App Router (pages, actions, API)
+│   │   ├── (auth)/              # Login, register, reset password
+│   │   ├── (main)/              # Dashboard, admin, archive, trash, chat,
+│   │   │                        # agents, reminders, lab, settings, support
+│   │   ├── actions/             # Server actions (auth, notes, AI, admin)
+│   │   └── api/                 # REST API routes
 │   ├── components/              # Composants React
 │   ├── lib/                     # Logique metier
-│   │   ├── ai/                  # Providers IA (factory pattern)
+│   │   ├── ai/                  # Factory IA + providers + services
+│   │   │   ├── factory.ts       # Factory pattern (ollama/openai/custom)
+│   │   │   ├── providers/       # Providers: ollama, openai, custom-openai
+│   │   │   └── services/        # Agent executor, RSS, title, batch, etc.
 │   │   ├── prisma.ts            # Client DB
-│   │   ├── mail.ts              # Envoi d'emails
-│   │   └── config.ts            # Config depuis DB
+│   │   ├── mail.ts              # Envoi d'emails (SMTP + Resend)
+│   │   ├── config.ts            # Config depuis DB (SystemConfig)
+│   │   └── i18n/                # Detection langue + provider
 │   ├── prisma/                  # Schema + migrations PostgreSQL
-│   ├── locales/                 # Fichiers i18n (fr.json, en.json)
-│   ├── Dockerfile               # Build multi-stage (node:22-bullseye)
+│   ├── locales/                 # 15 fichiers i18n (fr.json, en.json, etc.)
+│   ├── Dockerfile               # Build multi-stage (node:22-bullseye-slim)
 │   ├── docker-compose.yml       # Standalone (postgres + app)
 │   └── .env.example             # Template dev local
-├── mcp-server/                  # Serveur MCP
+├── mcp-server/                  # Serveur MCP (37 outils)
 │   ├── index.js                 # Mode stdio (Claude Desktop)
-│   ├── index-sse.js             # Mode SSE/HTTP (N8N, remote)
-│   ├── tools.js                 # Definitions des outils MCP
+│   ├── index-sse.js             # Mode HTTP Streamable (N8N, remote)
+│   ├── tools.js                 # Definitions des 37 outils MCP
+│   ├── auth.js                  # Authentification API keys
 │   ├── Dockerfile               # Conteneur MCP (node:20-alpine)
 │   └── .env.example             # Template MCP
-├── scripts/                     # Scripts de migration
 └── n8n-memento-workflow.json    # Workflow N8N preconfigure
 ```

 ### Flux de donnees

 ```
-Navigateur → Next.js App Router
-              ├── Server Components (lecture)
-              ├── Server Actions (ecriture)
-              └── API Routes (REST)
-                      ↓
+Navigateur -> Next.js App Router
+              |-- Server Components (lecture)
+              |-- Server Actions (ecriture)
+              `-- API Routes (REST)
+                      |
                  Prisma ORM
-                      ↓
+                      |
                  PostgreSQL 16
-                      ↑
-              MCP Server (stdio ou SSE)
-                      ↑
+                      ^
+              MCP Server (stdio ou HTTP Streamable)
+                      ^
              Claude Desktop / N8N / Client MCP
 ```

@@ -190,7 +222,7 @@ docker exec memento-ollama ollama pull embeddinggemma
 |---------|------|-------------|
 | memento-note | 3000 | Application web |
 | PostgreSQL | 5432 | Base de donnees |
-| MCP Server | 3001 | SSE mode uniquement |
+| MCP Server | 3001 | Mode HTTP Streamable |
 | Ollama | 11434 | IA locale (optionnel) |

 ### Reverse Proxy (Nginx)
@@ -286,6 +318,13 @@ AI_MODEL_TAGS="granite4:latest"
 AI_MODEL_EMBEDDING="text-embedding-3-small"
 ```

+### Chaine de fallback IA
+
+Chaque fonctionnalite IA a une chaine de fallback :
+- **Tags** : `AI_PROVIDER_TAGS` -> `AI_PROVIDER`
+- **Embeddings** : `AI_PROVIDER_EMBEDDING` -> `AI_PROVIDER_TAGS` -> `AI_PROVIDER`
+- **Chat** : `AI_PROVIDER_CHAT` -> `AI_PROVIDER_TAGS` -> `AI_PROVIDER_EMBEDDING` -> `AI_PROVIDER`
+
 ### Configuration via le panneau admin

 Les providers IA peuvent aussi etre configures depuis l'interface :
@@ -301,21 +340,76 @@ Les providers IA peuvent aussi etre configures depuis l'interface :

 ## Serveur MCP

-Le serveur MCP (Model Context Protocol) permet aux agents IA d'interagir avec vos notes via un protocole standardise.
+Le serveur MCP (Model Context Protocol, v3.1) permet aux agents IA d'interagir avec vos notes via un protocole standardise.

-### Outils disponibles (9 outils)
+### Outils disponibles (37 outils)
+
+**Notes (12) :**

 | Outil | Description |
 |-------|-------------|
 | `create_note` | Creer une nouvelle note |
-| `get_notes` | Recuperer toutes les notes |
+| `get_notes` | Recuperer les notes |
 | `get_note` | Recuperer une note specifique |
 | `update_note` | Modifier une note existante |
 | `delete_note` | Supprimer une note |
+| `delete_all_notes` | Supprimer toutes les notes |
 | `search_notes` | Rechercher des notes par contenu |
-| `get_labels` | Lister les labels |
+| `move_note` | Deplacer une note vers un notebook |
 | `toggle_pin` | Epingler/Depingler une note |
 | `toggle_archive` | Archiver/Desarchiver une note |
+| `export_notes` | Exporter les notes en JSON |
+| `import_notes` | Importer des notes depuis JSON |
+
+**Notebooks (6) :**
+
+| Outil | Description |
+|-------|-------------|
+| `create_notebook` | Creer un notebook |
+| `get_notebooks` | Lister les notebooks |
+| `get_notebook` | Details d'un notebook |
+| `update_notebook` | Modifier un notebook |
+| `delete_notebook` | Supprimer un notebook |
+| `reorder_notebooks` | Reordonner les notebooks |
+
+**Labels (4) :**
+
+| Outil | Description |
+|-------|-------------|
+| `create_label` | Creer un label |
+| `get_labels` | Lister les labels |
+| `update_label` | Modifier un label |
+| `delete_label` | Supprimer un label |
+
+**IA (11) :**
+
+| Outil | Description |
+|-------|-------------|
+| `generate_title_suggestions` | Suggestions de titre pour une note |
+| `reformulate_text` | Reformuler un texte |
+| `generate_tags` | Generer des tags pour une note |
+| `suggest_notebook` | Suggerer un notebook pour une note |
+| `get_notebook_summary` | Resume d'un notebook |
+| `get_memory_echo` | Echo memoire - connexions entre notes |
+| `get_note_connections` | Connexions d'une note |
+| `dismiss_connection` | Ignorer une connexion |
+| `fuse_notes` | Fusionner des notes |
+| `batch_organize` | Organisation automatique par batch |
+| `suggest_auto_labels` | Suggerer des labels automatiques |
+
+**Rappels (1) :**
+
+| Outil | Description |
+|-------|-------------|
+| `get_due_reminders` | Recuperer les rappels dus |
+
+**Gestion des cles API (3) :**
+
+| Outil | Description |
+|-------|-------------|
+| `generate_api_key` | Generer une cle API |
+| `list_api_keys` | Lister les cles API |
+| `revoke_api_key` | Revoquer une cle API |

 ### Mode stdio (Claude Desktop, Cline)

@@ -333,9 +427,9 @@ Communication via stdin/stdout, ideal pour les clients locaux.
 }
 ```

-### Mode SSE (N8N, HTTP)
+### Mode HTTP Streamable (N8N, remote)

-Communication via HTTP Server-Sent Events, accessible sur le reseau.
+Communication via HTTP Streamable (remplace l'ancien SSE), accessible sur le reseau.

 ```bash
 # .env.docker
@@ -345,20 +439,20 @@ MCP_PORT="3001"

 Le serveur sera accessible sur `http://localhost:3001`.

-#### Endpoints SSE
+#### Endpoints HTTP

 | Endpoint | Methode | Description |
 |----------|---------|-------------|
 | `/` | GET | Health check |
-| `/sse` | GET/POST | Endpoint MCP principal |
-| `/message` | POST | Envoi de messages |
+| `/mcp` | GET/POST | Endpoint MCP principal (Streamable HTTP) |
+| `/sse` | GET/POST | Legacy (redirige vers `/mcp`) |
 | `/sessions` | GET | Sessions actives |

 #### Verification

 ```bash
 curl http://localhost:3001/
-# {"name":"Memento MCP SSE Server","version":"1.0.0","status":"running"}
+# {"name":"Memento MCP Server","version":"3.1.0","status":"running",...}
 ```

 ### Configuration MCP avancee
@@ -380,7 +474,7 @@ APP_BASE_URL="http://localhost:3000"  # URL de l'app pour les liens

 1. Ajouter un noeud **"MCP Client"** dans N8N
 2. Selectionner **"HTTP Streamable"** comme transport
-3. Configurer l'endpoint : `http://memento-mcp:3001/sse` (Docker) ou `http://VOTRE_IP:3001/sse`
+3. Configurer l'endpoint : `http://memento-mcp:3001/mcp` (Docker) ou `http://VOTRE_IP:3001/mcp`

 ### Workflows preconfigures

@@ -391,10 +485,10 @@ Le fichier `n8n-memento-workflow.json` contient un workflow pret a l'emploi pour

 ### Exemples d'utilisation

-#### Creer une note via curl (SSE mode)
+#### Creer une note via curl

 ```bash
-curl -X POST http://localhost:3001/sse \
+curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
@@ -413,7 +507,7 @@ curl -X POST http://localhost:3001/sse \
 #### Lister les outils disponibles

 ```bash
-curl -X POST http://localhost:3001/sse \
+curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
@@ -427,7 +521,7 @@ curl -X POST http://localhost:3001/sse \

 ## Configuration email

-L'email est necessaire pour la reinitialisation de mot de passe et les rappels.
+L'email est necessaire pour la reinitialisation de mot de passe et les rappels. Deux providers sont supportes.

 ### Option 1 : SMTP

@@ -454,7 +548,11 @@ SMTP_FROM="noreply@votre-domaine.com"
 RESEND_API_KEY="re_votre-cle"
 ```

-Les parametres `SMTP_SECURE` et `SMTP_IGNORE_CERT` sont configurables depuis le panneau admin.
+### Mode auto
+
+En mode `auto` (defaut), Memento essaie Resend en premier, puis SMTP en fallback.
+
+Les parametres `SMTP_SECURE` et `SMTP_IGNORE_CERT` sont configurables depuis le panneau admin (stockes en DB).

 ---

@@ -472,6 +570,16 @@ Accessibles uniquement par le premier utilisateur inscrit (ou les utilisateurs a
 2. **Email Settings** - Configuration SMTP
 3. **General Settings** - Inscription publique activee/desactivee

+### Pages settings utilisateur
+
+| Page | Route | Description |
+|------|-------|-------------|
+| Profil | `/settings/profile` | Nom, email, mot de passe |
+| Apparence | `/settings/appearance` | Theme, langue |
+| Donnees | `/settings/data` | Export/import, suppression |
+| MCP | `/settings/mcp` | Configuration serveur MCP |
+| IA | `/settings/ai` | Preferences IA |
+
 ### Gestion des utilisateurs

 - Les utilisateurs sont geres via `/admin`
@@ -523,14 +631,14 @@ Accessibles uniquement par le premier utilisateur inscrit (ou les utilisateurs a

 | Variable | Defaut | Description |
 |----------|--------|-------------|
-| `AI_PROVIDER_EMBEDDING` | - | Provider pour embeddings |
+| `AI_PROVIDER_EMBEDDING` | fallback Tags | Provider pour embeddings |
 | `AI_MODEL_EMBEDDING` | `embeddinggemma:latest` | Modele pour embeddings |

 #### IA - Chat

 | Variable | Defaut | Description |
 |----------|--------|-------------|
-| `AI_PROVIDER_CHAT` | fallback Tags | Provider pour chat |
+| `AI_PROVIDER_CHAT` | fallback Tags->Embedding | Provider pour chat |
 | `AI_MODEL_CHAT` | fallback Tags | Modele pour chat |

 #### IA - OpenAI
@@ -557,7 +665,7 @@ Accessibles uniquement par le premier utilisateur inscrit (ou les utilisateurs a
 | Variable | Defaut | Description |
 |----------|--------|-------------|
 | `MCP_MODE` | `stdio` | Mode (`stdio` ou `sse`) |
-| `MCP_PORT` | `3001` | Port SSE |
+| `MCP_PORT` | `3001` | Port HTTP Streamable |
 | `MCP_LOG_LEVEL` | `info` | Niveau de log |
 | `MCP_REQUEST_TIMEOUT` | `30000` | Timeout (ms) |
 | `MCP_REQUIRE_AUTH` | `false` | Activer authentification |