diff --git a/DEPLOY.md b/DEPLOY.md index 5d9fe8a..4eae762 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -19,7 +19,7 @@ Internet/LAN | ├── / ──► [memento-web] ── port 3000 ── Next.js App | - └── /mcp ──► [memento-mcp] ── port 3001 ── MCP Server (SSE) + └── /mcp ──► [memento-mcp] ── port 3001 ── MCP Server (Streamable HTTP) | [postgres] ── port 5432 (127.0.0.1 seulement) @@ -246,7 +246,7 @@ server { proxy_read_timeout 86400; } - # MCP Server (SSE - long-lived connections) + # MCP Server (Streamable HTTP) location /mcp { proxy_pass http://127.0.0.1:3001/mcp; proxy_set_header Host $host; diff --git a/GUIDE.en.md b/GUIDE.en.md index 9c30f2e..00f32c7 100644 --- a/GUIDE.en.md +++ b/GUIDE.en.md @@ -51,7 +51,7 @@ **Advanced tools:** - **Canvas/Lab** - whiteboard with drawing (Excalidraw) - **RSS feeds** - RSS feed integration -- **MCP Server** - 37 tools to integrate with Claude Desktop, N8N, or any MCP client +- **MCP Server** - 22 tools to integrate with Claude Desktop, N8N, or any MCP client **Administration:** - **Authentication** via NextAuth.js v5 (credentials, registration, password reset) @@ -107,10 +107,10 @@ Momento/ │ ├── Dockerfile # Multi-stage build (node:22-bullseye-slim) │ ├── docker-compose.yml # Standalone (postgres + app) │ └── .env.example # Local dev template -├── mcp-server/ # MCP Server (37 tools) +├── mcp-server/ # MCP Server (22 tools) │ ├── index.js # stdio mode (Claude Desktop) │ ├── index-sse.js # HTTP Streamable mode (N8N, remote) -│ ├── tools.js # Definitions of the 37 MCP tools +│ ├── tools.js # Definitions of the 22 MCP tools │ ├── auth.js # API key authentication │ ├── Dockerfile # MCP container (node:20-alpine) │ └── .env.example # MCP template @@ -433,9 +433,9 @@ Agents are also available in **AI Chat**: when web search is enabled, the chat a The MCP server (Model Context Protocol, v3.1) allows AI agents to interact with your notes via a standardized protocol. -### Available Tools (37 tools) +### Available Tools (22 tools) -**Notes (12):** +**Notes (11):** | Tool | Description | |------|-------------| @@ -444,7 +444,6 @@ The MCP server (Model Context Protocol, v3.1) allows AI agents to interact with | `get_note` | Retrieve a specific note | | `update_note` | Modify an existing note | | `delete_note` | Delete a note | -| `delete_all_notes` | Delete all notes | | `search_notes` | Search notes by content | | `move_note` | Move a note to a notebook | | `toggle_pin` | Pin/Unpin a note | @@ -472,36 +471,12 @@ The MCP server (Model Context Protocol, v3.1) allows AI agents to interact with | `update_label` | Modify a label | | `delete_label` | Delete a label | -**AI (11):** - -| Tool | Description | -|------|-------------| -| `generate_title_suggestions` | Title suggestions for a note | -| `reformulate_text` | Reformulate text | -| `generate_tags` | Generate tags for a note | -| `suggest_notebook` | Suggest a notebook for a note | -| `get_notebook_summary` | Notebook summary | -| `get_memory_echo` | Memory echo - connections between notes | -| `get_note_connections` | Connections of a note | -| `dismiss_connection` | Dismiss a connection | -| `fuse_notes` | Merge notes | -| `batch_organize` | Automatic batch organization | -| `suggest_auto_labels` | Suggest automatic labels | - **Reminders (1):** | Tool | Description | |------|-------------| | `get_due_reminders` | Retrieve due reminders | -**API Key Management (3):** - -| Tool | Description | -|------|-------------| -| `generate_api_key` | Generate an API key | -| `list_api_keys` | List API keys | -| `revoke_api_key` | Revoke an API key | - ### stdio Mode (Claude Desktop, Cline) Communication via stdin/stdout, ideal for local clients. @@ -520,15 +495,17 @@ Communication via stdin/stdout, ideal for local clients. ### HTTP Streamable Mode (N8N, Remote) -Communication via HTTP Streamable (replaces the legacy SSE), accessible over the network. +Communication via HTTP Streamable, accessible over the network. API key authentication is enabled by default in Docker. + +API keys are generated from **Settings > MCP** in the Memento web UI. ```bash -# .env.docker -MCP_MODE="sse" -MCP_PORT="3001" +# docker-compose.yml (pre-configured) +MCP_MODE=sse +MCP_REQUIRE_AUTH=true ``` -The server will be accessible at `http://localhost:3001`. +The server will be accessible at `http://localhost:3001/mcp`. #### HTTP Endpoints @@ -552,8 +529,7 @@ curl http://localhost:3001/ # .env.docker MCP_LOG_LEVEL=info # debug, info, warn, error MCP_REQUEST_TIMEOUT=30000 # Timeout in ms -MCP_REQUIRE_AUTH=false # Enable authentication -MCP_API_KEY="your-key" # API key if auth is enabled +MCP_REQUIRE_AUTH=true # API key authentication APP_BASE_URL="http://localhost:3000" # App URL for links ``` @@ -566,6 +542,7 @@ APP_BASE_URL="http://localhost:3000" # App URL for links 1. Add an **"MCP Client"** node in N8N 2. Select **"HTTP Streamable"** as transport 3. Configure the endpoint: `http://memento-mcp:3001/mcp` (Docker) or `http://YOUR_IP:3001/mcp` +4. Add **Header Auth**: `x-api-key` = your API key (generated from Settings > MCP) ### Pre-configured Workflows diff --git a/GUIDE.md b/GUIDE.md index 07d2de4..31d01a7 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -52,7 +52,7 @@ **Outils avances :** - **Canvas/Lab** - tableau blanc avec dessin (Excalidraw) - **Flux RSS** - integration de feeds RSS -- **Serveur MCP** - 37 outils pour integrer avec Claude Desktop, N8N, ou tout client MCP +- **Serveur MCP** - 22 outils pour integrer avec Claude Desktop, N8N, ou tout client MCP **Administration :** - **Authentification** NextAuth.js v5 (credentials, inscription, reset mot de passe) @@ -108,10 +108,10 @@ Momento/ │ ├── Dockerfile # Build multi-stage (node:22-bullseye-slim) │ ├── docker-compose.yml # Standalone (postgres + app) │ └── .env.example # Template dev local -├── mcp-server/ # Serveur MCP (37 outils) +├── mcp-server/ # Serveur MCP (22 outils) │ ├── index.js # Mode stdio (Claude Desktop) │ ├── index-sse.js # Mode HTTP Streamable (N8N, remote) -│ ├── tools.js # Definitions des 37 outils MCP +│ ├── tools.js # Definitions des 22 outils MCP │ ├── auth.js # Authentification API keys │ ├── Dockerfile # Conteneur MCP (node:20-alpine) │ └── .env.example # Template MCP @@ -434,9 +434,9 @@ Les agents sont aussi disponibles dans le **Chat IA** : si la recherche web est Le serveur MCP (Model Context Protocol, v3.1) permet aux agents IA d'interagir avec vos notes via un protocole standardise. -### Outils disponibles (37 outils) +### Outils disponibles (22 outils) -**Notes (12) :** +**Notes (11) :** | Outil | Description | |-------|-------------| @@ -445,7 +445,6 @@ Le serveur MCP (Model Context Protocol, v3.1) permet aux agents IA d'interagir a | `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 | | `move_note` | Deplacer une note vers un notebook | | `toggle_pin` | Epingler/Depingler une note | @@ -473,36 +472,12 @@ Le serveur MCP (Model Context Protocol, v3.1) permet aux agents IA d'interagir a | `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) Communication via stdin/stdout, ideal pour les clients locaux. @@ -521,15 +496,17 @@ Communication via stdin/stdout, ideal pour les clients locaux. ### Mode HTTP Streamable (N8N, remote) -Communication via HTTP Streamable (remplace l'ancien SSE), accessible sur le reseau. +Communication via HTTP Streamable, accessible sur le reseau. L'authentification par cle API est activee par defaut dans Docker. + +Les cles API sont generees depuis **Parametres > MCP** dans l'interface Memento. ```bash -# .env.docker -MCP_MODE="sse" -MCP_PORT="3001" +# docker-compose.yml (preconfigure) +MCP_MODE=sse +MCP_REQUIRE_AUTH=true ``` -Le serveur sera accessible sur `http://localhost:3001`. +Le serveur sera accessible sur `http://localhost:3001/mcp`. #### Endpoints HTTP @@ -553,8 +530,7 @@ curl http://localhost:3001/ # .env.docker MCP_LOG_LEVEL=info # debug, info, warn, error MCP_REQUEST_TIMEOUT=30000 # Timeout en ms -MCP_REQUIRE_AUTH=false # Activer l'authentification -MCP_API_KEY="votre-cle" # Cle API si auth active +MCP_REQUIRE_AUTH=true # Authentification par cle API APP_BASE_URL="http://localhost:3000" # URL de l'app pour les liens ``` @@ -567,6 +543,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/mcp` (Docker) ou `http://VOTRE_IP:3001/mcp` +4. Ajouter une **Header Auth** : `x-api-key` = votre cle API (generee depuis Parametres > MCP) ### Workflows preconfigures diff --git a/README.fr.md b/README.fr.md index 61a112b..4513e61 100644 --- a/README.fr.md +++ b/README.fr.md @@ -26,7 +26,7 @@ Une application de prise de notes intelligente et powered by IA. Comme Google Ke - Workflows visuels **Integrations** -- Serveur MCP avec **37 outils** - connecter Claude Desktop, N8N, ou tout client MCP +- Serveur MCP avec **22 outils** - connecter Claude Desktop, N8N, ou tout client MCP - API REST pour integrations personnalisees - Support de flux RSS - Tableau blanc Canvas/Lab (Excalidraw) @@ -115,9 +115,9 @@ Connecter des agents IA a vos notes via le Model Context Protocol. } ``` -**37 outils disponibles** - CRUD notes, notebooks, labels, operations IA (generation de tags, suggestions de titre, memory echo, batch organize), rappels et gestion des cles API. +**22 outils disponibles** - CRUD notes, notebooks, labels, rappels, recherche, export/import. Chaque cle API est scopee a un utilisateur : seules ses notes sont accessibles. -Pour N8N ou clients HTTP, utiliser le mode HTTP Streamable : `http://localhost:3001/mcp` +Pour N8N ou clients HTTP, utiliser le mode HTTP Streamable : `http://localhost:3001/mcp` avec le header `x-api-key`. --- @@ -154,10 +154,11 @@ Momento/ │ ├── prisma/ # Schema + migrations │ ├── locales/ # 15 fichiers i18n │ └── Dockerfile # Build multi-stage -├── mcp-server/ # Serveur MCP (37 outils) +├── mcp-server/ # Serveur MCP (22 outils) │ ├── index.js # Mode stdio │ ├── index-sse.js # Mode HTTP Streamable │ ├── tools.js # Definitions des outils +│ ├── auth.js # Authentification par cle API │ └── Dockerfile # Build conteneur └── n8n-memento-workflow.json # Workflow N8N preconfigure ``` diff --git a/README.md b/README.md index 6ad4992..a9243c7 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ A smart, AI-powered note-taking app. Like Google Keep, but with notebooks, seman - Visual workflow builder **Integrations** -- MCP Server with **37 tools** - connect Claude Desktop, N8N, or any MCP client +- MCP Server with **22 tools** - connect Claude Desktop, N8N, or any MCP client - REST API for custom integrations - RSS feed support - Canvas/Lab whiteboard (Excalidraw) @@ -115,9 +115,9 @@ Connect AI agents to your notes via the Model Context Protocol. } ``` -**37 tools available** - notes CRUD, notebooks, labels, AI operations (tag generation, title suggestions, memory echo, batch organize), reminders, and API key management. +**22 tools available** - notes CRUD, notebooks, labels, reminders, search, export/import. Each API key is scoped to a user so only their notes are accessible. -For N8N or HTTP clients, use Streamable HTTP mode: `http://localhost:3001/mcp` +For N8N or HTTP clients, use Streamable HTTP mode: `http://localhost:3001/mcp` with `x-api-key` header auth. --- @@ -154,10 +154,11 @@ Momento/ │ ├── prisma/ # Schema + migrations │ ├── locales/ # 15 i18n JSON files │ └── Dockerfile # Multi-stage build -├── mcp-server/ # MCP server (37 tools) +├── mcp-server/ # MCP server (22 tools) │ ├── index.js # stdio mode │ ├── index-sse.js # HTTP Streamable mode │ ├── tools.js # Tool definitions +│ ├── auth.js # API key authentication │ └── Dockerfile # Container build └── n8n-memento-workflow.json # Pre-configured N8N workflow ``` diff --git a/mcp-server/N8N-CONFIG.md b/mcp-server/N8N-CONFIG.md index f578a4e..1be33b3 100644 --- a/mcp-server/N8N-CONFIG.md +++ b/mcp-server/N8N-CONFIG.md @@ -1,275 +1,122 @@ -# Configuration N8N - Memento MCP SSE Server +# Configuration N8N - Memento MCP Server -## 🎯 Ton IP Actuelle -**IP Principale**: `172.26.64.1` +## Configuration MCP Client dans N8N -## 🔌 Configuration MCP Client dans N8N +Le serveur MCP utilise le transport **Streamable HTTP** (remplace l'ancien SSE). -### Option 1: Via Settings → MCP Access (Recommandé) +### 1. Generer une cle API -1. Ouvre N8N dans ton navigateur -2. Va dans **Settings** (⚙️) -3. Sélectionne **MCP Access** -4. Clique sur **Add Server** ou **+** -5. Entre cette configuration: +Dans Memento : **Parametres > MCP > Generer une cle** -```json -{ - "name": "memento", - "transport": "sse", - "url": "http://172.26.64.1:3001/sse", - "description": "Memento Note-taking App MCP Server" -} -``` +La cle a le format `mcp_sk_...` et est associee a votre compte utilisateur. Seules vos notes seront accessibles. -6. Sauvegarde la configuration -7. Dans tes workflows, active **"Available in MCP"** (toggle) -8. Utilise le node **MCP Client** pour appeler les tools +### 2. Configurer le noeud MCP Client dans N8N -### Option 2: Via Variables d'Environnement +1. Ajouter un noeud **MCP Client** dans votre workflow +2. **Server Transport** : `Streamable HTTP` +3. **MCP Endpoint URL** : `http://memento-mcp:3001/mcp` (Docker) ou `http://VOTRE_IP:3001/mcp` +4. **Authentication** : Header Auth + - Header Name : `x-api-key` + - Header Value : votre cle API (`mcp_sk_...`) -Si tu as accès aux variables d'environnement de N8N: +### Alternative : curl ```bash -export N8N_MCP_SERVERS='{ - "memento": { - "transport": "sse", - "url": "http://172.26.64.1:3001/sse" - } -}' -``` +# Health check +curl -H "x-api-key: mcp_sk_votrecle" http://localhost:3001/ -Ou dans Docker: -```yaml -environment: - - N8N_MCP_SERVERS={"memento":{"transport":"sse","url":"http://172.26.64.1:3001/sse"}} -``` +# Lister les outils +curl -X POST http://localhost:3001/mcp \ + -H "Content-Type: application/json" \ + -H "x-api-key: mcp_sk_votrecle" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/list", + "params": {} + }' -### Option 3: Via Fichier de Configuration - -Si N8N utilise un fichier config: -```json -{ - "mcpServers": { - "memento": { - "transport": "sse", - "url": "http://172.26.64.1:3001/sse" +# Creer une note +curl -X POST http://localhost:3001/mcp \ + -H "Content-Type: application/json" \ + -H "x-api-key: mcp_sk_votrecle" \ + -d '{ + "jsonrpc": "2.0", + "id": 2, + "method": "tools/call", + "params": { + "name": "create_note", + "arguments": { + "title": "Ma note", + "content": "Contenu de la note" + } } - } -} + }' ``` -## 🛠️ 9 Tools Disponibles +## Outils disponibles (22) -Une fois configuré, tu peux appeler ces tools depuis N8N: +### Notes (11) -### 1. create_note -```json -{ - "tool": "create_note", - "arguments": { - "content": "Ma note de test", - "title": "Titre optionnel", - "color": "blue", - "type": "text", - "images": ["data:image/png;base64,..."] - } -} -``` +| Outil | Description | +|-------|-------------| +| `create_note` | Creer une note | +| `get_notes` | Lister les notes | +| `get_note` | Recuperer une note par ID | +| `update_note` | Modifier une note | +| `delete_note` | Supprimer une note | +| `search_notes` | Rechercher par mot-cle | +| `move_note` | Deplacer vers un notebook | +| `toggle_pin` | Epingler/Depingler | +| `toggle_archive` | Archiver/Desarchiver | +| `export_notes` | Exporter en JSON | +| `import_notes` | Importer depuis JSON | -### 2. get_notes -```json -{ - "tool": "get_notes", - "arguments": { - "includeArchived": false, - "search": "optionnel" - } -} -``` +### Notebooks (6) -### 3. get_note -```json -{ - "tool": "get_note", - "arguments": { - "id": "note_id_ici" - } -} -``` +| 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 | -### 4. update_note -```json -{ - "tool": "update_note", - "arguments": { - "id": "note_id_ici", - "title": "Nouveau titre", - "isPinned": true - } -} -``` +### Labels (4) -### 5. delete_note -```json -{ - "tool": "delete_note", - "arguments": { - "id": "note_id_ici" - } -} -``` +| Outil | Description | +|-------|-------------| +| `create_label` | Creer un label | +| `get_labels` | Lister les labels | +| `update_label` | Modifier un label | +| `delete_label` | Supprimer un label | -### 6. search_notes -```json -{ - "tool": "search_notes", - "arguments": { - "query": "recherche" - } -} -``` +### Rappels (1) -### 7. get_labels -```json -{ - "tool": "get_labels", - "arguments": {} -} -``` +| Outil | Description | +|-------|-------------| +| `get_due_reminders` | Recuperer les rappels dus | -### 8. toggle_pin -```json -{ - "tool": "toggle_pin", - "arguments": { - "id": "note_id_ici" - } -} -``` +## Endpoints HTTP -### 9. toggle_archive -```json -{ - "tool": "toggle_archive", - "arguments": { - "id": "note_id_ici" - } -} -``` +| Endpoint | Methode | Description | +|----------|---------|-------------| +| `/` | GET | Health check | +| `/mcp` | GET/POST | Endpoint MCP principal | +| `/sse` | GET/POST | Legacy (redirige vers `/mcp`) | +| `/sessions` | GET | Sessions actives | -## 🚀 Démarrage du Serveur SSE +## Securite -### Méthode 1: Script PowerShell (Simple) -```powershell -cd D:\dev_new_pc\Keep\mcp-server -.\start-sse.ps1 -``` +- **Authentification obligatoire** en production (`MCP_REQUIRE_AUTH=true` dans Docker) +- Les cles API sont gerees depuis **Parametres > MCP** dans Memento +- Chaque cle est scopee a un utilisateur : seules ses notes sont accessibles +- Les cles sont hashees en base (SHA256), seul le raw key est montre a la creation -### Méthode 2: npm -```bash -cd D:\dev_new_pc\Keep\mcp-server -npm run start:sse -``` - -### Méthode 3: Node direct -```bash -cd D:\dev_new_pc\Keep\mcp-server -node index-sse.js -``` - -Le serveur démarrera sur: -- **Local**: http://localhost:3001 -- **Réseau**: http://172.26.64.1:3001 -- **SSE Endpoint**: http://172.26.64.1:3001/sse - -## ✅ Vérification - -### Test 1: Health Check (depuis ton PC) -```powershell -Invoke-RestMethod -Uri "http://localhost:3001/" -``` - -### Test 2: Health Check (depuis N8N) -```bash -curl http://172.26.64.1:3001/ -``` - -### Test 3: Workflow N8N - -Crée un workflow avec: - -1. **Manual Trigger** -2. **MCP Client** node: - - Server: `memento` - - Tool: `get_notes` - - Arguments: `{}` -3. **Code** node pour voir le résultat - -## 🔥 Troubleshooting - -### Erreur: "Connection refused" -✅ Vérifie que le serveur SSE tourne: -```powershell -Get-Process | Where-Object { $_.ProcessName -eq "node" } -``` - -### Erreur: "Cannot reach server" -✅ Vérifie le firewall Windows: -```powershell -# Ajouter règle firewall pour port 3001 -New-NetFirewallRule -DisplayName "Memento MCP SSE" -Direction Inbound -LocalPort 3001 -Protocol TCP -Action Allow -``` - -### Erreur: "SSE connection timeout" -✅ Vérifie que N8N peut atteindre ton PC: -```bash -# Depuis la machine N8N -ping 172.26.64.1 -curl http://172.26.64.1:3001/ -``` - -### N8N sur Docker? -Si N8N tourne dans Docker, utilise l'IP de l'hôte Docker, pas `172.26.64.1`. - -Trouve l'IP du host: -```bash -docker inspect -f '{{range .NetworkSettings.Networks}}{{.Gateway}}{{end}}' -``` - -## 📊 Ports Utilisés +## Ports | Service | Port | URL | |---------|------|-----| -| Next.js (Memento UI) | 3000 | http://localhost:3000 | -| MCP SSE Server | 3001 | http://172.26.64.1:3001/sse | -| REST API | 3000 | http://localhost:3000/api/notes | - -## 🔐 Sécurité - -⚠️ **ATTENTION**: Le serveur SSE n'a **PAS D'AUTHENTIFICATION** actuellement! - -Pour production: -1. Ajoute une clé API -2. Utilise HTTPS avec certificat SSL -3. Restreins les CORS origins -4. Utilise un reverse proxy (nginx) - -## 📚 Documentation Complète - -- [MCP-SSE-ANALYSIS.md](../MCP-SSE-ANALYSIS.md) - Analyse détaillée SSE -- [README-SSE.md](README-SSE.md) - Documentation serveur SSE -- [README.md](../README.md) - Documentation projet - -## 🎉 C'est Prêt! - -Ton serveur MCP SSE est configuré et prêt pour N8N! - -**Endpoint N8N**: `http://172.26.64.1:3001/sse` - ---- - -**Dernière mise à jour**: 4 janvier 2026 -**IP**: 172.26.64.1 -**Port**: 3001 -**Status**: ✅ Opérationnel +| Memento UI | 3000 | http://localhost:3000 | +| MCP Server | 3001 | http://localhost:3001/mcp | diff --git a/mcp-server/N8N-WORKFLOWS.md b/mcp-server/N8N-WORKFLOWS.md index 48ada44..b7346af 100644 --- a/mcp-server/N8N-WORKFLOWS.md +++ b/mcp-server/N8N-WORKFLOWS.md @@ -1,376 +1,103 @@ -# Workflows N8N pour Keep Notes MCP +# Workflows N8N pour Memento MCP -## 📚 Introduction +## Introduction -Ce dossier contient 6 workflows N8N prêts à l'emploi pour votre serveur MCP Keep Notes. Chaque workflow est conçu pour une fonctionnalité spécifique et peut être importé directement dans N8N. +Exemples de workflows N8N utilisant le serveur MCP de Memento via le transport **Streamable HTTP**. -## 🚀 Workflows disponibles +**Prerequis** : une cle API generee depuis **Parametres > MCP** dans Memento. -### 1. **Create Note with Classification** (`n8n-workflow-create-note.json`) +## Configuration du noeud MCP Client -**Description:** Crée des notes dans Keep Notes avec classification automatique par IA. +Dans chaque workflow, le noeud MCP Client doit etre configure ainsi : -**Fonctionnalités:** -- Création de notes avec titres, contenus, labels, notebooks -- Classification automatique par IA pour suggérer: - - Titres pertinents - - Labels appropriés - - Notebook optimal - - Catégorie (work/personal/idea) +- **Server Transport** : `Streamable HTTP` +- **MCP Endpoint URL** : `http://memento-mcp:3001/mcp` (Docker) ou `http://VOTRE_IP:3001/mcp` +- **Authentication** : Header Auth avec `x-api-key` = votre cle API -**Cas d'usage:** -- Création rapide de notes depuis des conversations -- Capture d'idées avec auto-organisation -- Génération automatique de métadonnées +## Workflows disponibles + +### 1. Create Note (`n8n-workflow-create-note.json`) + +Cree des notes dans Memento avec classification par IA. -**Utilisation:** ```json { - "content": "Meeting with client next week to discuss project timeline", - "color": "blue", - "labels": ["work"] + "tool": "create_note", + "arguments": { + "content": "Meeting with client next week", + "title": "Client Meeting", + "labels": ["work"], + "notebookId": "cuid123..." + } } ``` ---- +### 2. Search & Summary (`n8n-workflow-search-summary.json`) -### 2. **Search & Summary** (`n8n-workflow-search-summary.json`) +Recherche des notes et genere un resume. -**Description:** Recherche des notes et génère un résumé avec IA. - -**Fonctionnalités:** -- Recherche par mot-clé dans titres et contenus -- Filtrage intelligent des résultats -- Génération de résumés par IA -- Extraction des thèmes principaux -- Identification des action items -- Groupement de notes par thème - -**Cas d'usage:** -- Rapports hebdomadaires d'activité -- Analyse de thématiques -- Synthèse rapide de projets - -**Utilisation:** ```json { - "searchQuery": "project timeline" + "tool": "search_notes", + "arguments": { + "query": "project timeline" + } } ``` ---- +### 3. Notebook Manager (`n8n-workflow-notebook-management.json`) -### 3. **Notebook Manager** (`n8n-workflow-notebook-management.json`) +CRUD complet des notebooks. -**Description:** Gestion complète des notebooks (créer, lister, modifier, supprimer). - -**Fonctionnalités:** -- **Create**: Créer de nouveaux notebooks avec icône et couleur -- **List**: Récupérer tous les notebooks avec leurs notes -- **Update**: Modifier nom, icône, couleur d'un notebook -- **Delete**: Supprimer un notebook et son contenu - -**Cas d'usage:** -- Organisation thématique des notes -- Restructuration de l'espace de travail -- Archivage de projets terminés - -**Utilisation:** ```json { - "action": "create", - "name": "Work Projects", - "icon": "💼", - "color": "#3B82F6" + "tool": "create_notebook", + "arguments": { + "name": "Work Projects", + "icon": "briefcase", + "color": "#3B82F6" + } } ``` ---- +### 4. Reminder Notifications (`n8n-workflow-reminder-notifications.json`) -### 4. **Reminder Notifications** (`n8n-workflow-reminder-notifications.json`) +Automatisation des rappels avec notifications. -**Description:** Automatisation des rappels et notifications pour les notes. +- Declencheur : Schedule (cron: `0 */30 * * * *`) +- Appelle `get_due_reminders` et envoie les notifications -**Fonctionnalités:** -- Vérification automatique des rappels (toutes les 30 min) -- Notifications Slack/Email -- Marquage des rappels comme terminés -- Gestion des rappels récurrents (daily, weekly, monthly, yearly) -- Mise à jour automatique des dates de rappel +### 5. Label Manager (`n8n-workflow-label-management.json`) -**Cas d'usage:** -- Gestion de tâches avec échéances -- Rappels de réunions importantes -- Notifications d'événements récurrents +Gestion des labels. -**Configuration:** -- Déclencheur: Schedule (cron: `0 */30 * * * *`) -- Canaux: Slack et Email (configurable) -- Récurrences: daily, weekly, monthly, yearly - ---- - -### 5. **Label Manager** (`n8n-workflow-label-management.json`) - -**Description:** Gestion complète des labels avec suggestion automatique par IA. - -**Fonctionnalités:** -- **Create**: Créer des labels avec couleur et notebook -- **List**: Récupérer tous les labels (optionnel par notebook) -- **Update**: Modifier nom et couleur d'un label -- **Delete**: Supprimer un label -- **Suggest**: Suggestion automatique de labels par IA - -**Cas d'usage:** -- Organisation avancée par tags -- Classification automatique de contenu -- Gestion de taxonomie dynamique - -**Utilisation:** ```json { - "action": "suggest", - "title": "Budget planning for Q4", - "content": "Need to plan budget for the next quarter..." + "tool": "create_label", + "arguments": { + "name": "urgent", + "color": "red", + "notebookId": "cuid123..." + } } ``` -**Réponse IA:** -```json -{ - "labels": ["finance", "budget", "quarterly", "planning"] -} -``` +### 6. Email to Note (`n8n-workflow-email-integration.json`) ---- +Conversion automatique d'emails en notes. -### 6. **Email to Note** (`n8n-workflow-email-integration.json`) +- Declencheur : Email Trigger (IMAP) +- Cree une note avec le contenu de l'email -**Description:** Conversion automatique d'emails en notes avec classification. - -**Fonctionnalités:** -- Déclenchement sur nouveaux emails (IMAP) -- Extraction automatique de données email -- Classification par IA: - - Thème principal - - Détection d'urgence - - Suggestion de labels et notebooks -- Gestion des emails urgents (pinned, couleur rouge) -- Notification Slack après création - -**Cas d'usage:** -- Capture automatique d'emails importants -- Gestion de boîte de réception -- Intégration email → notes intelligentes - -**Configuration:** -- Déclencheur: Email Trigger (IMAP) -- Filtre: Emails non lus uniquement -- Urgence: Détection automatique par IA - ---- - -## 📥 Importation des Workflows - -### Méthode 1: Import direct +## Importation 1. Ouvrir N8N -2. Cliquer sur **"Import from File"** -3. Sélectionner le fichier JSON souhaité -4. Configurer les paramètres nécessaires (Slack, Email, etc.) -5. Activer le workflow +2. **Import from File** -> selectionner le fichier JSON +3. Configurer le noeud MCP Client (URL + cle API) +4. Activer le workflow -### Méthode 2: Import via API +## Securite -```bash -curl -X POST http://localhost:5678/rest/workflows/import \ - -H "Content-Type: application/json" \ - -d @n8n-workflow-create-note.json -``` - ---- - -## ⚙️ Configuration requise - -### Variables d'environnement - -Dans N8N, configurez les variables suivantes: - -```bash -KEEP_NOTES_API_URL=http://localhost:3000 -SLACK_WEBHOOK_URL=votre_slack_webhook_url -EMAIL_ADDRESS=votre_email@gmail.com -EMAIL_PASSWORD=votre_mot_de_passe_app -OPENAI_API_KEY=votre_clé_openai -``` - -### Connexions requises - -1. **Keep Notes API** - - URL: `http://localhost:3000/api` - - Authentification: Si nécessaire - -2. **Slack** - - Webhook URL ou OAuth token - -3. **Email (IMAP)** - - Serveur IMAP (ex: `imap.gmail.com`) - - Email et mot de passe/application password - -4. **OpenAI API** - - Pour la classification et la génération de résumés - ---- - -## 🔧 Personnalisation - -### Modifier les délais de rappel - -Dans "Reminder Notifications", modifiez l'expression cron: - -```cron -# Toutes les 15 minutes -0 */15 * * * * - -# Toutes les heures -0 * * * * - -# Toutes les 2 heures -0 */2 * * * -``` - -### Changer les couleurs par défaut - -Dans "Create Note", modifiez la valeur par défaut: - -```json -{ - "color": "purple" -} -``` - -### Adapter les catégories de classification - -Dans "Email to Note", modifiez le prompt IA pour inclure vos catégories personnalisées. - ---- - -## 🎯 Combinaison de Workflows - -### Exemple: Pipeline complet Email → Classification → Rappel - -``` -Email Trigger - → Extract Email Data - → AI Classify - → Create Note - → Set Reminder - → Notify Slack -``` - -### Exemple: Recherche intelligente avec labels - -``` -MCP Trigger (search) - → Get Notes - → Filter - → AI Suggest Labels - → Apply Labels - → Return Summary -``` - ---- - -## 📊 Monitoring et Logs - -Activer les logs dans N8N pour suivre l'exécution: - -1. Aller dans **Settings** → **Executions** -2. Filtrer par workflow -3. Voir les détails de chaque exécution -4. Déboguer les erreurs éventuelles - ---- - -## 🔒 Sécurité - -### Bonnes pratiques - -1. **Ne jamais** exposer des données sensibles dans les workflows -2. Utiliser des **variables d'environnement** pour les clés API -3. **Limiter** l'accès aux workflows MCP avec authentification -4. **Valider** toutes les entrées utilisateur -5. **Auditer** régulièrement les exécutions - -### Accès MCP - -Pour sécuriser l'accès MCP aux workflows: - -1. Configurer l'authentification dans le **MCP Server Trigger** -2. Utiliser des **Bearer tokens** ou **OAuth** -3. Restreindre l'accès par IP si nécessaire - ---- - -## 🐛 Dépannage - -### Erreur: "Connection refused to localhost:3000" - -**Solution:** Vérifiez que Keep Notes est démarré sur le port 3000. - -### Erreur: "AI classification failed" - -**Solution:** Vérifiez votre clé OpenAI API et vos crédits. - -### Erreur: "Email trigger not working" - -**Solution:** -- Activez l'accès "less secure apps" pour Gmail -- Utilisez un "App Password" si 2FA activé - -### Erreur: "Slack notification failed" - -**Solution:** Vérifiez l'URL du webhook Slack et les permissions. - ---- - -## 📚 Documentation complémentaire - -- [N8N Documentation](https://docs.n8n.io) -- [MCP Protocol](https://modelcontextprotocol.io) -- [Keep Notes API](./README.md) - ---- - -## 🤝 Contribution - -Pour ajouter de nouveaux workflows: - -1. Créez le fichier JSON correspondant -2. Ajoutez la documentation dans ce fichier -3. Testez le workflow en local -4. Partagez-le avec l'équipe - ---- - -## 📝 Notes importantes - -- Tous les workflows utilisent le protocole MCP -- L'URL de l'API Keep Notes doit être configurée correctement -- Les workflows nécessitent que le serveur Keep Notes soit en cours d'exécution -- Les coûts OpenAI s'appliquent pour la classification et la génération de résumés - ---- - -## 🎉 Résumé - -| Workflow | Utilisation principale | Complexité | -|----------|----------------------|-------------| -| Create Note | Création avec IA | ⭐⭐ | -| Search & Summary | Analyse de contenu | ⭐⭐⭐ | -| Notebook Manager | Gestion notebooks | ⭐ | -| Reminder Notifications | Automatisation rappels | ⭐⭐⭐ | -| Label Manager | Gestion labels | ⭐⭐ | -| Email to Note | Intégration email | ⭐⭐⭐⭐ | - -**Total:** 6 workflows prêts à l'emploi! 🚀 +- Toujours utiliser une cle API dediee par workflow +- Ne jamais exposer la cle dans les logs +- Restreindre l'acces reseau au port 3001 si possible diff --git a/mcp-server/README.md b/mcp-server/README.md index 46a015a..229e323 100644 --- a/mcp-server/README.md +++ b/mcp-server/README.md @@ -1,344 +1,139 @@ -# Keep Notes MCP Server +# Memento MCP Server -Model Context Protocol (MCP) server for integrating Keep Notes note-taking app with N8N, Cursor, and other automation tools. +Model Context Protocol (MCP) server for integrating Memento note-taking app with N8N, Claude Desktop, and other MCP clients. -## Installation +## Quick Start ```bash cd mcp-server npm install ``` -## Usage - -### Quick Start (Windows) - -Le plus simple pour démarrer le serveur MCP: - -```powershell -# Exécuter depuis le dossier mcp-server -.\start-mcp.ps1 -``` - -Ou le script batch: - -```cmd -start-mcp.bat -``` - -Ces scripts vérifient automatiquement les prérequis et démarrent le serveur. - -### Standalone Server (Cross-platform) - -```bash -npm start -``` - -Ou directement: +### stdio Mode (Claude Desktop, Cline) ```bash node index.js ``` -Pour le mode SSE (Server-Sent Events): - -```bash -npm run start:sse -``` - -Voir [START-MCP.md](./START-MCP.md) pour le guide complet de démarrage. - -### With Cursor MCP - -Add to your Cursor MCP client configuration: - +Claude Desktop configuration: ```json { "mcpServers": { - "memento-note": { - "command": "node", - "args": ["D:/dev_new_pc/Keep/mcp-server/index.js"] + "memento": { + "command": "docker", + "args": ["exec", "-i", "memento-mcp", "node", "index.js"] } } } ``` -### With N8N +### HTTP Streamable Mode (N8N, remote) -Configure the MCP node in N8N with the server details above. - -## Available Tools - -### Note Management - -#### create_note -Create a new note in Keep Notes. - -**Parameters:** -- `title` (string, optional): Note title -- `content` (string, required): Note content -- `color` (string, optional): Note color (default, red, orange, yellow, green, teal, blue, purple, pink, gray) -- `type` (string, optional): Note type (text or checklist) -- `checkItems` (array, optional): Checklist items -- `labels` (array, optional): Note labels/tags -- `isPinned` (boolean, optional): Pin the note -- `isArchived` (boolean, optional): Archive the note -- `images` (array, optional): Note images as base64 encoded strings -- `links` (array, optional): Note links -- `reminder` (string, optional): Reminder date/time (ISO 8601 format) -- `isReminderDone` (boolean, optional): Mark reminder as done -- `reminderRecurrence` (string, optional): Reminder recurrence (daily, weekly, monthly, yearly) -- `reminderLocation` (string, optional): Reminder location -- `isMarkdown` (boolean, optional): Enable markdown support -- `size` (string, optional): Note size (small, medium, large) -- `notebookId` (string, optional): Notebook ID to associate the note with - -**Example:** -```json -{ - "title": "Shopping List", - "content": "Buy groceries", - "color": "blue", - "type": "checklist", - "checkItems": [ - { "id": "1", "text": "Milk", "checked": false }, - { "id": "2", "text": "Bread", "checked": false } - ], - "labels": ["shopping", "personal"], - "notebookId": "cuid123..." -} +```bash +node index-sse.js ``` -#### get_notes -Get all notes from Keep Notes. +Requires `DATABASE_URL` environment variable pointing to your PostgreSQL database. -**Parameters:** -- `includeArchived` (boolean, optional): Include archived notes -- `search` (string, optional): Search query to filter notes -- `notebookId` (string, optional): Filter notes by notebook ID +For Docker deployment, MCP_MODE and MCP_REQUIRE_AUTH are pre-configured in `docker-compose.yml`. -#### get_note -Get a specific note by ID. +## Authentication -**Parameters:** -- `id` (string, required): Note ID +When `MCP_REQUIRE_AUTH=true` (default in Docker), all requests require an `x-api-key` header. -#### update_note -Update an existing note. +Generate API keys from the Memento web UI: **Settings > MCP**. -**Parameters:** -- `id` (string, required): Note ID -- All other fields from create_note are optional +```bash +# Example: health check with API key +curl -H "x-api-key: mcp_sk_xxx" http://localhost:3001/ +``` -#### delete_note -Delete a note by ID. +## Available Tools (22) -**Parameters:** -- `id` (string, required): Note ID +### Notes (11) -#### search_notes -Search notes by query. +| Tool | Description | +|------|-------------| +| `create_note` | Create a new note | +| `get_notes` | List notes (filterable) | +| `get_note` | Get a specific note by ID | +| `update_note` | Update an existing note | +| `delete_note` | Delete a note | +| `search_notes` | Search notes by keyword | +| `move_note` | Move a note to a notebook | +| `toggle_pin` | Pin/unpin a note | +| `toggle_archive` | Archive/unarchive a note | +| `export_notes` | Export notes as JSON | +| `import_notes` | Import notes from JSON | -**Parameters:** -- `query` (string, required): Search query -- `notebookId` (string, optional): Filter search by notebook ID +### Notebooks (6) -#### get_labels -Get all unique labels from notes (legacy method). +| Tool | Description | +|------|-------------| +| `create_notebook` | Create a notebook | +| `get_notebooks` | List all notebooks | +| `get_notebook` | Get notebook details | +| `update_notebook` | Update a notebook | +| `delete_notebook` | Delete a notebook | +| `reorder_notebooks` | Reorder notebooks | -**Parameters:** None +### Labels (4) -#### toggle_pin -Toggle pin status of a note. +| Tool | Description | +|------|-------------| +| `create_label` | Create a label | +| `get_labels` | List labels | +| `update_label` | Update a label | +| `delete_label` | Delete a label | -**Parameters:** -- `id` (string, required): Note ID +### Reminders (1) -#### toggle_archive -Toggle archive status of a note. +| Tool | Description | +|------|-------------| +| `get_due_reminders` | Get due reminders | -**Parameters:** -- `id` (string, required): Note ID +## N8N Integration -### Notebook Management +### MCP Client Node Configuration -#### create_notebook -Create a new notebook. +1. Add a **MCP Client** node in N8N +2. Select **Streamable HTTP** as transport +3. Endpoint: `http://memento-mcp:3001/mcp` (Docker) or `http://YOUR_IP:3001/mcp` +4. Add **Header Auth**: `x-api-key` = your MCP API key -**Parameters:** -- `name` (string, required): Notebook name -- `icon` (string, optional): Notebook icon (emoji) -- `color` (string, optional): Notebook color (hex code) -- `order` (number, optional): Notebook order +### Example Workflow: Create a note from email -#### get_notebooks -Get all notebooks. - -**Parameters:** None - -#### get_notebook -Get a specific notebook by ID with its notes. - -**Parameters:** -- `id` (string, required): Notebook ID - -#### update_notebook -Update an existing notebook. - -**Parameters:** -- `id` (string, required): Notebook ID -- `name` (string, optional): Notebook name -- `icon` (string, optional): Notebook icon -- `color` (string, optional): Notebook color -- `order` (number, optional): Notebook order - -#### delete_notebook -Delete a notebook by ID. - -**Parameters:** -- `id` (string, required): Notebook ID - -### Label Management - -#### create_label -Create a new label. - -**Parameters:** -- `name` (string, required): Label name -- `color` (string, optional): Label color (red, orange, yellow, green, teal, blue, purple, pink, gray) -- `notebookId` (string, required): Notebook ID to associate the label with - -#### get_labels_detailed -Get all labels with details. - -**Parameters:** -- `notebookId` (string, optional): Filter labels by notebook ID - -#### update_label -Update an existing label. - -**Parameters:** -- `id` (string, required): Label ID -- `name` (string, optional): Label name -- `color` (string, optional): Label color - -#### delete_label -Delete a label by ID. - -**Parameters:** -- `id` (string, required): Label ID - -## N8N Integration Example - -### Create a note from email ```json { "tool": "create_note", "arguments": { "title": "{{ $json.subject }}", "content": "{{ $json.body }}", - "labels": ["email", "inbox"], - "notebookId": "cuid123..." + "labels": ["email", "inbox"] } } ``` -### Search notes -```json -{ - "tool": "search_notes", - "arguments": { - "query": "meeting", - "notebookId": "cuid123..." - } -} -``` +## HTTP Endpoints -### Create a notebook -```json -{ - "tool": "create_notebook", - "arguments": { - "name": "Work Projects", - "icon": "💼", - "color": "#3B82F6" - } -} -``` +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/` | GET | Health check | +| `/mcp` | GET/POST | Main MCP endpoint (Streamable HTTP) | +| `/sse` | GET/POST | Legacy redirect to `/mcp` | +| `/sessions` | GET | Active sessions | -## Database +## Configuration -The MCP server connects to the same SQLite database as the Keep Notes web app located at: -`D:/dev_new_pc/Keep/memento-note/prisma/dev.db` - -## Prisma Schema Reference - -The MCP server works with the following Prisma models: - -### Note Model -- id: String (CUID) -- title: String? -- content: String -- color: String (default: "default") -- isPinned: Boolean -- isArchived: Boolean -- type: String (default: "text") -- checkItems: String? (JSON) -- labels: String? (JSON) -- images: String? (JSON) -- links: String? (JSON) -- reminder: DateTime? -- isReminderDone: Boolean -- reminderRecurrence: String? -- reminderLocation: String? -- isMarkdown: Boolean -- size: String (default: "small") -- notebookId: String? -- userId: String? -- order: Int -- createdAt: DateTime -- updatedAt: DateTime - -### Notebook Model -- id: String (CUID) -- name: String -- icon: String? -- color: String? -- order: Int -- userId: String -- createdAt: DateTime -- updatedAt: DateTime - -### Label Model -- id: String (CUID) -- name: String -- color: String (default: "gray") -- notebookId: String? -- userId: String? -- createdAt: DateTime -- updatedAt: DateTime - -## N8N Workflows - -Ce serveur MCP est accompagné de 6 workflows N8N prêts à l'emploi pour une intégration complète: - -1. **Create Note with Classification** - Création de notes avec classification automatique par IA -2. **Search & Summary** - Recherche et résumé intelligent de notes -3. **Notebook Manager** - Gestion complète des notebooks (CRUD) -4. **Reminder Notifications** - Automatisation des rappels avec notifications -5. **Label Manager** - Gestion des labels avec suggestion IA -6. **Email to Note** - Conversion automatique d'emails en notes - -Pour plus de détails, consultez [N8N-WORKFLOWS.md](./N8N-WORKFLOWS.md) - -### Importation des Workflows - -Chaque workflow peut être importé directement dans N8N via le fichier JSON correspondant: - -```bash -# Exemple: Importer le workflow de création de notes -# Ouvrir N8N → Import from File → Sélectionner n8n-workflow-create-note.json -``` +| Variable | Default | Description | +|----------|---------|-------------| +| `PORT` | 3001 | Server port | +| `DATABASE_URL` | required | PostgreSQL connection string | +| `MCP_MODE` | stdio | Transport mode (stdio or sse) | +| `MCP_REQUIRE_AUTH` | false | Require x-api-key header | +| `MCP_LOG_LEVEL` | info | Log level (debug, info, warn, error) | +| `MCP_REQUEST_TIMEOUT` | 30000 | Request timeout in ms | +| `APP_BASE_URL` | http://localhost:3000 | Memento app URL | ## License