fa7e166f3e
- Add reminders page with navigation support - Upgrade BMad builder module to skills-based architecture - Refactor MCP server: extract tools and auth into separate modules - Add connections cache, custom AI provider support - Update prisma schema and generated client - Various UI/UX improvements and i18n updates - Add service worker for PWA support Made-with: Cursor
1132 lines
37 KiB
Markdown
1132 lines
37 KiB
Markdown
# Memento MCP Server - Documentation Complete
|
|
|
|
> Version 3.0.0 | 34 outils | Model Context Protocol
|
|
|
|
## Table des matieres
|
|
|
|
1. [Introduction](#1-introduction)
|
|
2. [Architecture](#2-architecture)
|
|
3. [Installation](#3-installation)
|
|
4. [Configuration](#4-configuration)
|
|
5. [Modes de transport](#5-modes-de-transport)
|
|
6. [Reference complete des outils](#6-reference-complete-des-outils)
|
|
7. [Integrations](#7-integrations)
|
|
8. [Docker](#8-docker)
|
|
9. [Securite](#9-securite)
|
|
10. [Guide de demarrage rapide](#10-guide-de-demarrage-rapide)
|
|
11. [Depannage](#11-depannage)
|
|
|
|
---
|
|
|
|
## 1. Introduction
|
|
|
|
**Memento MCP Server** est un serveur [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) qui expose toutes les fonctionnalites de l'application de prise de notes **Memento** sous forme d'outils programmables.
|
|
|
|
Il permet a n'importe quel client MCP (Claude Code, Cursor, N8N, scripts Python, etc.) de :
|
|
|
|
- Creer, lire, modifier, supprimer des notes
|
|
- Gerer les notebooks et labels
|
|
- Utiliser les fonctionnalites AI (titres, tags, reformulation, Memory Echo, fusion, etc.)
|
|
- Exporter/importer les donnees
|
|
- Traiter les rappels en retard
|
|
|
|
### Pourquoi MCP ?
|
|
|
|
```
|
|
Sans MCP : Vous devez utiliser l'interface web manuellement
|
|
Avec MCP : N'importe quel agent AI ou automate peut interagir avec vos notes
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Architecture
|
|
|
|
### Vue d'ensemble
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ CLIENTS MCP │
|
|
│ ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
|
|
│ │Claude Code│ │ Cursor │ │ N8N │ │Script Python │ │
|
|
│ └─────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │
|
|
│ │ │ │ │ │
|
|
│ stdio stdio HTTP/SSE HTTP/SSE │
|
|
└────────┼──────────────┼──────────────┼────────────────┼─────────┘
|
|
│ │ │ │
|
|
▼ ▼ ▼ ▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ MCP SERVER v3.0.0 │
|
|
│ │
|
|
│ ┌──────────────────────────────────────────────────────────┐ │
|
|
│ │ tools.js (34 outils) │ │
|
|
│ │ │ │
|
|
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
|
|
│ │ │ Notes │ │Notebooks │ │ Labels │ │Reminders │ │ │
|
|
│ │ │ 12 tools│ │ 6 tools │ │ 4 tools │ │ 1 tool │ │ │
|
|
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
|
|
│ │ ┌────────────────────────────────────────────────────┐ │ │
|
|
│ │ │ AI (11 tools) │ │ │
|
|
│ │ │ Titres | Tags | Reformulation | Memory Echo │ │ │
|
|
│ │ │ Fusion | Notebook AI | Batch | Auto-labels │ │ │
|
|
│ │ └────────────────────────────────────────────────────┘ │ │
|
|
│ └──────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────┐ ┌─────────────────┐ │
|
|
│ │ index.js │ │ index-sse.js │ │
|
|
│ │ (stdio) │ │ (HTTP/SSE) │ │
|
|
│ └──────┬──────┘ └────────┬────────┘ │
|
|
└─────────┼─────────────────────────────────────────┼────────────┘
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────────┐ ┌──────────────────────┐
|
|
│ SQLite DB │ │ Next.js App API │
|
|
│ (Prisma ORM) │ │ (Outils AI) │
|
|
│ │ │ │
|
|
│ - Notes │ │ /api/ai/* │
|
|
│ - Notebooks │ │ /api/notes/* │
|
|
│ - Labels │ │ │
|
|
│ - Users │ │ localhost:3000 │
|
|
│ - Reminders │ └──────────────────────┘
|
|
└──────────────────┘
|
|
```
|
|
|
|
### Flux de donnees par type d'outil
|
|
|
|
**Outils CRUD (Notes, Notebooks, Labels, Reminders) :**
|
|
|
|
```
|
|
Client MCP ──► tools.js ──► Prisma ORM ──► SQLite
|
|
```
|
|
|
|
Acces direct a la base de donnees. Pas besoin que l'app Next.js soit lancee.
|
|
|
|
**Outils AI :**
|
|
|
|
```
|
|
Client MCP ──► tools.js ──► fetch() ──► Next.js /api/ai/* ──► AI Provider
|
|
```
|
|
|
|
Proxy vers l'API Next.js. L'application doit etre lancee et un provider AI configure.
|
|
|
|
### Structure des fichiers
|
|
|
|
```
|
|
mcp-server/
|
|
├── index.js # Transport stdio (CLI local)
|
|
├── index-sse.js # Transport HTTP/SSE (distant)
|
|
├── tools.js # Definitions et handlers des 34 outils
|
|
├── package.json # Dependances et scripts
|
|
├── Dockerfile # Image Docker multi-mode
|
|
│
|
|
├── n8n-workflow-create-note.json # Workflow N8N pre-construit
|
|
├── n8n-workflow-email-integration.json
|
|
├── n8n-workflow-label-management.json
|
|
├── n8n-workflow-notebook-management.json
|
|
├── n8n-workflow-reminder-notifications.json
|
|
├── n8n-workflow-search-summary.json
|
|
│
|
|
└── prisma/ # Schema Prisma (generation)
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Installation
|
|
|
|
### Prerequis
|
|
|
|
- **Node.js** 18+ (recommande 20+)
|
|
- **SQLite** (inclus avec Prisma)
|
|
- L'application Memento Next.js (pour les outils AI)
|
|
|
|
### Installation rapide
|
|
|
|
```bash
|
|
cd mcp-server
|
|
|
|
# Installer les dependances
|
|
npm install
|
|
|
|
# Regenerer le client Prisma (si le schema a change)
|
|
npx prisma generate --schema=../keep-notes/prisma/schema.prisma
|
|
```
|
|
|
|
### Verification
|
|
|
|
```bash
|
|
# Test d'import du module
|
|
node -e "import('./tools.js').then(() => console.log('OK'))"
|
|
|
|
# Lancement rapide en mode stdio
|
|
node index.js
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Configuration
|
|
|
|
### Variables d'environnement
|
|
|
|
| Variable | Defaut | Requis | Description |
|
|
|---|---|---|---|
|
|
| `DATABASE_URL` | `file:../keep-notes/prisma/dev.db` | Non | Chemin vers la base SQLite |
|
|
| `USER_ID` | Auto-detecte (1er user) | Non | ID utilisateur pour le filtrage multi-user |
|
|
| `APP_BASE_URL` | `http://localhost:3000` | AI | URL de l'app Next.js (requis pour les outils AI) |
|
|
| `PORT` | `3001` | Non | Port du serveur HTTP (mode SSE uniquement) |
|
|
| `MCP_REQUIRE_AUTH` | `false` | Non | Activer l'authentification (`true`/`false`) |
|
|
| `MCP_API_KEY` | - | Non | Cle API statique (si auth activee) |
|
|
|
|
### Multi-utilisateur
|
|
|
|
Memento supporte plusieurs utilisateurs. Le MCP peut operer de deux manieres :
|
|
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ USER_ID non defini │
|
|
│ → Auto-detection du 1er utilisateur │
|
|
│ → Toutes les operations utilisent │
|
|
│ cet utilisateur par defaut │
|
|
└─────────────────────────────────────────┘
|
|
|
|
┌─────────────────────────────────────────┐
|
|
│ USER_ID="cmk36y..." defini │
|
|
│ → Toutes les operations sont filtreees │
|
|
│ pour cet utilisateur specifique │
|
|
│ → Create/Read/Update/Delete scopes │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Modes de transport
|
|
|
|
### 5.1 Mode Stdio (CLI local)
|
|
|
|
Pour une utilisation locale avec Claude Code, Cursor, ou tout client MCP qui supporte le transport stdio.
|
|
|
|
```
|
|
┌──────────────┐ stdin/stdout ┌──────────────┐
|
|
│ Claude Code │ ◄──────────────► │ index.js │
|
|
│ ou Cursor │ (JSON-RPC) │ (stdio) │
|
|
└──────────────┘ └──────┬───────┘
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ SQLite DB │
|
|
└──────────────┘
|
|
```
|
|
|
|
**Lancement :**
|
|
|
|
```bash
|
|
node index.js
|
|
```
|
|
|
|
**Configuration Claude Code (`.claude/mcp.json`) :**
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"memento": {
|
|
"command": "node",
|
|
"args": ["/chemin/vers/mcp-server/index.js"],
|
|
"env": {
|
|
"APP_BASE_URL": "http://localhost:3000",
|
|
"USER_ID": "votre-user-id"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Configuration Cursor (`.cursor/mcp.json`) :**
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"memento": {
|
|
"command": "node",
|
|
"args": ["/chemin/vers/mcp-server/index.js"],
|
|
"env": {
|
|
"APP_BASE_URL": "http://localhost:3000"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 5.2 Mode HTTP/SSE (distant)
|
|
|
|
Pour les automatisations N8N, les scripts, ou tout client HTTP.
|
|
|
|
```
|
|
┌──────────────┐ HTTP POST ┌──────────────────┐
|
|
│ N8N │ ────────────────► │ index-sse.js │
|
|
│ ou Script │ ◄──────────────── │ (port 3001) │
|
|
└──────────────┘ SSE response └────────┬─────────┘
|
|
│
|
|
┌─────────┴─────────┐
|
|
▼ ▼
|
|
┌──────────────┐ ┌──────────────┐
|
|
│ SQLite DB │ │ Next.js API │
|
|
└──────────────┘ └──────────────┘
|
|
```
|
|
|
|
**Lancement :**
|
|
|
|
```bash
|
|
# Mode dev (sans auth)
|
|
node index-sse.js
|
|
|
|
# Mode production (avec auth)
|
|
MCP_REQUIRE_AUTH=true MCP_API_KEY=votre-cle-secrete node index-sse.js
|
|
|
|
# Port personnalise
|
|
PORT=8080 node index-sse.js
|
|
```
|
|
|
|
**Endpoints HTTP :**
|
|
|
|
```
|
|
GET / → Health check (version, status, outils)
|
|
GET /sessions → Sessions utilisateur actives
|
|
ALL /mcp → Endpoint MCP Streamable HTTP
|
|
ALL /sse → Alias legacy → /mcp
|
|
```
|
|
|
|
**Exemple de health check :**
|
|
|
|
```bash
|
|
curl http://localhost:3001/
|
|
|
|
# Reponse :
|
|
{
|
|
"name": "Memento MCP Server",
|
|
"version": "3.0.0",
|
|
"status": "running",
|
|
"tools": { "notes": 12, "notebooks": 6, "labels": 4, "ai": 11, "reminders": 1, "total": 34 }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Reference complete des outils
|
|
|
|
### 6.1 Notes (12 outils)
|
|
|
|
#### `create_note`
|
|
|
|
Cree une nouvelle note avec support complet.
|
|
|
|
```
|
|
Parametres :
|
|
content* string Contenu de la note
|
|
title string Titre (optionnel)
|
|
color string Couleur (default, red, orange, yellow,
|
|
green, teal, blue, purple, pink, gray)
|
|
type string "text" ou "checklist"
|
|
checkItems array Items de checklist [{id, text, checked}]
|
|
labels array[string] Tags/labels
|
|
isPinned boolean Epingler la note
|
|
isArchived boolean Creer directement archivee
|
|
images array[string] URLs ou base64
|
|
links array[string] URLs attachees
|
|
reminder string Date/heure ISO 8601
|
|
reminderRecurrence string "daily" | "weekly" | "monthly" | "yearly"
|
|
reminderLocation string Lieu du rappel
|
|
isMarkdown boolean Activer le rendu Markdown
|
|
size string "small" | "medium" | "large"
|
|
notebookId string ID du notebook cible
|
|
```
|
|
|
|
**Exemple :**
|
|
|
|
```json
|
|
{
|
|
"title": "Idees de projet",
|
|
"content": "Creer un bot Discord qui resume les notes",
|
|
"color": "blue",
|
|
"labels": ["idee", "bot"],
|
|
"isMarkdown": true,
|
|
"notebookId": "cmk36..."
|
|
}
|
|
```
|
|
|
|
#### `get_notes`
|
|
|
|
Recupere les notes avec filtres. Retourne un format leger par defaut (contenu tronque a 200 caracteres, pas d'images).
|
|
|
|
```
|
|
Parametres :
|
|
includeArchived boolean Inclure les notes archivees (defaut: false)
|
|
search string Filtrer par mot-cle
|
|
notebookId string Filtrer par notebook ("inbox" = sans notebook)
|
|
fullDetails boolean Retour complet avec images (defaut: false)
|
|
limit number Max notes (defaut: 100)
|
|
```
|
|
|
|
#### `get_note`
|
|
|
|
Recupere une note par ID avec tous les details.
|
|
|
|
```
|
|
Parametres :
|
|
id* string ID de la note
|
|
```
|
|
|
|
#### `update_note`
|
|
|
|
Met a jour une note. N'inclure que les champs a modifier.
|
|
|
|
```
|
|
Parametres :
|
|
id* string ID de la note
|
|
title string
|
|
content string
|
|
color string
|
|
type string
|
|
checkItems array
|
|
labels array[string]
|
|
isPinned boolean
|
|
isArchived boolean
|
|
images array[string]
|
|
links array[string]
|
|
reminder string
|
|
isReminderDone boolean
|
|
reminderRecurrence string
|
|
reminderLocation string
|
|
isMarkdown boolean
|
|
size string
|
|
notebookId string
|
|
```
|
|
|
|
#### `delete_note`
|
|
|
|
Supprime une note par ID.
|
|
|
|
```
|
|
Parametres :
|
|
id* string ID de la note
|
|
```
|
|
|
|
#### `delete_all_notes`
|
|
|
|
Supprime TOUTES les notes, labels et notebooks. **Use avec extreme caution.**
|
|
|
|
#### `search_notes`
|
|
|
|
Recherche par mot-cle dans le titre et le contenu.
|
|
|
|
```
|
|
Parametres :
|
|
query* string Requete de recherche
|
|
notebookId string Limiter a un notebook
|
|
includeArchived boolean Inclure les archivees (defaut: false)
|
|
```
|
|
|
|
#### `move_note`
|
|
|
|
Deplace une note vers un autre notebook (ou Inbox).
|
|
|
|
```
|
|
Parametres :
|
|
id* string ID de la note
|
|
notebookId string ID du notebook cible (null = Inbox)
|
|
```
|
|
|
|
#### `toggle_pin`
|
|
|
|
Inverse le statut d'epinglage d'une note.
|
|
|
|
```
|
|
Parametres : id* (string)
|
|
```
|
|
|
|
#### `toggle_archive`
|
|
|
|
Inverse le statut d'archivage d'une note.
|
|
|
|
```
|
|
Parametres : id* (string)
|
|
```
|
|
|
|
#### `export_notes`
|
|
|
|
Exporte toutes les donnees au format JSON.
|
|
|
|
```json
|
|
// Reponse :
|
|
{
|
|
"version": "2.0",
|
|
"exportDate": "2026-04-11T...",
|
|
"data": {
|
|
"notes": [...],
|
|
"notebooks": [...],
|
|
"labels": [...]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `import_notes`
|
|
|
|
Importe des donnees depuis un export JSON. Les doublons (meme nom) sont ignores.
|
|
|
|
```
|
|
Parametres :
|
|
data* object L'objet JSON exporte (de export_notes)
|
|
```
|
|
|
|
---
|
|
|
|
### 6.2 Notebooks (6 outils)
|
|
|
|
#### `create_notebook`
|
|
|
|
```
|
|
Parametres :
|
|
name* string Nom du notebook
|
|
icon string Icone emoji (defaut: "📁")
|
|
color string Couleur hex (defaut: "#3B82F6")
|
|
order number Position (auto si omis)
|
|
```
|
|
|
|
#### `get_notebooks`
|
|
|
|
Retourne tous les notebooks avec nombre de notes et labels.
|
|
|
|
#### `get_notebook`
|
|
|
|
```
|
|
Parametres : id* (string)
|
|
```
|
|
|
|
Retourne le notebook avec ses notes (format leger) et labels.
|
|
|
|
#### `update_notebook`
|
|
|
|
```
|
|
Parametres :
|
|
id* string ID du notebook
|
|
name string
|
|
icon string
|
|
color string
|
|
order number
|
|
```
|
|
|
|
#### `delete_notebook`
|
|
|
|
Supprime un notebook. Les notes a l'interieur sont deplacees vers Inbox.
|
|
|
|
```
|
|
Parametres : id* (string)
|
|
```
|
|
|
|
#### `reorder_notebooks`
|
|
|
|
Reordonne les notebooks. Passe un tableau d'IDs dans l'ordre souhaite.
|
|
|
|
```
|
|
Parametres :
|
|
notebookIds* array[string] IDs dans l'ordre voulu
|
|
```
|
|
|
|
---
|
|
|
|
### 6.3 Labels (4 outils)
|
|
|
|
#### `create_label`
|
|
|
|
```
|
|
Parametres :
|
|
name* string Nom du label
|
|
notebookId* string Notebook d'appartenance
|
|
color string Couleur (red, orange, yellow, green, teal, blue, purple, pink, gray)
|
|
```
|
|
|
|
#### `get_labels`
|
|
|
|
```
|
|
Parametres :
|
|
notebookId string Filtrer par notebook (optionnel)
|
|
```
|
|
|
|
#### `update_label`
|
|
|
|
```
|
|
Parametres :
|
|
id* string ID du label
|
|
name string
|
|
color string
|
|
```
|
|
|
|
#### `delete_label`
|
|
|
|
```
|
|
Parametres : id* (string)
|
|
```
|
|
|
|
---
|
|
|
|
### 6.4 AI (11 outils)
|
|
|
|
> **Important :** Ces outils necessitent que l'application Next.js soit lancee (`localhost:3000`) ET qu'un provider AI soit configure (OpenAI, Ollama, etc.).
|
|
|
|
#### `generate_title_suggestions`
|
|
|
|
Genere 3 suggestions de titre pour un contenu.
|
|
|
|
```
|
|
Parametres :
|
|
content* string Contenu de la note (10+ mots recommandes)
|
|
|
|
Reponse :
|
|
{ suggestions: [{ title, confidence, reasoning }] }
|
|
```
|
|
|
|
#### `reformulate_text`
|
|
|
|
Reformule un texte avec 3 modes disponibles.
|
|
|
|
```
|
|
Parametres :
|
|
text* string Texte a reformuler
|
|
option* string "clarify" | "shorten" | "improve"
|
|
|
|
Reponse :
|
|
{ originalText, reformulatedText, option, wordCountChange }
|
|
```
|
|
|
|
#### `generate_tags`
|
|
|
|
Genere des tags/labels pour un contenu. Mode contextuel si un notebookId est fourni.
|
|
|
|
```
|
|
Parametres :
|
|
content* string Contenu a analyser
|
|
notebookId string ID du notebook pour tags contextuels
|
|
language string Langue (defaut: "en")
|
|
|
|
Reponse :
|
|
{ tags: [{ tag, confidence, isNewLabel }] }
|
|
```
|
|
|
|
#### `suggest_notebook`
|
|
|
|
Suggere un notebook pour une note base sur son contenu.
|
|
|
|
```
|
|
Parametres :
|
|
noteContent* string Contenu (20+ mots recommandes)
|
|
language string Langue (defaut: "en")
|
|
```
|
|
|
|
#### `get_notebook_summary`
|
|
|
|
Genere un resume AI de toutes les notes d'un notebook.
|
|
|
|
```
|
|
Parametres :
|
|
notebookId* string ID du notebook
|
|
language string Langue (defaut: "en")
|
|
```
|
|
|
|
#### `get_memory_echo`
|
|
|
|
Recupere le prochain insight Memory Echo - des connexions semantiques decouvertes entre vos notes.
|
|
|
|
```
|
|
Pas de parametres.
|
|
|
|
Reponse :
|
|
{ insight: { note1, note2, similarityScore, insight } | null }
|
|
```
|
|
|
|
#### `get_note_connections`
|
|
|
|
Liste toutes les notes semantiquement liees a une note donnee.
|
|
|
|
```
|
|
Parametres :
|
|
noteId* string ID de la note
|
|
page number Page (defaut: 1)
|
|
limit number Par page (defaut: 10, max: 50)
|
|
|
|
Reponse :
|
|
{ connections: [...], pagination: { total, page, totalPages } }
|
|
```
|
|
|
|
#### `dismiss_connection`
|
|
|
|
Rejette une connexion entre deux notes.
|
|
|
|
```
|
|
Parametres :
|
|
noteId* string ID de la premiere note
|
|
connectedNoteId* string ID de la note connectee a rejeter
|
|
```
|
|
|
|
#### `fuse_notes`
|
|
|
|
Fusionne plusieurs notes en une seule via AI.
|
|
|
|
```
|
|
Parametres :
|
|
noteIds* array[string] IDs des notes (minimum 2)
|
|
prompt string Instructions supplementaires
|
|
```
|
|
|
|
#### `batch_organize`
|
|
|
|
Organisation intelligente des notes de l'Inbox.
|
|
|
|
```
|
|
# Etape 1 : Creer le plan
|
|
{ "action": "create_plan", "language": "fr" }
|
|
|
|
# Etape 2 : Appliquer le plan
|
|
{
|
|
"action": "apply_plan",
|
|
"plan": { ... }, // L'objet retourne par create_plan
|
|
"selectedNoteIds": [...] // IDs des notes a deplacer
|
|
}
|
|
```
|
|
|
|
#### `suggest_auto_labels`
|
|
|
|
Suggere ou cree des labels pour un notebook (requiert 15+ notes).
|
|
|
|
```
|
|
# Suggere des labels
|
|
{ "action": "suggest", "notebookId": "..." }
|
|
|
|
# Cree les labels selectionnes
|
|
{
|
|
"action": "create",
|
|
"notebookId": "...",
|
|
"selectedLabels": ["label1", "label2"],
|
|
"suggestions": { ... } // Objet de l'etape suggest
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 6.5 Reminders (1 outil)
|
|
|
|
#### `get_due_reminders`
|
|
|
|
Recupere les notes avec des rappels en retard non traites. Les marque comme traites.
|
|
|
|
```
|
|
Pas de parametres.
|
|
|
|
Reponse :
|
|
{ count: 3, reminders: [{ id, title, content, reminder }] }
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Integrations
|
|
|
|
### 7.1 N8N
|
|
|
|
Le serveur MCP inclut 6 workflows N8N pre-construits :
|
|
|
|
| Fichier | Description |
|
|
|---|---|
|
|
| `n8n-workflow-create-note.json` | Creation de notes depuis diverses sources |
|
|
| `n8n-workflow-email-integration.json` | Création de notes depuis les emails |
|
|
| `n8n-workflow-label-management.json` | Gestion automatique des labels |
|
|
| `n8n-workflow-notebook-management.json` | Organisation automatique des notebooks |
|
|
| `n8n-workflow-reminder-notifications.json` | Notifications de rappels |
|
|
| `n8n-workflow-search-summary.json` | Recherche et resume automatique |
|
|
|
|
**Configuration dans N8N :**
|
|
|
|
```
|
|
1. Ajouter un noeud "MCP" dans N8N
|
|
2. Configurer :
|
|
- Transport : SSE / Streamable HTTP
|
|
- URL : http://VOTRE_IP:3001/mcp
|
|
- Headers : x-api-key: votre-cle (si auth activee)
|
|
3. Importer un workflow JSON depuis le dossier n8n-workflow-*
|
|
```
|
|
|
|
**Exemple de workflow - Sauvegarde automatique d'articles RSS :**
|
|
|
|
```
|
|
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
│ RSS Feed │────►│ AI Agent │────►│ Filtre │────►│ create_note │
|
|
│ (trigger) │ │ (analyse) │ │ (pertinence)│ │ (MCP tool) │
|
|
│ Toutes les │ │ Resume et │ │ Score > 7 │ │ Sauvegarde │
|
|
│ 2 heures │ │ evalue │ │ │ │ dans Memento│
|
|
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
|
|
```
|
|
|
|
### 7.2 Claude Code
|
|
|
|
```json
|
|
// .claude/mcp.json
|
|
{
|
|
"mcpServers": {
|
|
"memento": {
|
|
"command": "node",
|
|
"args": ["/chemin/absolu/vers/mcp-server/index.js"],
|
|
"env": {
|
|
"APP_BASE_URL": "http://localhost:3000",
|
|
"USER_ID": "votre-user-id-optionnel"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Apres configuration, vous pouvez dire a Claude :
|
|
|
|
```
|
|
"Cree une note avec mes idees de vacances"
|
|
"Recherche toutes les notes sur l'IA"
|
|
"Combien de notebooks ai-je ?"
|
|
"Genere des tags pour ce contenu"
|
|
"Resume le notebook Boulot"
|
|
```
|
|
|
|
### 7.3 Cursor
|
|
|
|
```json
|
|
// .cursor/mcp.json
|
|
{
|
|
"mcpServers": {
|
|
"memento": {
|
|
"command": "node",
|
|
"args": ["/chemin/absolu/vers/mcp-server/index.js"],
|
|
"env": {
|
|
"APP_BASE_URL": "http://localhost:3000"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 7.4 Script Personnalise (HTTP)
|
|
|
|
```python
|
|
import requests
|
|
|
|
MCP_URL = "http://localhost:3001/mcp"
|
|
HEADERS = {
|
|
"Content-Type": "application/json",
|
|
"Accept": "application/json, text/event-stream",
|
|
}
|
|
|
|
# 1. Initialiser
|
|
res = requests.post(MCP_URL, headers=HEADERS, json={
|
|
"jsonrpc": "2.0", "id": 1, "method": "initialize",
|
|
"params": {
|
|
"protocolVersion": "2024-11-05",
|
|
"capabilities": {},
|
|
"clientInfo": {"name": "mon-script", "version": "1.0"}
|
|
}
|
|
})
|
|
session_id = res.headers["mcp-session-id"]
|
|
HEADERS["mcp-session-id"] = session_id
|
|
|
|
# 2. Appeler un outil
|
|
res = requests.post(MCP_URL, headers=HEADERS, json={
|
|
"jsonrpc": "2.0", "id": 2, "method": "tools/call",
|
|
"params": {
|
|
"name": "create_note",
|
|
"arguments": {
|
|
"title": "Depuis Python",
|
|
"content": "Note creee automatiquement !",
|
|
"color": "green"
|
|
}
|
|
}
|
|
})
|
|
print(res.json())
|
|
```
|
|
|
|
```bash
|
|
# En bash avec curl
|
|
SESSION_ID=$(curl -s -D - -X POST http://localhost:3001/mcp \
|
|
-H "Content-Type: application/json" \
|
|
-H "Accept: application/json, text/event-stream" \
|
|
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
|
|
2>&1 | grep -i 'mcp-session-id' | awk '{print $2}' | tr -d '\r')
|
|
|
|
curl -s -X POST http://localhost:3001/mcp \
|
|
-H "Content-Type: application/json" \
|
|
-H "Accept: application/json, text/event-stream" \
|
|
-H "mcp-session-id: $SESSION_ID" \
|
|
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_notebooks","arguments":{}}}'
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Docker
|
|
|
|
### Docker Compose (recommande)
|
|
|
|
Le fichier `docker-compose.yml` a la racine du projet inclut le MCP server :
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ docker-compose.yml │
|
|
│ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │
|
|
│ │ memento-web │ │ memento-mcp │ │ ollama │ │
|
|
│ │ :3000 │ │ :3001 │ │ :11434 │ │
|
|
│ │ Next.js │ │ MCP Server │ │ (option) │ │
|
|
│ └──────┬───────┘ └──────┬───────┘ └───────────┘ │
|
|
│ │ │ │
|
|
│ └────────┬────────┘ │
|
|
│ ▼ │
|
|
│ ┌──────────────┐ │
|
|
│ │ db-data │ Volume partage SQLite │
|
|
│ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
```bash
|
|
# Lancer l'ensemble
|
|
docker compose up -d
|
|
|
|
# MCP en mode SSE (HTTP)
|
|
MCP_MODE=sse docker compose up -d mcp-server
|
|
|
|
# MCP en mode stdio (CLI)
|
|
MCP_MODE=stdio docker compose up -d mcp-server
|
|
```
|
|
|
|
### Docker seul
|
|
|
|
```bash
|
|
# Build
|
|
docker build -t memento-mcp ./mcp-server
|
|
|
|
# Run en mode HTTP
|
|
docker run -d \
|
|
-p 3001:3001 \
|
|
-e MCP_MODE=sse \
|
|
-e DATABASE_URL=file:/app/db/dev.db \
|
|
-v /chemin/vers/db:/app/db \
|
|
memento-mcp
|
|
|
|
# Run en mode stdio
|
|
docker run -i \
|
|
-e MCP_MODE=stdio \
|
|
-e DATABASE_URL=file:/app/db/dev.db \
|
|
-v /chemin/vers/db:/app/db \
|
|
memento-mcp
|
|
```
|
|
|
|
---
|
|
|
|
## 9. Securite
|
|
|
|
### Modele d'authentification
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────┐
|
|
│ MCP_REQUIRE_AUTH=false (defaut) │
|
|
│ │
|
|
│ → Aucune authentification requise │
|
|
│ → Pour developpement et reseau local uniquement │
|
|
│ → Session "dev-user" assignee automatiquement │
|
|
└──────────────────────────────────────────────────────┘
|
|
|
|
┌──────────────────────────────────────────────────────┐
|
|
│ MCP_REQUIRE_AUTH=true │
|
|
│ │
|
|
│ → Header requis : x-api-key OU x-user-id │
|
|
│ → Si MCP_API_KEY defini : valide la cle statique │
|
|
│ → Sinon : accepte n'importe quelle valeur comme ID │
|
|
│ → Sessions en memoire (perdues au redemarrage) │
|
|
└──────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Recommandations production
|
|
|
|
1. **Activez l'authentification** : `MCP_REQUIRE_AUTH=true`
|
|
2. **Definissez une cle API forte** : `MCP_API_KEY=une-cle-tres-longue-et-aleatoire`
|
|
3. **Utilisez HTTPS** via un reverse proxy (nginx, caddy)
|
|
4. **Limitez le reseau** : n'exposez pas le port publiquement
|
|
5. **Filtrez par utilisateur** : definissez `USER_ID` pour isoler les donnees
|
|
|
|
### Exemple avec reverse proxy
|
|
|
|
```
|
|
Internet ──► Nginx (HTTPS) ──► MCP Server (localhost:3001)
|
|
- SSL/TLS
|
|
- Rate limiting
|
|
- IP whitelist
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Guide de demarrage rapide
|
|
|
|
### Scenario 1 : Utilisation locale avec Claude Code
|
|
|
|
```bash
|
|
# 1. Installer les dependances
|
|
cd mcp-server && npm install
|
|
|
|
# 2. Ajouter dans .claude/mcp.json
|
|
```
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"memento": {
|
|
"command": "node",
|
|
"args": ["/chemin/vers/mcp-server/index.js"],
|
|
"env": { "APP_BASE_URL": "http://localhost:3000" }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
```bash
|
|
# 3. Lancer l'app Next.js (pour les outils AI)
|
|
cd ../keep-notes && npm run dev
|
|
|
|
# 4. Redemarrer Claude Code - les outils sont disponibles !
|
|
```
|
|
|
|
### Scenario 2 : Automatisation N8N
|
|
|
|
```bash
|
|
# 1. Lancer le serveur HTTP
|
|
MCP_REQUIRE_AUTH=true MCP_API_KEY=ma-cle node index-sse.js
|
|
|
|
# 2. Dans N8N, ajouter un noeud MCP
|
|
# URL : http://IP_SERVEUR:3001/mcp
|
|
# Headers : x-api-key: ma-cle
|
|
|
|
# 3. Importer un workflow pre-construit
|
|
```
|
|
|
|
### Scenario 3 : Docker
|
|
|
|
```bash
|
|
# 1. Lancer tout l'ecosysteme
|
|
MCP_MODE=sse docker compose up -d
|
|
|
|
# 2. Verifier
|
|
curl http://localhost:3001/
|
|
|
|
# 3. Utiliser depuis n'importe quel client MCP
|
|
```
|
|
|
|
---
|
|
|
|
## 11. Depannage
|
|
|
|
### Erreurs communes
|
|
|
|
| Erreur | Cause | Solution |
|
|
|---|---|---|
|
|
| `Cannot find package 'zod'` | Dependance manquante | `npm install zod` |
|
|
| `Unknown field 'labels' for include` | Client Prisma obsolete | `npx prisma generate --schema=../keep-notes/prisma/schema.prisma` |
|
|
| `Tool execution failed: ... Invalid prisma` | Schema DB incompatibles | Regenerer le client Prisma |
|
|
| Outils AI retournent des erreurs | App Next.js non lancee | `cd keep-notes && npm run dev` |
|
|
| `Port 3001 already in use` | Port occupe | Changer avec `PORT=3002` |
|
|
| Aucune note retournee | USER_ID incorrect ou absent | Verifier l'ID ou le retirer pour auto-detection |
|
|
|
|
### Logs
|
|
|
|
```bash
|
|
# Mode stdio - les logs vont dans stderr
|
|
node index.js 2>mcp.log
|
|
|
|
# Mode HTTP - logs dans la console
|
|
node index-sse.js
|
|
|
|
# Verifier les sessions actives
|
|
curl http://localhost:3001/sessions
|
|
```
|
|
|
|
### Regenerer le client Prisma
|
|
|
|
Si le schema de la base de donnees change dans l'app Next.js :
|
|
|
|
```bash
|
|
cd mcp-server
|
|
npx prisma generate --schema=../keep-notes/prisma/schema.prisma
|
|
```
|
|
|
|
### Test de connectivite
|
|
|
|
```bash
|
|
# Test HTTP
|
|
curl -s http://localhost:3001/ | python3 -m json.tool
|
|
|
|
# Test d'initialisation MCP
|
|
curl -s -X POST http://localhost:3001/mcp \
|
|
-H "Content-Type: application/json" \
|
|
-H "Accept: application/json, text/event-stream" \
|
|
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
|
|
|
|
# Test d'appel d'outil (apres avoir recupere le session-id)
|
|
curl -s -X POST http://localhost:3001/mcp \
|
|
-H "Content-Type: application/json" \
|
|
-H "Accept: application/json, text/event-stream" \
|
|
-H "mcp-session-id: VOTRE_SESSION_ID" \
|
|
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_notebooks","arguments":{}}}'
|
|
```
|
|
|
|
---
|
|
|
|
## Resume des 34 outils
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ NOTES (12 outils) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ create_note Creer une note │
|
|
│ get_notes Lister les notes (filtres) │
|
|
│ get_note Lire une note par ID │
|
|
│ update_note Modifier une note │
|
|
│ delete_note Supprimer une note │
|
|
│ delete_all_notes Supprimer TOUTES les donnees │
|
|
│ search_notes Rechercher par mot-cle │
|
|
│ move_note Deplacer vers un notebook │
|
|
│ toggle_pin Epingler/Destingler │
|
|
│ toggle_archive Archiver/Desarchiver │
|
|
│ export_notes Exporter en JSON │
|
|
│ import_notes Importer depuis JSON │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ NOTEBOOKS (6 outils) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ create_notebook Creer un notebook │
|
|
│ get_notebooks Lister les notebooks │
|
|
│ get_notebook Lire un notebook avec ses notes │
|
|
│ update_notebook Modifier un notebook │
|
|
│ delete_notebook Supprimer (notes → Inbox) │
|
|
│ reorder_notebooks Reordonner les notebooks │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ LABELS (4 outils) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ create_label Creer un label │
|
|
│ get_labels Lister les labels │
|
|
│ update_label Modifier un label │
|
|
│ delete_label Supprimer un label │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ AI (11 outils) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ generate_title_suggestions Suggestions de titre │
|
|
│ reformulate_text Clarifier/Reduire/Ameliorer │
|
|
│ generate_tags Generation de tags AI │
|
|
│ suggest_notebook Suggestion de notebook │
|
|
│ get_notebook_summary Resume AI d'un notebook │
|
|
│ get_memory_echo Connexions entre notes │
|
|
│ get_note_connections Notes liees a une note │
|
|
│ dismiss_connection Rejeter une connexion │
|
|
│ fuse_notes Fusionner des notes │
|
|
│ batch_organize Organisation automatique │
|
|
│ suggest_auto_labels Suggestion de labels AI │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ REMINDERS (1 outil) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ get_due_reminders Rappels en retard │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|