connected-workspace-mcp 1.0.0

package/dist/src/tools/calendar/index.js

@@ -0,0 +1,123 @@
+import * as z from 'zod/v4';
+import { jsonText, runTool } from '../shared.js';
+export function registerCalendarTools(server, calendar) {
+    server.registerTool('calendar_list_events', {
+        description: 'List Google Calendar events in a date/time range.',
+        inputSchema: z.object({
+            calendarId: z.string().default('primary'),
+            timeMin: z.iso.datetime(),
+            timeMax: z.iso.datetime(),
+            query: z.string().optional(),
+            maxResults: z.number().int().min(1).max(250).default(50),
+        }),
+    }, async ({ calendarId, timeMin, timeMax, query, maxResults }) => runTool('calendar_list_events', async () => {
+        const result = await calendar.events.list({
+            calendarId,
+            timeMin,
+            timeMax,
+            q: query,
+            maxResults,
+            singleEvents: true,
+            orderBy: 'startTime',
+        });
+        return jsonText(result.data.items || []);
+    }));
+    server.registerTool('calendar_create_event', {
+        description: 'Schedule an event on Google Calendar.',
+        inputSchema: z.object({
+            calendarId: z.string().default('primary'),
+            summary: z.string().min(1),
+            description: z.string().optional(),
+            location: z.string().optional(),
+            start: z.iso.datetime(),
+            end: z.iso.datetime(),
+            timeZone: z.string().optional(),
+            attendees: z.array(z.string().email()).default([]),
+            sendUpdates: z.enum(['all', 'externalOnly', 'none']).default('all'),
+        }),
+    }, async ({ calendarId, summary, description, location, start, end, timeZone, attendees, sendUpdates, }) => runTool('calendar_create_event', async () => {
+        const result = await calendar.events.insert({
+            calendarId,
+            sendUpdates,
+            requestBody: {
+                summary,
+                description,
+                location,
+                start: { dateTime: start, timeZone },
+                end: { dateTime: end, timeZone },
+                attendees: attendees.map((email) => ({ email })),
+            },
+        });
+        return jsonText({
+            id: result.data.id,
+            htmlLink: result.data.htmlLink,
+            status: result.data.status,
+        });
+    }));
+    server.registerTool('calendar_update_event', {
+        description: 'Update fields on an existing Google Calendar event.',
+        inputSchema: z.object({
+            calendarId: z.string().default('primary'),
+            eventId: z.string().min(1),
+            summary: z.string().min(1).optional(),
+            description: z.string().optional(),
+            location: z.string().optional(),
+            start: z.iso.datetime().optional(),
+            end: z.iso.datetime().optional(),
+            timeZone: z.string().optional(),
+            attendees: z.array(z.string().email()).optional(),
+            sendUpdates: z.enum(['all', 'externalOnly', 'none']).default('all'),
+        }),
+    }, async ({ calendarId, eventId, summary, description, location, start, end, timeZone, attendees, sendUpdates, }) => runTool('calendar_update_event', async () => {
+        const result = await calendar.events.patch({
+            calendarId,
+            eventId,
+            sendUpdates,
+            requestBody: {
+                summary,
+                description,
+                location,
+                ...(start ? { start: { dateTime: start, timeZone } } : {}),
+                ...(end ? { end: { dateTime: end, timeZone } } : {}),
+                ...(attendees
+                    ? { attendees: attendees.map((email) => ({ email })) }
+                    : {}),
+            },
+        });
+        return jsonText({
+            id: result.data.id,
+            htmlLink: result.data.htmlLink,
+            status: result.data.status,
+        });
+    }));
+    server.registerTool('calendar_delete_event', {
+        description: 'Delete an event from Google Calendar.',
+        inputSchema: z.object({
+            calendarId: z.string().default('primary'),
+            eventId: z.string().min(1),
+            sendUpdates: z.enum(['all', 'externalOnly', 'none']).default('all'),
+        }),
+    }, async ({ calendarId, eventId, sendUpdates }) => runTool('calendar_delete_event', async () => {
+        await calendar.events.delete({ calendarId, eventId, sendUpdates });
+        return jsonText({ deleted: true, eventId });
+    }));
+    server.registerTool('calendar_free_busy', {
+        description: 'Read busy periods for one or more calendars in a date/time range.',
+        inputSchema: z.object({
+            calendarIds: z.array(z.string()).min(1).default(['primary']),
+            timeMin: z.iso.datetime(),
+            timeMax: z.iso.datetime(),
+            timeZone: z.string().optional(),
+        }),
+    }, async ({ calendarIds, timeMin, timeMax, timeZone }) => runTool('calendar_free_busy', async () => {
+        const result = await calendar.freebusy.query({
+            requestBody: {
+                timeMin,
+                timeMax,
+                timeZone,
+                items: calendarIds.map((id) => ({ id })),
+            },
+        });
+        return jsonText(result.data.calendars || {});
+    }));
+}

