Pôle Formation UIMM-CVDL

S. Jaubert

Tutoriel Complet : Connecter Gemini (IA) à votre Google Drive en toute sécurité

◉ Le Plan d'Action (Les 3 Grandes Parties)

1. Partie 1 : Construire le Moteur (Setup gas-fakes). C'est la base. Nous allons configurer l'outil gas-fakes pour qu'il puisse parler à Google. C'est l'étape la plus complexe, car elle implique la console Google Cloud.
2. Partie 2 : Installer le Chauffeur IA (Serveur MCP). Nous installerons le "traducteur" (un serveur MCP) qui permet à Gemini de "donner des ordres" à notre moteur gas-fakes.
3. Partie 3 : Le Test de Conduite (Simulation). Nous lancerons Gemini et lui donnerons nos premières instructions en langage naturel.

Partie 1 : Construire le Moteur (Setup gas-fakes)

C'est la fondation. Nous allons obtenir les clés de l'atelier Google Cloud.

A. Prérequis

• Node.js installé sur votre PC.
• Un compte Google (un compte @gmail.com personnel est parfait).

B. Installation locale

Dans votre terminal, créez un dossier pour le projet et installez gas-fakes.

mkdir projet-ia-secure
cd projet-ia-secure
npm install @mcpher/gas-fakes

Ensuite, téléchargez le dossier shells depuis le dépôt GitHub (lien corrigé) et placez-le dans votre dossier projet-ia-secure.

