restricted-github-mcp 1.0.0

package/README.md

@@ -0,0 +1,105 @@
+# GitHub MCP Server (Controlled)
+
+Ce serveur implémente le **Model Context Protocol (MCP)** pour permettre à des agents IA (comme Cursor, Claude Desktop, etc.) d'interagir avec GitHub de manière sécurisée et contrôlée.
+
+## 🚀 Fonctionnalités
+
+Le serveur expose plusieurs outils (tools) pour manipuler les dépôts GitHub :
+
+- **`get_file_contents`** : Lire le contenu d'un fichier.
+- **`git_push`** : Créer ou mettre à jour un fichier (Push).
+- **`pull_request_create`** : Créer une Pull Request.
+- **`list_issues`** : Lister les issues et PRs d'un dépôt.
+- **`create_issue_comment`** : Ajouter un commentaire sur une issue ou PR.
+
+## 🔒 Sécurité et Contrôle
+
+Le serveur est conçu avec un principe de contrôle strict via des variables d'environnement :
+
+- **`ALLOWED_REPOS`** : Liste des dépôts (`propriétaire/nom`) que l'agent est autorisé à manipuler.
+- **`ALLOWED_BRANCHES`** : Masques de branches autorisés pour les pushs (ex: `feature/*`, `mcp-*`).
+- **`READ_ONLY`** : Si mis à `true`, toutes les actions d'écriture (push, PR, commentaires) sont désactivées.
+
+## 🛠️ Installation
+
+1.  **Cloner le projet** (ou copier les fichiers).
+2.  **Installer les dépendances** :
+    ```bash
+    npm install
+    ```
+3.  **Configurer l'environnement** :
+    Créez un fichier `.env` à la racine (voir section Configuration ci-dessous).
+
+## ⚙️ Configuration
+
+Créez un fichier `.env` avec les variables suivantes :
+
+```env
+# Votre Token d'accès personnel GitHub (PAT)
+GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+
+# Dépôts autorisés (séparés par des virgules)
+ALLOWED_REPOS=votre-org/votre-repo,un-autre/depot
+
+# Branches autorisées pour le push (supporte *)
+ALLOWED_BRANCHES=main,develop,mcp-*
+
+# Mode lecture seule (true/false)
+READ_ONLY=false
+```
+
+## 🖥️ Utilisation
+
+### Mode Développement
+Pour lancer le serveur directement avec `ts-node` :
+```bash
+npm start
+```
+
+### Build et Production
+Pour compiler en JavaScript :
+```bash
+npm run build
+node dist/index.js
+```
+
+### Intégration dans Cursor
+Pour utiliser ce serveur dans Cursor :
+1. Allez dans les paramètres de Cursor (Cursor Settings) > MCP.
+2. Ajoutez un nouveau serveur MCP :
+   - **Name** : GitHub Controlled
+   - **Type** : `command`
+   - **Command** : `node "C:/chemin/vers/githubmcp/node_modules/ts-node/dist/bin.js" "C:/chemin/vers/githubmcp/src/index.ts"`
+   - **Environment Variables** : (Vous pouvez aussi les définir ici au lieu du fichier .env)
+
+### Intégration dans Claude Desktop
+Ajoutez la configuration suivante dans votre fichier `claude_desktop_config.json` :
+
+```json
+{
+  "mcpServers": {
+    "github-controlled": {
+      "command": "node",
+      "args": [
+        "C:/chemin/vers/githubmcp/node_modules/ts-node/dist/bin.js",
+        "C:/chemin/vers/githubmcp/src/index.ts"
+      ],
+      "env": {
+        "GITHUB_TOKEN": "votre_token",
+        "ALLOWED_REPOS": "org/repo",
+        "ALLOWED_BRANCHES": "mcp-*",
+        "READ_ONLY": "false"
+      }
+    }
+  }
+}
+```
+
+## 🧪 Debugging
+Vous pouvez utiliser l'inspecteur MCP pour tester le serveur localement :
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+## 📄 Licence
+ISC

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { Octokit } from "octokit";
+import * as dotenv from "dotenv";
+import { execSync } from "child_process";
+// MCP servers must not log to stdout as it's used for the protocol.
+// Some libraries might log to stdout on initialization.
+// We redirect all console.log to console.error to avoid polluting stdout.
+console.log = console.error;
+dotenv.config();
+const GITHUB_TOKEN = process.env.GITHUB_TOKEN;
+const TARGET_BRANCH = process.env.TARGET_BRANCH;
+const BASE_BRANCH = process.env.BASE_BRANCH || "main";
+const TARGET_REPO = process.env.TARGET_REPO;
+const READ_ONLY = process.env.READ_ONLY === "true";
+if (!GITHUB_TOKEN) {
+    console.error("GITHUB_TOKEN environment variable is required");
+    process.exit(1);
+}
+const octokit = new Octokit({ auth: GITHUB_TOKEN });
+const server = new Server({
+    name: "restricted-github-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+const TOOLS = [
+    {
+        name: "push",
+        description: "Automated push: adds all local changes (including untracked), commits with a message, and pushes to the specific branch defined in TARGET_BRANCH",
+        inputSchema: {
+            type: "object",
+            properties: {
+                message: { type: "string", description: "The commit message" },
+            },
+            required: ["message"],
+        },
+    },
+    {
+        name: "pull_request",
+        description: "Create a pull request from the TARGET_BRANCH to the BASE_BRANCH",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "The title of the pull request" },
+                body: { type: "string", description: "The body/description of the pull request" },
+            },
+            required: ["title"],
+        },
+    },
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "push": {
+                if (READ_ONLY)
+                    throw new Error("Server is in read-only mode");
+                const { message } = args;
+                if (!TARGET_BRANCH) {
+                    throw new Error("TARGET_BRANCH environment variable is not defined");
+                }
+                try {
+                    // 1. Add all changes (including untracked)
+                    execSync("git add .");
+                    // 2. Commit
+                    try {
+                        execSync(`git commit -m "${message}"`);
+                    }
+                    catch (e) {
+                        // Check if there was nothing to commit
+                        const status = execSync("git status --porcelain").toString();
+                        if (status.length === 0) {
+                            return {
+                                content: [{ type: "text", text: "Nothing to commit, working tree clean." }],
+                            };
+                        }
+                        throw e;
+                    }
+                    // 3. Push to target branch
+                    // If TARGET_REPO is defined (e.g. "user/repo"), we push to that remote
+                    // Otherwise we push to 'origin'
+                    const remote = TARGET_REPO && GITHUB_TOKEN
+                        ? `https://x-access-token:${GITHUB_TOKEN}@github.com/${TARGET_REPO}.git`
+                        : "origin";
+                    execSync(`git push ${remote} HEAD:${TARGET_BRANCH}`);
+                    return {
+                        content: [{ type: "text", text: `Successfully committed and pushed all changes to branch ${TARGET_BRANCH}` }],
+                    };
+                }
+                catch (error) {
+                    throw new Error(`Git operation failed: ${error.message}`);
+                }
+            }
+            case "pull_request": {
+                if (READ_ONLY)
+                    throw new Error("Server is in read-only mode");
+                const { title, body } = args;
+                if (!TARGET_REPO || !TARGET_REPO.includes("/")) {
+                    throw new Error("TARGET_REPO must be defined as 'owner/repo'");
+                }
+                if (!TARGET_BRANCH) {
+                    throw new Error("TARGET_BRANCH is not defined");
+                }
+                const [owner, repo] = TARGET_REPO.split("/");
+                if (!owner || !repo) {
+                    throw new Error("Invalid TARGET_REPO format. Expected 'owner/repo'");
+                }
+                try {
+                    const response = await octokit.rest.pulls.create({
+                        owner,
+                        repo,
+                        title,
+                        body,
+                        head: TARGET_BRANCH,
+                        base: BASE_BRANCH,
+                    });
+                    return {
+                        content: [{ type: "text", text: `Pull request created successfully: ${response.data.html_url}` }],
+                    };
+                }
+                catch (error) {
+                    throw new Error(`Failed to create pull request: ${error.message}`);
+                }
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("GitHub MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "restricted-github-mcp",
+  "version": "1.0.0",
+  "main": "index.js",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "restricted-github-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "inspect": "mcp-inspector node dist/index.js",
+    "inspect:dev": "mcp-inspector --config mcp-config.json",
+    "inspect:no-auth": "mcp-inspector -e DANGEROUSLY_OMIT_AUTH=true --config mcp-config.json"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "Un serveur MCP GitHub contrôlé et sécurisé pour les agents IA.",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "dotenv": "^17.2.3",
+    "octokit": "^5.0.5"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/inspector": "^0.19.0",
+    "@types/node": "^25.0.10", 
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}