# Guide Utilisateur : MCP dans Keep Notes

## Table des matières

1. [Qu'est-ce que MCP ? (en termes simples)](#1-quest-ce-que-mcp--en-termes-simples)
2. [Comment ça marche dans Keep Notes](#2-comment-ca-marche-dans-keep-notes)
3. [Les clés API : à quoi ça sert](#3-les-cles-api--a-quoi-ca-sert)
4. [Gérer ses clés API depuis l'interface](#4-gerer-ses-cles-api-depuis-linterface)
5. [Configurer Claude Code](#5-configurer-claude-code)
6. [Configurer Cursor](#6-configurer-cursor)
7. [Configurer N8N](#7-configurer-n8n)
8. [Questions fréquentes](#8-questions-frequentes)

---

## 1. Qu'est-ce que MCP ? (en termes simples)

**MCP** = **Model Context Protocol** (Protocole de Contexte de Modèle).

C'est un standard qui permet à des outils IA (comme Claude, Cursor, N8N) de **parler** à votre application Keep Notes.

### Analogie simple

Imaginez que Keep Notes est un restaurant. Normalement, pour lire le menu ou commander, vous devez ouvrir l'application web dans votre navigateur.

MCP, c'est comme un **service de livraison** : il permet à d'autres applications de passer des commandes directement au restaurant, sans ouvrir le site web. Votre clé API, c'est votre **numéro de client** qui prouve que vous avez le droit de commander.

### Concrètement, que permet MCP ?

Avec MCP, vous pouvez depuis Claude Code, Cursor ou N8N :

- **Lire** vos notes existantes
- **Créer** de nouvelles notes
- **Rechercher** dans vos notes (recherche sémantique IA)
- **Organiser** vos notes dans des carnets
- **Gérer** vos étiquettes
- **Générer des titres** avec l'IA
- Et 30+ autres actions

### Les deux modes de connexion

Votre serveur MCP Keep Notes peut fonctionner de deux façons :

| Mode | Comment ça marche | Pour qui | Clé API nécessaire ? |
|------|-------------------|----------|----------------------|
| **Stdio** | L'outil IA lance directement le serveur MCP en arrière-plan | Claude Code, Cursor (local) | Non |
| **HTTP** | Le serveur MCP tourne en continu sur le port 3001, les outils s'y connectent via le réseau | N8N, Cursor (distant), tout outil réseau | Oui |

---

## 2. Comment ça marche dans Keep Notes

Votre projet Keep Notes contient **deux serveurs** qui partagent la même base de données :

```
Keep/
├── keep-notes/          ← Application web (port 3000)
│   └── prisma/dev.db    ← Base de données SQLite
│
└── mcp-server/          ← Serveur MCP (port 3001 en mode HTTP)
    ├── index.js         ← Mode Stdio
    ├── index-sse.js     ← Mode HTTP
    └── tools.js         ← Les 37 outils disponibles
```

**Important** : Les deux serveurs accèdent à la **même base de données**. Quand vous créez une note via MCP, elle apparaît immédiatement dans l'interface web, et inversement.

---

## 3. Les clés API : à quoi ça sert

Une **clé API** est un mot de passe secret qui permet à un outil externe de prouver son identité au serveur MCP.

### Quand vous avez besoin d'une clé API

- **Mode HTTP** (N8N, Cursor distant, etc.) : **OUI**, vous devez fournir votre clé API à chaque requête.
- **Mode Stdio** (Claude Code, Cursor local) : **NON**, l'outil accède directement à la base de données.

### Format d'une clé

Les clés générées par Keep Notes ressemblent à ça :

```
mcp_sk_0f0fe746d34dabdf7370d06352a2fd5fabf5994d2a980a31
```

- Préfixe `mcp_sk_` (pour "MCP Secret Key")
- Suivi de 48 caractères hexadécimaux

### Securité

- La clé brute n'est affichée **qu'une seule fois** au moment de sa création
- En base de données, seul le **hash SHA-256** est stocké (comme un mot de passe)
- Personne (même pas vous) ne peut retrouver la clé brute après fermeture de la fenêtre
- Si vous perdez une clé, il faut la révoquer et en générer une nouvelle

---

## 4. Gérer ses clés API depuis l'interface

### Accéder à la page MCP

1. Ouvrez Keep Notes dans votre navigateur (`http://localhost:3000`)
2. Cliquez sur **Paramètres** (icône engrenage)
3. Dans le menu latéral, cliquez sur **MCP Settings** (icône clé)

### Générer une nouvelle clé

1. Cliquez sur le bouton **"Générer une nouvelle clé"**
2. Donnez un nom à votre clé (ex: "Mon Claude Code", "N8N Prod")
3. Cliquez sur **"Générer"**
4. **Copiez immédiatement la clé** — elle ne sera plus jamais visible
5. Cliquez sur **"Terminé"**

### Gérer vos clés existantes

Pour chaque clé, vous verrez :

- Le **nom** que vous lui avez donné
- La **date de création**
- La **date de dernière utilisation**
- Le **statut** : Active (verte) ou Révoquée (grise)

#### Révoquer une clé

La révocation **désactive** la clé sans la supprimer. L'outil qui l'utilisait perdra son accès.

> Utile si vous pensez qu'une clé a été compromise mais voulez garder un historique.

#### Supprimer une clé

La suppression est **définitive**. La clé et son historique disparaissent.

---

## 5. Configurer Claude Code

Claude Code est l'outil en ligne de commande de Claude (celui que vous utilisez actuellement).

### Méthode recommandée : Mode Stdio (sans clé API)

Avec le mode stdio, Claude Code lance le serveur MCP directement. Pas besoin de clé API car il accède à la base SQLite directement.

#### Étape 1 : Ouvrir la configuration MCP

Dans votre terminal Claude Code, tapez :

```
/mcp
```

#### Étape 2 : Ajouter le serveur

Choisissez d'ajouter un nouveau serveur et collez cette configuration :

```json
{
  "mcpServers": {
    "keep-notes": {
      "command": "node",
      "args": ["/Users/sepehr/dev/Keep/mcp-server/index.js"],
      "env": {
        "DATABASE_URL": "file:/Users/sepehr/dev/Keep/keep-notes/prisma/dev.db",
        "APP_BASE_URL": "http://localhost:3000"
      }
    }
  }
}
```

#### Explication de chaque champ

| Champ | Valeur | À quoi ça sert |
|-------|--------|----------------|
| `command` | `"node"` | Lance Node.js |
| `args` | `["/chemin/vers/mcp-server/index.js"]` | Chemin vers le serveur MCP (mode stdio) |
| `env.DATABASE_URL` | `"file:/chemin/vers/prisma/dev.db"` | Où trouver la base de données |
| `env.APP_BASE_URL` | `"http://localhost:3000"` | URL de l'app web (pour les fonctions IA) |

#### Étape 3 : Vérifier

Redémarrez Claude Code. Tapez un message demandant d'utiliser un outil Keep Notes, par exemple :

> "Liste mes notes Keep Notes"

Claude Code devrait automatiquement détecter les outils MCP disponibles.

### Méthode alternative : fichier de configuration

Vous pouvez aussi éditer directement le fichier de config :

```bash
# Configuration globale (tous les projets)
nano ~/.claude.json

# OU configuration par projet
nano /Users/sepehr/dev/Keep/.claude/settings.local.json
```

Ajoutez le bloc `mcpServers` dans le fichier JSON.

---

## 6. Configurer Cursor

Cursor est un éditeur de code avec IA intégrée qui supporte MCP.

### Mode local (Stdio — sans clé API)

Ouvrez les paramètres MCP dans Cursor (`Settings` > `MCP`) et ajoutez :

```json
{
  "mcpServers": {
    "keep-notes": {
      "command": "node",
      "args": ["/Users/sepehr/dev/Keep/mcp-server/index.js"],
      "env": {
        "DATABASE_URL": "file:/Users/sepehr/dev/Keep/keep-notes/prisma/dev.db",
        "APP_BASE_URL": "http://localhost:3000"
      }
    }
  }
}
```

C'est **exactement la même config** que Claude Code en mode stdio.

### Mode distant (HTTP — avec clé API)

Si le serveur MCP tourne sur une autre machine ou si vous préférez le mode HTTP :

#### 1. Démarrez le serveur MCP en mode HTTP

```bash
cd /Users/sepehr/dev/Keep/mcp-server
node index-sse.js
```

Le serveur démarre sur `http://localhost:3001`.

#### 2. Configurez Cursor

```json
{
  "mcpServers": {
    "keep-notes": {
      "url": "http://localhost:3001/mcp",
      "headers": {
        "x-api-key": "mcp_sk_VOTRE_CLE_API_ICI"
      }
    }
  }
}
```

Remplacez `mcp_sk_VOTRE_CLE_API_ICI` par votre vraie clé (générée depuis `/settings/mcp`).

---

## 7. Configurer N8N

N8N est un outil d'automatisation qui peut utiliser MCP pour interagir avec vos notes.

### Prérequis

1. Le serveur MCP doit tourner en mode HTTP :

```bash
cd /Users/sepehr/dev/Keep/mcp-server
node index-sse.js
```

2. Vous devez avoir généré une clé API depuis `/settings/mcp`

### Configuration dans N8N

#### Étape 1 : Ajouter un nœud MCP Client

Dans votre workflow N8N, ajoutez un nœud **"MCP Client"**.

#### Étape 2 : Configurer la connexion

| Paramètre | Valeur |
|-----------|--------|
| **Transport** | HTTP Streamable |
| **URL** | `http://VOTRE_IP:3001/mcp` |
| **Authentication** | API Key |
| **Header** | `x-api-key` |
| **Valeur** | `mcp_sk_VOTRE_CLE_API_ICI` |

#### Trouver votre IP locale

```bash
# macOS
ifconfig | grep "inet " | grep -v 127.0.0.1

# Résultat typique : 192.168.1.XX
```

Utilisez cette IP (pas `localhost`) si N8N tourne sur une autre machine.

#### Étape 3 : Utiliser un outil

Après connexion, N8N charge la liste des 37 outils disponibles. Choisissez celui que vous voulez utiliser, par exemple :

- `create_note` — Créer une note
- `search_notes` — Rechercher des notes
- `get_notes` — Lister les notes

### Exemple de workflow

**Workflow "Sauvegarder un article web en note"** :

```
Webhook (reçoit un article)
    → MCP Client : create_note
        title = article.title
        content = article.body
        labels = ["article", "web"]
```

---

## 8. Questions fréquentes

### J'ai perdu ma clé API, que faire ?

Les clés ne sont jamais stockées en clair. Si vous avez perdu une clé :
1. Allez dans `/settings/mcp`
2. **Révoquez** l'ancienne clé
3. **Générez** une nouvelle clé
4. **Copiez-la** immédiatement
5. Mettez à jour la config de votre outil (Claude Code, Cursor, N8N)

### Peut-on utiliser MCP sans clé API ?

**Oui**, en mode stdio. C'est le cas pour Claude Code et Cursor configurés en local. La clé API n'est nécessaire que pour le mode HTTP distant.

### Le serveur MCP doit-il tourner en permanence ?

- **Mode Stdio** : Non. L'outil (Claude Code/Cursor) lance le serveur automatiquement quand il en a besoin.
- **Mode HTTP** : Oui. Le serveur doit tourner en continu (`node index-sse.js`) pour que N8N et les autres outils puissent s'y connecter.

### Mes notes sont-elles en sécurité ?

- Les clés API sont hashées (SHA-256) en base de données, comme des mots de passe
- Le serveur MCP accède à la même base que l'app web — les permissions utilisateur sont respectées
- En mode HTTP, le trafic peut être sécurisé avec HTTPS (configuration du reverse proxy)

### Combien de clés API puis-je créer ?

Pas de limite. Il est recommandé de créer une clé par outil (une pour Claude Code, une pour N8N, etc.) pour pouvoir les révoquer indépendamment.

### Quels sont les 37 outils disponibles ?

| Catégorie | Outils |
|-----------|--------|
| **Notes** | `create_note`, `get_note`, `get_notes`, `update_note`, `delete_note`, `search_notes`, `toggle_pin`, `toggle_archive`, `export_notes`, `import_notes`, `restore_note` |
| **Carnets** | `create_notebook`, `get_notebooks`, `get_notebook`, `update_notebook`, `delete_notebook`, `reorder_notebooks` |
| **Etiquettes** | `create_label`, `get_labels`, `update_label`, `delete_label` |
| **IA** | `generate_title_suggestions`, `reformulate_text`, `generate_tags`, `fuse_notes`, `batch_organize`, `generate_notebook_summary`, etc. |
| **Rappels** | `get_due_reminders` |
| **Clés API** | `generate_api_key`, `list_api_keys`, `revoke_api_key` |