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 à un serveur distant via SSH. 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).

Serveur distant via SSH

• deploy : Sur le serveur SSH configuré, exécute git fetch --all, git checkout TARGET_BRANCH, git pull dans SSH_REMOTE_PATH. Le repo doit être préalablement cloné manuellement sur le serveur.
• test : Exécute TEST_COMMAND sur le serveur distant (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.

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.
• Visualiser la configuration active en temps réel.

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

Toutes les variables sont définies dans un fichier .env ou dans la section env du client MCP.

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.

Variables SSH (outils deploy / test)

| Variable | Description | Exemple | | :--- | :--- | :--- | | SSH_HOST | Adresse IP ou hostname du serveur distant | 195.35.24.113 | | SSH_USER | Utilisateur SSH | root | | 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 sur le serveur distant | /var/www/mon-projet | | TEST_COMMAND | Commande de test à exécuter sur le serveur | npx tsc --noEmit --pretty |

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).

Variables GUI / Proxy

| Variable | Description | Exemple | | :--- | :--- | :--- | | PROXY_URL | URL du reverse proxy central | http://localhost:3000 | | GUI_PATH | Chemin d'accès via le proxy | /github-mcp (défaut) | | GUI_NAME | Nom affiché dans le proxy | GitHub MCP Config (défaut) | | AGENT_NAME | Nom de l'agent affiché dans la GUI | Agent Zero |

📝 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_*, AGENT_NAME et SSH sont optionnelles selon votre usage.

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 :

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