@imenam/mcp-github 1.1.54 → 1.1.56

package/README.md

@@ -1,191 +1,280 @@
-# Restricted GitHub MCP Server
-
-Un serveur MCP (Model Context Protocol) spécialisé pour automatiser le workflow Git local vers GitHub, avec délégation des compilations/tests soit à un serveur distant via SSH, soit directement en local sur la même machine. Conçu pour être minimaliste et sécurisé.
-
-## 🚀 Outils disponibles
-
-### Git local → GitHub
-
-- **`commit`** : Exécute `git add .` puis crée un commit avec le message fourni. *Ne pousse pas vers le remote.*
-- **`push`** : Pousse la branche actuelle vers `TARGET_BRANCH`. *Ne fait pas de commit.*
-- **`commit_and_push`** : Enchaîne `git add .`, commit et push vers `TARGET_BRANCH`.
-- **`pull_request`** : Crée une Pull Request GitHub de `TARGET_BRANCH` vers `BASE_BRANCH`.
-- **`clone`** : Clone `TARGET_REPO` dans `CLONE_DIR/<TARGET_BRANCH>/`. Crée la branche distante si elle n'existe pas encore.
-- **`get_info`** : Affiche la configuration active (dépôt, branches, chemins) sans exposer les secrets.
-- **`get_logs`** : Récupère les dernières lignes du fichier de log serveur. Argument optionnel : `lines` (défaut : 50).
-
-### Déploiement & test (serveur distant ou local)
-
-Selon la configuration active, ces outils s'exécutent soit sur un serveur distant via SSH, soit directement en local sur la machine du serveur MCP (interrupteur `LOCAL_DEPLOY`).
-
-- **`deploy`** : Exécute `git fetch --all`, `git checkout TARGET_BRANCH`, `git pull` dans `SSH_REMOTE_PATH`. Le repo doit être préalablement cloné à cet emplacement (sur le serveur distant, ou en local).
-- **`test`** : Exécute `TEST_COMMAND` (cwd = `SSH_REMOTE_PATH`) et renvoie stdout, stderr et exit code. Stocke la sortie pour `test_logs`.
-- **`test_logs`** : Renvoie la sortie du dernier `test` exécuté sans relancer la commande.
-
-> **Mode local (`LOCAL_DEPLOY`)** : quand il est activé, aucune connexion SSH n'est ouverte — la commande est lancée directement dans le shell de la machine, dans le dossier `SSH_REMOTE_PATH` (interprété comme un chemin local). Pratique lorsque le serveur MCP tourne sur le serveur de déploiement lui-même.
-
-### Flux typique agent
-
-```
-clone → (modifier des fichiers) → commit_and_push → deploy → test
-                                        ↑                       |
-                                        └─── (corriger) ────────┘ (si exit code ≠ 0)
-```
-
-## 🖥️ Interface de Configuration (GUI)
-
-Le serveur lance automatiquement une interface graphique au démarrage (si `PROXY_URL` est défini). Elle permet de :
-
-- Gérer plusieurs configurations nommées (multi-projets).
-- Sélectionner le dépôt et les branches via des menus déroulants GitHub.
-- Configurer le déploiement **par projet** : serveur SSH (hôte, utilisateur, port, clé privée) et commande de test, ou bascule en **déploiement local** sans SSH.
-- Visualiser la configuration active en temps réel.
-
-Le formulaire est organisé en sections repliables : **Dépôt & branches** (toujours dépliée, cœur de l'usage), **Options** et **Déploiement & test** (repliées par défaut, le paramétrage serveur n'étant fait qu'une fois). Activer l'interrupteur **Déployer en local** masque automatiquement les champs de connexion SSH devenus inutiles.
-
-> **Proxy dynamique** : La GUI s'enregistre auprès du reverse proxy défini dans `PROXY_URL` et reçoit un port dynamique. Elle est alors accessible sous le chemin effectivement enregistré — `GUI_PATH` seul par défaut, éventuellement préfixé par `APP_PATH_PREFIX` (voir *Variables GUI / Proxy*). L'enregistrement passe par le client partagé [`@imenam/mcp-gui-interface`](https://www.npmjs.com/package/@imenam/mcp-gui-interface), commun à tous les MCP à interface ; le timeout d'enregistrement est de **1 s** (il était de 5 s avec l'ancien client interne).
-
-## ⚙️ Configuration
-
-Les variables **globales** (token, dossiers, proxy) sont définies dans un fichier `.env` ou dans la section `env` du client MCP. Les **paramètres par projet** (dépôt, branches, déploiement SSH ou local…) sont gérés dans l'interface GUI et stockés dans `configs.json`.
-
-### Variables GitHub
-
-| Variable | Description | Exemple |
-| :--- | :--- | :--- |
-| `GITHUB_TOKEN` | Personal Access Token GitHub (PAT) | `github_pat_...` |
-| `MCP_DATA_DIR` | Dossier contenant `configs.json` (multi-configs) | `./data` |
-| `CLONE_DIR` | Dossier racine dans lequel les branches seront clonées | `./cloned_repos` |
-
-> Les configurations par projet (dépôt, branches, mode lecture seule…) sont gérées dans l'interface GUI et stockées dans `configs.json`.
-
-### Paramètres de déploiement (outils `deploy` / `test`)
-
-Ces paramètres sont définis **par projet** dans l'interface GUI et stockés dans `configs.json` (et non dans le `.env` global). Chaque configuration peut donc viser un serveur — et une clé — différents, ou basculer en mode local.
-
-| Paramètre | Description | Exemple |
-| :--- | :--- | :--- |
-| `LOCAL_DEPLOY` | Si activé, exécution locale sans SSH (la machine du serveur MCP) | `false` |
-| `SSH_HOST` | Adresse IP ou hostname du serveur distant | `mon-serveur.example.com` |
-| `SSH_USER` | Utilisateur SSH | `deploy` |
-| `SSH_PORT` | Port SSH (défaut : 22) | `22` |
-| `SSH_KEY_PATH` | Chemin absolu vers la clé privée SSH | `C:/Users/.../.ssh/id_ed25519` |
-| `SSH_REMOTE_PATH` | Chemin du repo (distant en mode SSH, **local** si `LOCAL_DEPLOY`) | `/var/www/mon-projet` |
-| `TEST_COMMAND` | Commande de test à exécuter | `npx tsc --noEmit --pretty` |
-
-> En mode local, seuls `SSH_REMOTE_PATH` (qui doit exister sur le disque) et `TEST_COMMAND` sont utilisés ; les champs de connexion SSH sont ignorés.
-
-> **Note** : Pour `tsc`, utilisez `--pretty` pour obtenir la sortie complète avec contexte de code (sans cette option, `tsc` passe en format compact une ligne par erreur quand il n'y a pas de TTY).
-
-> **Migration** : ces clés peuvent aussi être fournies via le `.env` ou la section `env` du client MCP. Elles ne sont alors lues **qu'une seule fois** au premier démarrage (si `configs.json` n'existe pas encore) pour amorcer la configuration par défaut ; ensuite, c'est la GUI qui fait foi.
-
-### Variables GUI / Proxy
-
-| Variable | Description | Exemple |
-| :--- | :--- | :--- |
-| `PROXY_URL` | URL du reverse proxy central | `http://localhost:3000` |
-| `APP_PATH` | Chemin d'accès via le proxy. Nom canonique, commun à tous les MCP. | `/github-mcp` |
-| `APP_NAME` | Nom affiché dans le proxy. Nom canonique. | `GitHub MCP Config` |
-| `GUI_PATH` | Ancien nom de `APP_PATH`, toujours accepté (utilisé si `APP_PATH` et `PROXY_APP_PATH` sont absents) | `/github-mcp` (défaut) |
-| `GUI_NAME` | Ancien nom de `APP_NAME`, toujours accepté (même ordre de priorité) | `GitHub MCP Config` (défaut) |
-| `APP_PATH_PREFIX` | Préfixe de namespace ajouté au chemin **par défaut** uniquement | `/abc123` → `/abc123/github-mcp` |
-| `AGENT_NAME` | Nom de l'agent affiché dans la GUI | `Agent Zero` |
-| `APP_GROUP` | Section repliable (repliée par défaut) du dashboard proxy dans laquelle placer l'app. Les apps partageant la même valeur sont regroupées ; si non défini, l'app apparaît dans la section « non groupées ». | `Développement` |
-
-`APP_PATH` / `APP_NAME` sont les noms canoniques de l'écosystème ; `PROXY_APP_*` puis `GUI_*` restent acceptés, dans cet ordre de priorité décroissante. `APP_PATH_PREFIX` **ne préfixe que le chemin par défaut** : si `APP_PATH` (ou `GUI_PATH`) est renseigné, sa valeur est prise telle quelle, sans préfixe — la saisie manuelle l'emporte. Les chemins sont normalisés (un seul `/` de séparation, pas de `/` final).
-
-### L'environnement du process l'emporte sur le `.env`
-
-Une variable déjà présente dans l'environnement du process qui lance ce MCP
-(`export` dans un shell, bloc `env` d'une configuration MCP, ou superviseur comme
-`@imenam/mcp-gateway-manager`) **l'emporte sur la même clé du `.env` de ce
-dépôt**. C'est le comportement par défaut de dotenv, et la convention Unix
-habituelle : l'appelant gagne.
-
-Le `.env` reste rechargé à chaud — la GUI de configuration l'édite et la valeur
-est reprise sans redémarrer le serveur — mais ce rechargement ne peut plus
-écraser ce que l'appelant a injecté. Concrètement, une ligne
-`APP_GROUP=Développement` dans ce `.env` ne remplace plus un `APP_GROUP` fourni
-par un superviseur : elle ne s'applique que si personne n'en a fourni.
-
-Pour changer une variable que l'appelant fournit, changez-la chez l'appelant :
-l'éditer depuis la GUI n'aura aucun effet sur cette clé.
-
-## 📝 Journalisation (Logs)
-
-- **Windows** : `C:\var\log\restricted-github-mcp\server.log`
-- **Linux/macOS** : `/var/log/restricted-github-mcp/server.log`
-
-Le dossier est créé automatiquement. Les logs du processus principal (`[MASTER]`) et de la GUI (`[GUI]`) sont centralisés dans le même fichier.
-
-## 🖥️ Exemple de Configuration MCP
-
-### Via npx (Recommandé)
-
-```json
-{
-  "mcpServers": {
-    "@imenam/mcp-github": {
-      "command": "npx",
-      "args": ["-y", "@imenam/mcp-github"],
-      "env": {
-        "GITHUB_TOKEN": "votre_token_github_ici",
-        "CLONE_DIR": "/chemin/vers/dossier-de-clonage",
-        "MCP_DATA_DIR": "./data",
-        "PROXY_URL": "http://localhost:3000",
-        "GUI_PATH": "/github-mcp",
-        "GUI_NAME": "GitHub MCP Config",
-        "AGENT_NAME": "Mon Agent",
-        "SSH_HOST": "mon-serveur.example.com",
-        "SSH_USER": "ubuntu",
-        "SSH_PORT": "22",
-        "SSH_KEY_PATH": "/chemin/vers/.ssh/id_ed25519",
-        "SSH_REMOTE_PATH": "/var/www/mon-projet",
-        "TEST_COMMAND": "npx tsc --noEmit --pretty"
-      }
-    }
-  }
-}
-```
-
-> Les variables `PROXY_URL`, `GUI_*` et `AGENT_NAME` sont optionnelles selon votre usage. Les variables SSH (`SSH_HOST`, `SSH_USER`, `SSH_PORT`, `SSH_KEY_PATH`, `SSH_REMOTE_PATH`, `TEST_COMMAND`) ainsi que `LOCAL_DEPLOY` sont désormais gérées **par projet via la GUI** ; les inclure ici ne sert qu'à amorcer la configuration par défaut au premier démarrage (voir la note Migration ci-dessus).
-
-### Via installation locale
-
-```json
-{
-  "mcpServers": {
-    "@imenam/mcp-github": {
-      "command": "node",
-      "args": ["C:/chemin/vers/gitHubMCP/dist/index.js"],
-      "env": {
-        "GITHUB_TOKEN": "votre_token_github_ici",
-        "CLONE_DIR": "./cloned_repos"
-      }
-    }
-  }
-}
-```
-
-## 🛠️ Installation locale & build
-
-```bash
-git clone https://github.com/votre-pseudo/gitHubMCP.git
-cd gitHubMCP
-npm install
-cp .env.example .env
-# Éditez .env avec vos valeurs
-npm run build
-```
-
-## 📦 Publication Automatisée
-
-Ce projet est configuré pour être publié sur npm via **GitHub Actions** à chaque nouvelle Release :
-
-1. Mettez à jour la version dans `package.json`.
-2. Poussez sur GitHub et créez une Release.
-3. Le workflow OIDC publie automatiquement sur npm.
-
-## 📄 Licence
-
-ISC
+# Restricted GitHub MCP Server
+
+Un serveur MCP (Model Context Protocol) spécialisé pour automatiser le workflow Git local vers GitHub, avec délégation des compilations/tests soit à un serveur distant via SSH, soit directement en local sur la même machine. Conçu pour être minimaliste et sécurisé.
+
+## 🚀 Outils disponibles
+
+### Git local → GitHub
+
+- **`commit`** : Exécute `git add .` puis crée un commit avec le message fourni. *Ne pousse pas vers le remote.*
+- **`push`** : Pousse la branche actuelle vers `TARGET_BRANCH`. *Ne fait pas de commit.*
+- **`commit_and_push`** : Enchaîne `git add .`, commit et push vers `TARGET_BRANCH`.
+- **`pull_request`** : Crée une Pull Request GitHub de `TARGET_BRANCH` vers `BASE_BRANCH`.
+- **`clone`** : Clone `TARGET_REPO` dans `CLONE_DIR/<TARGET_BRANCH>/`. Crée la branche distante si elle n'existe pas encore.
+- **`get_info`** : Affiche la configuration active (dépôt, branches, chemins) sans exposer les secrets.
+- **`get_logs`** : Récupère les dernières lignes du fichier de log serveur. Argument optionnel : `lines` (défaut : 50).
+
+### Déploiement & test (serveur distant ou local)
+
+Selon la configuration active, ces outils s'exécutent soit sur un serveur distant via SSH, soit directement en local sur la machine du serveur MCP (interrupteur `LOCAL_DEPLOY`).
+
+- **`deploy`** : Exécute `git fetch --all`, `git checkout TARGET_BRANCH`, `git pull` dans `SSH_REMOTE_PATH`. Le repo doit être préalablement cloné à cet emplacement (sur le serveur distant, ou en local).
+- **`test`** : Exécute `TEST_COMMAND` (cwd = `SSH_REMOTE_PATH`) et renvoie stdout, stderr et exit code. Stocke la sortie pour `test_logs`.
+- **`test_logs`** : Renvoie la sortie du dernier `test` exécuté sans relancer la commande.
+
+> **Mode local (`LOCAL_DEPLOY`)** : quand il est activé, aucune connexion SSH n'est ouverte — la commande est lancée directement dans le shell de la machine, dans le dossier `SSH_REMOTE_PATH` (interprété comme un chemin local). Pratique lorsque le serveur MCP tourne sur le serveur de déploiement lui-même.
+
+### Flux typique agent
+
+```
+clone → (modifier des fichiers) → commit_and_push → deploy → test
+                                        ↑                       |
+                                        └─── (corriger) ────────┘ (si exit code ≠ 0)
+```
+
+## 🔀 Rôles : faire tourner le MCP derrière mcp-http-gateway
+
+Déclaré directement dans la configuration de l'agent, le MCP expose à l'agent son token GitHub, le dépôt et la branche cibles : l'agent peut les lire, et les modifier. Pour l'empêcher, le MCP tourne dans [mcp-http-gateway](https://www.npmjs.com/package/@imenam/mcp-http-gateway), sur un autre serveur. La variable `GITHUB_MCP_ROLE` fixe le rôle de l'instance :
+
+| Rôle | Où | Git s'exécute |
+| :--- | :--- | :--- |
+| `standalone` (défaut) | Machine de l'agent | Sur la même machine, en direct vers GitHub avec le token |
+| `remote` | Dans mcp-http-gateway | Sur la machine de l'agent, lancé par le relais agent, à travers le proxy git de l'instance |
+
+En rôle `remote`, l'instance est la seule à connaître le token, le dépôt et les branches. Elle expose tous les outils : l'agent les appelle à travers le relais agent du gateway (`mcp-http-gateway --mcp`), comme n'importe quel outil du gateway.
+
+### Le proxy git
+
+L'instance ouvre un proxy git sur `127.0.0.1:<MCP_HTTP_RELAY_PORT>`, que le gateway rend joignable à `<gateway>/<route>/http/*` après avoir authentifié la requête. Ce proxy :
+
+- envoie toujours les requêtes vers `TARGET_REPO`, quel que soit le chemin demandé par git ;
+- lit les commandes de chaque push avant de contacter GitHub, et refuse tout push qui vise une autre ref que `refs/heads/<TARGET_BRANCH>` ou qui la supprime. GitHub n'est alors jamais contacté, et git affiche `! [remote rejected] … (seule la branche <TARGET_BRANCH> est autorisée)` ;
+- refuse tout push quand la configuration est en lecture seule ;
+- ajoute le token GitHub, que la machine de l'agent ne voit jamais ;
+- rend un refus du token par GitHub (`401`) comme une erreur `502` du proxy, pour que git ne demande pas d'identifiants.
+
+Le proxy ne bloque pas les push forcés sur `TARGET_BRANCH`. Pour les interdire, activez une règle de protection de branche côté GitHub.
+
+### Git sur la machine de l'agent
+
+Les outils `clone`, `init_working_dir`, `commit`, `push`, `commit_and_push` et `check_status` font exécuter git par le relais agent, selon la convention d'exécution de mcp-http-gateway (voir son README, *Exécution sur la machine de l'agent*) :
+
+1. L'outil répond au relais agent par une demande d'exécution : des commandes `git`, lancées sans shell.
+2. Le relais agent les exécute sur la machine de l'agent, puis rappelle l'outil avec les résultats.
+3. L'outil enchaîne les étapes suivantes, puis rend son résultat final. L'agent ne voit que ce résultat.
+
+- **Copie de travail :** `REPO_PATH` s'il est configuré sur l'instance, sinon `<dossier de lancement du relais agent>/<nom du dépôt>`.
+- **Remote git :** `<GATEWAY_URL><MCP_SERVER_ROUTE>/http/repo.git`. `clone` et `init_working_dir` y font pointer `origin`.
+- **Jeton du gateway :** passé à git par variables d'environnement (`GIT_CONFIG_*`), limité aux URL du gateway. Il n'apparaît ni dans les arguments des commandes, ni dans `.git/config`.
+- **Prérequis :** la route de l'instance (ex. `/github`) doit figurer dans `GATEWAY_EXEC_ROUTES`, la liste blanche du relais agent. Sinon, ces outils refusent l'appel en nommant la route à ajouter.
+
+Un `git push` lancé à la main par l'agent vers `origin` passe par le même proxy et subit les mêmes contrôles.
+
+Les outils `pull_request`, `deploy`, `test` et `test_logs` s'exécutent entièrement sur l'instance.
+
+### Configuration de l'instance `remote` (dans le gateway)
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@imenam/mcp-github"],
+      "env": {
+        "MCP_SERVER_ROUTE": "/github",
+        "MCP_HTTP_RELAY_PORT": "4610",
+        "GITHUB_MCP_ROLE": "remote",
+        "GITHUB_TOKEN": "votre_token_github_ici",
+        "MCP_DATA_DIR": "/chemin/vers/data",
+        "PROXY_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+- `MCP_SERVER_ROUTE` et `MCP_HTTP_RELAY_PORT` sont des directives du gateway. L'instance lit la route pour construire l'URL du remote git, et le port pour ouvrir son proxy. Elle refuse de démarrer sans l'une ou l'autre.
+- `REPO_PATH` (optionnel) fixe la copie de travail sur la machine de l'agent.
+- Le dépôt, les branches et le déploiement se règlent dans la GUI de l'instance. En rôle `remote`, la GUI ne propose ni le clonage ni la suppression du dossier de travail : la copie de travail est sur la machine de l'agent.
+
+### Configuration du relais agent (chez l'agent)
+
+Le relais agent est celui du gateway ; il suffit d'y autoriser la route de l'instance :
+
+```json
+{
+  "mcpServers": {
+    "gateway": {
+      "command": "npx",
+      "args": ["-y", "@imenam/mcp-http-gateway", "--mcp"],
+      "env": {
+        "GATEWAY_URL": "https://gateway.example.com",
+        "GATEWAY_TOKEN": "jeton_du_gateway",
+        "GATEWAY_EXEC_ROUTES": "/github"
+      }
+    }
+  }
+}
+```
+
+## 🖥️ Interface de Configuration (GUI)
+
+Le serveur lance automatiquement une interface graphique au démarrage (si `PROXY_URL` est défini). Elle permet de :
+
+- Gérer plusieurs configurations nommées (multi-projets).
+- Sélectionner le dépôt et les branches via des menus déroulants GitHub.
+- Configurer le déploiement **par projet** : serveur SSH (hôte, utilisateur, port, clé privée) et commande de test, ou bascule en **déploiement local** sans SSH.
+- Visualiser la configuration active en temps réel.
+
+Le formulaire est organisé en sections repliables : **Dépôt & branches** (toujours dépliée, cœur de l'usage), **Options** et **Déploiement & test** (repliées par défaut, le paramétrage serveur n'étant fait qu'une fois). Activer l'interrupteur **Déployer en local** masque automatiquement les champs de connexion SSH devenus inutiles.
+
+> **Proxy dynamique** : La GUI s'enregistre auprès du reverse proxy défini dans `PROXY_URL` et reçoit un port dynamique. Elle est alors accessible sous le chemin effectivement enregistré — `GUI_PATH` seul par défaut, éventuellement préfixé par `APP_PATH_PREFIX` (voir *Variables GUI / Proxy*). L'enregistrement passe par le client partagé [`@imenam/mcp-gui-interface`](https://www.npmjs.com/package/@imenam/mcp-gui-interface), commun à tous les MCP à interface ; le timeout d'enregistrement est de **1 s** (il était de 5 s avec l'ancien client interne).
+
+### Exposition réseau
+
+La GUI écoute uniquement sur `127.0.0.1`, comme le proxy git : une autre machine y accède par le proxy ou le gateway manager. Un garde de requêtes fourni par [`@imenam/mcp-gui-interface`](https://www.npmjs.com/package/@imenam/mcp-gui-interface) répond `403` à toute requête dont l'en-tête `Host` n'est pas `localhost`, `127.0.0.1` ou `::1` (protection contre le DNS rebinding), ainsi qu'aux requêtes de modification (`POST`, `DELETE`…) émises depuis un autre site (`Sec-Fetch-Site` ou `Origin` étranger). L'hôte de `PROXY_URL` fait partie des origines acceptées.
+
+## ⚙️ Configuration
+
+Les variables **globales** (token, dossiers, proxy) sont définies dans un fichier `.env` ou dans la section `env` du client MCP. Les **paramètres par projet** (dépôt, branches, déploiement SSH ou local…) sont gérés dans l'interface GUI et stockés dans `configs.json`.
+
+### Variables GitHub
+
+| Variable | Description | Exemple |
+| :--- | :--- | :--- |
+| `GITHUB_TOKEN` | Personal Access Token GitHub (PAT) | `github_pat_...` |
+| `MCP_DATA_DIR` | Dossier contenant `configs.json` (multi-configs) | `./data` |
+| `CLONE_DIR` | Dossier racine dans lequel les branches seront clonées | `./cloned_repos` |
+
+> Les configurations par projet (dépôt, branches, mode lecture seule…) sont gérées dans l'interface GUI et stockées dans `configs.json`.
+
+### Paramètres de déploiement (outils `deploy` / `test`)
+
+Ces paramètres sont définis **par projet** dans l'interface GUI et stockés dans `configs.json` (et non dans le `.env` global). Chaque configuration peut donc viser un serveur — et une clé — différents, ou basculer en mode local.
+
+| Paramètre | Description | Exemple |
+| :--- | :--- | :--- |
+| `LOCAL_DEPLOY` | Si activé, exécution locale sans SSH (la machine du serveur MCP) | `false` |
+| `SSH_HOST` | Adresse IP ou hostname du serveur distant | `mon-serveur.example.com` |
+| `SSH_USER` | Utilisateur SSH | `deploy` |
+| `SSH_PORT` | Port SSH (défaut : 22) | `22` |
+| `SSH_KEY_PATH` | Chemin absolu vers la clé privée SSH | `C:/Users/.../.ssh/id_ed25519` |
+| `SSH_REMOTE_PATH` | Chemin du repo (distant en mode SSH, **local** si `LOCAL_DEPLOY`) | `/var/www/mon-projet` |
+| `TEST_COMMAND` | Commande de test à exécuter | `npx tsc --noEmit --pretty` |
+
+> En mode local, seuls `SSH_REMOTE_PATH` (qui doit exister sur le disque) et `TEST_COMMAND` sont utilisés ; les champs de connexion SSH sont ignorés.
+
+> **Note** : Pour `tsc`, utilisez `--pretty` pour obtenir la sortie complète avec contexte de code (sans cette option, `tsc` passe en format compact une ligne par erreur quand il n'y a pas de TTY).
+
+> **Migration** : ces clés peuvent aussi être fournies via le `.env` ou la section `env` du client MCP. Elles ne sont alors lues **qu'une seule fois** au premier démarrage (si `configs.json` n'existe pas encore) pour amorcer la configuration par défaut ; ensuite, c'est la GUI qui fait foi.
+
+### Variables GUI / Proxy
+
+| Variable | Description | Exemple |
+| :--- | :--- | :--- |
+| `PROXY_URL` | URL du reverse proxy central | `http://localhost:3000` |
+| `APP_PATH` | Chemin d'accès via le proxy. Nom canonique, commun à tous les MCP. | `/github-mcp` |
+| `APP_NAME` | Nom affiché dans le proxy. Nom canonique. | `GitHub MCP Config` |
+| `GUI_PATH` | Ancien nom de `APP_PATH`, toujours accepté (utilisé si `APP_PATH` et `PROXY_APP_PATH` sont absents) | `/github-mcp` (défaut) |
+| `GUI_NAME` | Ancien nom de `APP_NAME`, toujours accepté (même ordre de priorité) | `GitHub MCP Config` (défaut) |
+| `APP_PATH_PREFIX` | Préfixe de namespace ajouté au chemin **par défaut** uniquement | `/abc123` → `/abc123/github-mcp` |
+| `AGENT_NAME` | Nom de l'agent affiché dans la GUI | `Agent Zero` |
+| `APP_GROUP` | Section repliable (repliée par défaut) du dashboard proxy dans laquelle placer l'app. Les apps partageant la même valeur sont regroupées ; si non défini, l'app apparaît dans la section « non groupées ». | `Développement` |
+
+`APP_PATH` / `APP_NAME` sont les noms canoniques de l'écosystème ; `PROXY_APP_*` puis `GUI_*` restent acceptés, dans cet ordre de priorité décroissante. `APP_PATH_PREFIX` **ne préfixe que le chemin par défaut** : si `APP_PATH` (ou `GUI_PATH`) est renseigné, sa valeur est prise telle quelle, sans préfixe — la saisie manuelle l'emporte. Les chemins sont normalisés (un seul `/` de séparation, pas de `/` final).
+
+### L'environnement du process l'emporte sur le `.env`
+
+Une variable déjà présente dans l'environnement du process qui lance ce MCP
+(`export` dans un shell, bloc `env` d'une configuration MCP, ou superviseur comme
+`@imenam/mcp-gateway-manager`) **l'emporte sur la même clé du `.env` de ce
+dépôt**. C'est le comportement par défaut de dotenv, et la convention Unix
+habituelle : l'appelant gagne.
+
+Le `.env` reste rechargé à chaud — la GUI de configuration l'édite et la valeur
+est reprise sans redémarrer le serveur — mais ce rechargement ne peut plus
+écraser ce que l'appelant a injecté. Concrètement, une ligne
+`APP_GROUP=Développement` dans ce `.env` ne remplace plus un `APP_GROUP` fourni
+par un superviseur : elle ne s'applique que si personne n'en a fourni.
+
+Pour changer une variable que l'appelant fournit, changez-la chez l'appelant :
+l'éditer depuis la GUI n'aura aucun effet sur cette clé.
+
+## 📝 Journalisation (Logs)
+
+- **Windows** : `C:\var\log\restricted-github-mcp\server.log`
+- **Linux/macOS** : `/var/log/restricted-github-mcp/server.log`
+
+Le dossier est créé automatiquement. Les logs du processus principal (`[MASTER]`) et de la GUI (`[GUI]`) sont centralisés dans le même fichier.
+
+## 🖥️ Exemple de Configuration MCP
+
+### Via npx (Recommandé)
+
+```json
+{
+  "mcpServers": {
+    "@imenam/mcp-github": {
+      "command": "npx",
+      "args": ["-y", "@imenam/mcp-github"],
+      "env": {
+        "GITHUB_TOKEN": "votre_token_github_ici",
+        "CLONE_DIR": "/chemin/vers/dossier-de-clonage",
+        "MCP_DATA_DIR": "./data",
+        "PROXY_URL": "http://localhost:3000",
+        "GUI_PATH": "/github-mcp",
+        "GUI_NAME": "GitHub MCP Config",
+        "AGENT_NAME": "Mon Agent",
+        "SSH_HOST": "mon-serveur.example.com",
+        "SSH_USER": "ubuntu",
+        "SSH_PORT": "22",
+        "SSH_KEY_PATH": "/chemin/vers/.ssh/id_ed25519",
+        "SSH_REMOTE_PATH": "/var/www/mon-projet",
+        "TEST_COMMAND": "npx tsc --noEmit --pretty"
+      }
+    }
+  }
+}
+```
+
+> Les variables `PROXY_URL`, `GUI_*` et `AGENT_NAME` sont optionnelles selon votre usage. Les variables SSH (`SSH_HOST`, `SSH_USER`, `SSH_PORT`, `SSH_KEY_PATH`, `SSH_REMOTE_PATH`, `TEST_COMMAND`) ainsi que `LOCAL_DEPLOY` sont désormais gérées **par projet via la GUI** ; les inclure ici ne sert qu'à amorcer la configuration par défaut au premier démarrage (voir la note Migration ci-dessus).
+
+### Via installation locale
+
+```json
+{
+  "mcpServers": {
+    "@imenam/mcp-github": {
+      "command": "node",
+      "args": ["C:/chemin/vers/gitHubMCP/dist/index.js"],
+      "env": {
+        "GITHUB_TOKEN": "votre_token_github_ici",
+        "CLONE_DIR": "./cloned_repos"
+      }
+    }
+  }
+}
+```
+
+## 🛠️ Installation locale & build
+
+```bash
+git clone https://github.com/votre-pseudo/gitHubMCP.git
+cd gitHubMCP
+npm install
+cp .env.example .env
+# Éditez .env avec vos valeurs
+npm run build
+```
+
+## 📦 Publication Automatisée
+
+Ce projet est configuré pour être publié sur npm via **GitHub Actions** à chaque nouvelle Release :
+
+1. Mettez à jour la version dans `package.json`.
+2. Poussez sur GitHub et créez une Release.
+3. Le workflow OIDC publie automatiquement sur npm.
+
+## 📄 Licence
+
+ISC

package/dist/__tests__/config-server.guard.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config-server.guard.test.d.ts.map

package/dist/__tests__/config-server.guard.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-server.guard.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/config-server.guard.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/config-server.guard.test.js

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi, beforeAll } from "vitest";
+import http from "node:http";
+import net from "node:net";
+import os from "node:os";
+/**
+ * Exposition réseau de la GUI de configuration : `startConfigServer` démarre le
+ * vrai serveur Express, avec le proxy et la configuration remplacés par des
+ * doublures. Les requêtes passent par `node:http`, seul moyen de fixer Host.
+ */
+/** URL du proxy connue uniquement de `getConfig()`, pas de `process.env`. */
+const PROXY_URL = "http://proxy.lan:3000";
+let port;
+vi.mock("../logger.js", () => ({ logToFile: vi.fn() }));
+vi.mock("../utils/role.js", () => ({ getRole: () => "standalone" }));
+vi.mock("../utils/config.js", () => ({
+    getConfig: () => ({ PROXY_URL, GUI_PATH: "/github-mcp", GUI_NAME: "GitHub MCP Config" }),
+    updateEnvFile: vi.fn(),
+    safeSend: vi.fn(() => true),
+    migrateFromLegacyEnv: vi.fn(),
+    getAllConfigNames: () => [],
+    getConfigByName: () => null,
+    saveConfiguration: vi.fn(),
+    deleteConfiguration: () => false,
+    setCurrentConfiguration: () => true,
+    getCurrentConfigName: () => "demo",
+}));
+vi.mock("@imenam/mcp-gui-interface", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        ProxyClient: class {
+            async register() {
+                return { success: true, port, path: "/github-mcp" };
+            }
+            async unregister() { }
+        },
+    };
+});
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const { port: free } = server.address();
+            server.close(() => resolve(free));
+        });
+    });
+}
+function canConnect(host, target) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host, port: target });
+        socket.setTimeout(1000);
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("error", () => resolve(false));
+        socket.once("timeout", () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
+async function waitForListening(target) {
+    for (let attempt = 0; attempt < 50; attempt++) {
+        if (await canConnect("127.0.0.1", target))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error(`La GUI n'écoute pas sur 127.0.0.1:${target}`);
+}
+function request(method, path, headers, body) {
+    return new Promise((resolve, reject) => {
+        const req = http.request({ host: "127.0.0.1", port, method, path, headers }, (res) => {
+            let data = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => (data += chunk));
+            res.on("end", () => resolve({ status: res.statusCode ?? 0, body: data }));
+        });
+        req.on("error", reject);
+        if (body !== undefined)
+            req.write(body);
+        req.end();
+    });
+}
+const saveBody = JSON.stringify({ name: "demo", config: { GITHUB_TOKEN: "x" } });
+const jsonHeaders = { "Content-Type": "application/json" };
+/** Première adresse IPv4 non loopback de la machine, s'il y en a une. */
+const externalIpv4 = Object.values(os.networkInterfaces())
+    .flat()
+    .find((address) => address && address.family === "IPv4" && !address.internal)?.address;
+beforeAll(async () => {
+    port = await freePort();
+    vi.spyOn(console, "error").mockImplementation(() => { });
+    const { startConfigServer } = await import("../config-server.js");
+    await startConfigServer();
+    await waitForListening(port);
+});
+describe("config-server — exposition réseau", () => {
+    it("refuse un Host étranger (DNS rebinding)", async () => {
+        const reply = await request("GET", "/api/configs", { Host: `attacker.example:${port}` });
+        expect(reply.status).toBe(403);
+        expect(JSON.parse(reply.body).error).toMatch(/not allowed/);
+    });
+    it("refuse une modification cross-site signalée par Sec-Fetch-Site", async () => {
+        const reply = await request("POST", "/api/configs", { ...jsonHeaders, Host: `localhost:${port}`, "Sec-Fetch-Site": "cross-site" }, saveBody);
+        expect(reply.status).toBe(403);
+    });
+    it("refuse une modification venant d'une Origin étrangère", async () => {
+        const reply = await request("POST", "/api/configs", { ...jsonHeaders, Host: `localhost:${port}`, Origin: "http://attacker.example" }, saveBody);
+        expect(reply.status).toBe(403);
+    });
+    it("filtre avant l'analyse du corps : un JSON invalide cross-site reçoit 403", async () => {
+        const reply = await request("POST", "/api/configs", { ...jsonHeaders, Host: `localhost:${port}`, Origin: "http://attacker.example" }, "{not json");
+        expect(reply.status).toBe(403);
+    });
+    it("accepte une modification relayée par le proxy (Origin localhost:3000)", async () => {
+        const reply = await request("POST", "/api/configs", {
+            ...jsonHeaders,
+            Host: `localhost:${port}`,
+            Origin: "http://localhost:3000",
+            "Sec-Fetch-Site": "same-origin",
+        }, saveBody);
+        expect(reply.status).toBe(200);
+        expect(JSON.parse(reply.body).message).toMatch(/saved/);
+    });
+    it("fait confiance à l'hôte du PROXY_URL de la configuration", async () => {
+        const reply = await request("POST", "/api/configs", { ...jsonHeaders, Host: `localhost:${port}`, Origin: PROXY_URL }, saveBody);
+        expect(reply.status).toBe(200);
+    });
+    it.skipIf(!externalIpv4)("n'est pas joignable sur l'adresse IPv4 externe", async () => {
+        expect(await canConnect(externalIpv4, port)).toBe(false);
+    });
+});
+//# sourceMappingURL=config-server.guard.test.js.map