configure

Files (1)

• SKILL.md

SKILL.md (first lines)

# GWS Configure

Walk the user through the complete setup of the GWS connector plugin, step by step.

## Step 1: Check current state

Call `gws.accounts.list` to see if any accounts are already connected.

If accounts exist, show them and ask if the user wants to add another account or reconfigure.

## Step 2: Google Cloud Project setup

If no credentials are configured (the tool returns an error about missing credentials), guide the user through creating a GCP project:

### 2a. Create or select a GCP project

Tell the user:

> To connect Google accounts, you need OAuth credentials from a Google Cloud project. Here's how to set them up (one-time):
>
> **1. Go to the Google Cloud Console:**
>    https://console.cloud.google.com/
>
> **2. Create a new project** (or select an existing one):
>    - Click the project dropdown at the top → "New Project"
>    - Name it something like "GWS Connector"
>    - Click "Create"
>
> **3. Enable the required APIs** — go to each link and click "Enable":
>    - Gmail API: https://console.cloud.google.com/apis/library/gmail.googleapis.com
>    - Google Calendar API: https://console.cloud.google.com/apis/library/calendar-json.googleapis.com
>    - Google Drive API: https://console.cloud.google.com/apis/library/drive.googleapis.com
>    - Google Sheets API: https://console.cloud.google.com/apis/library/sheets.googleapis.com
>    - Google Docs API: https://console.cloud.google.com/apis/library/docs.googleapis.com
>    - Google People API: https://console.cloud.google.com/apis/library/people.googleapis.com
>    - Google Tasks API: https://console.cloud.google.com/apis/library/tasks.googleapis.com
>    - Google Slides API: https://console.cloud.google.com/apis/library/slides.googleapis.com
>
> **4. Configure the OAuth consent screen:**
>    - Go to: https://console.cloud.google.com/auth/consent
>    - Choose "External" (unless you have a Google Workspace org and want "Internal")
>    - Fill in the app name (e.g., "Claude GWS") and your email for support contact
>    - Click "Save"
>
> **5. Add scopes** — go to the Data Access tab:
>    - Go to: https://console.cloud.google.com/auth/scopes
>    - Click "Add or Remove Scopes"
>    - In the panel that opens, paste these scopes into the "Manually add scopes" box at the bottom (one per line):
>      - `https://www.googleapis.com/auth/gmail.modify`
>      - `https://www.googleapis.com/auth/calendar`
>      - `https://www.googleapis.com/auth/drive`
>      - `https://www.googleapis.com/auth/spreadsheets`
>      - `https://www.googleapis.com/auth/documents`
>      - `https://www.googleapis.com/auth/contacts.readonly`
>      - `https://www.googleapis.com/auth/directory.readonly`
>      - `https://www.googleapis.com/auth/tasks`
>      - `https://www.googleapis.com/auth/presentations`
>      - `https://www.googleapis.com/auth/userinfo.email`
>      - `https://www.googleapis.com/auth/userinfo.profile`
>    - Click "Update" to confirm, then "Save"
>
>    Why each scope is requested:
>
>    | Scope | Purpose | Tools using it |
>    |-------|---------|----------------|
>    | `gmail.modify` | Read/draft/modify messages and labels | `gws.mail.*` |
>    | `calendar` | Read/create/update events | `gws.cal.*` |
>    | `drive` | Search/read files across Drive | `gws.drive.*` |
>    | `spreadsheets` | Read and write Google Sheets cells and metadata | `gws.sheets.*` |
>    | `documents` | Read and write Google Docs content | `gws.docs.*` |
>    | `contacts.readonly` | Read-only search of your own Google Contacts | `gws.contacts.search` |
>    | `directory.readonly` | Read-only search of the Workspace org directory (Workspace accounts only) | `gws.contacts.directory_search` |
>    | `tasks` | Read and write Google Tasks lists and tasks | `gws.tasks.*` |
>    | `presentations` | Read and write Google Slides content | `gws.slides.*` |
>    | `userinfo.email` | Identify the authorizing account (email match on reauth) | account management |
>    | `userinfo.profile` | Store a display name alongside the email | account management |
>
> **6. Add test users:**
>    - Go to: https://console.cloud.google.com/auth/audience
>    - Add each Google email address you plan to connect
>
> **7. Create OAuth credentials:**
>    - Go to: https://console.cloud.google.com/auth/clients
>    - Click "+ Create Client" → "OAuth client ID"
>    - Application type: **Desktop app**
>    - Name it (e.g., "Claude GWS Desktop")
>    - Click "Create"
>    - **Download the JSON file** (click the download icon next to your new client)

Ask the user to share or point to the downloaded JSON file, or provide the Client ID and Client Secret directly.

### 2b. Read credentials from JSON file

If the user provides a path to the downloaded `client_secret_*.json` file:

1. Read the file to extract `client_id` and `client_secret` from the `installed` object
2. The JSON structure looks like: `{"installed": {"client_id": "...", "client_secret": "..."}}`
3. Use these values when calling `gws.accounts.add`

If the user provides Client ID and Client Secret directly as text, use those.

**Important:** Do NOT suggest setting environment variables. Credentials are stored per-account in the OS keychain — no env vars needed.

## Step 3: Connect accounts

Once credentials are available, help the user add their first account:

1. Ask what label they want (e.g., "personal", "work", "client-name")
2. Call `gws.accounts.add` with the label, clientId, and clientSecret
3. This opens a browser — tell the user to authorize access
4. **If the user gets "Access blocked: has not completed the Google verification process" (error 403):**
   - They need to add their Google email as a test user in the GCP project
   - Go to: https://console.cloud.google.com/auth/audience
   - Click "Add users" and enter the exact email address they're trying to authorize
   - Save, then retry the OAuth flow
5. Confirm success — the client secret is now stored in the OS keychain

Then ask: "Would you like to connect another account? Each account can use different OAuth credentials if it belongs to a different organization."

From orieg/gws-connector, MIT.

More from orieg/gws-connector