# 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                      │
└─────────────────────────────────────────────────────────────┘
```