package/dist/src/tools/gmail/index.js

@@ -0,0 +1,177 @@
+import * as z from 'zod/v4';
+import { jsonText, runTool } from '../shared.js';
+function encodeMessage(message) {
+    return Buffer.from(message)
+        .toString('base64')
+        .replaceAll('+', '-')
+        .replaceAll('/', '_')
+        .replace(/=+$/, '');
+}
+function mimeMessage(input) {
+    const headers = [
+        `To: ${input.to.join(', ')}`,
+        ...(input.cc?.length ? [`Cc: ${input.cc.join(', ')}`] : []),
+        ...(input.bcc?.length ? [`Bcc: ${input.bcc.join(', ')}`] : []),
+        `Subject: ${input.subject}`,
+        ...(input.inReplyTo ? [`In-Reply-To: ${input.inReplyTo}`] : []),
+        ...(input.references ? [`References: ${input.references}`] : []),
+        'MIME-Version: 1.0',
+        'Content-Type: text/plain; charset=UTF-8',
+        'Content-Transfer-Encoding: 8bit',
+    ];
+    return [...headers, '', input.body].join('\r\n');
+}
+function decodedBody(part) {
+    if (!part)
+        return '';
+    if (part.mimeType === 'text/plain' && part.body?.data) {
+        return Buffer.from(part.body.data, 'base64url').toString('utf8');
+    }
+    for (const child of part.parts || []) {
+        const body = decodedBody(child);
+        if (body)
+            return body;
+    }
+    if (part.body?.data)
+        return Buffer.from(part.body.data, 'base64url').toString('utf8');
+    return '';
+}
+function headers(message) {
+    return Object.fromEntries((message.payload?.headers || [])
+        .filter((header) => header.name && header.value)
+        .map((header) => [header.name.toLowerCase(), header.value]));
+}
+const recipientsSchema = {
+    to: z.array(z.string().email()).min(1),
+    cc: z.array(z.string().email()).default([]),
+    bcc: z.array(z.string().email()).default([]),
+    subject: z.string().min(1),
+    body: z.string(),
+};
+export function registerGmailTools(server, gmail) {
+    server.registerTool('gmail_search', {
+        description: 'Search Gmail using Gmail query syntax and return message summaries.',
+        inputSchema: z.object({
+            query: z.string().default('in:inbox'),
+            maxResults: z.number().int().min(1).max(100).default(20),
+            pageToken: z.string().optional(),
+        }),
+    }, async ({ query, maxResults, pageToken }) => runTool('gmail_search', async () => {
+        const result = await gmail.users.messages.list({
+            userId: 'me',
+            q: query,
+            maxResults,
+            pageToken,
+        });
+        const messages = await Promise.all((result.data.messages || []).map(async ({ id }) => {
+            const response = await gmail.users.messages.get({
+                userId: 'me',
+                id: id,
+                format: 'metadata',
+                metadataHeaders: ['From', 'To', 'Cc', 'Subject', 'Date'],
+            });
+            const messageHeaders = headers(response.data);
+            return {
+                id: response.data.id,
+                threadId: response.data.threadId,
+                from: messageHeaders.from,
+                to: messageHeaders.to,
+                cc: messageHeaders.cc,
+                subject: messageHeaders.subject,
+                date: messageHeaders.date,
+                snippet: response.data.snippet,
+                labelIds: response.data.labelIds,
+            };
+        }));
+        return jsonText({ messages, nextPageToken: result.data.nextPageToken });
+    }));
+    server.registerTool('gmail_get_message', {
+        description: 'Read one Gmail message with headers and decoded body text.',
+        inputSchema: z.object({ messageId: z.string().min(1) }),
+    }, async ({ messageId }) => runTool('gmail_get_message', async () => {
+        const result = await gmail.users.messages.get({
+            userId: 'me',
+            id: messageId,
+            format: 'full',
+        });
+        return jsonText({
+            id: result.data.id,
+            threadId: result.data.threadId,
+            headers: headers(result.data),
+            body: decodedBody(result.data.payload),
+            snippet: result.data.snippet,
+            labelIds: result.data.labelIds,
+        });
+    }));
+    server.registerTool('gmail_send_message', {
+        description: 'Send a plain-text email from the authenticated Gmail account.',
+        inputSchema: z.object(recipientsSchema),
+    }, async (input) => runTool('gmail_send_message', async () => {
+        const result = await gmail.users.messages.send({
+            userId: 'me',
+            requestBody: { raw: encodeMessage(mimeMessage(input)) },
+        });
+        return jsonText({
+            id: result.data.id,
+            threadId: result.data.threadId,
+            labelIds: result.data.labelIds,
+        });
+    }));
+    server.registerTool('gmail_reply', {
+        description: 'Reply to a Gmail message in its existing thread.',
+        inputSchema: z.object({
+            messageId: z.string().min(1),
+            body: z.string().min(1),
+        }),
+    }, async ({ messageId, body }) => runTool('gmail_reply', async () => {
+        const original = await gmail.users.messages.get({
+            userId: 'me',
+            id: messageId,
+            format: 'metadata',
+            metadataHeaders: [
+                'From',
+                'Reply-To',
+                'Subject',
+                'Message-ID',
+                'References',
+            ],
+        });
+        const originalHeaders = headers(original.data);
+        const subject = originalHeaders.subject?.toLowerCase().startsWith('re:')
+            ? originalHeaders.subject
+            : `Re: ${originalHeaders.subject || ''}`;
+        const messageIdHeader = originalHeaders['message-id'];
+        const raw = mimeMessage({
+            to: [originalHeaders['reply-to'] || originalHeaders.from],
+            subject,
+            body,
+            inReplyTo: messageIdHeader,
+            references: [originalHeaders.references, messageIdHeader]
+                .filter(Boolean)
+                .join(' '),
+        });
+        const result = await gmail.users.messages.send({
+            userId: 'me',
+            requestBody: {
+                raw: encodeMessage(raw),
+                threadId: original.data.threadId,
+            },
+        });
+        return jsonText({ id: result.data.id, threadId: result.data.threadId });
+    }));
+    server.registerTool('gmail_modify_message', {
+        description: 'Add or remove Gmail labels such as UNREAD, STARRED, INBOX, or TRASH.',
+        inputSchema: z.object({
+            messageId: z.string().min(1),
+            addLabelIds: z.array(z.string()).default([]),
+            removeLabelIds: z.array(z.string()).default([]),
+        }),
+    }, async ({ messageId, addLabelIds, removeLabelIds }) => runTool('gmail_modify_message', async () => {
+        const result = await gmail.users.messages.modify({
+            userId: 'me',
+            id: messageId,
+            requestBody: { addLabelIds, removeLabelIds },
+        });
+        return jsonText({ id: result.data.id, labelIds: result.data.labelIds });
+    }));
+}

