Restricted GitHub MCP Server

Un serveur MCP (Model Context Protocol) spécialisé pour automatiser le workflow Git local vers GitHub. Ce serveur est conçu pour être minimaliste et sécurisé, en limitant les actions possibles à un flux de travail spécifique.

🚀 Fonctionnalités Automatisées

Contrairement aux serveurs GitHub classiques, celui-ci propose des outils hautement automatisés et une interface de configuration simplifiée :

• commit :
  1. Exécute git add . (ajoute tous les fichiers modifiés et nouveaux).
  2. Crée un commit avec le message fourni. Ne pousse PAS vers le remote.
• push :
  1. Pousse la branche actuelle vers la branche cible définie dans la configuration. Ne fait PAS de commit. Suppose que les changements sont déjà commités.
• commit_and_push :
  1. Exécute git add . (ajoute tous les fichiers modifiés et nouveaux).
  2. Crée un commit avec le message fourni.
  3. Pousse automatiquement vers la branche cible définie dans la configuration.
• pull_request :
  1. Crée une Pull Request sur GitHub.
  2. Utilise automatiquement la branche de destination (TARGET_BRANCH) et la branche de base (BASE_BRANCH) configurées.
• get_info :
  1. Renvoie la configuration actuelle (dépôt, branches, chemin local, répertoire de travail).
  2. Utile pour vérifier que l'agent est sur le bon contexte sans exposer de secrets.
• clone :
  1. Clone le dépôt défini dans TARGET_REPO dans le dossier défini par REPO_PATH.
  2. Crée et bascule sur la branche définie par TARGET_BRANCH.
  3. Utilise le token GitHub configuré pour l'authentification.
• get_logs :
  1. Récupère les dernières lignes du fichier de log du serveur. Argument optionnel : lines (nombre de lignes à récupérer, défaut 50).

🖥️ Interface de Configuration (GUI)

Le serveur lance automatiquement une interface graphique sur le port 3000 au démarrage. Cette interface permet de :

• Visualiser la configuration actuelle.
• Modifier dynamiquement le token GitHub, le dépôt cible, les branches et le chemin local.
• Sauvegarder les modifications dans un fichier .env local.
• Consulter les erreurs de configuration en temps réel.

Accès : http://localhost:3000

Proxy dynamique : La GUI peut s'enregistrer automatiquement auprès d'un reverse proxy pour recevoir un port dynamique. Voir la section Configuration Proxy.

📝 Journalisation (Logs)

Pour garantir la stabilité et faciliter le débogage, le serveur enregistre ses activités et ses erreurs dans un fichier de log persistant. Les logs du serveur MCP et de l'interface GUI sont centralisés dans le même fichier.

• Emplacement (Windows) : C:\var\log\restricted-github-mcp\server.log
• Emplacement (Linux/macOS) : /var/log/restricted-github-mcp/server.log
• Contenu : Horodatage, PID, préfixe ([MASTER] pour le MCP, [GUI] pour l'interface), exécution des outils, succès et erreurs détaillées.

Le serveur vérifie et crée automatiquement le dossier de log s'il n'existe pas. Les erreurs critiques sont également redirigées vers stderr pour être visibles dans les consoles des clients MCP.

🛠️ Installation & Utilisation via npx

Une fois publié, ce serveur peut être utilisé sans installation globale :

npx restricted-github-mcp

⚙️ Configuration

Le serveur se configure exclusivement via des variables d'environnement. Ces variables doivent être définies dans votre client MCP (Cursor, Claude Desktop) ou dans un fichier .env.

| Variable | Description | Exemple | | :--- | :--- | :--- | | GITHUB_TOKEN | Votre Personal Access Token GitHub (PAT) | github_pat_... | | TARGET_REPO | Le dépôt cible au format propriétaire/nom | MonPseudo/mon-expose | | TARGET_BRANCH | La branche sur laquelle le code doit être poussé | feature/test | | BASE_BRANCH | (Optionnel) La branche de destination pour la PR | main (défaut) | | REPO_PATH | (Optionnel) Le chemin local du dépôt Git | /chemin/vers/projet | | READ_ONLY | (Optionnel) Désactive les actions d'écriture | false (défaut) |

🌐 Configuration Proxy (Optionnel)

Si vous utilisez un reverse proxy dynamique pour centraliser plusieurs applications sur un seul port, vous pouvez configurer les variables suivantes :

| Variable | Description | Exemple | | :--- | :--- | :--- | | PROXY_URL | URL du serveur proxy | 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) |

Comportement :

• Si PROXY_URL est défini, la GUI tente de s'enregistrer au démarrage
• En cas de succès, elle utilise le port attribué par le proxy et devient accessible via http://[PROXY_URL][GUI_PATH]/
• En cas d'échec (proxy indisponible, timeout), elle démarre sur le port 3000 par défaut
• À l'arrêt, elle se désenregistre automatiquement du proxy

🖥️ Exemple de Configuration MCP

Copiez-collez cette configuration dans votre client MCP (ex: claude_desktop_config.json ou paramètres Cursor) :

Via npx (Recommandé)

{
  "mcpServers": {
    "restricted-github-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "restricted-github-mcp"
      ],
      "env": {
        "GITHUB_TOKEN": "votre_token_github_ici",
        "TARGET_REPO": "propriétaire/nom-du-repo",
        "TARGET_BRANCH": "votre-branche-de-travail",
        "BASE_BRANCH": "main",
        "REPO_PATH": "/chemin/vers/votre/projet/local",
        "PROXY_URL": "http://localhost:3000",
        "GUI_PATH": "/github-mcp",
        "GUI_NAME": "GitHub MCP Config"
      }
    }
  }
}

Note : Les variables PROXY_URL, GUI_PATH et GUI_NAME sont optionnelles. Supprimez-les si vous n'utilisez pas de proxy.

Via installation locale

Si vous avez cloné le dépôt et exécuté npm run build :

{
  "mcpServers": {
    "restricted-github-mcp": {
      "command": "node",
      "args": [
        "C:/chemin/vers/votre/projet/dist/index.js"
      ],
      "env": {
        "GITHUB_TOKEN": "votre_token_github_ici",
        "TARGET_REPO": "propriétaire/nom-du-repo",
        "TARGET_BRANCH": "votre-branche-de-travail",
        "BASE_BRANCH": "main",
        "REPO_PATH": "/chemin/vers/votre/projet/local",
        "PROXY_URL": "http://localhost:3000",
        "GUI_PATH": "/github-mcp",
        "GUI_NAME": "GitHub MCP Config"
      }
    }
  }
}

📦 Publication Automatisée

Ce projet est configuré pour être publié sur npm via GitHub Actions à chaque nouvelle "Release" sur le dépôt GitHub.

1. Modifiez la version dans package.json.
2. Poussez votre code sur GitHub.
3. Créez une nouvelle "Release" sur GitHub.
4. Le workflow OIDC (Trusted Publishing) s'occupera de la publication sur npm sans jeton statique.

📄 Licence

ISC