C. Configuration Google Cloud (L'Étape du "Mur")

C'est ici que vous étiez bloqué. Suivez ce guide précisément. Il est conçu pour contourner les bugs de l'interface Google.

1. Créer le Projet "Atelier"

1. Allez sur la Console Google Cloud Platform.
2. Créez un nouveau projet (ex: "Mon-Atelier-IA").
3. Assurez-vous que ce projet est bien sélectionné en haut de la page.

2. Créer le Badge OAuth (L'ID Client)

1. Dans le menu de recherche en haut, tapez "Identifiants" (ou "Credentials").
2. Cliquez sur "+ CRÉER DES IDENTIFIANTS" et choisissez "ID client OAuth".
3. Type d'application : "Application de bureau" (Desktop app).
4. Donnez-lui un nom (ex: "Client Dev Local").
5. Cliquez sur "Créer". Une fenêtre s'ouvre.
6. IMPORTANT : Cliquez sur "TÉLÉCHARGER LE JSON".
7. Créez un dossier private dans votre projet. Renommez ce fichier credentials.json et placez-le dans projet-ia-secure/private/.

3. Configurer l'Écran de Consentement (La Procédure "Anti-Bug")

1. Dans le menu de gauche, cliquez sur "Écran de consentement OAuth".
2. Vous verrez le choix : "Interne" (grisé) et "Externe".
3. Choisissez "Externe" (c'est normal pour un compte @gmail.com) et cliquez sur "Créer".

Page 1 : "Branding" (Informations sur l'application)

• Nom de l'application : Mon App de Test IA
• Adresse e-mail d'assistance... : Votre email @gmail.com
• Logo : Laissez vide.
• Lien vers la page d'accueil... : Mettez https://www.google.com (juste pour passer).
• Lien vers les règles de confidentialité... : Mettez https://policies.google.com/privacy (juste pour passer).
• Domaines autorisés : Cliquez sur + AJOUTER UN DOMAINE et entrez google.com.
• Informations de contact du développeur : Supprimez votre email s'il est pré-rempli, puis retapez-le à la main et appuyez sur Entrée. C'est l'astuce qui débloque le bouton "Continuer".
• Tout en bas, cliquez sur le bouton bleu "ENREGISTRER ET CONTINUER".

Page 2 : "Scopes" (Champs d'application)

• Cliquez sur "AJOUTER OU SUPPRIMER DES CHAMPS D'APPLICATION".
• Faites défiler tout en bas, dans le champ "Ajouter manuellement les champs d'application".
• Collez cette liste (les scopes les plus courants) :

  https://www.googleapis.com/auth/spreadsheets
  https://www.googleapis.com/auth/drive
  https://www.googleapis.com/auth/documents
  https://www.googleapis.com/auth/userinfo.email
  openid

• Cliquez sur "AJOUTER À LA TABLE", puis sur le bouton "METTRE À JOUR".
• Tout en bas de la page "Scopes", cliquez sur "ENREGISTRER ET CONTINUER".

Page 3 : "Test users" (Utilisateurs test)

• Cliquez sur "+ ADD USERS".
• Entrez votre propre adresse email (ex: stephane.jaubert@gmail.com).
• Cliquez sur "AJOUTER".
• Tout en bas, cliquez sur "ENREGISTRER ET CONTINUER".

Page 4 : "Summary" (Résumé)

• Cliquez sur "REVENIR AU TABLEAU DE BORD".
• IMPORTANT : NE CLIQUEZ PAS SUR "PUBLIER L'APPLICATION". L'application doit rester en "Testing".

D. Configuration Locale (Le .env)

Nous allons maintenant dire à gas-fakes où trouver vos clés.

1. Ouvrez votre terminal dans le dossier projet-ia-secure.
2. Allez dans le dossier shells :
   Terminal (bash)

   cd shells

3. Exécutez le script de configuration :
   Terminal (bash)

   ./setup.sh

4. Le script va vous poser des questions :
   • Enter GCP_PROJECT_ID : Entrez l'ID de votre projet (ex: mon-atelier-ia-123456). Vous le trouvez sur la page d'accueil de la console GCP.
   • Enter CLIENT_CREDENTIAL_FILE : Entrez le chemin vers votre fichier JSON : ../private/credentials.json (le ../ est pour "remonter" d'un dossier).
   • Pour toutes les autres questions (DRIVE_TEST_FILE_ID, STORE_TYPE...), appuyez simplement sur Entrée pour accepter les valeurs par défaut.

E. Autorisation Finale (La Connexion)

Toujours dans le dossier shells/ :

1. Lancez l'autorisation :
   Terminal (bash)

   bash setaccount.sh

2. Votre navigateur va s'ouvrir.
3. Vous verrez un grand écran rouge d'avertissement ("Google n'a pas validé cette application"). C'EST NORMAL. C'est parce que votre application est en "Mode Test".
4. Cliquez sur "Paramètres avancés", puis sur "Accéder à [Nom de votre app] (non sécurisé)".
5. Cochez les cases pour autoriser les permissions (Drive, Sheets...) que vous avez ajoutées.
6. Activez les Outils (APIs) :
   Terminal (bash)

   bash enable.sh

   (Cela peut prendre une minute).

F. Fichiers de Projet (Le "Casier")

Retournez à la racine de votre projet (cd ..). Créez deux fichiers de configuration :

1. appsscript.json (pour lister les permissions) :

{
  "oauthScopes": [
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/documents",
    "https://www.googleapis.com/auth/userinfo.email",
    "openid"
  ]
}

2. gasfakes.json (pour donner un "numéro de casier" unique à votre projet) :

{
  "manifest": "./appsscript.json",
  "scriptId": "mon-projet-ia-secure-001"
}

Partie 2 : Installer le Chauffeur IA (Serveur MCP)

Maintenant que le moteur tourne, nous allons y connecter le "Chauffeur" (Gemini).

A. Installation des Outils (le "Traducteur")

Dans votre terminal, à la racine de projet-ia-secure, installez les modules pour le serveur MCP :

npm install @modelcontextprotocol/sdk zod

B. Le Script Serveur (gas-fakes-mcp.js)

Créez un fichier nommé gas-fakes-mcp.js à la racine de votre projet. C'est le "Maître d'Hôtel" qui écoutera Gemini.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { exec } from "child_process";
import fs from "fs/promises";
import { setTimeout } from "node:timers/promises";
import { promisify } from "util";
import { z } from "zod";

const server = new McpServer({
  name: "Serveur MCP pour gas-fakes",
  version: "0.0.1",
});

const execAsync = promisify(exec);

const tool = {
  name: "run_gas_with_gas-fakes", // Le nom de l'outil que Gemini utilisera
  schema: {
    description:
      "Exécute un script Google Apps Script dans un 'sandbox' sécurisé via gas-fakes.",
    inputSchema: {
      gas_script: z
        .string()
        .describe(
          `Le script Google Apps Script à exécuter.
           IMPORTANT: Utiliser 'console.log()' au lieu de 'Logger.log()'.
           Si le script est dans une fonction, ne pas oublier de l'appeler (ex: maFonction();).`
        ),
      whitelistItems: z
        .array(z.string().describe(`ID de fichier sur Google Drive`))
        .describe(
          `LISTE BLANCHE : IDs des fichiers (Sheets, Docs...) auxquels ce script a le droit d'accéder.`
        )
        .optional(),
      sandbox: z
        .boolean()
        .describe(
          `'true' (défaut) : Mode sécurisé. Le script ne peut rien faire en dehors de la whitelist.
           'false' : Mode non-sécurisé.`
        ),
    },
  },
  func: async (object = {}) => {
    const { sandbox = true, whitelistItems = [], gas_script } = object;
    const importFile = "./script_ia_temporaire.mjs"; // Fichier temporaire

    function getImportScript() {
      const importScriptAr = [
        // Importe gas-fakes pour simuler l'environnement
        `import "./node_modules/@mcpher/gas-fakes/main.js"`,
        "",
      ];
      if (whitelistItems.length === 0) {
        // Mode Sandbox STANDARD (autorisé à créer de nouveaux fichiers)
        importScriptAr.push(
          sandbox ? `ScriptApp.__behavior.sandBoxMode = true;` : "",
          `\n\n${gas_script}\n\n`,
          // Met à la corbeille tous les fichiers créés pendant ce script
          sandbox ? `ScriptApp.__behavior.trash();` : ""
        );
      } else {
        // Mode Sandbox STRICT (uniquement la whitelist)
        const wl = whitelistItems
          .map((id) => `behavior.newIdWhitelistItem("${id}").setWrite(true)`)
          .join(",");
        importScriptAr.push(
          `const behavior = ScriptApp.__behavior;`,
          `behavior.sandboxMode = true;`,
          `behavior.strictSandbox = true;`, // N'autorise QUE la whitelist
          `behavior.setIdWhitelist([${wl}]);`, // Applique la whitelist
          `\n\n${gas_script}\n\n`,
          `ScriptApp.__behavior.trash();`
        );
      }
      return importScriptAr.join("\n");
    }

    try {
      // 1. Écrit le script de l'IA dans un fichier
      const importScript = getImportScript();
      await fs.writeFile(importFile, importScript);
      await setTimeout(500); // Laisse le temps au fichier d'être écrit

      // 2. Exécute le fichier avec Node.js
      const { stdout } = await execAsync(`node ./${importFile}`);
      return {
        content: [{ type: "text", text: stdout || "Terminé." }],
        isError: false,
      };
    } catch (err) {
      // 3. Renvoie une erreur à Gemini si le script échoue
      return {
        content: [{ type: "text", text: err.message }],
        isError: true,
      };
    } finally {
      // 4. Supprime toujours le fichier temporaire
      try {
        await fs.unlink(importFile);
      } catch (err) {
        console.error(err.message);
      }
    }
  },
};

const { name, schema, func } = tool;
server.registerTool(name, schema, func);

const transport = new StdioServerTransport();
await server.connect(transport);

C. Configuration de Gemini (Le "GPS")

1. Installez le Gemini CLI si ce n'est pas déjà fait.
2. Trouvez le fichier settings.json du Gemini CLI (souvent dans votre dossier utilisateur, dans un dossier .gemini).
3. Modifiez ce fichier pour y ajouter la section mcpServers.

{
  "security": {
    "auth": {
      "selectedType": "..."
    }
  },
  "ui": {
    "theme": "Default"
  },
  "mcpServers": {
    "gas-fakes": {
      "command": "node",
      "args": ["VOTRE_CHEMIN_ABSOLU_VERS/projet-ia-secure/gas-fakes-mcp.js"]
    }
  }
}

Partie 3 : Le Test de Conduite (Simulation)

Tout est prêt. Lançons le test !

1. Ouvrez votre terminal (dans le dossier projet-ia-secure).
2. Lancez Gemini :
   Terminal (bash)

   gemini

3. Gemini va démarrer et vous dire qu'il a chargé l'outil gas-fakes. C'est la preuve que la connexion est réussie.

Exemple 1 : Sandbox Standard (Créer un fichier)

Donnez ce prompt à Gemini :

Ce qui se passe :

1. Gemini génère le script (avec DocumentApp.create()).
2. Il appelle votre outil run_gas_with_gas-fakes avec le script.
3. gas-fakes l'exécute, crée le fichier réellement dans votre Google Drive.
4. Il affiche l'ID du fichier dans votre terminal.
5. Il met immédiatement le fichier "Test IA Sandbox" à la corbeille (à cause de ScriptApp.__behavior.trash();).

Exemple 2 : Sandbox Sécurisé (Lire un fichier)

C'est le test ultime.

1. Créez un Google Sheet dans votre Drive. Mettez "Pomme" dans la cellule A1.
2. Copiez l'ID de ce Google Sheet (depuis l'URL, ex: .../d/ID_DU_FICHIER/edit).
3. Donnez ce prompt à Gemini (en remplaçant [VOTRE_ID_DE_FICHIER]) :

Ce qui se passe :

1. Gemini génère le script (avec SpreadsheetApp.openById(...)).
2. Il appelle votre outil en passant le gas_script ET whitelistItems: ["[VOTRE_ID_DE_FICHIER]"].
3. Votre serveur gas-fakes-mcp.js active le mode strict et n'autorise l'accès qu'à cet ID.
4. Le script s'exécute et affiche "Pomme" dans votre terminal.