@google/clasp 3.0.4-alpha → 3.0.5-alpha

package/README.md

@@ -394,6 +394,8 @@ Updates local files with Apps Script project.
 #### Options
 
 - `--versionNumber <number>`: The version number of the project to retrieve.
+- `--deleteUnusedFiles`: Deletes local files that would have been pushed that were not returned by the server. Prompts for confirmation
+- `--force`: Used with `--deleteUnusedFiles` to automatically confirm. Use with caution.
 
 #### Examples
 
@@ -541,6 +543,23 @@ Lists your most recent Apps Script projects.
 
 - `clasp list-scripts`: Prints `helloworld1 – xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ...`
 
+### MCP (EXPERIMENTAL)
+
+Runs clasp in MCP (model context protocol) mode for use with coding agents. Configure clasp as a local tool using STDIO transport. While running in MCP mode clasp uses the same credentials as
+normal when used as a CLI. Run `clasp login` ahead of time to authorize.
+
+When used in MCP mode clasp does not need to be started from the project directory. The project directoy is specified in the tool calls. Switching projects does not require a restart of the MCP server, while switching credentials does.
+
+This feature is experimental and currently offers a limited subset of tools for agents. Feedback is welcome.
+
+#### Options
+
+N/A
+
+#### Examples
+
+- `clasp mcp`
+
 ## Advanced Commands
 
 > **NOTE**: These commands require Project ID/credentials setup ([see below](#projectid-optional)).

package/build/src/commands/program.js

@@ -24,6 +24,7 @@ import { command as runCommand } from './run-function.js';
 import { command as setupLogsCommand } from './setup-logs.js';
 import { command as authStatusCommand } from './show-authorized-user.js';
 import { command as filesStatusCommand } from './show-file-status.js';
+import { command as mcpCommand } from './start-mcp.js';
 import { command as tailLogsCommand } from './tail-logs.js';
 import { dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -31,10 +32,14 @@ import { readPackageUpSync } from 'read-package-up';
 import { initAuth } from '../auth/auth.js';
 import { initClaspInstance } from '../core/clasp.js';
 import { intl } from '../intl.js';
-export function makeProgram(exitOveride) {
+export function getVersion() {
     const __dirname = dirname(fileURLToPath(import.meta.url));
     const manifest = readPackageUpSync({ cwd: __dirname });
     const version = manifest ? manifest.packageJson.version : 'unknown';
+    return version;
+}
+export function makeProgram(exitOveride) {
+    const version = getVersion();
     const program = new Command();
     program.exitOverride(exitOveride);
     program.storeOptionsAsProperties(false);
@@ -92,6 +97,7 @@ export function makeProgram(exitOveride) {
         listCommand,
         createVersionCommand,
         listVersionsCommand,
+        mcpCommand,
     ];
     for (const cmd of commandsToAdd) {
         program.addCommand(cmd);

package/build/src/commands/pull.js

@@ -1,19 +1,55 @@
 import { Command } from 'commander';
+import fs from 'fs/promises';
+import inquirer from 'inquirer';
 import { intl } from '../intl.js';
-import { withSpinner } from './utils.js';
+import { isInteractive, withSpinner } from './utils.js';
 export const command = new Command('pull')
     .description('Fetch a remote project')
     .option('--versionNumber <version>', 'The version number of the project to retrieve.')
+    .option('-d, --deleteUnusedFiles ', 'Delete local files that are not in the remote project. Use with caution.')
+    .option('-f, --force', 'Forcibly delete local files that are not in the remote project without prompting.')
     .action(async function (options) {
     const clasp = this.opts().clasp;
     const versionNumber = options.versionNumber;
-    const spinnerMsg = intl.formatMessage({ id: "jilcJH", defaultMessage: [{ type: 0, value: "Pulling files..." }] });
+    const forceDelete = options.force;
+    let spinnerMsg = intl.formatMessage({ id: "dh7Bw6", defaultMessage: [{ type: 0, value: "Checking local files..." }] });
+    const localFiles = await clasp.files.collectLocalFiles();
+    spinnerMsg = intl.formatMessage({ id: "jilcJH", defaultMessage: [{ type: 0, value: "Pulling files..." }] });
     const files = await withSpinner(spinnerMsg, async () => {
         return await clasp.files.pull(versionNumber);
     });
+    if (options.deleteUnusedFiles) {
+        const filesToDelete = localFiles.filter(f => !files.find(p => p.localPath === f.localPath));
+        await deleteLocalFiles(filesToDelete, forceDelete);
+    }
     files.forEach(f => console.log(`└─ ${f.localPath}`));
     const successMessage = intl.formatMessage({ id: "4mRAfN", defaultMessage: [{ type: 0, value: "Pulled " }, { type: 6, value: "count", options: { "=0": { value: [{ type: 0, value: "no files." }] }, one: { value: [{ type: 0, value: "one file." }] }, other: { value: [{ type: 7 }, { type: 0, value: " files" }] } }, offset: 0, pluralType: "cardinal" }, { type: 0, value: "." }] }, {
         count: files.length,
     });
     console.log(successMessage);
 });
+async function deleteLocalFiles(filesToDelete, forceDelete = false) {
+    if (!filesToDelete || filesToDelete.length === 0) {
+        return;
+    }
+    const skipConfirmation = forceDelete;
+    if (!isInteractive() && !forceDelete) {
+        const msg = intl.formatMessage({ id: "zLuvSg", defaultMessage: [{ type: 0, value: "You are not in an interactive terminal and --force not used. Skipping file deletion." }] });
+        console.warn(msg);
+        return;
+    }
+    for (const file of filesToDelete) {
+        if (!skipConfirmation) {
+            const confirm = await inquirer.prompt({
+                type: 'confirm',
+                name: 'deleteFile',
+                message: intl.formatMessage({ id: "lVx/lI", defaultMessage: [{ type: 0, value: "Delete " }, { type: 1, value: "file" }, { type: 0, value: "?" }] }, { file: file.localPath }),
+            });
+            if (!confirm.deleteFile) {
+                continue;
+            }
+        }
+        await fs.unlink(file.localPath);
+        console.log(intl.formatMessage({ id: "Nx315v", defaultMessage: [{ type: 0, value: "Deleted " }, { type: 1, value: "file" }] }, { file: file.localPath }));
+    }
+}

package/build/src/commands/start-mcp.js

@@ -0,0 +1,12 @@
+import { Command } from 'commander';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildMcpServer } from '../mcp/server.js';
+export const command = new Command('start-mcp-server')
+    .alias('mcp')
+    .description('Starts an MCP server for interacting with apps script.')
+    .action(async function () {
+    const auth = this.opts().auth;
+    const server = buildMcpServer(auth);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+});

package/build/src/core/clasp.js

@@ -63,11 +63,13 @@ export class Clasp {
     }
 }
 export async function initClaspInstance(options) {
+    var _a;
     debug('Initializing clasp instance');
     const projectRoot = await findProjectRootdDir(options.configFile);
     if (!projectRoot) {
-        debug('No project found, defaulting to cwd');
-        const rootDir = path.resolve(process.cwd());
+        const dir = (_a = options.rootDir) !== null && _a !== void 0 ? _a : process.cwd();
+        debug(`No project found, defaulting to ${dir}`);
+        const rootDir = path.resolve(dir);
         const configFilePath = path.resolve(rootDir, '.clasp.json');
         const ignoreFile = await findIgnoreFile(rootDir, options.ignoreFile);
         const ignoreRules = await loadIgnoreFileOrDefaults(ignoreFile);

package/build/src/mcp/server.js

@@ -0,0 +1,329 @@
+import path from 'path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { mkdir } from 'fs/promises';
+import { z } from 'zod';
+import { getDefaultProjectName } from '../commands/create-script.js';
+import { getVersion } from '../commands/program.js';
+import { initClaspInstance } from '../core/clasp.js';
+export function buildMcpServer(auth) {
+    const server = new McpServer({
+        name: 'Clasp',
+        version: getVersion(),
+    });
+    server.tool('push_files', 'Pushes the local Apps Script project to the remote server.', {
+        projectDir: z
+            .string()
+            .describe('The local directory of the Apps Script project to push. Must contain a .clasp.json file containing the project info.'),
+    }, {
+        title: 'Push project files to Apps Script',
+        openWorldHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        readOnlyHint: false,
+    }, async ({ projectDir }) => {
+        if (!projectDir) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Project directory is required.',
+                    },
+                ],
+            };
+        }
+        const clasp = await initClaspInstance({
+            credentials: auth.credentials,
+            configFile: projectDir,
+            rootDir: projectDir,
+        });
+        try {
+            const files = await clasp.files.push();
+            const fileList = files.map(file => ({
+                type: 'text',
+                text: `Updated file: ${path.resolve(file.localPath)}`,
+            }));
+            return {
+                status: 'success',
+                content: [
+                    {
+                        type: 'text',
+                        text: `Pushed project in ${projectDir} to remote server successfully.`,
+                    },
+                    ...fileList,
+                ],
+                structuredContent: {
+                    scriptId: clasp.project.scriptId,
+                    projectDir: projectDir,
+                    files: files.map(file => path.resolve(file.localPath)),
+                },
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error pushing project: ${err.message}`,
+                    },
+                ],
+            };
+        }
+    });
+    server.tool('pull_files', 'Pulls files from Apps Script project to local file system.', {
+        projectDir: z
+            .string()
+            .describe('The local directory of the Apps Script project to update. Must contain a .clasp.json file containing the project info.'),
+    }, {
+        title: 'Pull project files from Apps Script',
+        openWorldHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        readOnlyHint: false,
+    }, async ({ projectDir }) => {
+        if (!projectDir) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Project directory is required.',
+                    },
+                ],
+            };
+        }
+        const clasp = await initClaspInstance({
+            credentials: auth.credentials,
+            configFile: projectDir,
+            rootDir: projectDir,
+        });
+        try {
+            const files = await clasp.files.pull();
+            const fileList = files.map(file => ({
+                type: 'text',
+                text: `Updated file: ${path.resolve(file.localPath)}`,
+            }));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Pushed project in ${projectDir} to remote server successfully.`,
+                    },
+                    ...fileList,
+                ],
+                structuredContent: {
+                    scriptId: clasp.project.scriptId,
+                    projectDir: projectDir,
+                    files: files.map(file => path.resolve(file.localPath)),
+                },
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error pushing project: ${err.message}`,
+                    },
+                ],
+            };
+        }
+    });
+    server.tool('create_project', 'Create a new apps script project.', {
+        projectDir: z.string().describe('The local directory where the Apps Script project will be created.'),
+        sourceDir: z
+            .string()
+            .optional()
+            .describe('Local directory relative to projectDir where the Apps Script source files are located. If not specified, files are placed in the project directory.'),
+        projectName: z
+            .string()
+            .optional()
+            .describe('Name of the project. If not provided, the project name will be infered from the directory.'),
+    }, {
+        title: 'Create Apps Script project',
+        openWorldHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        readOnlyHint: false,
+    }, async ({ projectDir, sourceDir, projectName }) => {
+        if (!projectDir) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Project directory is required.',
+                    },
+                ],
+            };
+        }
+        await mkdir(projectDir, { recursive: true });
+        if (!projectName) {
+            projectName = getDefaultProjectName(projectDir);
+        }
+        const clasp = await initClaspInstance({
+            credentials: auth.credentials,
+            configFile: projectDir,
+            rootDir: projectDir,
+        });
+        clasp.withContentDir(sourceDir !== null && sourceDir !== void 0 ? sourceDir : '.');
+        try {
+            const id = await clasp.project.createScript(projectName);
+            const files = await clasp.files.pull();
+            await clasp.project.updateSettings();
+            const fileList = files.map(file => ({
+                type: 'text',
+                text: `Updated file: ${path.resolve(file.localPath)}`,
+            }));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Created project ${id} in ${projectDir} successfully.`,
+                    },
+                    ...fileList,
+                ],
+                structuredContent: {
+                    scriptId: id,
+                    projectDir: projectDir,
+                    files: files.map(file => path.resolve(file.localPath)),
+                },
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error pushing project: ${err.message}`,
+                    },
+                ],
+            };
+        }
+    });
+    server.tool('clone_project', 'Clones and pulls an existing Apps Script project to a local directory.', {
+        projectDir: z.string().describe('The local directory where the Apps Script project will be created.'),
+        sourceDir: z
+            .string()
+            .optional()
+            .describe('Local directory relative to projectDir where the Apps Script source files are located. If not specified, files are placed in the project directory.'),
+        scriptId: z.string().optional().describe('ID of the Apps Script project to clone.'),
+    }, {
+        title: 'Create Apps Script project',
+        openWorldHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        readOnlyHint: false,
+    }, async ({ projectDir, sourceDir, scriptId }) => {
+        if (!projectDir) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Project directory is required.',
+                    },
+                ],
+            };
+        }
+        await mkdir(projectDir, { recursive: true });
+        if (!scriptId) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Script ID is required.',
+                    },
+                ],
+            };
+        }
+        const clasp = await initClaspInstance({
+            credentials: auth.credentials,
+            configFile: projectDir,
+            rootDir: projectDir,
+        });
+        clasp.withContentDir(sourceDir !== null && sourceDir !== void 0 ? sourceDir : '.').withScriptId(scriptId);
+        try {
+            const files = await clasp.files.pull();
+            clasp.project.updateSettings();
+            const fileList = files.map(file => ({
+                type: 'text',
+                text: `Updated file: ${path.resolve(file.localPath)}`,
+            }));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Cloned project ${scriptId} in ${projectDir} successfully.`,
+                    },
+                    ...fileList,
+                ],
+                structuredContent: {
+                    scriptId: scriptId,
+                    projectDir: projectDir,
+                    files: files.map(file => path.resolve(file.localPath)),
+                },
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error pushing project: ${err.message}`,
+                    },
+                ],
+            };
+        }
+    });
+    server.tool('list_projects', 'List Apps Script projects', {}, {
+        title: 'List Apps Script projects',
+        openWorldHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        readOnlyHint: false,
+    }, async () => {
+        const clasp = await initClaspInstance({
+            credentials: auth.credentials,
+        });
+        try {
+            const scripts = await clasp.project.listScripts();
+            const scriptList = scripts.results.map(script => ({
+                type: 'text',
+                text: `${script.name} (${script.id})`,
+            }));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Found ${scripts.results.length} Apps Script projects (script ID in parentheses):`,
+                    },
+                    ...scriptList,
+                ],
+                structuredContent: {
+                    scripts: scripts.results.map(script => ({
+                        scriptId: script.id,
+                        name: script.name,
+                    })),
+                },
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error listing projects: ${err.message}`,
+                    },
+                ],
+            };
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google/clasp",
-  "version": "3.0.4-alpha",
+  "version": "3.0.5-alpha",
   "description": "Develop Apps Script Projects locally",
   "type": "module",
   "exports": "./build/src/index.js",
@@ -72,6 +72,7 @@
     "inquirer-autocomplete-standalone": "^0.8.1",
     "loud-rejection": "^2.2.0",
     "micromatch": "^4.0.8",
+    "@modelcontextprotocol/sdk": "^1.12.1",
     "normalize-path": "^3.0.0",
     "open": "^10.1.2",
     "ora": "^8.1.1",
@@ -80,7 +81,8 @@
     "read-package-up": "^11.0.0",
     "server-destroy": "^1.0.1",
     "split-lines": "^3.0.0",
-    "strip-bom": "^5.0.0"
+    "strip-bom": "^5.0.0",
+    "zod": "^3.25.36"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",