Google Apps Script MCP Server

Instructions

Implementation Reference

• tools/google-app-script-api/apps-script-api/script-projects-deployments-list.js:15-118 (handler)

  Main handler function `executeFunction` that makes the Google Apps Script API call to list deployments for a given script project, including OAuth token retrieval, URL construction, fetch request, logging, and error handling.

  const executeFunction = async ({ scriptId, pageSize = 50, pageToken, fields, prettyPrint = true }) => {
    const baseUrl = 'https://script.googleapis.com';
    const startTime = Date.now();
  
    logger.info('API_CALL', 'Starting deployments list request', {
      scriptId,
      pageSize,
      pageToken: pageToken ? 'provided' : 'none',
      fields: fields || 'all',
      baseUrl
    });
  
    try {
      // Get OAuth access token
      logger.debug('API_CALL', 'Getting OAuth access token');
      const token = await getOAuthAccessToken();
      logger.debug('API_CALL', 'OAuth token obtained successfully');
      
      // Construct the URL with query parameters
      const url = new URL(`${baseUrl}/v1/projects/${scriptId}/deployments`);
      url.searchParams.append('pageSize', pageSize.toString());
      if (pageToken) url.searchParams.append('pageToken', pageToken);
      if (fields) url.searchParams.append('fields', fields);
      url.searchParams.append('alt', 'json');
      url.searchParams.append('prettyPrint', prettyPrint.toString());
  
      logger.debug('API_CALL', 'Constructed API URL', {
        url: url.toString(),
        pathSegments: url.pathname.split('/'),
        queryParams: Object.fromEntries(url.searchParams)
      });
  
      // Set up headers for the request
      const headers = {
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      };
  
      logger.logAPICall('GET', url.toString(), headers);
  
      // Perform the fetch request
      const fetchStartTime = Date.now();
      const response = await fetch(url.toString(), {
        method: 'GET',
        headers
      });
      
      const fetchDuration = Date.now() - fetchStartTime;
      const responseSize = response.headers.get('content-length') || 'unknown';
      
      logger.logAPIResponse('GET', url.toString(), response.status, fetchDuration, responseSize);
  
      // Check if the response was successful
      if (!response.ok) {
        const errorText = await response.text();
        
        logger.error('API_CALL', 'API request failed', {
          status: response.status,
          statusText: response.statusText,
          url: url.toString(),
          errorResponse: errorText,
          duration: Date.now() - startTime
        });
        
        console.error('API Error Response:', errorText);
        throw new Error(`HTTP ${response.status}: ${errorText}`);
      }
  
      // Parse and return the response data
      const data = await response.json();
      const totalDuration = Date.now() - startTime;
      
      logger.info('API_CALL', 'Deployments list request completed successfully', {
        scriptId,
        deploymentCount: data.deployments ? data.deployments.length : 0,
        hasNextPageToken: !!data.nextPageToken,
        totalDuration: `${totalDuration}ms`,
        responseSize: JSON.stringify(data).length
      });
      
      return data;
    } catch (error) {
      const totalDuration = Date.now() - startTime;
      
      logger.error('API_CALL', 'Deployments list request failed', {
        scriptId,
        error: {
          message: error.message,
          stack: error.stack
        },
        totalDuration: `${totalDuration}ms`
      });
      
      console.error('Error listing deployments:', error);
      return { 
        error: 'An error occurred while listing deployments.',
        details: {
          message: error.message,
          scriptId,
          timestamp: new Date().toISOString()
        }
      };
    }
  };

• tools/google-app-script-api/apps-script-api/script-projects-deployments-list.js:124-159 (schema)

  Tool definition `apiTool` export including the schema for input parameters (scriptId required, others optional) and tool metadata.

  const apiTool = {
    function: executeFunction,
    definition: {
      type: 'function',
      function: {
        name: 'script_projects_deployments_list',
        description: 'Lists the deployments of an Apps Script project.',
        parameters: {
          type: 'object',
          properties: {
            scriptId: {
              type: 'string',
              description: 'The ID of the script project.'
            },
            pageSize: {
              type: 'integer',
              description: 'The number of deployments to return per page.'
            },
            pageToken: {
              type: 'string',
              description: 'Token for pagination.'
            },
            fields: {
              type: 'string',
              description: 'Selector specifying which fields to include in a partial response.'
            },
            prettyPrint: {
              type: 'boolean',
              description: 'Returns response with indentations and line breaks.'
            }
          },
          required: ['scriptId']
        }
      }
    }
  };

• tools/paths.js:7-7 (registration)

  The tool file path is registered in the `toolPaths` array, which drives dynamic tool discovery.

  'google-app-script-api/apps-script-api/script-projects-deployments-list.js',

• lib/tools.js:8-64 (registration)

  The `discoverTools` function dynamically imports and loads all tools (including this one) from toolPaths, wraps handlers with logging, and prepares them for MCP registration.

  export async function discoverTools() {
    logger.info('DISCOVERY', `Starting tool discovery for ${toolPaths.length} tool paths`);
    
    const toolPromises = toolPaths.map(async (file) => {
      try {
        logger.debug('DISCOVERY', `Loading tool from: ${file}`);
        const module = await import(`../tools/${file}`);
        
        if (!module.apiTool) {
          logger.warn('DISCOVERY', `Tool file missing apiTool export: ${file}`);
          return null;
        }
  
        const toolName = module.apiTool.definition?.function?.name;
        if (!toolName) {
          logger.warn('DISCOVERY', `Tool missing function name: ${file}`);
          return null;
        }
  
        // Wrap the original function with logging
        const originalFunction = module.apiTool.function;
        const wrappedFunction = withLogging(toolName, originalFunction);
  
        logger.debug('DISCOVERY', `Successfully loaded tool: ${toolName}`, {
          file,
          toolName,
          description: module.apiTool.definition?.function?.description
        });
  
        return {
          ...module.apiTool,
          function: wrappedFunction,
          path: file,
        };
      } catch (error) {
        logger.error('DISCOVERY', `Failed to load tool: ${file}`, {
          file,
          error: {
            message: error.message,
            stack: error.stack
          }
        });
        return null;
      }
    });
    
    const tools = (await Promise.all(toolPromises)).filter(Boolean);
    
    logger.info('DISCOVERY', `Tool discovery completed`, {
      totalPaths: toolPaths.length,
      successfullyLoaded: tools.length,
      failed: toolPaths.length - tools.length,
      toolNames: tools.map(t => t.definition?.function?.name).filter(Boolean)
    });
    
    return tools;
  }