package/dist/src/tools/linkedin/client.js

@@ -0,0 +1,122 @@
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { createLinkedInAuth } from '../../auth/linkedin/index.js';
+const API_BASE = 'https://api.linkedin.com';
+function imageContentType(path) {
+    const types = {
+        '.gif': 'image/gif',
+        '.jpeg': 'image/jpeg',
+        '.jpg': 'image/jpeg',
+        '.png': 'image/png',
+    };
+    const contentType = types[extname(path).toLowerCase()];
+    if (!contentType)
+        throw new Error('LinkedIn images must be GIF, JPEG, or PNG files.');
+    return contentType;
+}
+export class LinkedInClient {
+    async request(path, init = {}) {
+        const auth = createLinkedInAuth();
+        const response = await fetch(`${API_BASE}${path}`, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${auth.accessToken}`,
+                'LinkedIn-Version': auth.apiVersion,
+                'X-Restli-Protocol-Version': '2.0.0',
+                ...init.headers,
+            },
+        });
+        const responseText = await response.text();
+        const data = responseText ? JSON.parse(responseText) : {};
+        if (!response.ok) {
+            throw new Error(`LinkedIn API ${response.status}: ${data.message || responseText || response.statusText}`);
+        }
+        return { data: data, headers: response.headers };
+    }
+    async getProfile() {
+        const auth = createLinkedInAuth();
+        const response = await fetch(`${API_BASE}/v2/userinfo`, {
+            headers: { Authorization: `Bearer ${auth.accessToken}` },
+        });
+        const data = await response.json();
+        if (!response.ok)
+            throw new Error(`LinkedIn profile API ${response.status}: ${JSON.stringify(data)}`);
+        return data;
+    }
+    async listPosts(count) {
+        const params = new URLSearchParams({
+            author: createLinkedInAuth().userUrn,
+            q: 'author',
+            count: String(count),
+        });
+        return (await this.request(`/rest/posts?${params}`)).data;
+    }
+    async getPost(postUrn) {
+        return (await this.request(`/rest/posts/${encodeURIComponent(postUrn)}`))
+            .data;
+    }
+    async getEngagement(postUrn) {
+        return (await this.request(`/rest/socialActions/${encodeURIComponent(postUrn)}`)).data;
+    }
+    async publishText(commentary, visibility) {
+        return this.publish(commentary, visibility);
+    }
+    async publishImage(commentary, imagePath, altText, visibility) {
+        const image = await this.initializeImageUpload();
+        const bytes = await readFile(image.uploadUrl ? imagePath : '');
+        const upload = await fetch(image.uploadUrl, {
+            method: 'PUT',
+            headers: {
+                Authorization: `Bearer ${createLinkedInAuth().accessToken}`,
+                'Content-Type': imageContentType(imagePath),
+            },
+            body: bytes,
+        });
+        if (!upload.ok)
+            throw new Error(`LinkedIn image upload ${upload.status}: ${await upload.text()}`);
+        return this.publish(commentary, visibility, image.image, altText);
+    }
+    async deletePost(postUrn) {
+        await this.request(`/rest/posts/${encodeURIComponent(postUrn)}`, {
+            method: 'DELETE',
+        });
+    }
+    async initializeImageUpload() {
+        const auth = createLinkedInAuth();
+        const result = await this.request('/rest/images?action=initializeUpload', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                initializeUploadRequest: { owner: auth.userUrn },
+            }),
+        });
+        return result.data.value;
+    }
+    async publish(commentary, visibility, imageUrn, altText) {
+        const auth = createLinkedInAuth();
+        const result = await this.request('/rest/posts', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                author: auth.userUrn,
+                commentary,
+                visibility,
+                distribution: {
+                    feedDistribution: 'MAIN_FEED',
+                    targetEntities: [],
+                    thirdPartyDistributionChannels: [],
+                },
+                ...(imageUrn
+                    ? {
+                        content: {
+                            media: { id: imageUrn, ...(altText ? { altText } : {}) },
+                        },
+                    }
+                    : {}),
+                lifecycleState: 'PUBLISHED',
+                isReshareDisabledByAuthor: false,
+            }),
+        });
+        return result.headers.get('x-restli-id') || '';
+    }
+}

package/dist/src/tools/linkedin/index.js

@@ -0,0 +1,52 @@
+import * as z from 'zod/v4';
+import { jsonText, runTool } from '../shared.js';
+import { LinkedInClient } from './client.js';
+export function registerLinkedInTools(server, linkedin = new LinkedInClient()) {
+    server.registerTool('linkedin_get_profile', {
+        description: 'Read the authenticated LinkedIn member profile.',
+        inputSchema: z.object({}),
+    }, async () => runTool('linkedin_get_profile', async () => jsonText(await linkedin.getProfile())));
+    server.registerTool('linkedin_list_posts', {
+        description: 'List posts authored by the authenticated LinkedIn member.',
+        inputSchema: z.object({
+            count: z.number().int().min(1).max(100).default(10),
+        }),
+    }, async ({ count }) => runTool('linkedin_list_posts', async () => jsonText(await linkedin.listPosts(count))));
+    server.registerTool('linkedin_get_post', {
+        description: 'Read one LinkedIn post by its full URN.',
+        inputSchema: z.object({ postUrn: z.string().min(1) }),
+    }, async ({ postUrn }) => runTool('linkedin_get_post', async () => jsonText(await linkedin.getPost(postUrn))));
+    server.registerTool('linkedin_get_engagement', {
+        description: 'Read available like and comment metrics for a LinkedIn post.',
+        inputSchema: z.object({ postUrn: z.string().min(1) }),
+    }, async ({ postUrn }) => runTool('linkedin_get_engagement', async () => jsonText(await linkedin.getEngagement(postUrn))));
+    server.registerTool('linkedin_publish_text', {
+        description: 'Publish a text post to the authenticated LinkedIn member feed.',
+        inputSchema: z.object({
+            commentary: z.string().min(1).max(3000),
+            visibility: z.enum(['PUBLIC', 'CONNECTIONS']).default('PUBLIC'),
+        }),
+    }, async ({ commentary, visibility }) => runTool('linkedin_publish_text', async () => {
+        const postUrn = await linkedin.publishText(commentary, visibility);
+        return jsonText({ published: true, postUrn });
+    }));
+    server.registerTool('linkedin_publish_image', {
+        description: 'Upload a local GIF, JPEG, or PNG and publish it with text to LinkedIn.',
+        inputSchema: z.object({
+            commentary: z.string().min(1).max(3000),
+            imagePath: z.string().min(1),
+            altText: z.string().max(4086).optional(),
+            visibility: z.enum(['PUBLIC', 'CONNECTIONS']).default('PUBLIC'),
+        }),
+    }, async ({ commentary, imagePath, altText, visibility }) => runTool('linkedin_publish_image', async () => {
+        const postUrn = await linkedin.publishImage(commentary, imagePath, altText, visibility);
+        return jsonText({ published: true, postUrn });
+    }));
+    server.registerTool('linkedin_delete_post', {
+        description: 'Permanently delete a LinkedIn post owned by the authenticated member.',
+        inputSchema: z.object({ postUrn: z.string().min(1) }),
+    }, async ({ postUrn }) => runTool('linkedin_delete_post', async () => {
+        await linkedin.deletePost(postUrn);
+        return jsonText({ deleted: true, postUrn });
+    }));
+}

package/dist/src/tools/shared.js

@@ -0,0 +1,33 @@
+import { logger, publicErrorMessage } from '../logging/logger.js';
+export function jsonText(value) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    };
+}
+export async function runTool(name, operation) {
+    const startedAt = Date.now();
+    await logger.info('Tool started', { tool: name });
+    try {
+        const result = await operation();
+        await logger.info('Tool completed', {
+            tool: name,
+            durationMs: Date.now() - startedAt,
+        });
+        return result;
+    }
+    catch (error) {
+        await logger.error('Tool failed', error, {
+            tool: name,
+            durationMs: Date.now() - startedAt,
+        });
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `Unable to complete ${name}: ${publicErrorMessage(error)}`,
+                },
+            ],
+        };
+    }
+}

package/dist/src/utils/common.js

@@ -0,0 +1,25 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function getCurrentDir() {
+    return path.dirname(fileURLToPath(import.meta.url));
+}
+function findProjectRoot(startDir) {
+    let currentDir = startDir;
+    while (currentDir !== path.parse(currentDir).root) {
+        if (fs.existsSync(path.join(currentDir, 'package.json'))) {
+            return currentDir;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    return process.cwd();
+}
+export const projectRoot = findProjectRoot(getCurrentDir());
+export function getPackageMetadata() {
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    return {
+        name: packageJson.name || 'connected-workspace-mcp',
+        version: packageJson.version || '0.1.0',
+    };
+}

package/docs/README.md

@@ -0,0 +1,25 @@
+# Connected Workspace MCP Documentation
+
+Connected Workspace MCP connects MCP-compatible assistants to Gmail, Google
+Calendar, and LinkedIn through a TypeScript stdio server.
+
+## Guides
+
+- [Installation and MCP host setup](installation.md)
+- [Google OAuth setup](google-auth.md)
+- [LinkedIn OAuth setup](linkedin-auth.md)
+- [Configuration, tokens, and logs](configuration.md)
+- [Tool reference](tools.md)
+- [Authentication troubleshooting](troubleshooting.md)
+- [Publishing to npm](publishing.md)
+
+## Security Model
+
+- OAuth client settings are read from environment variables or a local `.env`.
+- Reusable provider tokens are stored outside the package directory.
+- Tool arguments, email bodies, post text, and credentials are excluded from
+  logs.
+- Write operations are exposed as explicit MCP tools so the host can request
+  confirmation according to its own policy.
+
+Never commit `.env`, token files, or log files.

package/docs/configuration.md

@@ -0,0 +1,59 @@
+# Configuration
+
+## Storage
+
+```dotenv
+PA_MCP_TOKEN_PATH=C:/Users/you/.connected-workspace-mcp/tokens.json
+PA_MCP_LOG_PATH=C:/Users/you/.connected-workspace-mcp/server.log
+```
+
+When these are omitted, the current defaults remain
+`%USERPROFILE%/.pa-mcp/tokens.json` and `pa-mcp.log` beside it for backward
+compatibility.
+
+The token file contains sensitive OAuth credentials. Restrict access to your
+user account, never commit it, and do not include it in support requests.
+
+Logs are JSON Lines, rotate at 5 MB, and retain one rotated file. The logger
+redacts common credential forms and never records tool arguments.
+
+## Google
+
+```dotenv
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+GOOGLE_REDIRECT_URI=http://localhost:3000
+```
+
+`GOOGLE_REFRESH_TOKEN` is supported only as a legacy fallback. New
+authorizations write the token store.
+
+## LinkedIn
+
+```dotenv
+LINKEDIN_CLIENT_ID=
+LINKEDIN_CLIENT_SECRET=
+LINKEDIN_REDIRECT_URI=http://localhost:3001/callback
+LINKEDIN_API_VERSION=202609
+```
+
+`LINKEDIN_ACCESS_TOKEN` and `LINKEDIN_USER_URN` are legacy fallbacks. The OAuth
+command persists both values in the token store.
+
+## Loading Rules
+
+All three executables accept either `--env-file <path>` or
+`--env-file=<path>`. This is the recommended approach for `npx`, because its
+working directory depends on the MCP host:
+
+```powershell
+npx -y connected-workspace-mcp --env-file "C:\Users\you\.connected-workspace-mcp\.env"
+```
+
+Without this argument, the process loads `.env` from its current working
+directory. Values already in the process environment take precedence over the
+file. Provider tokens are loaded from the token store before legacy token
+environment values.
+
+Pass only the file path in command arguments. Credentials supplied directly on
+the command line can be exposed by process inspection.

package/docs/google-auth.md

@@ -0,0 +1,60 @@
+# Google OAuth Setup
+
+Gmail and Google Calendar share one OAuth client and one refresh token.
+
+## Create The Google Client
+
+1. Open https://console.cloud.google.com/ and select a project.
+2. Enable **Gmail API** and **Google Calendar API**.
+3. Configure the Google Auth Platform consent screen.
+4. Add your Google account as a test user if the app remains in testing mode.
+5. Create an OAuth client of type **Desktop app**.
+6. Save the client ID and create a client secret.
+
+Configure:
+
+```dotenv
+GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your-client-secret
+GOOGLE_REDIRECT_URI=http://localhost:3000
+```
+
+## Required Scopes
+
+```text
+https://www.googleapis.com/auth/gmail.modify
+https://www.googleapis.com/auth/gmail.send
+https://www.googleapis.com/auth/gmail.compose
+https://www.googleapis.com/auth/calendar
+```
+
+## Authorize
+
+From a source checkout:
+
+```powershell
+npm run auth:google
+```
+
+After a global npm installation:
+
+```powershell
+connected-workspace-google-auth
+```
+
+Open the printed URL and approve every Gmail and Calendar permission. The flow
+rejects partial grants and saves credentials only after all required scopes are
+returned.
+
+## Verify
+
+The server automatically refreshes Google access tokens. A successful setup
+allows `gmail_search` and `calendar_list_events` to run without another browser
+login.
+
+If Google returns `invalid_grant`, confirm the client ID and secret belong to
+the same OAuth client, revoke the old grant, and authorize again. Testing-mode
+Google refresh tokens may expire after seven days.
+
+See [Authentication troubleshooting](troubleshooting.md) for detailed provider
+console checks and reauthorization steps.