From cbcd8f53b689d2a6fc38df974aa6877113232c93 Mon Sep 17 00:00:00 2001 From: hermes-nyora Date: Wed, 26 Aug 2026 20:52:31 +0100 Subject: [PATCH] deploy: brief passerelle MCP dediee NyoraNotes - separation multi-agent stricte --- ...gemini-nyora-notes-mcp-gateway-20260826.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 common/brief-gemini-nyora-notes-mcp-gateway-20260826.md diff --git a/common/brief-gemini-nyora-notes-mcp-gateway-20260826.md b/common/brief-gemini-nyora-notes-mcp-gateway-20260826.md new file mode 100644 index 0000000..02abfe4 --- /dev/null +++ b/common/brief-gemini-nyora-notes-mcp-gateway-20260826.md @@ -0,0 +1,45 @@ +# Brief — Passerelle MCP dédiée pour NyoraNotes (multi-agent, séparation stricte) + +**Date** : 26 août 2026 +**Auteur** : Claude (cerveau stratégique) +**Exécutant** : Gemini AntiGravity +**Décision de Nabil** : chantier dédié, résout définitivement le problème MCP rencontré sur DSH (3 tentatives échouées côté DSH, cause racine côté NyoraNotes). + +--- + +## 1. Diagnostic (établi, pas à revérifier) + +NyoraNotes est une API REST pure (FastAPI), sans endpoint MCP/SSE (`/mcp` renvoie 404, confirmé). Les 5 instances Hermes s'y connectent en REST directement. DSH (et tout futur agent basé sur un client MCP standard) ne peut pas s'y connecter en l'état — patcher chaque agent individuellement ne résout rien, le trou est côté NyoraNotes. + +Séparation actuelle insuffisante : le token `hermes-perso` utilisé jusqu'ici pour DSH est décrit comme propriétaire du coffre racine `/vault` entier, sans scoping par dossier appliqué côté serveur. À corriger dans ce chantier. + +## 2. Architecture cible + +**Nouveau service séparé** (ne pas modifier le code de NyoraNotes lui-même — il sert 5 instances en production, zéro régression tolérée dessus) : une passerelle MCP légère, colocalisée sur le NAS à côté de NyoraNotes, qui : + +1. Expose un serveur MCP (transport `streamable-http`, pour rester compatible avec `dsh-mcp-client` et les clients MCP standards) avec au minimum les outils : `notes.create`, `notes.search`, `notes.list`, `notes.get`. +2. Traduit chaque appel d'outil MCP en appel REST vers l'API NyoraNotes existante (`http://127.0.0.1:8787` en local sur le NAS). +3. Gère l'authentification et le scoping **elle-même**, indépendamment de la logique actuelle de NyoraNotes : chaque token MCP est associé à un agent et un préfixe de dossier unique dans le vault (ex. token DSH → `vault/dsh/` uniquement). Toute tentative de lecture/écriture hors du préfixe autorisé est refusée (403), sur le modèle déjà en place et validé sur context-hub (5 scopes, séparation stricte, éprouvé en production). +4. Ne remplace pas les intégrations REST existantes des 5 Hermes — elles continuent telles quelles, aucune migration forcée. + +## 3. Actions + +1. Choisir une librairie MCP serveur adaptée (Python, écosystème déjà en place sur le NAS) pour implémenter le transport `streamable-http` proprement — vérifier les options disponibles et choisir la plus stable/maintenue au moment de l'implémentation plutôt que de figer un choix ici. +2. Implémenter les 4 outils, avec le mapping token → agent → préfixe vault en dur ou dans une petite table de config (pas besoin d'une DB dédiée pour démarrer). +3. Générer un token MCP neuf et proprement scopé pour DSH (`vault/dsh/` uniquement) — ne pas réutiliser le token `hermes-perso`. +4. Déployer le service (nouveau container, nouveau port à choisir et documenter dans `ports-registry.md`), joignable depuis le VPS via le même chemin Tailscale déjà prouvé fonctionnel pour Bifrost/NyoraNotes/context-hub. +5. Reconfigurer `cordis.patch.yml` sur `dsh-vps` : pointer l'entrée `nyora-notes` vers cette nouvelle passerelle (et son nouveau token), au lieu de l'URL REST actuelle qui ne fonctionne pas en MCP. +6. Redémarrer DSH, vérifier au démarrage que la connexion MCP réussit réellement cette fois (pas seulement l'absence d'erreur grâce à `failOnStartupError: false` — chercher une confirmation positive de connexion dans les logs). +7. Test de bout en bout : demander à DSH, via une interaction normale (pas une invocation headless bricolée), de lire puis d'écrire une note dans sa propre mémoire, sans instruction explicite de curl — l'outil MCP doit être utilisé nativement. +8. Test de la séparation : tenter depuis le token DSH d'accéder à un chemin hors `vault/dsh/` (ex. `vault/hermes-tt/`), confirmer un refus explicite. + +## 4. Vérification + +Comme pour tous les chantiers précédents : chaque affirmation du rapport final doit être étayée par une commande réellement exécutée au moment du rapport, avec sa sortie brute. Vérification de l'existence de fichiers ou de l'état du vault **via le disque NAS en direct** (`/volume1/docker/nyora-notes/vault/...` ou équivalent monté), pas via un miroir ou une copie qui pourrait avoir du retard. + +## 5. Capitalisation + +- Runbook `bolbol/nas-runbooks/common/` dédié à cette passerelle (nom de service, port, table de scoping, procédure pour ajouter un futur agent). +- `ports-registry.md` : nouvelle entrée. +- Note NyoraNotes `[infra, runbook]`. +- Une fois validé et stable : c'est ce runbook qui devient la référence pour brancher un futur harnais sur NyoraNotes — pas avant.