mcp-gsheets

Instructions

Implementation Reference

• src/tools/check-access.ts:26-110 (handler)

  The core handler function that implements the tool logic: parses input, authenticates with Google Sheets API, checks read/write permissions by attempting API calls, handles errors, and returns permission status and recommendations.

  export async function handleCheckAccess(input: any) {
    try {
      const { spreadsheetId } = CheckAccessSchema.parse(input);
      const sheets = await getAuthenticatedClient();
  
      const permissions = {
        canRead: false,
        canWrite: false,
        canShare: false,
        isOwner: false,
        error: null as string | null,
      };
  
      try {
        // Try to read spreadsheet metadata
        const response = await sheets.spreadsheets.get({
          spreadsheetId,
          fields: 'properties.title,sheets.properties.sheetId,sheets.properties.title',
        });
  
        permissions.canRead = true;
  
        // Try to create a test request (but don't execute it) to check write permissions
        try {
          // Test write access by trying to prepare a values update
          await sheets.spreadsheets.values.update(
            {
              spreadsheetId,
              range: 'A1',
              valueInputOption: 'RAW',
              requestBody: {
                values: [['']],
              },
            },
            {
              // Use validateOnly to not actually write
              params: {
                validateOnly: true,
              },
            }
          );
          permissions.canWrite = true;
        } catch (writeError: any) {
          if (writeError.code === 403) {
            permissions.canWrite = false;
          } else if (writeError.code !== 400) {
            permissions.canWrite = true;
          }
        }
  
        return {
          spreadsheetId,
          title: response.data.properties?.title || 'Unknown',
          permissions,
          sheets:
            response.data.sheets?.map((sheet: any) => ({
              sheetId: sheet.properties?.sheetId,
              title: sheet.properties?.title,
            })) || [],
          recommendation: permissions.canWrite
            ? 'You have full read/write access to this spreadsheet.'
            : 'You have read-only access to this spreadsheet. To write data, the spreadsheet owner needs to grant you Editor permissions.',
        };
      } catch (error: any) {
        if (error.code === 404) {
          permissions.error = 'Spreadsheet not found. Check if the ID is correct.';
        } else if (error.code === 403) {
          permissions.error =
            'Access denied. The spreadsheet needs to be shared with your service account.';
        } else {
          permissions.error = error.message || 'Unknown error occurred';
        }
  
        return {
          spreadsheetId,
          permissions,
          error: permissions.error,
          recommendation:
            'Share the spreadsheet with your service account email and grant appropriate permissions.',
        };
      }
    } catch (error) {
      return handleError(error);
    }
  }

• src/tools/check-access.ts:6-24 (schema)

  Zod schema for input validation and the Tool definition including name, description, and inputSchema for MCP protocol compliance.

  const CheckAccessSchema = z.object({
    spreadsheetId: z.string().describe('The ID of the spreadsheet to check access for'),
  });
  
  export const checkAccessTool: Tool = {
    name: 'sheets_check_access',
    description:
      'Check access permissions for a spreadsheet. Returns information about what operations are allowed.',
    inputSchema: {
      type: 'object',
      properties: {
        spreadsheetId: {
          type: 'string',
          description: 'The ID of the spreadsheet to check access for',
        },
      },
      required: ['spreadsheetId'],
    },
  };

• src/index.ts:33-33 (registration)

  Registration of the tool handler in the toolHandlers Map used for executing called tools.

  ['sheets_check_access', tools.handleCheckAccess],

• src/index.ts:68-68 (registration)

  Registration of the tool definition in the allTools array used for listing available tools.

  tools.checkAccessTool,

• src/tools/index.ts:19-19 (registration)

  Re-export of the tool and handler from check-access module for barrel import in main index.

  export * from './check-access.js';