@mcpher/gas-fakes 2.3.8 → 2.3.9

package/README.md

@@ -183,6 +183,8 @@ As I mentioned earlier, to take this further, I'm going to need a lot of help to
 - [gas fakes intro video](https://youtu.be/oEjpIrkYpEM)
 - [getting started](GETTING_STARTED.md) - how to handle authentication for Workspace scopes.
 - [readme](README.md)
+- [Natural Language Automation with Gemini Skills & MCP Server](gemini-skills-mcp.md) - new skills-based agent approach.
+- [gf_agent documentation](../gf_agent/README.md) - instructions for the Gemini CLI automation agent and MCP server.
 - [gas fakes cli](gas-fakes-cli.md)
 - [github actions using adc](https://github.com/brucemcpherson/gas-fakes-actions-adc)
 - [github actions using dwd and wif](https://github.com/brucemcpherson/gas-fakes-actions-dwd)

package/gf_agent/scripts/builder.js

@@ -0,0 +1,62 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+const PROGRESS_DIR = './progress';
+const SKILLS_DIR = './gf_agent/skills';
+const INDEX_FILE = './gf_agent/index.md';
+
+async function build() {
+  await fs.mkdir(SKILLS_DIR, { recursive: true });
+
+  const files = await fs.readdir(PROGRESS_DIR);
+  const mdFiles = files.filter(f => f.endsWith('.md') || f.endsWith('.MD'));
+
+  let masterIndex = '# gf_agent Skills Index\n\nThis index lists all Google Apps Script services and classes supported by `gf_agent` via `gas-fakes`.\n\n';
+
+  for (const file of mdFiles) {
+    const content = await fs.readFile(path.join(PROGRESS_DIR, file), 'utf-8');
+    const serviceName = file.replace(/\.md$/i, '');
+    
+    // Extract classes
+    const classMatches = content.matchAll(/## Class: \[(.*?)\]/g);
+    const classes = [];
+    
+    for (const match of classMatches) {
+      const className = match[1];
+      // Find the table for this class
+      const classSection = content.slice(match.index);
+      const tableEnd = classSection.indexOf('## Class:') > 0 ? classSection.indexOf('## Class:', 10) : classSection.length;
+      const tableContent = classSection.slice(0, tableEnd);
+      
+      // Extract completed methods
+      const methodMatches = tableContent.matchAll(/\| \[(.*?)\]\(.*?\) \| .*? \| .*? \| .*? \| (completed) \|/g);
+      const methods = Array.from(methodMatches).map(m => m[1]);
+      
+      if (methods.length > 0) {
+        classes.push({ name: className, methods });
+      }
+    }
+
+    if (classes.length > 0) {
+      const skillFile = `${serviceName.toLowerCase()}.md`;
+      let skillContent = `# Service: ${serviceName}\n\n`;
+      
+      classes.forEach(c => {
+        skillContent += `## Class: ${c.name}\n\n`;
+        skillContent += `Supported Methods:\n`;
+        c.methods.forEach(m => {
+          skillContent += `- \`${m}\`\n`;
+        });
+        skillContent += '\n';
+      });
+
+      await fs.writeFile(path.join(SKILLS_DIR, skillFile), skillContent);
+      masterIndex += `- [${serviceName}](skills/${skillFile})\n`;
+    }
+  }
+
+  await fs.writeFile(INDEX_FILE, masterIndex);
+  console.log('Build complete! Skills and Index generated.');
+}
+
+build().catch(console.error);

package/package.json

@@ -38,7 +38,7 @@
   },
   "name": "@mcpher/gas-fakes",
   "author": "bruce mcpherson",
-  "version": "2.3.8",
+  "version": "2.3.9",
   "license": "MIT",
   "main": "main.js",
   "description": "An implementation of the Google Workspace Apps Script runtime: Run native App Script Code on Node and Cloud Run",

package/src/cli/mcp.js

@@ -1,49 +1,15 @@
-import fs from "fs";
-import path from "path";
-import { spawn } from "child_process";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { spawn } from "child_process";
 import { MCP_VERSION } from "./utils.js";
-import { getLibraries } from "./lib-manager.js";
-
-/**
- * Constructs the CLI arguments array for gas-fakes execution.
- */
-function buildCliArguments(params) {
-  const {
-    filename,
-    script,
-    args,
-    sandbox,
-    whitelistRead,
-    whitelistReadWrite,
-    whitelistReadWriteTrash,
-    json,
-  } = params;
-
-  const cliArgs = [];
-
-  if (filename) cliArgs.push("-f", filename);
-  if (script) cliArgs.push("-s", script);
-  if (args) cliArgs.push("-a", JSON.stringify(args));
-  if (sandbox) cliArgs.push("-x");
-  if (whitelistRead) cliArgs.push("-w", whitelistRead);
-  if (whitelistReadWrite) cliArgs.push("--ww", whitelistReadWrite);
-  if (whitelistReadWriteTrash) cliArgs.push("--wt", whitelistReadWriteTrash);
-  if (json) cliArgs.push("-j", JSON.stringify(json));
-
-  return cliArgs;
-}
 
 /**
- * Executes the gas-fakes command via child_process.spawn.
+ * Executes a GAS script using the gas-fakes CLI logic.
  */
-async function runGasFakesProcess(cliArgs) {
+async function runGasFakes(script) {
   return new Promise((resolve) => {
-    // Invoke the current node executable with the current script (gas-fakes.js)
-    // We assume process.argv[1] points to the entry point
-    const child = spawn(process.execPath, [process.argv[1], ...cliArgs], {
+    const child = spawn(process.execPath, [process.argv[1], "-s", script], {
       env: process.env,
       stdio: ["ignore", "pipe", "pipe"],
       shell: false,
@@ -52,223 +18,114 @@ async function runGasFakesProcess(cliArgs) {
     let stdoutData = "";
     let stderrData = "";
 
-    child.stdout.on("data", (data) => {
-      stdoutData += data.toString();
-    });
-
-    child.stderr.on("data", (data) => {
-      stderrData += data.toString();
-    });
+    child.stdout.on("data", (data) => (stdoutData += data.toString()));
+    child.stderr.on("data", (data) => (stderrData += data.toString()));
 
     child.on("close", (code) => {
       if (code === 0) {
         resolve({
-          content: [
-            { type: "text", text: stdoutData || "Execution finished." },
-          ],
+          content: [{ type: "text", text: stdoutData || "Success" }],
           isError: false,
         });
       } else {
-        const output = stderrData || stdoutData || "Unknown error occurred";
         resolve({
-          content: [{ type: "text", text: output }],
+          content: [{ type: "text", text: stderrData || stdoutData || "Error" }],
           isError: true,
         });
       }
     });
-
-    child.on("error", (err) => {
-      resolve({
-        content: [{ type: "text", text: err.message }],
-        isError: true,
-      });
-    });
-  });
-}
-
-function registerDefaultTool(server) {
-  const schema1 = {
-    description: [
-      `Use this to safely run Google Apps Script in a sandbox using gas-fakes.`,
-      `# Important`,
-      `- Use the extension of the Google Apps Script files as \`js\`. Don't use \`gs\``,
-      `- When providing script content, ensure functions are called (e.g., add \`sample();\`).`,
-    ].join("\n"),
-    inputSchema: {
-      filename: z
-        .string()
-        .optional()
-        .describe(`Path to the file containing Google Apps Script.`),
-      script: z
-        .string()
-        .optional()
-        .describe(`Direct GAS script content string.`),
-      sandbox: z
-        .boolean()
-        .describe("Use to run Google Apps Script in a sandbox."),
-      whitelistRead: z
-        .string()
-        .optional()
-        .describe("Whitelist of file IDs for readonly access."),
-      whitelistReadWrite: z
-        .string()
-        .optional()
-        .describe("Whitelist of file IDs for read/write access."),
-      whitelistReadWriteTrash: z
-        .string()
-        .optional()
-        .describe("Whitelist of file IDs for read/write/trash access."),
-      json: z.any().optional().describe("Advanced sandbox configuration JSON."),
-    },
-  };
-
-  server.registerTool("run-gas-by-gas-fakes", schema1, async (args) => {
-    if (!args.filename && !args.script) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "Error: Either `filename` or `script` is required.",
-          },
-        ],
-        isError: true,
-      };
-    }
-    const cliArgs = buildCliArguments(args);
-    return await runGasFakesProcess(cliArgs);
-  });
-
-  const schema2 = {
-    description: "Use this to create the tools of the MCP server...",
-    inputSchema: {
-      filename: z.string().describe("Filename of the tool file (.js)."),
-      tools: z.array(
-        z.object({
-          name: z.string(),
-          schema: z.string(),
-          gas_script: z.string(),
-          libraries: z.array(z.string()).default([]),
-        })
-      ),
-    },
-  };
-
-  server.registerTool("create-new-tools", schema2, async (args) => {
-    if (!args.filename || !args.tools) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "Error: `filename` and `tools` are required.",
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    const tool_ar = [];
-    for (let i = 0; i < args.tools.length; i++) {
-      const { name, schema, gas_script, libraries } = args.tools[i];
-      tool_ar.push(
-        `{ name: "${name}", schema: ${schema}, func: (object = {}) => { \n\n${gas_script} }, libraries: ${JSON.stringify(
-          libraries || []
-        )} }`
-      );
-    }
-
-    const tool_script = [
-      `import { z } from "zod";`,
-      ``,
-      `const tools = [${tool_ar.join(", ")}];`,
-    ].join("\n");
-    const absolutePath = path.resolve(process.cwd(), args.filename);
-    fs.writeFileSync(absolutePath, tool_script);
-    return {
-      content: [
-        {
-          type: "text",
-          text: `A new file including tools for gas-fakes-mcp was successfully created as "${absolutePath}".`,
-        },
-      ],
-      isError: false,
-    };
   });
 }
 
-async function registerCustomTools(server, toolsPath) {
-  if (!toolsPath || !fs.existsSync(toolsPath)) {
-    if (toolsPath) console.error(`No tool file: ${toolsPath}`);
-    return;
+const SERVICES = [
+  {
+    name: "spreadsheet_service",
+    description: "Automate Google Sheets: Create, read, and modify spreadsheets, ranges, and formatting.",
+    example: "const ss = SpreadsheetApp.create('Test'); ss.getActiveSheet().getRange('A1').setValue('Hello');"
+  },
+  {
+    name: "document_service",
+    description: "Automate Google Docs: Create and edit documents, paragraphs, tables, and styles.",
+    example: "const doc = DocumentApp.create('Hello'); doc.getBody().appendParagraph('World');"
+  },
+  {
+    name: "drive_service",
+    description: "Manage Google Drive: Search files, create folders, and handle permissions.",
+    example: "const files = DriveApp.getFilesByName('Test'); while(files.hasNext()) console.log(files.next().getName());"
+  },
+  {
+    name: "gmail_service",
+    description: "Automate Gmail: Send emails, search threads, and manage labels.",
+    example: "GmailApp.sendEmail('test@example.com', 'Subject', 'Body');"
+  },
+  {
+    name: "calendar_service",
+    description: "Manage Google Calendar: Create events, list calendars, and handle invitations.",
+    example: "CalendarApp.getDefaultCalendar().createEvent('Meeting', new Date(), new Date());"
+  },
+  {
+    name: "slides_service",
+    description: "Automate Google Slides: Create and edit presentations, slides, and shapes.",
+    example: "const deck = SlidesApp.create('Presentation'); deck.appendSlide().insertShape(SlidesApp.ShapeType.RECTANGLE);"
+  },
+  {
+    name: "forms_service",
+    description: "Automate Google Forms: Create forms, add items, and manage responses.",
+    example: "const form = FormApp.create('Survey'); form.addTextItem().setTitle('Name');"
+  },
+  {
+    name: "jdbc_service",
+    description: "Connect to databases via JDBC: Execute SQL queries and manage connections.",
+    example: "const conn = Jdbc.getConnection(url, user, pass); const stmt = conn.createStatement();"
+  },
+  {
+    name: "utilities_service",
+    description: "General utilities: Formatting, parsing, and base64 encoding/decoding.",
+    example: "const base64 = Utilities.base64Encode('hello');"
+  },
+  {
+    name: "urlfetch_service",
+    description: "HTTP Requests: Fetch external resources and APIs via GET/POST.",
+    example: "const res = UrlFetchApp.fetch('https://api.example.com'); console.log(res.getContentText());"
   }
+];
 
-  const absolutePath = path.resolve(process.cwd(), toolsPath);
-  let toolsStr = fs.readFileSync(absolutePath, "utf8");
-  toolsStr = toolsStr.replace(/^import.*/gm, "");
-  const getTools = new Function("z", `${toolsStr} return tools || [];`);
-  const tools = getTools(z);
-
-  if (!tools || tools.length === 0) return;
-
-  for (let i = 0; i < tools.length; i++) {
-    const tool = tools[i];
-    const extendedSchema = { ...tool.schema };
-    extendedSchema.inputSchema = {
-      gas_args: z
-        .object(tool.schema.inputSchema)
-        .describe("Arguments for Google Apps Script."),
-      sandbox: z.boolean().describe("Run in sandbox."),
-      whitelistRead: z.string().optional(),
-      whitelistReadWrite: z.string().optional(),
-      whitelistReadWriteTrash: z.string().optional(),
-      json: z.any().optional(),
-    };
-
-    let originalFuncStr = tool.func.toString();
-    if (tool.libraries && tool.libraries.length > 0) {
-      const gas_library = await getLibraries({ libraries: tool.libraries });
-
-      if (gas_library && gas_library.length > 0) {
-        const libs = gas_library.reduce((ar, { identifier, libScript }) => {
-          if (originalFuncStr.includes(identifier)) {
-            ar.push(libScript);
-          }
-          return ar;
-        }, []);
-        if (libs.length > 0) {
-          originalFuncStr = `(object = {}) => {\n\n${libs.join(
-            "\n\n"
-          )}\n\nconst main_gas_fakes = ${originalFuncStr}\n\nreturn main_gas_fakes(object);\n}`;
-        }
-      }
-    }
-
-    const toolHandler = async (opts) => {
-      const wrappedScript = `return (${originalFuncStr})(args)`;
-      const cliArgs = buildCliArguments({
-        script: wrappedScript,
-        args: opts.gas_args,
-        ...opts,
-      });
-      return await runGasFakesProcess(cliArgs);
-    };
-
-    server.registerTool(tool.name, extendedSchema, toolHandler);
-  }
-}
-
-export async function startMcpServer(options) {
-  const { tools } = options;
+export async function startMcpServer() {
   const server = new McpServer({
-    name: "gas-fakes-mcp",
+    name: "gas-fakes-skills-mcp",
     version: MCP_VERSION,
   });
 
-  registerDefaultTool(server);
-
-  if (tools) {
-    await registerCustomTools(server, tools);
+  // Register a tool for each high-level service
+  for (const service of SERVICES) {
+    server.registerTool(
+      service.name,
+      {
+        description: `${service.description}\nExample script:\n${service.example}`,
+        inputSchema: {
+          script: z.string().describe("The Google Apps Script code to execute locally."),
+        },
+      },
+      async ({ script }) => {
+        return await runGasFakes(script);
+      }
+    );
   }
 
+  // Also add a generic tool for tasks that span multiple services
+  server.registerTool(
+    "workspace_agent",
+    {
+      description: "A general-purpose agent to automate tasks across multiple Google Workspace services (Sheets, Docs, Drive, etc.)",
+      inputSchema: {
+        script: z.string().describe("The Google Apps Script code to execute locally."),
+      },
+    },
+    async ({ script }) => {
+      return await runGasFakes(script);
+    }
+  );
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/src/cli/setup.js

@@ -610,6 +610,41 @@ export async function initializeConfiguration(options = {}) {
 
   fs.writeFileSync(envPath, envContent + "\n", "utf8");
   console.log("Setup complete. Your .env file has been updated.");
+
+  // --- Skill Installation Hint ---
+  console.log("\n--- Gemini CLI Integration ---");
+  const skillResponse = await prompts({
+    type: "confirm",
+    name: "installSkills",
+    message: "Would you like to install the gas-fakes skills for Gemini CLI?",
+    initial: true,
+  });
+
+  if (skillResponse.installSkills) {
+    console.log("Installing Gemini CLI skills and MCP server...");
+    try {
+      // 1. Install the agent skill
+      const skillCmd = "gemini skills install https://github.com/brucemcpherson/gas-fakes.git --path gf_agent";
+      console.log(`Executing: ${skillCmd}`);
+      execSync(skillCmd, { stdio: "inherit" });
+
+      // 2. Add the MCP server
+      const mcpCmd = "gemini mcp add --scope project gas-fakes-mcp gas-fakes mcp";
+      console.log(`Executing: ${mcpCmd}`);
+      execSync(mcpCmd, { stdio: "inherit" });
+
+      console.log("\x1b[1;32mInstallation complete!\x1b[0m");
+      console.log("\nYou can now use natural language to automate tasks:");
+      console.log("   \x1b[1;33m\"Create a spreadsheet of my recent Drive files\"\x1b[0m");
+    } catch (err) {
+      console.error(`\x1b[1;31mError during Gemini installation: ${err.message}\x1b[0m`);
+      console.log("You may need to install them manually:");
+      console.log("1. gemini skills install https://github.com/brucemcpherson/gas-fakes.git --path gf_agent");
+      console.log("2. gemini mcp add --scope project gas-fakes-mcp gas-fakes mcp");
+    }
+  } else {
+    console.log("Skipping Gemini CLI integration.");
+  }
 }
 
 /**

package/src/services/gmailapp/fakegmailmessage.js

@@ -31,6 +31,68 @@ class FakeGmailMessage {
     return newFakeGmailThread(threadResource);
   }
   
+  /**
+   * Helper to get a header value.
+   * @param {string} name - Header name
+   * @returns {string}
+   */
+  __getHeader(name) {
+    if (this.__messageResource.payload && this.__messageResource.payload.headers) {
+      const header = this.__messageResource.payload.headers.find(h => h.name.toLowerCase() === name.toLowerCase());
+      return header ? header.value : '';
+    }
+    return '';
+  }
+
+  /**
+   * Gets the subject of this message.
+   * @returns {string} The subject.
+   */
+  getSubject() {
+    ScriptApp.__behavior.checkMethod('GmailMessage', 'getSubject');
+    return this.__getHeader('Subject');
+  }
+
+  /**
+   * Gets the date and time of this message.
+   * @returns {Date} The date and time.
+   */
+  getDate() {
+    ScriptApp.__behavior.checkMethod('GmailMessage', 'getDate');
+    if (this.__messageResource.internalDate) {
+      return new Date(parseInt(this.__messageResource.internalDate, 10));
+    }
+    const dateHeader = this.__getHeader('Date');
+    return dateHeader ? new Date(dateHeader) : new Date();
+  }
+
+  /**
+   * Gets the snippet of the email.
+   * @returns {string} The snippet.
+   */
+  getSnippet() {
+    ScriptApp.__behavior.checkMethod('GmailMessage', 'getSnippet');
+    return this.__messageResource.snippet || '';
+  }
+
+  /**
+   * Gets the sender of this message.
+   * @returns {string} The sender's email address.
+   */
+  getFrom() {
+    ScriptApp.__behavior.checkMethod('GmailMessage', 'getFrom');
+    return this.__getHeader('From');
+  }
+
+  /**
+   * Gets the recipient of this message.
+   * @returns {string} The recipient's email address.
+   */
+  getTo() {
+    ScriptApp.__behavior.checkMethod('GmailMessage', 'getTo');
+    return this.__getHeader('To');
+  }
+
   toString() {
     return this.__fakeObjectType;
   }

package/src/services/gmailapp/fakegmailthread.js

@@ -20,6 +20,23 @@ class FakeGmailThread {
     return this.__threadResource.id;
   }
 
+  /**
+   * Gets the messages in this thread.
+   * @returns {GmailMessage[]} An array of messages in this thread.
+   */
+  getMessages() {
+    ScriptApp.__behavior.checkMethod('GmailThread', 'getMessages');
+    if (globalThis.GmailApp) {
+      return globalThis.GmailApp.getMessagesForThread(this);
+    }
+    // Fallback if GmailApp isn't initialized, though it should be.
+    if (this.__threadResource.messages) {
+      const { newFakeGmailMessage } = require('./fakegmailmessage.js');
+      return this.__threadResource.messages.map(m => newFakeGmailMessage(m));
+    }
+    return [];
+  }
+
   /**
    * Gets the labels of this thread.
    * @returns {GmailLabel[]} An array of labels for this thread.

package/summarize_advanced.js

@@ -0,0 +1,69 @@
+import './main.js';
+
+try {
+  console.log('Searching for emails from Martin...');
+  
+  // Search Gmail for messages from Martin (getting up to 10 recent threads)
+  const threads = GmailApp.search('from:Martin', 0, 10);
+  
+  if (threads.length === 0) {
+    console.log('No emails found from Martin.');
+    process.exit(0);
+  }
+
+  console.log(`Found ${threads.length} threads. Creating summary doc...`);
+
+  // Create the Document
+  const doc = DocumentApp.create('Email Summary: Martin');
+  const body = doc.getBody();
+  
+  // Add a title
+  body.appendParagraph('Summary of Recent Emails from Martin')
+      .setHeading(DocumentApp.ParagraphHeading.TITLE);
+  
+  body.appendParagraph(`Generated on: ${new Date().toLocaleString()}`);
+  body.appendParagraph(''); 
+
+  // We have to use the advanced Gmail service directly because gas-fakes' 
+  // FakeGmailMessage does not yet support getSubject(), getDate(), or getSnippet()
+  for (const thread of threads) {
+    // Get the raw thread resource from the Gmail API
+    const threadResource = Gmail.Users.Threads.get('me', thread.getId());
+    if (!threadResource.messages || threadResource.messages.length === 0) continue;
+    
+    const firstMsg = threadResource.messages[0];
+    
+    // Extract Subject from headers
+    const headers = firstMsg.payload && firstMsg.payload.headers ? firstMsg.payload.headers : [];
+    const subjectHeader = headers.find(h => h.name.toLowerCase() === 'subject');
+    const dateHeader = headers.find(h => h.name.toLowerCase() === 'date');
+    
+    const subject = subjectHeader ? subjectHeader.value : 'No Subject';
+    const date = dateHeader ? dateHeader.value : 'Unknown Date';
+    
+    body.appendParagraph(`Subject: ${subject}`)
+        .setHeading(DocumentApp.ParagraphHeading.HEADING1);
+    
+    for (const msg of threadResource.messages) {
+      const msgHeaders = msg.payload && msg.payload.headers ? msg.payload.headers : [];
+      const msgDateHeader = msgHeaders.find(h => h.name.toLowerCase() === 'date');
+      const msgDate = msgDateHeader ? msgDateHeader.value : 'Unknown Date';
+      
+      body.appendParagraph(`Date: ${msgDate}`)
+          .setHeading(DocumentApp.ParagraphHeading.HEADING3);
+      
+      const snippet = msg.snippet || "No content.";
+      body.appendParagraph(snippet);
+    }
+    
+    body.appendParagraph(''); // Spacing
+  }
+
+  doc.saveAndClose();
+
+  console.log(`Successfully created document "${doc.getName()}"`);
+  console.log(`Document URL: ${doc.getUrl()}`);
+
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+}