@imenam/mcp-github

v1.1.50

Published

12 days ago

Un serveur MCP GitHub contrôlé et sécurisé pour les agents IA.

Downloads

689

0High
0Medium
0Low

imenam

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 via http://[PROXY_URL][GUI_PATH]/.

⚙️ 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

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.

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

📝 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é)

{
  "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

{
  "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

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 :

Mettez à jour la version dans package.json.
Poussez sur GitHub et créez une Release.
Le workflow OIDC publie automatiquement sur npm.

📄 Licence

ISC