Gas Execution

Google Apps Script Execution and Development Skill

Follow these guidelines when writing, reviewing, and executing Google Apps Script (GAS) applications:

Script Execution via ggsrun

• Execution Tool (exe1): Always prefer the exe1 tool of the ggsrun MCP server to synchronize local code/directories and run the entry function in a single transaction.
• Opt-in Log Retrieval (Default Off): To guarantee sub-second execution, ggsrun does not fetch logs from Cloud Logging by default. If you need to inspect Logger.log() or console.log() outputs, you must explicitly set the log: true parameter (or use the --log / -l flag in CLI mode). Note that enabling log retrieval adds a 5–10 second delay to allow Google's indexing.
• Clock-Drift Immunity: ggsrun queries Cloud Logging using a wide past window (timestamp >= startTime - 60m) and completely omits any future upper bounds (timestamp <= ...). This makes the query completely immune to local clock drift (e.g., when the host machine's clock is minutes or hours behind the actual time). Do not worry about clock discrepancies when retrieving logs.
• Post-Detection Multi-Poll Buffer: Due to Google's parallel logging nodes, console.log and Logger.log can index several seconds apart. Once ggsrun detects the first log entry for the current Apps Script process_id, it automatically queries 4 more times at 2.0-second intervals (providing an 8.0-second stabilization window) to capture all lagging streams.
• TUI On-Demand Async Log Injection: When executing via the TUI (ggsrun fd), the execution result is displayed instantly without waiting. An overlay modal then prompts: "Do you want to retrieve execution logs from Cloud Logging?". If you select Yes, logs are fetched in a background goroutine and dynamically injected into the active text view.
• In-Memory Sandbox (sandbox): For secure execution, pass the path of your whitelist configuration JSON (e.g. sandbox: "sandbox_config.json") to exe1. This instructs ggsrun to generate a separate sandbox guard file (_for_sandbox_gas.gs) containing the whitelists, which is evaluated first alphabetically by the GAS V8 engine. The user's execution scripts only undergo static token replacement (e.g., SpreadsheetApp -> _wrappedSpreadsheetApp), meaning their line numbers remain completely unchanged. If an error occurs, the line numbers in the stack trace will match your local source files exactly, allowing you to debug directly.
• Auto-Cleanup & Resilient Rollback: ggsrun performs an in-memory backup of the remote project state (including all script files and the appsscript.json manifest). On execution completion, runtime sandboxing halts, or process interrupts (Ctrl+C), ggsrun automatically rolls back all file changes on the remote script project, leaving your codebase 100% clean and pristine. This cleanup behavior is enabled by default. To bypass this cleanup and leave the uploaded files in the remote project, use the undeleteScript: true option (or --undeleteScript / --ud flag in CLI mode).
• Intelligent Manifest Merging: When executing scripts that require Advanced Services or custom dependencies, you can upload a local appsscript.json manifest. ggsrun will automatically merge your dependencies (e.g., enabledAdvancedServices or custom libraries) with the remote project's existing manifest without breaking critical configurations like executionApi or webapp needed for execution.
• Self-Healing Recovery: If a script execution is interrupted and the remote project is left in an inconsistent state, you can run the ggsrun recover command to immediately restore the project to the pristine ggsrun state.
• Designing Return Values: The execution response displays only the value returned by the return statement of the executed function. Design your script to return a meaningful value representing the execution result.
• Detailed Logs: You can return detailed logs or execution summaries as the final return string to provide context and results to the user.
• JSON Serialization: If returning structured data (such as objects, arrays, or status maps), use JSON.stringify() to serialize it before returning.

Other ggsrun MCP Server Tools

Beyond the stateful script execution (exe1), you can leverage the following tools from the ggsrun-mcp server for managing files, projects, and directories on Google Drive:

1. searchfiles

• Purpose: Search for files or folders in Google Drive using standard Drive API v3 queries, with optional local regex filtering on filenames.
• Usage Guide: Specify the query (e.g., name = 'MyScript' and trashed = false or mimeType = 'application/vnd.google-apps.folder'). Optionally provide a regex pattern to filter result names.
• Example Case: Finding the folder ID named "Backup" or discovering spreadsheet files with a matching pattern:
  • Arguments: { "query": "mimeType = 'application/vnd.google-apps.spreadsheet' and trashed = false", "regex": "^Production_.*" }

2. filelist

• Purpose: Perform exact matches by File Name or resolve filenames by File ID on Google Drive.
• Usage Guide: Use searchbyname to find IDs matching an exact name, or searchbyid to get the metadata of a specific ID.
• Example Case: Quick lookup of a target Spreadsheet ID before execution:
  • Arguments: { "searchbyname": "TargetSpreadsheet" }

3. download

• Purpose: Download files or entire recursive folder structures to your local system, supporting on-the-fly Google Workspace format export.
• Usage Guide: Provide the target fileid. Use the extension parameter to convert Google Docs, Sheets, Slides, or Drawings to local formats (e.g., Doc -> PDF/Markdown, Sheet -> Excel/CSV).
• Example Case: Fetching a Google Spreadsheet as an .xlsx file into a local ./downloads folder:
  • Arguments: { "fileid": "SPREADSHEET_ID", "extension": "xlsx", "destination": "./downloads", "conflict-mode": "OverwriteIfNewer" }