docs: update all MCP documentation for 22 tools + API key auth

- Rewrite mcp-server/README.md: clean structure, auth section, 22 tools - Rewrite N8N-CONFIG.md: remove hardcoded IPs, add x-api-key auth flow - Rewrite N8N-WORKFLOWS.md: simplified, removed AI proxy tool references - Update README.md/README.fr.md: 37→22 tools, add auth mention - Update GUIDE.md/GUIDE.en.md: remove AI/API key tool tables, add auth - Update DEPLOY.md: SSE → Streamable HTTP in architecture diagram Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-26 16:25:00 +02:00
parent 49e076a4bb
commit bbaae76103
8 changed files with 270 additions and 945 deletions
--- 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