From 8783de9fd09ff35482946f099621ea4fbd1c028b Mon Sep 17 00:00:00 2001
From: bolbol <nabil.derouiche@gmx.com>
Date: Wed, 26 Aug 2026 20:17:11 +0000
Subject: [PATCH] docs: ajout runbook deploiement passerelle MCP
 nyora-notes-mcp avec scoping strict

---
 ...-notes-mcp-gateway-deploiement-20260826.md | 68 +++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 common/nyora-notes-mcp-gateway-deploiement-20260826.md

diff --git a/common/nyora-notes-mcp-gateway-deploiement-20260826.md b/common/nyora-notes-mcp-gateway-deploiement-20260826.md
new file mode 100644
index 0000000..d0d9bfe
--- /dev/null
+++ b/common/nyora-notes-mcp-gateway-deploiement-20260826.md
@@ -0,0 +1,68 @@
+# Déploiement Passerelle MCP NyoraNotes (Multi-Agent, Séparation Stricte par Scope)
+
+**Date** : 26 août 2026  
+**Auteur** : Gemini AntiGravity (sur brief Claude v2)  
+**Tags** : nyora-notes-mcp, mcp, streamable-http, scoping, dsh, tailscale, runbook  
+**Statut** : Validé et testé en direct de bout en bout sur NAS DS920+ et VPS Contabo  
+
+---
+
+## 1. Contexte & Problématique
+
+NyoraNotes est une application FastAPI purement REST, sans endpoint MCP natif (`/mcp` renvoyait 404). Les tentatives directes de connexion MCP depuis DSH étaient vouées à l'échec.
+De plus, la séparation d'accès entre agents nécessitait un contrôle strict par sous-dossier de vault (`vault/dsh/`), sans altérer le fonctionnement des 5 instances Hermes en production.
+
+---
+
+## 2. Architecture & Topologie
+
+- **Service** : `nyora-notes-mcp` (conteneur Python 3.11 / FastAPI / Starlette / MCP SDK 1.29.1).
+- **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.
+- **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
+
+| 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_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
+
+| 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é |
+| 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é |
+
+---
+
+## 5. 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`.
+2. Ajouter une entrée dans `AGENT_SCOPES` :
+   ```python
+   "mcp-nouvel-agent-secret-key": AgentScope(
+       agent_id="nouvel-agent",
+       allowed_prefixes=["nouvel-agent/"],
+       description="Nouvel agent scopé à son dossier"
+   )
+   ```
+3. Redémarrer le conteneur : `cd /volume1/docker/nyora-notes-mcp && docker compose restart nyora-notes-mcp`.