From 66db7f678b43268b3690965b39a90dcb2a1a62cf Mon Sep 17 00:00:00 2001 From: bolbol Date: Wed, 26 Aug 2026 20:25:16 +0000 Subject: [PATCH] docs: mise a jour runbook nyora-notes-mcp avec fix de routage tag automatique --- ...-notes-mcp-gateway-deploiement-20260826.md | 24 +++++++++++++------ 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/common/nyora-notes-mcp-gateway-deploiement-20260826.md b/common/nyora-notes-mcp-gateway-deploiement-20260826.md index d0d9bfe..ae6d577 100644 --- a/common/nyora-notes-mcp-gateway-deploiement-20260826.md +++ b/common/nyora-notes-mcp-gateway-deploiement-20260826.md @@ -20,40 +20,50 @@ De plus, la séparation d'accès entre agents nécessitait un contrôle strict p - **Emplacement** : `/volume1/docker/nyora-notes-mcp` sur le NAS DS920+. - **Port** : `3098` (mappé `0.0.0.0:3098 -> 8000/tcp`). - **Réseau** : `n8n` (communique directement avec `http://nyora-notes:8787` par nom de conteneur). -- **Transport MCP** : `streamable-http` (point de montage `/mcp/`), compatible avec `dsh-mcp-client` et la spec MCP 2025-03-26. +- **Transport MCP** : `streamable-http` sur `/mcp/` (compatible spec MCP 2025-03-26 et `dsh-mcp-client`). - **Backend Auth** : La passerelle utilise un credential backend unique (`NYORA_BACKEND_TOKEN`) pour relayer les requêtes vers NyoraNotes. - **Scoping par agent** : La couche applicative de la passerelle valide chaque requête MCP selon le token de l'agent appelant : - `mcp-dsh-89f4b32a10e74c5d98bc7211e405a8f2` → `agent_id: dsh`, préfixe autorisé : `dsh/`. --- -## 3. Outils MCP Exposés +## 3. Logique de Routage & Contrôle d'Accès + +### Double niveau de protection : +1. **Contrôle d'accès par `file_path` (Gatekeeper Passerelle)** : + Si le client fournit un argument `file_path`, la passerelle vérifie qu'il débute strictement par l'un des `allowed_prefixes` de l'agent (ex: `dsh/`). Tout chemin interdit (`hermes-tt/...`, `infra/...`) ou tentative de traversée (`../...`) est immédiatement rejeté avec `403 Forbidden` sans être transmis au backend. +2. **Routage de stockage par injection automatique de tag (Backend NyoraNotes)** : + L'API REST NyoraNotes place les fichiers dans le dossier correspondant au premier tag de la note (`tags[0]`), ou dans `inbox/` si aucun tag n'est fourni. Pour garantir que chaque note créée atterrisse physiquement dans le dossier de vault alloué, le handler `notes_create` de la passerelle injecte systématiquement le tag de scope (`dsh`) en tête de liste (`tags`), que le client ait fourni des tags ou non. + +--- + +## 4. Outils MCP Exposés | Outil | Description | Contrôle de Sécurité / Scoping | |-------|-------------|--------------------------------| -| `notes_create` | Crée une note Markdown | Chemin forcé ou validé sous `dsh/` ; tag `dsh` injecté en tête | +| `notes_create` | Crée une note Markdown | Contrôle de `file_path` + injection automatique du tag de scope en tête | | `notes_get` | Récupère une note par son UUID | Vérifie que le `file_path` appartient au scope de l'agent (sinon 403) | | `notes_list` | Liste les notes paginées | Filtre les résultats pour ne retourner que les notes du scope de l'agent | | `notes_search` | Recherche FTS plein texte | Filtre les résultats pour exclure tout document hors scope de l'agent | --- -## 4. Matrice de Validation & Preuves Brutes +## 5. Matrice de Validation & Preuves Brutes | Test | Commande / Méthode | Résultat constaté | Statut | |------|--------------------|-------------------|--------| | Healthcheck | `GET http://192.168.100.33:3098/health` | `HTTP 200 OK`, service `nyora-notes-mcp` | ✅ Validé | | MCP Initialize | `POST /mcp/` avec token DSH | `HTTP 200 OK`, `serverInfo: nyora-notes-mcp` | ✅ Validé | -| Test Scoping (Écriture autorisée) | `notes_create` sur `dsh/...` | `HTTP 201 Created`, note écrite dans `vault/dsh/` | ✅ Validé | +| Création SANS TAG (Injection auto) | `notes_create` sans tags | `HTTP 201 Created`, note placée dans `dsh/test-fix-injection-tag-dsh-automatique.md` | ✅ Validé | | Test Scoping (Violation hermes-tt) | `notes_create` sur `hermes-tt/...` | `403 Forbidden` ("hors du scope autorise") | ✅ Validé | | Test Scoping (Path traversal) | `notes_create` sur `../hermes-tt/...` | `403 Forbidden` ("hors du scope autorise") | ✅ Validé | | Auth Invalide | `POST /mcp/` avec token erroné | `HTTP 401 Unauthorized` | ✅ Validé | | Exécution Native DSH | `dsh --profile headless` (sans curl) | Appel natif `notes_create` + `notes_list` + `notes_get` | ✅ Validé | -| Preuve Physique NAS | `cat /volume1/docker/nyora-notes/vault/dsh/validation-finale-mcp-dsh.md` | Fichier présent sur disque NAS (257 octets) | ✅ Validé | +| Preuve Physique NAS (disque direct) | `cat /volume1/docker/nyora-notes/vault/dsh/test-fix-injection-tag-dsh-automatique.md` | Présent sur disque NAS Synology (282 octets) | ✅ Validé | --- -## 5. Procédure pour Ajouter un Nouvel Agent +## 6. Procédure pour Ajouter un Nouvel Agent Pour ajouter un futur agent MCP sans toucher à NyoraNotes : 1. Ouvrir `/volume1/docker/nyora-notes-mcp/app/config.py`.