;
+ let mockSlidesAPI: any;
+ let mockDriveAPI: any;
+
+ beforeEach(() => {
+ // Clear all mocks before each test
+ jest.clearAllMocks();
+
+ // Create mock AuthManager
+ mockAuthManager = {
+ getAuthenticatedClient: jest.fn(),
+ } as any;
+
+
+ // Create mock Slides API
+ mockSlidesAPI = {
+ presentations: {
+ get: jest.fn(),
+ },
+ };
+
+ mockDriveAPI = {
+ files: {
+ list: jest.fn(),
+ },
+ };
+
+ // Mock the google constructors
+ (google.slides as jest.Mock) = jest.fn().mockReturnValue(mockSlidesAPI);
+ (google.drive as jest.Mock) = jest.fn().mockReturnValue(mockDriveAPI);
+
+ // Create SlidesService instance
+ slidesService = new SlidesService(mockAuthManager);
+ });
+
+ afterEach(() => {
+ jest.restoreAllMocks();
+ });
+
+ describe('initialize', () => {
+ it('should initialize Slides and Drive API clients', async () => {
+ const mockAuthClient = { access_token: 'test-token' };
+ mockAuthManager.getAuthenticatedClient.mockResolvedValue(mockAuthClient as any);
+
+ await slidesService.initialize();
+
+ expect(mockAuthManager.getAuthenticatedClient).toHaveBeenCalledTimes(1);
+ expect(google.slides).toHaveBeenCalledWith(
+ expect.objectContaining({
+ version: 'v1',
+ auth: mockAuthClient,
+ })
+ );
+ expect(google.drive).toHaveBeenCalledWith(
+ expect.objectContaining({
+ version: 'v3',
+ auth: mockAuthClient,
+ })
+ );
+ });
+ });
+
+ describe('getText', () => {
+ beforeEach(async () => {
+ const mockAuthClient = { access_token: 'test-token' };
+ mockAuthManager.getAuthenticatedClient.mockResolvedValue(mockAuthClient as any);
+ await slidesService.initialize();
+ });
+
+ it('should extract text from a presentation', async () => {
+ const mockPresentation = {
+ data: {
+ title: 'Test Presentation',
+ slides: [
+ {
+ pageElements: [
+ {
+ shape: {
+ text: {
+ textElements: [
+ { textRun: { content: 'Slide 1 Title' } },
+ { paragraphMarker: {} },
+ { textRun: { content: 'Slide 1 Content' } },
+ ],
+ },
+ },
+ },
+ ],
+ },
+ {
+ pageElements: [
+ {
+ table: {
+ tableRows: [
+ {
+ tableCells: [
+ {
+ text: {
+ textElements: [
+ { textRun: { content: 'Cell 1' } },
+ ],
+ },
+ },
+ {
+ text: {
+ textElements: [
+ { textRun: { content: 'Cell 2' } },
+ ],
+ },
+ },
+ ],
+ },
+ ],
+ },
+ },
+ ],
+ },
+ ],
+ },
+ };
+
+ mockSlidesAPI.presentations.get.mockResolvedValue(mockPresentation);
+
+ const result = await slidesService.getText({ presentationId: 'test-presentation-id' });
+
+ expect(mockSlidesAPI.presentations.get).toHaveBeenCalledWith({
+ presentationId: 'test-presentation-id',
+ fields: 'title,slides(pageElements(shape(text,shapeProperties),table(tableRows(tableCells(text)))))',
+ });
+
+ expect(result.content[0].type).toBe('text');
+ expect(result.content[0].text).toContain('Test Presentation');
+ expect(result.content[0].text).toContain('Slide 1 Title');
+ expect(result.content[0].text).toContain('Slide 1 Content');
+ expect(result.content[0].text).toContain('Cell 1 | Cell 2');
+ });
+
+ it('should handle presentations with no slides', async () => {
+ const mockPresentation = {
+ data: {
+ title: 'Empty Presentation',
+ slides: [],
+ },
+ };
+
+ mockSlidesAPI.presentations.get.mockResolvedValue(mockPresentation);
+
+ const result = await slidesService.getText({ presentationId: 'empty-presentation-id' });
+
+ expect(result.content[0].type).toBe('text');
+ expect(result.content[0].text).toContain('Empty Presentation');
+ });
+
+ it('should handle errors gracefully', async () => {
+ mockSlidesAPI.presentations.get.mockRejectedValue(new Error('API Error'));
+
+ const result = await slidesService.getText({ presentationId: 'error-presentation-id' });
+
+ expect(result.content[0].type).toBe('text');
+ const response = JSON.parse(result.content[0].text);
+ expect(response.error).toBe('API Error');
+ });
+ });
+
+ describe('find', () => {
+ beforeEach(async () => {
+ const mockAuthClient = { access_token: 'test-token' };
+ mockAuthManager.getAuthenticatedClient.mockResolvedValue(mockAuthClient as any);
+ await slidesService.initialize();
+ });
+
+ it('should find presentations by query', async () => {
+ const mockResponse = {
+ data: {
+ files: [
+ { id: 'pres1', name: 'Presentation 1' },
+ { id: 'pres2', name: 'Presentation 2' },
+ ],
+ nextPageToken: 'next-token',
+ },
+ };
+
+ mockDriveAPI.files.list.mockResolvedValue(mockResponse);
+
+ const result = await slidesService.find({ query: 'test query' });
+ const response = JSON.parse(result.content[0].text);
+
+ expect(mockDriveAPI.files.list).toHaveBeenCalledWith({
+ pageSize: 10,
+ fields: 'nextPageToken, files(id, name)',
+ q: "mimeType='application/vnd.google-apps.presentation' and fullText contains 'test query'",
+ pageToken: undefined,
+ });
+
+ expect(response.files).toHaveLength(2);
+ expect(response.files[0].name).toBe('Presentation 1');
+ expect(response.nextPageToken).toBe('next-token');
+ });
+
+ it('should handle title-specific searches', async () => {
+ const mockResponse = {
+ data: {
+ files: [{ id: 'pres1', name: 'Specific Title' }],
+ },
+ };
+
+ mockDriveAPI.files.list.mockResolvedValue(mockResponse);
+
+ const result = await slidesService.find({ query: 'title:"Specific Title"' });
+ const response = JSON.parse(result.content[0].text);
+
+ expect(mockDriveAPI.files.list).toHaveBeenCalledWith(
+ expect.objectContaining({
+ q: "mimeType='application/vnd.google-apps.presentation' and name contains 'Specific Title'",
+ })
+ );
+
+ expect(response.files).toHaveLength(1);
+ expect(response.files[0].name).toBe('Specific Title');
+ });
+ });
+
+ describe('getMetadata', () => {
+ beforeEach(async () => {
+ const mockAuthClient = { access_token: 'test-token' };
+ mockAuthManager.getAuthenticatedClient.mockResolvedValue(mockAuthClient as any);
+ await slidesService.initialize();
+ });
+
+ it('should retrieve presentation metadata', async () => {
+ const mockPresentation = {
+ data: {
+ presentationId: 'test-id',
+ title: 'Test Presentation',
+ slides: [{ objectId: 'slide1' }, { objectId: 'slide2' }],
+ pageSize: { width: { magnitude: 10 }, height: { magnitude: 7.5 } },
+ masters: [{ objectId: 'master1' }],
+ layouts: [{ objectId: 'layout1' }],
+ notesMaster: { objectId: 'notesMaster1' },
+ },
+ };
+
+ mockSlidesAPI.presentations.get.mockResolvedValue(mockPresentation);
+
+ const result = await slidesService.getMetadata({ presentationId: 'test-id' });
+ const metadata = JSON.parse(result.content[0].text);
+
+ expect(mockSlidesAPI.presentations.get).toHaveBeenCalledWith({
+ presentationId: 'test-id',
+ fields: 'presentationId,title,slides(objectId),pageSize,notesMaster,masters,layouts',
+ });
+
+ expect(metadata.presentationId).toBe('test-id');
+ expect(metadata.title).toBe('Test Presentation');
+ expect(metadata.slideCount).toBe(2);
+ expect(metadata.hasMasters).toBe(true);
+ expect(metadata.hasLayouts).toBe(true);
+ expect(metadata.hasNotesMaster).toBe(true);
+ });
+
+ it('should handle errors gracefully', async () => {
+ mockSlidesAPI.presentations.get.mockRejectedValue(new Error('Metadata Error'));
+
+ const result = await slidesService.getMetadata({ presentationId: 'error-id' });
+ const response = JSON.parse(result.content[0].text);
+
+ expect(response.error).toBe('Metadata Error');
+ });
+ });
+});
diff --git a/workspace-mcp-server/src/__tests__/services/TimeService.test.ts b/workspace-mcp-server/src/__tests__/services/TimeService.test.ts
new file mode 100644
index 00000000..2b3a8452
--- /dev/null
+++ b/workspace-mcp-server/src/__tests__/services/TimeService.test.ts
@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { TimeService } from '../../services/TimeService';
+
+describe('TimeService', () => {
+ let timeService: TimeService;
+ const mockDate = new Date('2025-08-19T12:34:56Z');
+
+ beforeEach(() => {
+ timeService = new TimeService();
+ jest.useFakeTimers();
+ jest.setSystemTime(mockDate);
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ describe('getCurrentDate', () => {
+ it('should return the current date in YYYY-MM-DD format', async () => {
+ const result = await timeService.getCurrentDate();
+ expect(result.content[0].text).toEqual(JSON.stringify({ date: '2025-08-19' }));
+ });
+ });
+
+ describe('getCurrentTime', () => {
+ it('should return the current time in HH:MM:SS format', async () => {
+ const result = await timeService.getCurrentTime();
+ expect(result.content[0].text).toEqual(JSON.stringify({ time: '12:34:56' }));
+ });
+ });
+
+ describe('getTimeZone', () => {
+ it('should return the local timezone', async () => {
+ const result = await timeService.getTimeZone();
+ const expectedTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+ expect(result.content[0].text).toEqual(JSON.stringify({ timeZone: expectedTimeZone }));
+ });
+ });
+});
diff --git a/workspace-mcp-server/src/__tests__/setup.ts b/workspace-mcp-server/src/__tests__/setup.ts
new file mode 100644
index 00000000..7274d642
--- /dev/null
+++ b/workspace-mcp-server/src/__tests__/setup.ts
@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Test setup file for Jest
+// This file runs before all tests
+import { jest } from '@jest/globals';
+
+// Mock console methods to reduce noise in test output
+global.console = {
+ ...console,
+ // Keep errors and warnings
+ error: jest.fn(console.error),
+ warn: jest.fn(console.warn),
+ // Silence other logs during tests unless explicitly needed
+ log: jest.fn(),
+ info: jest.fn(),
+ debug: jest.fn(),
+};
+
+// Set test environment variables
+process.env.NODE_ENV = 'test';
+
+// Increase timeout for integration tests if needed
+jest.setTimeout(10000);
+
+// Clean up after all tests
+afterAll(() => {
+ jest.clearAllMocks();
+ jest.restoreAllMocks();
+});
\ No newline at end of file
diff --git a/workspace-mcp-server/src/__tests__/utils/DriveQueryBuilder.test.ts b/workspace-mcp-server/src/__tests__/utils/DriveQueryBuilder.test.ts
new file mode 100644
index 00000000..ff4a78d7
--- /dev/null
+++ b/workspace-mcp-server/src/__tests__/utils/DriveQueryBuilder.test.ts
@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { buildDriveSearchQuery, MIME_TYPES } from '../../utils/DriveQueryBuilder';
+
+describe('DriveQueryBuilder', () => {
+ describe('buildDriveSearchQuery', () => {
+ it('should build fullText query for regular search', () => {
+ const query = buildDriveSearchQuery(MIME_TYPES.DOCUMENT, 'test query');
+ expect(query).toBe("mimeType='application/vnd.google-apps.document' and fullText contains 'test query'");
+ });
+
+ it('should build name query for title-prefixed search', () => {
+ const query = buildDriveSearchQuery(MIME_TYPES.PRESENTATION, 'title:My Presentation');
+ expect(query).toBe("mimeType='application/vnd.google-apps.presentation' and name contains 'My Presentation'");
+ });
+
+ it('should handle quoted title searches', () => {
+ const query = buildDriveSearchQuery(MIME_TYPES.SPREADSHEET, 'title:"Budget 2024"');
+ expect(query).toBe("mimeType='application/vnd.google-apps.spreadsheet' and name contains 'Budget 2024'");
+ });
+
+ it('should handle single-quoted title searches', () => {
+ const query = buildDriveSearchQuery(MIME_TYPES.DOCUMENT, "title:'Q4 Report'");
+ expect(query).toBe("mimeType='application/vnd.google-apps.document' and name contains 'Q4 Report'");
+ });
+
+ it('should escape special characters in query', () => {
+ const query = buildDriveSearchQuery(MIME_TYPES.DOCUMENT, "test's query\\path");
+ expect(query).toBe("mimeType='application/vnd.google-apps.document' and fullText contains 'test\\'s query\\\\path'");
+ });
+
+ it('should escape special characters in title search', () => {
+ const query = buildDriveSearchQuery(MIME_TYPES.PRESENTATION, "title:John's Presentation\\2024");
+ expect(query).toBe("mimeType='application/vnd.google-apps.presentation' and name contains 'John\\'s Presentation\\\\2024'");
+ });
+
+ it('should handle empty strings', () => {
+ const query = buildDriveSearchQuery(MIME_TYPES.SPREADSHEET, '');
+ expect(query).toBe("mimeType='application/vnd.google-apps.spreadsheet' and fullText contains ''");
+ });
+
+ it('should handle whitespace-only queries', () => {
+ const query = buildDriveSearchQuery(MIME_TYPES.DOCUMENT, ' ');
+ expect(query).toBe("mimeType='application/vnd.google-apps.document' and fullText contains ' '");
+ });
+
+ it('should handle title prefix with whitespace', () => {
+ const query = buildDriveSearchQuery(MIME_TYPES.PRESENTATION, ' title: "My Doc" ');
+ expect(query).toBe("mimeType='application/vnd.google-apps.presentation' and name contains 'My Doc'");
+ });
+
+ it('should work with all MIME types', () => {
+ expect(buildDriveSearchQuery(MIME_TYPES.DOCUMENT, 'test'))
+ .toContain('application/vnd.google-apps.document');
+ expect(buildDriveSearchQuery(MIME_TYPES.PRESENTATION, 'test'))
+ .toContain('application/vnd.google-apps.presentation');
+ expect(buildDriveSearchQuery(MIME_TYPES.SPREADSHEET, 'test'))
+ .toContain('application/vnd.google-apps.spreadsheet');
+ expect(buildDriveSearchQuery(MIME_TYPES.FOLDER, 'test'))
+ .toContain('application/vnd.google-apps.folder');
+ });
+ });
+
+ describe('MIME_TYPES constants', () => {
+ it('should have correct MIME type values', () => {
+ expect(MIME_TYPES.DOCUMENT).toBe('application/vnd.google-apps.document');
+ expect(MIME_TYPES.PRESENTATION).toBe('application/vnd.google-apps.presentation');
+ expect(MIME_TYPES.SPREADSHEET).toBe('application/vnd.google-apps.spreadsheet');
+ expect(MIME_TYPES.FOLDER).toBe('application/vnd.google-apps.folder');
+ });
+ });
+});
diff --git a/workspace-mcp-server/src/__tests__/utils/IdUtils.test.ts b/workspace-mcp-server/src/__tests__/utils/IdUtils.test.ts
new file mode 100644
index 00000000..9e52d48e
--- /dev/null
+++ b/workspace-mcp-server/src/__tests__/utils/IdUtils.test.ts
@@ -0,0 +1,116 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { extractDocId } from '../../utils/IdUtils';
+
+describe('IdUtils', () => {
+ describe('extractDocId', () => {
+ it('should extract document ID from a full Google Docs URL', () => {
+ const url = 'https://docs.google.com/document/d/1a2b3c4d5e6f7g8h9i0j/edit';
+ const result = extractDocId(url);
+ expect(result).toBe('1a2b3c4d5e6f7g8h9i0j');
+ });
+
+ it('should extract document ID from URL with additional parameters', () => {
+ const url = 'https://docs.google.com/document/d/abc123-XYZ_789/edit?usp=sharing';
+ const result = extractDocId(url);
+ expect(result).toBe('abc123-XYZ_789');
+ });
+
+ it('should extract document ID from URL with preview path', () => {
+ const url = 'https://docs.google.com/document/d/test-doc-id-123/preview';
+ const result = extractDocId(url);
+ expect(result).toBe('test-doc-id-123');
+ });
+
+ it('should extract document ID from URL without protocol', () => {
+ const url = 'docs.google.com/document/d/my_document_id/view';
+ const result = extractDocId(url);
+ expect(result).toBe('my_document_id');
+ });
+
+ it('should return undefined when raw document ID is passed directly', () => {
+ const docId = '1a2b3c4d5e6f7g8h9i0j';
+ const result = extractDocId(docId);
+ expect(result).toBeUndefined();
+ });
+
+ it('should return undefined for document ID with underscores and hyphens', () => {
+ const docId = 'doc_id-with-special_chars_123';
+ const result = extractDocId(docId);
+ expect(result).toBeUndefined();
+ });
+
+ it('should return undefined if no pattern matches', () => {
+ const randomString = 'not a doc id or url';
+ const result = extractDocId(randomString);
+ expect(result).toBeUndefined();
+ });
+
+ it('should return undefined for empty string', () => {
+ const result = extractDocId('');
+ expect(result).toBeUndefined();
+ });
+
+ it('should extract from partial URL path', () => {
+ const partialPath = '/document/d/abc123xyz/';
+ const result = extractDocId(partialPath);
+ expect(result).toBe('abc123xyz');
+ });
+
+ it('should handle URL with multiple document paths (edge case)', () => {
+ // Should extract the first match
+ const url = '/document/d/first123/document/d/second456/';
+ const result = extractDocId(url);
+ expect(result).toBe('first123');
+ });
+
+ it('should handle very long document IDs', () => {
+ const longId = 'a'.repeat(100) + '_' + 'b'.repeat(50);
+ const url = `https://docs.google.com/document/d/${longId}/edit`;
+ const result = extractDocId(url);
+ expect(result).toBe(longId);
+ });
+
+ it('should handle document ID with only numbers', () => {
+ const url = 'https://docs.google.com/document/d/1234567890/edit';
+ const result = extractDocId(url);
+ expect(result).toBe('1234567890');
+ });
+
+ it('should handle document ID with only letters', () => {
+ const url = 'https://docs.google.com/document/d/abcdefghij/edit';
+ const result = extractDocId(url);
+ expect(result).toBe('abcdefghij');
+ });
+
+ it('should handle malformed URLs gracefully', () => {
+ const malformedUrl = 'https://docs.google.com/document/edit';
+ const result = extractDocId(malformedUrl);
+ // Should return the input as-is when pattern doesn't match
+ expect(result).toBeUndefined();
+ });
+
+ it('should be case sensitive for document IDs', () => {
+ const url = 'https://docs.google.com/document/d/AbCdEfGhIj/edit';
+ const result = extractDocId(url);
+ expect(result).toBe('AbCdEfGhIj');
+ });
+
+ it('should extract document ID from a complex URL with resourcekey', () => {
+ const url = 'https://docs.google.com/document/d/1MGqTbt5joTs40QS-YZTP9QH1-TxQ5tij7RgXPFWMPiI/edit?resourcekey=0-X_p2TPxpk0visLTHHMF7Yg&tab=t.0';
+ const result = extractDocId(url);
+ expect(result).toBe('1MGqTbt5joTs40QS-YZTP9QH1-TxQ5tij7RgXPFWMPiI');
+ });
+
+ it('should extract document ID from a URL without a trailing slash', () => {
+ const url = 'https://docs.google.com/document/d/1MGqTbt5joTs40QS-YZTP9QH1-TxQ5tij7RgXPFWMPiI';
+ const result = extractDocId(url);
+ expect(result).toBe('1MGqTbt5joTs40QS-YZTP9QH1-TxQ5tij7RgXPFWMPiI');
+ });
+ });
+});
diff --git a/workspace-mcp-server/src/__tests__/utils/MimeHelper.test.ts b/workspace-mcp-server/src/__tests__/utils/MimeHelper.test.ts
new file mode 100644
index 00000000..c5106b8d
--- /dev/null
+++ b/workspace-mcp-server/src/__tests__/utils/MimeHelper.test.ts
@@ -0,0 +1,382 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { MimeHelper } from '../../utils/MimeHelper';
+
+describe('MimeHelper', () => {
+ describe('createMimeMessage', () => {
+ it('should create a basic plain text email', () => {
+ const encoded = MimeHelper.createMimeMessage({
+ to: 'recipient@example.com',
+ subject: 'Test Subject',
+ body: 'This is a test email body.',
+ });
+
+ // Decode the message to verify its structure
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ expect(decoded).toContain('To: recipient@example.com');
+ expect(decoded).toContain('Subject: =?utf-8?B?VGVzdCBTdWJqZWN0?=');
+ expect(decoded).toContain('Content-Type: text/plain; charset=utf-8');
+ expect(decoded).toContain('This is a test email body.');
+ });
+
+ it('should create an HTML email', () => {
+ const encoded = MimeHelper.createMimeMessage({
+ to: 'recipient@example.com',
+ subject: 'HTML Email',
+ body: 'Hello World
This is HTML content.
',
+ isHtml: true,
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ expect(decoded).toContain('Content-Type: text/html; charset=utf-8');
+ expect(decoded).toContain('Hello World
');
+ });
+
+ it('should include optional headers when provided', () => {
+ const encoded = MimeHelper.createMimeMessage({
+ to: 'recipient@example.com',
+ subject: 'Full Headers Test',
+ body: 'Test body',
+ from: 'sender@example.com',
+ cc: 'cc@example.com',
+ bcc: 'bcc@example.com',
+ replyTo: 'reply@example.com',
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ expect(decoded).toContain('From: sender@example.com');
+ expect(decoded).toContain('To: recipient@example.com');
+ expect(decoded).toContain('Cc: cc@example.com');
+ expect(decoded).toContain('Bcc: bcc@example.com');
+ expect(decoded).toContain('Reply-To: reply@example.com');
+ });
+
+ it('should handle UTF-8 subjects correctly', () => {
+ const encoded = MimeHelper.createMimeMessage({
+ to: 'recipient@example.com',
+ subject: 'Test with emoji 🎉 and special chars é ñ',
+ body: 'Test body',
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ // The subject should be base64 encoded
+ expect(decoded).toContain('Subject: =?utf-8?B?');
+
+ // Decode the subject to verify it's correct
+ const subjectMatch = decoded.match(/Subject: =\?utf-8\?B\?([^?]+)\?=/);
+ if (subjectMatch) {
+ const decodedSubject = Buffer.from(subjectMatch[1], 'base64').toString('utf-8');
+ expect(decodedSubject).toBe('Test with emoji 🎉 and special chars é ñ');
+ }
+ });
+
+ it('should properly format the MIME message with CRLF line endings', () => {
+ const encoded = MimeHelper.createMimeMessage({
+ to: 'recipient@example.com',
+ subject: 'CRLF Test',
+ body: 'Line 1\nLine 2',
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ // Should use CRLF (\r\n) as line separators
+ expect(decoded).toContain('\r\n');
+ expect(decoded.split('\r\n').length).toBeGreaterThan(3);
+ });
+
+ it('should handle multiple recipients in to field', () => {
+ const encoded = MimeHelper.createMimeMessage({
+ to: 'recipient1@example.com, recipient2@example.com',
+ subject: 'Multiple Recipients',
+ body: 'Test body',
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ expect(decoded).toContain('To: recipient1@example.com, recipient2@example.com');
+ });
+
+ it('should encode to base64url format (no padding, URL-safe characters)', () => {
+ const encoded = MimeHelper.createMimeMessage({
+ to: 'recipient@example.com',
+ subject: 'Base64URL Test',
+ body: 'Test content that should be encoded',
+ });
+
+ // Check that it doesn't contain standard base64 characters
+ expect(encoded).not.toContain('+');
+ expect(encoded).not.toContain('/');
+ expect(encoded).not.toContain('=');
+
+ // Should only contain base64url characters
+ expect(encoded).toMatch(/^[A-Za-z0-9\-_]+$/);
+ });
+ });
+
+ describe('createMimeMessageWithAttachments', () => {
+ it('should create a message without attachments when none provided', () => {
+ const encoded = MimeHelper.createMimeMessageWithAttachments({
+ to: 'recipient@example.com',
+ subject: 'No Attachments',
+ body: 'Simple message',
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ // Should not contain multipart boundary
+ expect(decoded).not.toContain('Content-Type: multipart/mixed');
+ expect(decoded).toContain('Content-Type: text/plain; charset=utf-8');
+ });
+
+ it('should create a multipart message with attachments', () => {
+ const attachments = [
+ {
+ filename: 'test.txt',
+ content: Buffer.from('Hello, World!'),
+ contentType: 'text/plain',
+ },
+ ];
+
+ const encoded = MimeHelper.createMimeMessageWithAttachments({
+ to: 'recipient@example.com',
+ subject: 'With Attachment',
+ body: 'Message with attachment',
+ attachments,
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ expect(decoded).toContain('Content-Type: multipart/mixed; boundary=');
+ expect(decoded).toContain('Content-Disposition: attachment; filename="test.txt"');
+ expect(decoded).toContain('Content-Type: text/plain');
+ expect(decoded).toContain('Content-Transfer-Encoding: base64');
+ });
+
+ it('should handle multiple attachments', () => {
+ const attachments = [
+ {
+ filename: 'file1.txt',
+ content: 'First file content',
+ contentType: 'text/plain',
+ },
+ {
+ filename: 'file2.pdf',
+ content: Buffer.from('PDF content'),
+ contentType: 'application/pdf',
+ },
+ ];
+
+ const encoded = MimeHelper.createMimeMessageWithAttachments({
+ to: 'recipient@example.com',
+ subject: 'Multiple Attachments',
+ body: 'Message with multiple attachments',
+ attachments,
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ expect(decoded).toContain('filename="file1.txt"');
+ expect(decoded).toContain('filename="file2.pdf"');
+ expect(decoded).toContain('Content-Type: text/plain');
+ expect(decoded).toContain('Content-Type: application/pdf');
+ });
+
+ it('should use default content type for attachments without specified type', () => {
+ const attachments = [
+ {
+ filename: 'unknown.bin',
+ content: Buffer.from('Binary content'),
+ },
+ ];
+
+ const encoded = MimeHelper.createMimeMessageWithAttachments({
+ to: 'recipient@example.com',
+ subject: 'Default Content Type',
+ body: 'Message',
+ attachments,
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ expect(decoded).toContain('Content-Type: application/octet-stream');
+ });
+
+ it('should properly format attachment content in 76-character lines', () => {
+ const longContent = 'a'.repeat(200); // Long content that needs to be wrapped
+ const attachments = [
+ {
+ filename: 'long.txt',
+ content: Buffer.from(longContent),
+ },
+ ];
+
+ const encoded = MimeHelper.createMimeMessageWithAttachments({
+ to: 'recipient@example.com',
+ subject: 'Long Attachment',
+ body: 'Message',
+ attachments,
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ // Find the base64 encoded attachment content
+ const lines = decoded.split('\r\n');
+ const attachmentStart = lines.findIndex(line =>
+ line.includes('Content-Transfer-Encoding: base64')
+ );
+
+ if (attachmentStart !== -1) {
+ // Check lines after the attachment header
+ for (let i = attachmentStart + 2; i < lines.length; i++) {
+ const line = lines[i];
+ if (line.startsWith('--')) break; // Reached boundary
+ if (line.length > 0) {
+ expect(line.length).toBeLessThanOrEqual(76);
+ }
+ }
+ }
+ });
+
+ it('should handle HTML body with attachments', () => {
+ const attachments = [
+ {
+ filename: 'doc.html',
+ content: 'HTML Doc',
+ contentType: 'text/html',
+ },
+ ];
+
+ const encoded = MimeHelper.createMimeMessageWithAttachments({
+ to: 'recipient@example.com',
+ subject: 'HTML with Attachment',
+ body: 'HTML Message Body
',
+ isHtml: true,
+ attachments,
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ // Body should be HTML
+ expect(decoded).toMatch(/Content-Type: text\/html; charset=utf-8\r\n\r\nHTML Message Body<\/p>/);
+ // Attachment should also be present
+ expect(decoded).toContain('filename="doc.html"');
+ });
+
+ it('should include all optional headers with attachments', () => {
+ const attachments = [
+ {
+ filename: 'test.txt',
+ content: 'Test',
+ },
+ ];
+
+ const encoded = MimeHelper.createMimeMessageWithAttachments({
+ to: 'recipient@example.com',
+ subject: 'Full Headers with Attachments',
+ body: 'Test body',
+ from: 'sender@example.com',
+ cc: 'cc@example.com',
+ bcc: 'bcc@example.com',
+ attachments,
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(encoded);
+
+ expect(decoded).toContain('From: sender@example.com');
+ expect(decoded).toContain('Cc: cc@example.com');
+ expect(decoded).toContain('Bcc: bcc@example.com');
+ expect(decoded).toContain('MIME-Version: 1.0');
+ });
+
+ it('should create unique boundary for each message', () => {
+ const attachments = [
+ {
+ filename: 'test.txt',
+ content: 'Test',
+ },
+ ];
+
+ const encoded1 = MimeHelper.createMimeMessageWithAttachments({
+ to: 'recipient@example.com',
+ subject: 'Message 1',
+ body: 'Body 1',
+ attachments,
+ });
+
+ const encoded2 = MimeHelper.createMimeMessageWithAttachments({
+ to: 'recipient@example.com',
+ subject: 'Message 2',
+ body: 'Body 2',
+ attachments,
+ });
+
+ const decoded1 = MimeHelper.decodeBase64Url(encoded1);
+ const decoded2 = MimeHelper.decodeBase64Url(encoded2);
+
+ const boundary1Match = decoded1.match(/boundary="([^"]+)"/);
+ const boundary2Match = decoded2.match(/boundary="([^"]+)"/);
+
+ expect(boundary1Match).toBeTruthy();
+ expect(boundary2Match).toBeTruthy();
+ expect(boundary1Match![1]).not.toBe(boundary2Match![1]);
+ });
+ });
+
+ describe('decodeBase64Url', () => {
+ it('should decode base64url encoded strings', () => {
+ const original = 'Hello, World! This is a test.';
+ const base64url = Buffer.from(original)
+ .toString('base64')
+ .replace(/\+/g, '-')
+ .replace(/\//g, '_')
+ .replace(/=+$/, '');
+
+ const decoded = MimeHelper.decodeBase64Url(base64url);
+
+ expect(decoded).toBe(original);
+ });
+
+ it('should handle strings without padding', () => {
+ const base64url = 'SGVsbG8'; // "Hello" without padding
+ const decoded = MimeHelper.decodeBase64Url(base64url);
+
+ expect(decoded).toBe('Hello');
+ });
+
+ it('should convert URL-safe characters back to standard base64', () => {
+ const base64url = 'SGVsbG8-V29ybGRfIQ'; // Contains - and _
+ const decoded = MimeHelper.decodeBase64Url(base64url);
+
+ expect(decoded).toBeTruthy();
+ expect(typeof decoded).toBe('string');
+ });
+
+ it('should handle empty strings', () => {
+ const decoded = MimeHelper.decodeBase64Url('');
+
+ expect(decoded).toBe('');
+ });
+
+ it('should properly decode a complete MIME message', () => {
+ const mimeMessage = MimeHelper.createMimeMessage({
+ to: 'test@example.com',
+ subject: 'Test',
+ body: 'Test body',
+ });
+
+ const decoded = MimeHelper.decodeBase64Url(mimeMessage);
+
+ expect(decoded).toContain('To: test@example.com');
+ expect(decoded).toContain('Test body');
+ });
+ });
+});
\ No newline at end of file
diff --git a/workspace-mcp-server/src/__tests__/utils/logger.test.ts b/workspace-mcp-server/src/__tests__/utils/logger.test.ts
new file mode 100644
index 00000000..6d00ac1e
--- /dev/null
+++ b/workspace-mcp-server/src/__tests__/utils/logger.test.ts
@@ -0,0 +1,235 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, jest, beforeEach, afterEach } from '@jest/globals';
+import * as path from 'node:path';
+
+// Mock fs/promises module BEFORE any imports that use it
+jest.mock('fs/promises');
+
+describe('logger', () => {
+ let consoleErrorSpy: any;
+ let logToFile: (message: string) => void;
+ let setLoggingEnabled: (enabled: boolean) => void;
+ let fs: any;
+
+ async function setupLogger(appendFileMock?: any) {
+ jest.resetModules();
+ jest.doMock('fs/promises', () => ({
+ mkdir: jest.fn(() => Promise.resolve()),
+ appendFile: appendFileMock || jest.fn(() => Promise.resolve()),
+ }));
+
+ fs = await import('node:fs/promises');
+ const loggerModule = await import('../../utils/logger');
+ logToFile = loggerModule.logToFile;
+ setLoggingEnabled = loggerModule.setLoggingEnabled;
+ setLoggingEnabled(true);
+ jest.clearAllMocks();
+ }
+
+ beforeEach(() => {
+ // Clear all mocks
+ jest.clearAllMocks();
+
+ // Clear module cache to ensure fresh imports
+ jest.resetModules();
+
+ // Spy on console.error
+ consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ jest.restoreAllMocks();
+ });
+
+ describe('module initialization', () => {
+ it('should create log directory on module load', async () => {
+ // Set up mocks
+ jest.doMock('fs/promises', () => ({
+ mkdir: jest.fn(() => Promise.resolve()),
+ appendFile: jest.fn(() => Promise.resolve()),
+ }));
+
+ // Import the module (this triggers initialization)
+ await import('../../utils/logger');
+
+ // Get the mocked fs module
+ fs = await import('node:fs/promises');
+
+ // Wait for async initialization
+ await new Promise(resolve => setTimeout(resolve, 10));
+
+ expect(fs.mkdir).toHaveBeenCalledWith(
+ expect.stringContaining('logs'),
+ { recursive: true }
+ );
+ });
+
+ it('should handle directory creation errors gracefully', async () => {
+ const mkdirError = new Error('Permission denied');
+
+ // Set up mocks
+ jest.doMock('fs/promises', () => ({
+ mkdir: jest.fn(() => Promise.reject(mkdirError)),
+ appendFile: jest.fn(() => Promise.resolve()),
+ }));
+
+ // Import the module
+ await import('../../utils/logger');
+
+ // Wait for async initialization
+ await new Promise(resolve => setTimeout(resolve, 10));
+
+ expect(consoleErrorSpy).toHaveBeenCalledWith(
+ 'Could not create log directory:',
+ mkdirError
+ );
+ });
+ });
+
+ describe('logToFile', () => {
+ beforeEach(async () => {
+ await setupLogger();
+ });
+
+ it('should append message with timestamp to log file', async () => {
+ const testMessage = 'Test log message';
+ const mockDate = new Date('2024-01-01T12:00:00.000Z');
+ jest.spyOn(global, 'Date').mockImplementation(() => mockDate as any);
+
+ logToFile(testMessage);
+
+ // Wait for async operation
+ await new Promise(resolve => setTimeout(resolve, 10));
+
+ expect(fs.appendFile).toHaveBeenCalledWith(
+ expect.stringContaining('server.log'),
+ '2024-01-01T12:00:00.000Z - Test log message\n'
+ );
+ });
+
+ it('should handle multiple log messages', async () => {
+ logToFile('First message');
+ logToFile('Second message');
+ logToFile('Third message');
+
+ // Wait for async operations
+ await new Promise(resolve => setTimeout(resolve, 10));
+
+ expect(fs.appendFile).toHaveBeenCalledTimes(3);
+ expect(fs.appendFile).toHaveBeenNthCalledWith(
+ 1,
+ expect.stringContaining('server.log'),
+ expect.stringContaining('First message')
+ );
+ expect(fs.appendFile).toHaveBeenNthCalledWith(
+ 2,
+ expect.stringContaining('server.log'),
+ expect.stringContaining('Second message')
+ );
+ expect(fs.appendFile).toHaveBeenNthCalledWith(
+ 3,
+ expect.stringContaining('server.log'),
+ expect.stringContaining('Third message')
+ );
+ });
+
+ it('should log to console.error when file write fails', async () => {
+ const writeError = new Error('Disk full');
+ await setupLogger(jest.fn(() => Promise.reject(writeError)));
+
+ logToFile('Failed write test');
+
+ // Wait for async operation
+ await new Promise(resolve => setTimeout(resolve, 10));
+
+ expect(consoleErrorSpy).toHaveBeenCalledWith(
+ 'Failed to write to log file:',
+ writeError
+ );
+ });
+
+ it('should format log message correctly', async () => {
+ const mockDate = new Date('2024-12-25T18:30:45.123Z');
+ jest.spyOn(global, 'Date').mockImplementation(() => mockDate as any);
+
+ logToFile('Holiday log entry');
+
+ // Wait for async operation
+ await new Promise(resolve => setTimeout(resolve, 10));
+
+ const expectedMessage = '2024-12-25T18:30:45.123Z - Holiday log entry\n';
+ expect(fs.appendFile).toHaveBeenCalledWith(
+ expect.any(String),
+ expectedMessage
+ );
+ });
+
+ it('should handle empty messages', async () => {
+ const mockDate = new Date('2024-01-01T12:00:00.000Z');
+ jest.spyOn(global, 'Date').mockImplementation(() => mockDate as any);
+ logToFile('');
+
+ // Wait for async operation
+ await new Promise(resolve => setTimeout(resolve, 10));
+
+ expect(fs.appendFile).toHaveBeenCalledWith(
+ expect.stringContaining('server.log'),
+ '2024-01-01T12:00:00.000Z - \n'
+ );
+ });
+
+ it('should handle special characters in messages', async () => {
+ const specialMessage = 'Message with \n newline, \t tab, and "quotes"';
+
+ logToFile(specialMessage);
+
+ // Wait for async operation
+ await new Promise(resolve => setTimeout(resolve, 10));
+
+ expect(fs.appendFile).toHaveBeenCalledWith(
+ expect.stringContaining('server.log'),
+ expect.stringContaining(specialMessage)
+ );
+ });
+
+ it('should use correct log file path', async () => {
+ logToFile('Path test');
+
+ // Wait for async operation
+ await new Promise(resolve => setTimeout(resolve, 10));
+
+ const callArgs = (fs.appendFile as jest.Mock).mock.calls[0];
+ const logPath = callArgs[0] as string;
+
+ expect(logPath).toContain('logs');
+ expect(logPath).toContain('server.log');
+ expect(path.isAbsolute(logPath)).toBe(true);
+ });
+
+ it('should not throw when appendFile fails', async () => {
+ await setupLogger(jest.fn(() => Promise.reject(new Error('Write failed'))));
+
+ // Should not throw
+ expect(() => logToFile('Test message')).not.toThrow();
+
+ // Wait for async operation
+ await new Promise(resolve => setTimeout(resolve, 10));
+
+ expect(consoleErrorSpy).toHaveBeenCalled();
+ });
+
+ it('should not log when logging is disabled', () => {
+ setLoggingEnabled(false);
+ const testMessage = 'Test log message';
+
+ logToFile(testMessage);
+
+ expect(fs.appendFile).not.toHaveBeenCalled();
+ });
+ });
+});
diff --git a/workspace-mcp-server/src/__tests__/utils/markdownToDocsRequests.test.ts b/workspace-mcp-server/src/__tests__/utils/markdownToDocsRequests.test.ts
new file mode 100644
index 00000000..4301be45
--- /dev/null
+++ b/workspace-mcp-server/src/__tests__/utils/markdownToDocsRequests.test.ts
@@ -0,0 +1,247 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { parseMarkdownToDocsRequests, processMarkdownLineBreaks } from '../../utils/markdownToDocsRequests';
+
+describe('markdownToDocsRequests', () => {
+ describe('parseMarkdownToDocsRequests', () => {
+ // Skip tests that rely on marked working if it's not functioning in test environment
+ // We'll check markedWorks inside each test instead of using a variable
+
+ it('should handle bold text', () => {
+ const markdown = 'This is **bold** text';
+ const startIndex = 10;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toBe('This is bold text');
+ expect(result.formattingRequests).toHaveLength(1);
+ expect(result.formattingRequests[0]).toEqual({
+ updateTextStyle: {
+ range: {
+ startIndex: 18, // 10 + 8 (position of "bold")
+ endIndex: 22, // 10 + 12 (end of "bold")
+ },
+ textStyle: {
+ bold: true,
+ },
+ fields: 'bold'
+ }
+ });
+ });
+
+ it('should handle italic text with asterisks', () => {
+ const markdown = 'This is *italic* text';
+ const startIndex = 0;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toBe('This is italic text');
+ expect(result.formattingRequests).toHaveLength(1);
+ expect(result.formattingRequests[0]).toEqual({
+ updateTextStyle: {
+ range: {
+ startIndex: 8,
+ endIndex: 14,
+ },
+ textStyle: {
+ italic: true,
+ },
+ fields: 'italic'
+ }
+ });
+ });
+
+ it('should handle italic text with underscores', () => {
+ const markdown = 'This is _italic_ text';
+ const startIndex = 0;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toBe('This is italic text');
+ expect(result.formattingRequests).toHaveLength(1);
+ expect(result.formattingRequests[0].updateTextStyle?.textStyle?.italic).toBe(true);
+ });
+
+ it('should handle inline code', () => {
+ const markdown = 'This is `code` text';
+ const startIndex = 0;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toBe('This is code text');
+ expect(result.formattingRequests).toHaveLength(1);
+ expect(result.formattingRequests[0]).toEqual({
+ updateTextStyle: {
+ range: {
+ startIndex: 8,
+ endIndex: 12,
+ },
+ textStyle: {
+ weightedFontFamily: {
+ fontFamily: 'Courier New',
+ weight: 400
+ },
+ backgroundColor: {
+ color: {
+ rgbColor: {
+ red: 0.95,
+ green: 0.95,
+ blue: 0.95
+ }
+ }
+ }
+ },
+ fields: 'weightedFontFamily,backgroundColor'
+ }
+ });
+ });
+
+ it('should handle multiple formatting in one text', () => {
+ const markdown = 'Text with **bold**, *italic*, and `code` formatting';
+ const startIndex = 0;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toBe('Text with bold, italic, and code formatting');
+ expect(result.formattingRequests).toHaveLength(3);
+ });
+
+ it('should handle text with no formatting', () => {
+ const markdown = 'Plain text without any formatting';
+ const startIndex = 0;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toBe('Plain text without any formatting');
+ expect(result.formattingRequests).toHaveLength(0);
+ });
+
+ it('should handle overlapping formatting (keeps first)', () => {
+ const markdown = '**bold and text**';
+ const startIndex = 0;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ // The bold formatting should be applied
+ expect(result.plainText).toBe('bold and text');
+ expect(result.formattingRequests).toHaveLength(1);
+ expect(result.formattingRequests[0].updateTextStyle?.textStyle?.bold).toBe(true);
+ });
+
+ it('should respect the startIndex parameter', () => {
+ const markdown = '**bold**';
+ const startIndex = 100;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toBe('bold');
+ expect(result.formattingRequests[0]).toEqual({
+ updateTextStyle: {
+ range: {
+ startIndex: 100,
+ endIndex: 104,
+ },
+ textStyle: {
+ bold: true,
+ },
+ fields: 'bold'
+ }
+ });
+ });
+
+ it('should handle heading 1', () => {
+ const markdown = '# Main Title';
+ const startIndex = 0;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toBe('Main Title');
+ expect(result.formattingRequests).toHaveLength(1);
+ expect(result.formattingRequests[0].updateParagraphStyle?.paragraphStyle?.namedStyleType).toBe('HEADING_1');
+ expect(result.formattingRequests[0].updateParagraphStyle?.range?.startIndex).toBe(0);
+ expect(result.formattingRequests[0].updateParagraphStyle?.range?.endIndex).toBe(10);
+ });
+
+ it('should handle heading 2', () => {
+ const markdown = '## Section Title';
+ const startIndex = 0;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toBe('Section Title');
+ expect(result.formattingRequests).toHaveLength(1);
+ expect(result.formattingRequests[0].updateParagraphStyle?.paragraphStyle?.namedStyleType).toBe('HEADING_2');
+ expect(result.formattingRequests[0].updateParagraphStyle?.range?.startIndex).toBe(0);
+ expect(result.formattingRequests[0].updateParagraphStyle?.range?.endIndex).toBe(13);
+ });
+
+ it('should handle heading 3', () => {
+ const markdown = '### Subsection';
+ const startIndex = 0;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toBe('Subsection');
+ expect(result.formattingRequests).toHaveLength(1);
+ expect(result.formattingRequests[0].updateParagraphStyle?.paragraphStyle?.namedStyleType).toBe('HEADING_3');
+ expect(result.formattingRequests[0].updateParagraphStyle?.range?.startIndex).toBe(0);
+ expect(result.formattingRequests[0].updateParagraphStyle?.range?.endIndex).toBe(10);
+ });
+
+ it('should handle mixed headings and text', () => {
+ const markdown = '# Title\n\nSome text\n\n## Section\n\nMore text';
+ const startIndex = 0;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toContain('Title');
+ expect(result.plainText).toContain('Some text');
+ expect(result.plainText).toContain('Section');
+ expect(result.plainText).toContain('More text');
+
+ // Should have formatting for both headings
+ const headingFormats = result.formattingRequests.filter(req =>
+ req.updateParagraphStyle?.paragraphStyle?.namedStyleType !== undefined
+ );
+ expect(headingFormats).toHaveLength(2);
+ });
+
+ it('should handle inline formatting within headings', () => {
+ const markdown = '# Main **bold** Title';
+ const startIndex = 0;
+ const result = parseMarkdownToDocsRequests(markdown, startIndex);
+
+ expect(result.plainText).toBe('Main bold Title');
+
+ // Should have both heading and bold formatting
+ const headingFormat = result.formattingRequests.find(req =>
+ req.updateParagraphStyle?.paragraphStyle?.namedStyleType !== undefined
+ );
+ const boldFormat = result.formattingRequests.find(req =>
+ req.updateTextStyle?.textStyle?.bold === true
+ );
+
+ expect(headingFormat).toBeDefined();
+ expect(boldFormat).toBeDefined();
+ });
+ });
+
+ describe('processMarkdownLineBreaks', () => {
+ it('should preserve single line breaks', () => {
+ const text = 'Line 1\nLine 2';
+ const result = processMarkdownLineBreaks(text);
+ expect(result).toBe('Line 1\nLine 2');
+ });
+
+ it('should convert double line breaks to double', () => {
+ const text = 'Paragraph 1\n\nParagraph 2';
+ const result = processMarkdownLineBreaks(text);
+ expect(result).toBe('Paragraph 1\n\nParagraph 2');
+ });
+
+ it('should convert multiple line breaks to double', () => {
+ const text = 'Paragraph 1\n\n\n\nParagraph 2';
+ const result = processMarkdownLineBreaks(text);
+ expect(result).toBe('Paragraph 1\n\nParagraph 2');
+ });
+
+ it('should handle text without line breaks', () => {
+ const text = 'Single line of text';
+ const result = processMarkdownLineBreaks(text);
+ expect(result).toBe('Single line of text');
+ });
+ });
+});
\ No newline at end of file
diff --git a/workspace-mcp-server/src/__tests__/utils/secure-browser-launcher.test.ts b/workspace-mcp-server/src/__tests__/utils/secure-browser-launcher.test.ts
new file mode 100644
index 00000000..141e6214
--- /dev/null
+++ b/workspace-mcp-server/src/__tests__/utils/secure-browser-launcher.test.ts
@@ -0,0 +1,312 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+ describe,
+ it,
+ expect,
+ beforeEach,
+ jest,
+ afterEach,
+} from '@jest/globals';
+import { openBrowserSecurely } from '../../utils/secure-browser-launcher';
+import { platform } from 'node:os';
+import { EventEmitter } from 'node:events';
+import { ChildProcess } from 'node:child_process';
+
+jest.mock('node:os');
+
+const mockPlatform = platform as jest.Mock;
+
+describe('secure-browser-launcher', () => {
+ let mockChild: EventEmitter;
+ let mockExecFile: jest.Mock;
+
+ beforeEach(() => {
+ mockChild = new EventEmitter();
+ mockExecFile = jest.fn().mockReturnValue(mockChild as ChildProcess);
+ mockPlatform.mockReturnValue('darwin'); // Default to macOS
+ });
+
+ afterEach(() => {
+ jest.clearAllMocks();
+ });
+
+ function simulateSuccess() {
+ process.nextTick(() => {
+ mockChild.emit('exit', 0);
+ });
+ }
+
+ function simulateFailure(error = new Error('Command failed')) {
+ process.nextTick(() => {
+ mockChild.emit('error', error);
+ });
+ }
+
+ describe('URL validation', () => {
+ it('should allow valid HTTP URLs', async () => {
+ const openPromise = openBrowserSecurely(
+ 'http://example.com',
+ mockExecFile as any
+ );
+ simulateSuccess();
+ await expect(openPromise).resolves.toBeUndefined();
+ expect(mockExecFile).toHaveBeenCalledWith(
+ 'open',
+ ['http://example.com'],
+ expect.any(Object),
+ expect.any(Function)
+ );
+ });
+
+ it('should allow valid HTTPS URLs', async () => {
+ const openPromise = openBrowserSecurely(
+ 'https://example.com',
+ mockExecFile as any
+ );
+ simulateSuccess();
+ await expect(openPromise).resolves.toBeUndefined();
+ expect(mockExecFile).toHaveBeenCalledWith(
+ 'open',
+ ['https://example.com'],
+ expect.any(Object),
+ expect.any(Function)
+ );
+ });
+
+ it('should reject non-HTTP(S) protocols', async () => {
+ await expect(
+ openBrowserSecurely('file:///etc/passwd', mockExecFile as any)
+ ).rejects.toThrow('Unsafe protocol');
+ await expect(
+ openBrowserSecurely('javascript:alert(1)', mockExecFile as any)
+ ).rejects.toThrow('Unsafe protocol');
+ await expect(
+ openBrowserSecurely('ftp://example.com', mockExecFile as any)
+ ).rejects.toThrow('Unsafe protocol');
+ });
+
+ it('should reject invalid URLs', async () => {
+ await expect(
+ openBrowserSecurely('not-a-url', mockExecFile as any)
+ ).rejects.toThrow('Invalid URL');
+ await expect(
+ openBrowserSecurely('', mockExecFile as any)
+ ).rejects.toThrow('Invalid URL');
+ });
+
+ it('should reject URLs with control characters', async () => {
+ await expect(
+ openBrowserSecurely(
+ 'http://example.com\nmalicious-command',
+ mockExecFile as any
+ )
+ ).rejects.toThrow('invalid characters');
+ await expect(
+ openBrowserSecurely(
+ 'http://example.com\rmalicious-command',
+ mockExecFile as any
+ )
+ ).rejects.toThrow('invalid characters');
+ await expect(
+ openBrowserSecurely('http://example.com\x00', mockExecFile as any)
+ ).rejects.toThrow('invalid characters');
+ });
+ });
+
+ describe('Command injection prevention', () => {
+ it('should prevent PowerShell command injection on Windows', async () => {
+ mockPlatform.mockReturnValue('win32');
+ const maliciousUrl =
+ "http://127.0.0.1:8080/?param=example#$(Invoke-Expression([System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('Y2FsYy5leGU='))))";
+
+ const openPromise = openBrowserSecurely(maliciousUrl, mockExecFile as any);
+ simulateSuccess();
+ await expect(openPromise).resolves.toBeUndefined();
+
+ expect(mockExecFile).toHaveBeenCalledWith(
+ 'powershell.exe',
+ [
+ '-NoProfile',
+ '-NonInteractive',
+ '-WindowStyle',
+ 'Hidden',
+ '-Command',
+ `Start-Process '${maliciousUrl.replace(/'/g, "''")}'`,
+ ],
+ expect.any(Object),
+ expect.any(Function)
+ );
+ });
+
+ it('should handle URLs with special shell characters safely', async () => {
+ const urlsWithSpecialChars = [
+ 'http://example.com/path?param=value&other=$value',
+ 'http://example.com/path#fragment;command',
+ 'http://example.com/$(whoami)',
+ 'http://example.com/`command`',
+ 'http://example.com/|pipe',
+ 'http://example.com/>redirect',
+ ];
+
+ for (const url of urlsWithSpecialChars) {
+ const openPromise = openBrowserSecurely(url, mockExecFile as any);
+ simulateSuccess();
+ await expect(openPromise).resolves.toBeUndefined();
+ expect(mockExecFile).toHaveBeenCalledWith(
+ 'open',
+ [url],
+ expect.any(Object),
+ expect.any(Function)
+ );
+ }
+ });
+
+ it('should properly escape single quotes in URLs on Windows', async () => {
+ mockPlatform.mockReturnValue('win32');
+ const urlWithSingleQuotes =
+ "http://example.com/path?name=O'Brien&test='value'";
+
+ const openPromise = openBrowserSecurely(
+ urlWithSingleQuotes,
+ mockExecFile as any
+ );
+ simulateSuccess();
+ await expect(openPromise).resolves.toBeUndefined();
+
+ expect(mockExecFile).toHaveBeenCalledWith(
+ 'powershell.exe',
+ [
+ '-NoProfile',
+ '-NonInteractive',
+ '-WindowStyle',
+ 'Hidden',
+ '-Command',
+ `Start-Process 'http://example.com/path?name=O''Brien&test=''value'''`,
+ ],
+ expect.any(Object),
+ expect.any(Function)
+ );
+ });
+ });
+
+ describe('Platform-specific behavior', () => {
+ it('should use correct command on macOS', async () => {
+ const openPromise = openBrowserSecurely(
+ 'https://example.com',
+ mockExecFile as any
+ );
+ simulateSuccess();
+ await expect(openPromise).resolves.toBeUndefined();
+ expect(mockExecFile).toHaveBeenCalledWith(
+ 'open',
+ ['https://example.com'],
+ expect.any(Object),
+ expect.any(Function)
+ );
+ });
+
+ it('should use PowerShell on Windows', async () => {
+ mockPlatform.mockReturnValue('win32');
+ const openPromise = openBrowserSecurely(
+ 'https://example.com',
+ mockExecFile as any
+ );
+ simulateSuccess();
+ await expect(openPromise).resolves.toBeUndefined();
+ expect(mockExecFile).toHaveBeenCalledWith(
+ 'powershell.exe',
+ [
+ '-NoProfile',
+ '-NonInteractive',
+ '-WindowStyle',
+ 'Hidden',
+ '-Command',
+ `Start-Process 'https://example.com'`,
+ ],
+ expect.any(Object),
+ expect.any(Function)
+ );
+ });
+
+ it('should use xdg-open on Linux', async () => {
+ mockPlatform.mockReturnValue('linux');
+ const openPromise = openBrowserSecurely(
+ 'https://example.com',
+ mockExecFile as any
+ );
+ simulateSuccess();
+ await expect(openPromise).resolves.toBeUndefined();
+ expect(mockExecFile).toHaveBeenCalledWith(
+ 'xdg-open',
+ ['https://example.com'],
+ expect.any(Object),
+ expect.any(Function)
+ );
+ });
+
+ it('should throw on unsupported platforms', async () => {
+ mockPlatform.mockReturnValue('aix');
+ await expect(
+ openBrowserSecurely('https://example.com', mockExecFile as any)
+ ).rejects.toThrow('Unsupported platform');
+ });
+ });
+
+ describe('Error handling', () => {
+ it('should handle browser launch failures gracefully', async () => {
+ const openPromise = openBrowserSecurely(
+ 'https://example.com',
+ mockExecFile as any
+ );
+ simulateFailure();
+ await expect(openPromise).rejects.toThrow('Failed to open browser');
+ });
+
+ it('should try fallback browsers on Linux', async () => {
+ mockPlatform.mockReturnValue('linux');
+
+ const mockChild2 = new EventEmitter();
+ mockExecFile.mockImplementationOnce(() => {
+ // Defer the emit call to allow the 'on' handlers to be set up.
+ process.nextTick(() => {
+ mockChild.emit('error', new Error('xdg-open not found'));
+ });
+ return mockChild as ChildProcess;
+ });
+ mockExecFile.mockImplementationOnce(() => {
+ process.nextTick(() => {
+ mockChild2.emit('exit', 0);
+ });
+ return mockChild2 as ChildProcess;
+ });
+
+ const openPromise = openBrowserSecurely(
+ 'https://example.com',
+ mockExecFile as any
+ );
+
+ await expect(openPromise).resolves.toBeUndefined();
+
+ expect(mockExecFile).toHaveBeenCalledTimes(2);
+ expect(mockExecFile).toHaveBeenNthCalledWith(
+ 1,
+ 'xdg-open',
+ ['https://example.com'],
+ expect.any(Object),
+ expect.any(Function)
+ );
+ expect(mockExecFile).toHaveBeenNthCalledWith(
+ 2,
+ 'gnome-open',
+ ['https://example.com'],
+ expect.any(Object),
+ expect.any(Function)
+ );
+ });
+ });
+});
\ No newline at end of file
diff --git a/workspace-mcp-server/src/__tests__/utils/validation.test.ts b/workspace-mcp-server/src/__tests__/utils/validation.test.ts
new file mode 100644
index 00000000..10fb1671
--- /dev/null
+++ b/workspace-mcp-server/src/__tests__/utils/validation.test.ts
@@ -0,0 +1,148 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import {
+ validateEmail,
+ validateDateTime,
+ validateDocumentId,
+ extractDocumentId,
+ emailSchema,
+ emailArraySchema,
+ searchQuerySchema,
+ ValidationError
+} from '../../utils/validation';
+
+describe('Validation Utilities', () => {
+ describe('Email Validation', () => {
+ it('should validate correct email addresses', () => {
+ expect(validateEmail('user@example.com')).toEqual({ success: true });
+ expect(validateEmail('john.doe+tag@company.co.uk')).toEqual({ success: true });
+ });
+
+ it('should reject invalid email addresses', () => {
+ expect(validateEmail('invalid')).toMatchObject({ success: false });
+ expect(validateEmail('@example.com')).toMatchObject({ success: false });
+ expect(validateEmail('user@')).toMatchObject({ success: false });
+ expect(validateEmail('user @example.com')).toMatchObject({ success: false });
+ });
+
+ it('should handle email arrays', () => {
+ const result1 = emailSchema.safeParse('user@example.com');
+ expect(result1.success).toBe(true);
+
+ const result2 = emailSchema.safeParse(['user1@example.com', 'user2@example.com']);
+ expect(result2.success).toBe(false); // Single schema doesn't accept arrays
+ });
+
+ it('should validate emailArraySchema with single email', () => {
+ const result = emailArraySchema.safeParse('user@example.com');
+ expect(result.success).toBe(true);
+ });
+
+ it('should validate emailArraySchema with array of emails', () => {
+ const result = emailArraySchema.safeParse(['user1@example.com', 'user2@example.com']);
+ expect(result.success).toBe(true);
+ });
+
+ it('should reject emailArraySchema with invalid emails in array', () => {
+ const result = emailArraySchema.safeParse(['valid@example.com', 'invalid-email']);
+ expect(result.success).toBe(false);
+ });
+ });
+
+ describe('DateTime Validation', () => {
+ it('should validate correct ISO 8601 datetime formats', () => {
+ expect(validateDateTime('2024-01-15T10:30:00Z')).toEqual({ success: true });
+ expect(validateDateTime('2024-01-15T10:30:00.000Z')).toEqual({ success: true });
+ expect(validateDateTime('2024-01-15T10:30:00-05:00')).toEqual({ success: true });
+ expect(validateDateTime('2024-01-15T10:30:00+09:30')).toEqual({ success: true });
+ });
+
+ it('should reject invalid datetime formats', () => {
+ expect(validateDateTime('2024-01-15')).toMatchObject({ success: false });
+ expect(validateDateTime('10:30:00')).toMatchObject({ success: false });
+ expect(validateDateTime('2024-01-15 10:30:00')).toMatchObject({ success: false });
+ expect(validateDateTime('not a date')).toMatchObject({ success: false });
+ });
+
+ it('should reject invalid dates', () => {
+ expect(validateDateTime('2024-13-01T10:30:00Z')).toMatchObject({ success: false }); // Invalid month
+ // Note: JavaScript Date constructor accepts Feb 30 and converts it to March 1st or 2nd
+ // So this test would pass as valid. We'd need more complex validation for this.
+ expect(validateDateTime('2024-00-01T10:30:00Z')).toMatchObject({ success: false }); // Invalid month (0)
+ });
+ });
+
+ describe('Document ID Validation', () => {
+ it('should validate correct document IDs', () => {
+ expect(validateDocumentId('1a2b3c4d5e6f7g8h9i0j')).toEqual({ success: true });
+ expect(validateDocumentId('abc-123_XYZ')).toEqual({ success: true });
+ expect(validateDocumentId('Document_ID-123')).toEqual({ success: true });
+ });
+
+ it('should reject invalid document IDs', () => {
+ expect(validateDocumentId('doc id with spaces')).toMatchObject({ success: false });
+ expect(validateDocumentId('doc#id')).toMatchObject({ success: false });
+ expect(validateDocumentId('doc/id')).toMatchObject({ success: false });
+ expect(validateDocumentId('')).toMatchObject({ success: false });
+ });
+ });
+
+ describe('Document ID Extraction', () => {
+ it('should extract ID from Google Docs URLs', () => {
+ const url = 'https://docs.google.com/document/d/1a2b3c4d5e6f/edit';
+ expect(extractDocumentId(url)).toBe('1a2b3c4d5e6f');
+ });
+
+ it('should extract ID from Google Drive URLs', () => {
+ const url = 'https://drive.google.com/file/d/abc123XYZ/view';
+ expect(extractDocumentId(url)).toBe('abc123XYZ');
+ });
+
+ it('should extract ID from Google Sheets URLs', () => {
+ const url = 'https://sheets.google.com/spreadsheets/d/sheet_id_123/edit';
+ expect(extractDocumentId(url)).toBe('sheet_id_123');
+ });
+
+ it('should return ID if already valid', () => {
+ const id = 'valid_document_id_123';
+ expect(extractDocumentId(id)).toBe(id);
+ });
+
+ it('should throw error for invalid input', () => {
+ expect(() => extractDocumentId('not a valid url or id')).toThrow();
+ expect(() => extractDocumentId('https://example.com/doc')).toThrow();
+ });
+ });
+
+ describe('Search Query Sanitization', () => {
+ it('should escape potentially dangerous characters', () => {
+ const result = searchQuerySchema.parse("test' OR '1'='1");
+ expect(result).toBe("test\\' OR \\'1\\'=\\'1"); // Quotes are escaped
+ });
+
+ it('should escape quotes while preserving search functionality', () => {
+ const result = searchQuerySchema.parse('search for "exact phrase"');
+ expect(result).toBe('search for \\"exact phrase\\"');
+ });
+
+ it('should preserve safe characters', () => {
+ const result = searchQuerySchema.parse('test query with spaces and-dashes');
+ expect(result).toBe('test query with spaces and-dashes');
+ });
+ });
+
+ describe('ValidationError', () => {
+ it('should create proper error with field and value', () => {
+ const error = new ValidationError('Invalid email', 'email', 'bad@');
+ expect(error.message).toBe('Invalid email');
+ expect(error.field).toBe('email');
+ expect(error.value).toBe('bad@');
+ expect(error.name).toBe('ValidationError');
+ });
+ });
+});
\ No newline at end of file
diff --git a/workspace-mcp-server/src/auth/AuthManager.ts b/workspace-mcp-server/src/auth/AuthManager.ts
new file mode 100644
index 00000000..5cfaa65a
--- /dev/null
+++ b/workspace-mcp-server/src/auth/AuthManager.ts
@@ -0,0 +1,259 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { google, Auth } from 'googleapis';
+import crypto from 'node:crypto';
+import * as http from 'node:http';
+import * as net from 'node:net';
+import * as url from 'node:url';
+import { logToFile } from '../utils/logger';
+import open from '../utils/open-wrapper';
+import { shouldLaunchBrowser } from '../utils/secure-browser-launcher';
+import { OAuthCredentialStorage } from './token-storage/oauth-credential-storage';
+
+// The Client ID for the OAuth flow.
+// The secret is handled by the cloud function, not in the client.
+const CLIENT_ID = '338689075775-o75k922vn5fdl18qergr96rp8g63e4d7.apps.googleusercontent.com';
+
+/**
+ * An Authentication URL for updating the credentials of a Oauth2Client
+ * as well as a promise that will resolve when the credentials have
+ * been refreshed (or which throws error when refreshing credentials failed).
+ */
+interface OauthWebLogin {
+ authUrl: string;
+ loginCompletePromise: Promise;
+}
+
+export class AuthManager {
+ private client: Auth.OAuth2Client | null = null;
+ private scopes: string[];
+
+ constructor(scopes: string[]) {
+ this.scopes = scopes;
+ }
+
+ private async loadCachedCredentials(client: Auth.OAuth2Client): Promise {
+ const credentials = await OAuthCredentialStorage.loadCredentials();
+
+ if (credentials) {
+ // Check if saved token has required scopes
+ const savedScopes = new Set(credentials.scope?.split(' ') ?? []);
+ logToFile(`Cached token has scopes: ${[...savedScopes].join(', ')}`);
+ logToFile(`Required scopes: ${this.scopes.join(', ')}`);
+
+ const missingScopes = this.scopes.filter(scope => !savedScopes.has(scope));
+
+ if (missingScopes.length > 0) {
+ logToFile(`Token cache missing required scopes: ${missingScopes.join(', ')}`);
+ logToFile('Removing cached token to force re-authentication...');
+ await OAuthCredentialStorage.clearCredentials();
+ return false;
+ } else {
+ client.setCredentials(credentials);
+ return true;
+ }
+ }
+
+ return false;
+ }
+
+ public async getAuthenticatedClient(): Promise {
+ logToFile('getAuthenticatedClient called');
+
+ // Check if we have a cached client with valid credentials
+ if (this.client && this.client.credentials && this.client.credentials.refresh_token) {
+ logToFile('Returning existing cached client with valid credentials');
+ return this.client;
+ }
+
+ // Note: No clientSecret is provided here. The secret is only known by the cloud function.
+ const options: Auth.OAuth2ClientOptions = {
+ clientId: CLIENT_ID,
+ };
+ const oAuth2Client = new google.auth.OAuth2(options);
+
+ logToFile('No valid cached client, checking for saved credentials...');
+ if (await this.loadCachedCredentials(oAuth2Client)) {
+ logToFile('Loaded saved credentials, caching and returning client');
+ this.client = oAuth2Client;
+ return this.client;
+ }
+
+ const webLogin = await this.authWithWeb(oAuth2Client);
+ await open(webLogin.authUrl);
+ console.log('Waiting for authentication...');
+
+ // Add timeout to prevent infinite waiting when browser tab gets stuck
+ const authTimeout = 5 * 60 * 1000; // 5 minutes timeout
+ const timeoutPromise = new Promise((_, reject) => {
+ setTimeout(() => {
+ reject(
+ new Error(
+ 'Authentication timed out after 5 minutes. The browser tab may have gotten stuck in a loading state. ' +
+ 'Please try again.',
+ ),
+ );
+ }, authTimeout);
+ });
+ await Promise.race([webLogin.loginCompletePromise, timeoutPromise]);
+
+ await OAuthCredentialStorage.saveCredentials(oAuth2Client.credentials);
+ this.client = oAuth2Client;
+ return this.client;
+ }
+
+ private async getAvailablePort(): Promise {
+ return new Promise((resolve, reject) => {
+ let port = 0;
+ try {
+ const portStr = process.env['OAUTH_CALLBACK_PORT'];
+ if (portStr) {
+ port = parseInt(portStr, 10);
+ if (isNaN(port) || port <= 0 || port > 65535) {
+ return reject(
+ new Error(`Invalid value for OAUTH_CALLBACK_PORT: "${portStr}"`),
+ );
+ }
+ return resolve(port);
+ }
+ const server = net.createServer();
+ server.listen(0, () => {
+ const address = server.address()! as net.AddressInfo;
+ port = address.port;
+ });
+ server.on('listening', () => {
+ server.close();
+ server.unref();
+ });
+ server.on('error', (e) => reject(e));
+ server.on('close', () => resolve(port));
+ } catch (e) {
+ reject(e);
+ }
+ });
+ }
+
+ private async authWithWeb(client: Auth.OAuth2Client): Promise {
+ logToFile(`Requesting authentication with scopes: ${this.scopes.join(', ')}`);
+
+ const port = await this.getAvailablePort();
+ const host = process.env['OAUTH_CALLBACK_HOST'] || 'localhost';
+
+ const localRedirectUri = `http://${host}:${port}/oauth2callback`;
+
+ const isGuiAvailable = shouldLaunchBrowser();
+
+ // SECURITY: Generate a random token for CSRF protection.
+ const csrfToken = crypto.randomBytes(32).toString('hex');
+
+ // The state now contains a JSON payload indicating the flow mode and CSRF token.
+ const statePayload = {
+ uri: isGuiAvailable ? localRedirectUri : undefined,
+ manual: !isGuiAvailable,
+ csrf: csrfToken,
+ };
+ const state = Buffer.from(JSON.stringify(statePayload)).toString('base64');
+
+ // The redirect URI for Google's auth server is the cloud function
+ const cloudFunctionRedirectUri = 'https://google-workspace-extension.geminicli.com';
+
+ const authUrl = client.generateAuthUrl({
+ redirect_uri: cloudFunctionRedirectUri, // Tell Google to go to the cloud function
+ access_type: 'offline',
+ scope: this.scopes,
+ state: state, // Pass our JSON payload in the state
+ prompt: 'consent', // Make sure we get a refresh token
+ });
+
+ const loginCompletePromise = new Promise((resolve, reject) => {
+ const server = http.createServer(async (req, res) => {
+ try {
+ // Use startsWith for more robust path checking.
+ if (!req.url || !req.url.startsWith('/oauth2callback')) {
+ res.end();
+ reject(
+ new Error(
+ 'OAuth callback not received. Unexpected request: ' + req.url,
+ ),
+ );
+ return;
+ }
+
+ const qs = new url.URL(req.url, `http://${host}:${port}`)
+ .searchParams;
+
+ // SECURITY: Validate the state parameter to prevent CSRF attacks.
+ const returnedState = qs.get('state');
+ if (returnedState !== csrfToken) {
+ res.end('State mismatch. Possible CSRF attack.');
+ reject(new Error('OAuth state mismatch. Possible CSRF attack.'));
+ return;
+ }
+
+ if (qs.get('error')) {
+ const errorCode = qs.get('error');
+ const errorDescription =
+ qs.get('error_description') || 'No additional details provided';
+ res.end();
+ reject(
+ new Error(
+ `Google OAuth error: ${errorCode}. ${errorDescription}`,
+ ),
+ );
+ return;
+ }
+
+ const access_token = qs.get('access_token');
+ const refresh_token = qs.get('refresh_token');
+ const scope = qs.get('scope');
+ const token_type = qs.get('token_type');
+ const expiry_date_str = qs.get('expiry_date');
+
+ if (access_token && expiry_date_str) {
+ const tokens: Auth.Credentials = {
+ access_token: access_token,
+ refresh_token: refresh_token || null,
+ scope: scope || undefined,
+ token_type: (token_type as 'Bearer') || undefined,
+ expiry_date: parseInt(expiry_date_str, 10),
+ };
+ client.setCredentials(tokens);
+ res.end('Authentication successful! Please return to the console.');
+ resolve();
+ } else {
+ reject(
+ new Error(
+ 'Authentication failed: Did not receive tokens from callback.',
+ ),
+ );
+ }
+ } catch (e) {
+ reject(e);
+ } finally {
+ server.close();
+ }
+ })
+
+ server.listen(port, host, () => {
+ // Server started successfully
+ });
+
+ server.on('error', (err) => {
+ reject(
+ new Error(
+ `OAuth callback server error: ${err}`,
+ ),
+ );
+ });
+ });
+
+ return {
+ authUrl,
+ loginCompletePromise,
+ };
+ }
+}
diff --git a/workspace-mcp-server/src/auth/token-storage/base-token-storage.ts b/workspace-mcp-server/src/auth/token-storage/base-token-storage.ts
new file mode 100644
index 00000000..8a9c44f5
--- /dev/null
+++ b/workspace-mcp-server/src/auth/token-storage/base-token-storage.ts
@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+ OAuthCredentials,
+ TokenStorage
+} from './types';
+
+export abstract class BaseTokenStorage implements TokenStorage {
+ protected readonly serviceName: string;
+
+ constructor(serviceName: string) {
+ this.serviceName = serviceName;
+ }
+
+ abstract getCredentials(serverName: string): Promise;
+ abstract setCredentials(credentials: OAuthCredentials): Promise;
+ abstract deleteCredentials(serverName: string): Promise;
+ abstract listServers(): Promise;
+ abstract getAllCredentials(): Promise>;
+ abstract clearAll(): Promise;
+
+ protected validateCredentials(credentials: OAuthCredentials): void {
+ if (!credentials.serverName) {
+ throw new Error('Server name is required');
+ }
+ if (!credentials.token) {
+ throw new Error('Token is required');
+ }
+ if (!credentials.token.accessToken && !credentials.token.refreshToken) {
+ throw new Error('Access token or refresh token is required');
+ }
+ if (!credentials.token.tokenType) {
+ throw new Error('Token type is required');
+ }
+ }
+
+
+
+ protected sanitizeServerName(serverName: string): string {
+ return serverName.replace(/[^a-zA-Z0-9-_.]/g, '_');
+ }
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/src/auth/token-storage/file-token-storage.ts b/workspace-mcp-server/src/auth/token-storage/file-token-storage.ts
new file mode 100644
index 00000000..d0a590dc
--- /dev/null
+++ b/workspace-mcp-server/src/auth/token-storage/file-token-storage.ts
@@ -0,0 +1,215 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+import { BaseTokenStorage } from './base-token-storage';
+import type { OAuthCredentials } from './types';
+import { logToFile } from '../../utils/logger';
+import {
+ ENCRYPTED_TOKEN_PATH,
+ ENCRYPTION_MASTER_KEY_PATH,
+} from '../../utils/paths';
+
+export class FileTokenStorage extends BaseTokenStorage {
+ private readonly tokenFilePath: string;
+ private readonly encryptionKey: Buffer;
+ private readonly masterKey: Buffer;
+
+ private constructor(serviceName: string, masterKey: Buffer) {
+ super(serviceName);
+ this.tokenFilePath = ENCRYPTED_TOKEN_PATH;
+ this.masterKey = masterKey;
+ this.encryptionKey = this.deriveEncryptionKey();
+ }
+
+ static async create(serviceName: string): Promise {
+ const masterKey = await this.loadMasterKey();
+ return new FileTokenStorage(serviceName, masterKey);
+ }
+
+ private static async loadMasterKey(): Promise {
+ try {
+ const masterKey = await fs.readFile(ENCRYPTION_MASTER_KEY_PATH);
+ return masterKey;
+ } catch (error) {
+ const err = error as NodeJS.ErrnoException;
+ if (err.code === 'ENOENT') {
+ const newKey = crypto.randomBytes(32);
+ await fs.writeFile(ENCRYPTION_MASTER_KEY_PATH, newKey, { mode: 0o600 });
+ return newKey;
+ }
+ throw error;
+ }
+ }
+
+ private deriveEncryptionKey(): Buffer {
+ const salt = `${os.hostname()}-${
+ os.userInfo().username
+ }-gemini-cli-workspace`;
+ return crypto.scryptSync(this.masterKey, salt, 32);
+ }
+
+ private encrypt(text: string): string {
+ const iv = crypto.randomBytes(16);
+ const cipher = crypto.createCipheriv('aes-256-gcm', this.encryptionKey, iv);
+
+ let encrypted = cipher.update(text, 'utf8', 'hex');
+ encrypted += cipher.final('hex');
+
+ const authTag = cipher.getAuthTag();
+
+ return iv.toString('hex') + ':' + authTag.toString('hex') + ':' + encrypted;
+ }
+
+ private decrypt(encryptedData: string): string {
+ const parts = encryptedData.split(':');
+ if (parts.length !== 3) {
+ throw new Error('Invalid encrypted data format');
+ }
+
+ const iv = Buffer.from(parts[0], 'hex');
+ const authTag = Buffer.from(parts[1], 'hex');
+ const encrypted = parts[2];
+
+ const decipher = crypto.createDecipheriv(
+ 'aes-256-gcm',
+ this.encryptionKey,
+ iv,
+ );
+ decipher.setAuthTag(authTag);
+
+ let decrypted = decipher.update(encrypted, 'hex', 'utf8');
+ decrypted += decipher.final('utf8');
+
+ return decrypted;
+ }
+
+ private async ensureDirectoryExists(): Promise {
+ const dir = path.dirname(this.tokenFilePath);
+ await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+ }
+
+ private async loadTokens(): Promise> {
+ try {
+ const data = await fs.readFile(this.tokenFilePath, 'utf-8');
+ const decrypted = this.decrypt(data);
+ const tokens = JSON.parse(decrypted) as Record;
+ return new Map(Object.entries(tokens));
+ } catch (error: unknown) {
+ const err = error as NodeJS.ErrnoException & { message?: string };
+ if (err.code === 'ENOENT') {
+ logToFile('Token file does not exist');
+ return new Map();
+ }
+ if (
+ err.message?.includes('Invalid encrypted data format') ||
+ err.message?.includes(
+ 'Unsupported state or unable to authenticate data',
+ )
+ ) {
+ logToFile('Token file corrupted');
+ return new Map();
+ }
+ throw error;
+ }
+ }
+
+ private async saveTokens(
+ tokens: Map,
+ ): Promise {
+ await this.ensureDirectoryExists();
+
+ const data = Object.fromEntries(tokens);
+ const json = JSON.stringify(data, null, 2);
+ const encrypted = this.encrypt(json);
+
+ await fs.writeFile(this.tokenFilePath, encrypted, { mode: 0o600 });
+ }
+
+ async getCredentials(serverName: string): Promise {
+ const tokens = await this.loadTokens();
+ const credentials = tokens.get(serverName);
+
+ if (!credentials) {
+ return null;
+ }
+
+
+
+ return credentials;
+ }
+
+ async setCredentials(credentials: OAuthCredentials): Promise {
+ this.validateCredentials(credentials);
+
+ const tokens = await this.loadTokens();
+ const updatedCredentials: OAuthCredentials = {
+ ...credentials,
+ updatedAt: Date.now(),
+ };
+
+ tokens.set(credentials.serverName, updatedCredentials);
+ await this.saveTokens(tokens);
+ }
+
+ async deleteCredentials(serverName: string): Promise {
+ const tokens = await this.loadTokens();
+
+ if (!tokens.has(serverName)) {
+ throw new Error(`No credentials found for ${serverName}`);
+ }
+
+ tokens.delete(serverName);
+
+ if (tokens.size === 0) {
+ try {
+ await fs.unlink(this.tokenFilePath);
+ } catch (error: unknown) {
+ const err = error as NodeJS.ErrnoException;
+ if (err.code !== 'ENOENT') {
+ throw error;
+ }
+ }
+ } else {
+ await this.saveTokens(tokens);
+ }
+ }
+
+ async listServers(): Promise {
+ const tokens = await this.loadTokens();
+ return Array.from(tokens.keys());
+ }
+
+ async getAllCredentials(): Promise> {
+ const tokens = await this.loadTokens();
+ const result = new Map();
+
+ for (const [serverName, credentials] of tokens) {
+ try {
+ this.validateCredentials(credentials);
+ result.set(serverName, credentials);
+ } catch (error) {
+ console.error(`Skipping invalid credentials for ${serverName}:`, error);
+ }
+ }
+
+ return result;
+ }
+
+ async clearAll(): Promise {
+ try {
+ await fs.unlink(this.tokenFilePath);
+ } catch (error: unknown) {
+ const err = error as NodeJS.ErrnoException;
+ if (err.code !== 'ENOENT') {
+ throw error;
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/src/auth/token-storage/hybrid-token-storage.ts b/workspace-mcp-server/src/auth/token-storage/hybrid-token-storage.ts
new file mode 100644
index 00000000..39f3962b
--- /dev/null
+++ b/workspace-mcp-server/src/auth/token-storage/hybrid-token-storage.ts
@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BaseTokenStorage } from './base-token-storage';
+import { FileTokenStorage } from './file-token-storage';
+import type { TokenStorage, OAuthCredentials } from './types';
+import { TokenStorageType } from './types';
+
+const FORCE_FILE_STORAGE_ENV_VAR = 'GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE';
+
+export class HybridTokenStorage extends BaseTokenStorage {
+ private storage: TokenStorage | null = null;
+ private storageType: TokenStorageType | null = null;
+ private storageInitPromise: Promise | null = null;
+
+ constructor(serviceName: string) {
+ super(serviceName);
+ }
+
+ private async initializeStorage(): Promise {
+ const forceFileStorage = process.env[FORCE_FILE_STORAGE_ENV_VAR] === 'true';
+
+ if (!forceFileStorage) {
+ try {
+ const { KeychainTokenStorage } = await import(
+ './keychain-token-storage'
+ );
+ const keychainStorage = new KeychainTokenStorage(this.serviceName);
+
+ const isAvailable = await keychainStorage.isAvailable();
+ if (isAvailable) {
+ this.storage = keychainStorage;
+ this.storageType = TokenStorageType.KEYCHAIN;
+ return this.storage;
+ }
+ } catch (e) {
+ // Fallback to file storage if keychain fails to initialize.
+ console.warn('Keychain initialization failed, falling back to file storage:', e);
+ }
+ }
+
+ this.storage = await FileTokenStorage.create(this.serviceName);
+ this.storageType = TokenStorageType.ENCRYPTED_FILE;
+ return this.storage;
+ }
+
+ private async getStorage(): Promise {
+ if (this.storage !== null) {
+ return this.storage;
+ }
+
+ // Use a single initialization promise to avoid race conditions
+ if (!this.storageInitPromise) {
+ this.storageInitPromise = this.initializeStorage();
+ }
+
+ // Wait for initialization to complete
+ return await this.storageInitPromise;
+ }
+
+ async getCredentials(serverName: string): Promise {
+ const storage = await this.getStorage();
+ return storage.getCredentials(serverName);
+ }
+
+ async setCredentials(credentials: OAuthCredentials): Promise {
+ const storage = await this.getStorage();
+ await storage.setCredentials(credentials);
+ }
+
+ async deleteCredentials(serverName: string): Promise {
+ const storage = await this.getStorage();
+ await storage.deleteCredentials(serverName);
+ }
+
+ async listServers(): Promise {
+ const storage = await this.getStorage();
+ return storage.listServers();
+ }
+
+ async getAllCredentials(): Promise> {
+ const storage = await this.getStorage();
+ return storage.getAllCredentials();
+ }
+
+ async clearAll(): Promise {
+ const storage = await this.getStorage();
+ await storage.clearAll();
+ }
+
+ async getStorageType(): Promise {
+ await this.getStorage();
+ return this.storageType!;
+ }
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/src/auth/token-storage/index.ts b/workspace-mcp-server/src/auth/token-storage/index.ts
new file mode 100644
index 00000000..6bc6ced3
--- /dev/null
+++ b/workspace-mcp-server/src/auth/token-storage/index.ts
@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from './types';
+export * from './base-token-storage';
+export * from './file-token-storage';
+export * from './hybrid-token-storage';
diff --git a/workspace-mcp-server/src/auth/token-storage/keychain-token-storage.ts b/workspace-mcp-server/src/auth/token-storage/keychain-token-storage.ts
new file mode 100644
index 00000000..c12bca3d
--- /dev/null
+++ b/workspace-mcp-server/src/auth/token-storage/keychain-token-storage.ts
@@ -0,0 +1,249 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as crypto from 'node:crypto';
+import { BaseTokenStorage } from './base-token-storage';
+import type { OAuthCredentials } from './types';
+
+interface Keytar {
+ getPassword(service: string, account: string): Promise;
+ setPassword(
+ service: string,
+ account: string,
+ password: string,
+ ): Promise;
+ deletePassword(service: string, account: string): Promise;
+ findCredentials(
+ service: string,
+ ): Promise>;
+}
+
+const KEYCHAIN_TEST_PREFIX = '__keychain_test__';
+
+export class KeychainTokenStorage extends BaseTokenStorage {
+ private keychainAvailable: boolean | null = null;
+ private keytarModule: Keytar | null = null;
+ private keytarLoadAttempted = false;
+
+ async getKeytar(): Promise {
+ // If we've already tried loading (successfully or not), return the result
+ if (this.keytarLoadAttempted) {
+ return this.keytarModule;
+ }
+
+ this.keytarLoadAttempted = true;
+
+ try {
+ // Try to import keytar without any timeout - let the OS handle it
+ const moduleName = 'keytar';
+ const module = await import(moduleName);
+ this.keytarModule = module.default || module;
+ } catch (error) {
+
+ console.error(error);
+ }
+ return this.keytarModule;
+ }
+
+ async getCredentials(serverName: string): Promise {
+ if (!(await this.checkKeychainAvailability())) {
+ throw new Error('Keychain is not available');
+ }
+
+ const keytar = await this.getKeytar();
+ if (!keytar) {
+ throw new Error('Keytar module not available');
+ }
+
+ try {
+ const sanitizedName = this.sanitizeServerName(serverName);
+ const data = await keytar.getPassword(this.serviceName, sanitizedName);
+
+ if (!data) {
+ return null;
+ }
+
+ const credentials = JSON.parse(data) as OAuthCredentials;
+
+
+
+ return credentials;
+ } catch (error) {
+ if (error instanceof SyntaxError) {
+ throw new Error(`Failed to parse stored credentials for ${serverName}`);
+ }
+ throw error;
+ }
+ }
+
+ async setCredentials(credentials: OAuthCredentials): Promise {
+ if (!(await this.checkKeychainAvailability())) {
+ throw new Error('Keychain is not available');
+ }
+
+ const keytar = await this.getKeytar();
+ if (!keytar) {
+ throw new Error('Keytar module not available');
+ }
+
+ this.validateCredentials(credentials);
+
+ const sanitizedName = this.sanitizeServerName(credentials.serverName);
+ const updatedCredentials: OAuthCredentials = {
+ ...credentials,
+ updatedAt: Date.now(),
+ };
+
+ const data = JSON.stringify(updatedCredentials);
+ await keytar.setPassword(this.serviceName, sanitizedName, data);
+ }
+
+ async deleteCredentials(serverName: string): Promise {
+ if (!(await this.checkKeychainAvailability())) {
+ throw new Error('Keychain is not available');
+ }
+
+ const keytar = await this.getKeytar();
+ if (!keytar) {
+ throw new Error('Keytar module not available');
+ }
+
+ const sanitizedName = this.sanitizeServerName(serverName);
+ const deleted = await keytar.deletePassword(
+ this.serviceName,
+ sanitizedName,
+ );
+
+ if (!deleted) {
+ throw new Error(`No credentials found for ${serverName}`);
+ }
+ }
+
+ async listServers(): Promise {
+ if (!(await this.checkKeychainAvailability())) {
+ throw new Error('Keychain is not available');
+ }
+
+ const keytar = await this.getKeytar();
+ if (!keytar) {
+ throw new Error('Keytar module not available');
+ }
+
+ try {
+ const credentials = await keytar.findCredentials(this.serviceName);
+ return credentials
+ .filter((cred) => !cred.account.startsWith(KEYCHAIN_TEST_PREFIX))
+ .map((cred: { account: string }) => cred.account);
+ } catch (error) {
+ console.error('Failed to list servers from keychain:', error);
+ return [];
+ }
+ }
+
+ async getAllCredentials(): Promise> {
+ if (!(await this.checkKeychainAvailability())) {
+ throw new Error('Keychain is not available');
+ }
+
+ const keytar = await this.getKeytar();
+ if (!keytar) {
+ throw new Error('Keytar module not available');
+ }
+
+ const result = new Map();
+ try {
+ const credentials = (
+ await keytar.findCredentials(this.serviceName)
+ ).filter((c) => !c.account.startsWith(KEYCHAIN_TEST_PREFIX));
+
+ for (const cred of credentials) {
+ try {
+ const data = JSON.parse(cred.password) as OAuthCredentials;
+ this.validateCredentials(data);
+ result.set(cred.account, data);
+ } catch (error) {
+ console.error(
+ `Failed to parse credentials for ${cred.account}:`,
+ error,
+ );
+ }
+ }
+ } catch (error) {
+ console.error('Failed to get all credentials from keychain:', error);
+ }
+
+ return result;
+ }
+
+ async clearAll(): Promise {
+ if (!(await this.checkKeychainAvailability())) {
+ throw new Error('Keychain is not available');
+ }
+
+ const servers = this.keytarModule
+ ? await this.keytarModule
+ .findCredentials(this.serviceName)
+ .then((creds) => creds.map((c) => c.account))
+ .catch((error: Error) => {
+ throw new Error(
+ `Failed to list servers for clearing: ${error.message}`,
+ );
+ })
+ : [];
+ const errors: Error[] = [];
+
+ for (const server of servers) {
+ try {
+ await this.deleteCredentials(server);
+ } catch (error) {
+ errors.push(error as Error);
+ }
+ }
+
+ if (errors.length > 0) {
+ throw new Error(
+ `Failed to clear some credentials: ${errors.map((e) => e.message).join(', ')}`,
+ );
+ }
+ }
+
+ // Checks whether or not a set-get-delete cycle with the keychain works.
+ // Returns false if any operation fails.
+ async checkKeychainAvailability(): Promise {
+ if (this.keychainAvailable !== null) {
+ return this.keychainAvailable;
+ }
+
+ try {
+ const keytar = await this.getKeytar();
+ if (!keytar) {
+ this.keychainAvailable = false;
+ return false;
+ }
+
+ const testAccount = `${KEYCHAIN_TEST_PREFIX}${crypto.randomBytes(8).toString('hex')}`;
+ const testPassword = 'test';
+
+ await keytar.setPassword(this.serviceName, testAccount, testPassword);
+ const retrieved = await keytar.getPassword(this.serviceName, testAccount);
+ const deleted = await keytar.deletePassword(
+ this.serviceName,
+ testAccount,
+ );
+
+ const success = deleted && retrieved === testPassword;
+ this.keychainAvailable = success;
+ return success;
+ } catch (_error) {
+ this.keychainAvailable = false;
+ return false;
+ }
+ }
+
+ async isAvailable(): Promise {
+ return this.checkKeychainAvailability();
+ }
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/src/auth/token-storage/oauth-credential-storage.ts b/workspace-mcp-server/src/auth/token-storage/oauth-credential-storage.ts
new file mode 100644
index 00000000..b314ea6b
--- /dev/null
+++ b/workspace-mcp-server/src/auth/token-storage/oauth-credential-storage.ts
@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type Credentials } from 'google-auth-library';
+import { HybridTokenStorage } from './hybrid-token-storage';
+import type { OAuthCredentials } from './types';
+
+const KEYCHAIN_SERVICE_NAME = 'gemini-cli-workspace-oauth';
+const MAIN_ACCOUNT_KEY = 'main-account';
+
+export class OAuthCredentialStorage {
+ private static storage: HybridTokenStorage = new HybridTokenStorage(
+ KEYCHAIN_SERVICE_NAME,
+ );
+
+ /**
+ * Load cached OAuth credentials
+ */
+ static async loadCredentials(): Promise {
+ try {
+ const credentials = await this.storage.getCredentials(MAIN_ACCOUNT_KEY);
+
+ if (credentials?.token) {
+ const { accessToken, refreshToken, expiresAt, tokenType, scope } =
+ credentials.token;
+ // Convert from OAuthCredentials format to Google Credentials format
+ const googleCreds: Credentials = {
+ access_token: accessToken,
+ refresh_token: refreshToken || undefined,
+ token_type: tokenType || undefined,
+ scope: scope || undefined,
+ };
+
+ if (expiresAt) {
+ googleCreds.expiry_date = expiresAt;
+ }
+
+ return googleCreds;
+ }
+
+ return null;
+ } catch (error: unknown) {
+ throw error;
+ }
+ }
+
+ /**
+ * Save OAuth credentials
+ */
+ static async saveCredentials(credentials: Credentials): Promise {
+ // Convert Google Credentials to OAuthCredentials format
+ const mcpCredentials: OAuthCredentials = {
+ serverName: MAIN_ACCOUNT_KEY,
+ token: {
+ accessToken: credentials.access_token || undefined,
+ refreshToken: credentials.refresh_token || undefined,
+ tokenType: credentials.token_type || 'Bearer',
+ scope: credentials.scope || undefined,
+ expiresAt: credentials.expiry_date || undefined,
+ },
+ updatedAt: Date.now(),
+ };
+
+ await this.storage.setCredentials(mcpCredentials);
+ }
+
+ /**
+ * Clear cached OAuth credentials
+ */
+ static async clearCredentials(): Promise {
+ try {
+ await this.storage.deleteCredentials(MAIN_ACCOUNT_KEY);
+ } catch (error: unknown) {
+ throw error;
+ }
+ }
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/src/auth/token-storage/types.ts b/workspace-mcp-server/src/auth/token-storage/types.ts
new file mode 100644
index 00000000..83f46669
--- /dev/null
+++ b/workspace-mcp-server/src/auth/token-storage/types.ts
@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Interface for OAuth tokens.
+ */
+export interface OAuthToken {
+ accessToken?: string;
+ refreshToken?: string;
+ expiresAt?: number;
+ tokenType: string;
+ scope?: string;
+}
+
+/**
+ * Interface for stored OAuth credentials.
+ */
+export interface OAuthCredentials {
+ serverName: string;
+ token: OAuthToken;
+ clientId?: string;
+ tokenUrl?: string;
+ mcpServerUrl?: string;
+ updatedAt: number;
+}
+
+export enum TokenStorageType {
+ KEYCHAIN = 'keychain',
+ ENCRYPTED_FILE = 'encrypted_file',
+}
+
+export interface TokenStorage {
+ getCredentials(serverName: string): Promise;
+ setCredentials(credentials: OAuthCredentials): Promise;
+ deleteCredentials(serverName: string): Promise;
+ listServers(): Promise;
+ getAllCredentials(): Promise>;
+ clearAll(): Promise;
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/src/index.ts b/workspace-mcp-server/src/index.ts
new file mode 100644
index 00000000..2141fc51
--- /dev/null
+++ b/workspace-mcp-server/src/index.ts
@@ -0,0 +1,647 @@
+#!/usr/bin/env node
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from 'zod';
+import { AuthManager } from './auth/AuthManager';
+import { DocsService } from './services/DocsService';
+import { DriveService } from "./services/DriveService";
+import { CalendarService } from "./services/CalendarService";
+import { ChatService } from "./services/ChatService";
+import { GmailService } from "./services/GmailService";
+import { TimeService } from "./services/TimeService";
+import { PeopleService } from "./services/PeopleService";
+import { SlidesService } from "./services/SlidesService";
+import { SheetsService } from "./services/SheetsService";
+import { GMAIL_SEARCH_MAX_RESULTS } from "./utils/constants";
+import { extractDocId } from "./utils/IdUtils";
+
+import { setLoggingEnabled } from "./utils/logger";
+
+// Shared schemas for Gmail tools
+const emailComposeSchema = {
+ to: z.union([z.string(), z.array(z.string())]).describe('Recipient email address(es).'),
+ subject: z.string().describe('Email subject.'),
+ body: z.string().describe('Email body content.'),
+ cc: z.union([z.string(), z.array(z.string())]).optional().describe('CC recipient email address(es).'),
+ bcc: z.union([z.string(), z.array(z.string())]).optional().describe('BCC recipient email address(es).'),
+ isHtml: z.boolean().optional().describe('Whether the body is HTML (default: false).'),
+};
+
+const SCOPES = [
+ 'https://www.googleapis.com/auth/documents',
+ 'https://www.googleapis.com/auth/drive',
+ 'https://www.googleapis.com/auth/calendar',
+ 'https://www.googleapis.com/auth/chat.spaces',
+ 'https://www.googleapis.com/auth/chat.messages',
+ 'https://www.googleapis.com/auth/chat.memberships',
+ 'https://www.googleapis.com/auth/userinfo.profile',
+ 'https://www.googleapis.com/auth/gmail.modify',
+ 'https://www.googleapis.com/auth/directory.readonly',
+ 'https://www.googleapis.com/auth/presentations.readonly',
+ 'https://www.googleapis.com/auth/spreadsheets.readonly',
+];
+
+async function main() {
+ // 1. Initialize services
+ if (process.argv.includes('--debug')) {
+ setLoggingEnabled(true);
+ }
+
+ const authManager = new AuthManager(SCOPES);
+ const driveService = new DriveService(authManager);
+ await driveService.initialize();
+ const docsService = new DocsService(authManager, driveService);
+ await docsService.initialize();
+ const peopleService = new PeopleService(authManager);
+ await peopleService.initialize();
+ const calendarService = new CalendarService(authManager);
+ await calendarService.initialize();
+ const chatService = new ChatService(authManager);
+ await chatService.initialize();
+ const gmailService = new GmailService(authManager);
+ await gmailService.initialize();
+ const timeService = new TimeService();
+ const slidesService = new SlidesService(authManager);
+ await slidesService.initialize();
+ const sheetsService = new SheetsService(authManager);
+ await sheetsService.initialize();
+
+ // 2. Create the server instance
+ const server = new McpServer({
+ name: "google-workspace-server",
+ version: "1.0.0",
+ });
+
+ // 3. Register tools directly on the server
+ server.registerTool(
+ "docs.create",
+ {
+ description: 'Creates a new Google Doc. Can be blank or with Markdown content.',
+ inputSchema: {
+ title: z.string().describe('The title for the new Google Doc.'),
+ folderName: z.string().optional().describe('The name of the folder to create the document in.'),
+ markdown: z.string().optional().describe('The Markdown content to create the document from.'),
+ }
+ },
+ docsService.create
+ );
+
+ server.registerTool(
+ "docs.insertText",
+ {
+ description: 'Inserts text at the beginning of a Google Doc.',
+ inputSchema: {
+ documentId: z.string().describe('The ID of the document to modify.'),
+ text: z.string().describe('The text to insert at the beginning of the document.'),
+ }
+ },
+ docsService.insertText
+ );
+
+ server.registerTool(
+ "docs.find",
+ {
+ description: 'Finds Google Docs by searching for a query in their title. Supports pagination.',
+ inputSchema: {
+ query: z.string().describe('The text to search for in the document titles.'),
+ pageToken: z.string().optional().describe('The token for the next page of results.'),
+ pageSize: z.number().optional().describe('The maximum number of results to return.'),
+ }
+ },
+ docsService.find
+ );
+
+ server.registerTool(
+ "drive.findFolder",
+ {
+ description: 'Finds a folder by name in Google Drive.',
+ inputSchema: {
+ folderName: z.string().describe('The name of the folder to find.'),
+ }
+ },
+ driveService.findFolder
+ );
+
+ server.registerTool(
+ "docs.move",
+ {
+ description: 'Moves a document to a specified folder.',
+ inputSchema: {
+ documentId: z.string().describe('The ID of the document to move.'),
+ folderName: z.string().describe('The name of the destination folder.'),
+ }
+ },
+ docsService.move
+ );
+
+ server.registerTool(
+ "docs.getText",
+ {
+ description: 'Retrieves the text content of a Google Doc.',
+ inputSchema: {
+ documentId: z.string().describe('The ID of the document to read.'),
+ }
+ },
+ docsService.getText
+ );
+
+ server.registerTool(
+ "docs.appendText",
+ {
+ description: 'Appends text to the end of a Google Doc.',
+ inputSchema: {
+ documentId: z.string().describe('The ID of the document to modify.'),
+ text: z.string().describe('The text to append to the document.'),
+ }
+ },
+ docsService.appendText
+ );
+
+ server.registerTool(
+ "docs.replaceText",
+ {
+ description: 'Replaces all occurrences of a given text with new text in a Google Doc.',
+ inputSchema: {
+ documentId: z.string().describe('The ID of the document to modify.'),
+ findText: z.string().describe('The text to find in the document.'),
+ replaceText: z.string().describe('The text to replace the found text with.'),
+ }
+ },
+ docsService.replaceText
+ );
+
+ server.registerTool(
+ "docs.extractIdFromUrl",
+ {
+ description: 'Extracts the document ID from a Google Workspace URL.',
+ inputSchema: {
+ url: z.string().describe('The URL of the Google Workspace document.'),
+ }
+ },
+ async (input: { url: string }) => {
+ const result = extractDocId(input.url);
+ return {
+ content: [{
+ type: "text" as const,
+ text: result || ''
+ }]
+ };
+ }
+ );
+
+ // Slides tools
+ server.registerTool(
+ "slides.getText",
+ {
+ description: 'Retrieves the text content of a Google Slides presentation.',
+ inputSchema: {
+ presentationId: z.string().describe('The ID or URL of the presentation to read.'),
+ }
+ },
+ slidesService.getText
+ );
+
+ server.registerTool(
+ "slides.find",
+ {
+ description: 'Finds Google Slides presentations by searching for a query. Supports pagination.',
+ inputSchema: {
+ query: z.string().describe('The text to search for in presentations.'),
+ pageToken: z.string().optional().describe('The token for the next page of results.'),
+ pageSize: z.number().optional().describe('The maximum number of results to return.'),
+ }
+ },
+ slidesService.find
+ );
+
+ server.registerTool(
+ "slides.getMetadata",
+ {
+ description: 'Gets metadata about a Google Slides presentation.',
+ inputSchema: {
+ presentationId: z.string().describe('The ID or URL of the presentation.'),
+ }
+ },
+ slidesService.getMetadata
+ );
+
+ // Sheets tools
+ server.registerTool(
+ "sheets.getText",
+ {
+ description: 'Retrieves the content of a Google Sheets spreadsheet.',
+ inputSchema: {
+ spreadsheetId: z.string().describe('The ID or URL of the spreadsheet to read.'),
+ format: z.enum(['text', 'csv', 'json']).optional().describe('Output format (default: text).'),
+ }
+ },
+ sheetsService.getText
+ );
+
+ server.registerTool(
+ "sheets.getRange",
+ {
+ description: 'Gets values from a specific range in a Google Sheets spreadsheet.',
+ inputSchema: {
+ spreadsheetId: z.string().describe('The ID or URL of the spreadsheet.'),
+ range: z.string().describe('The A1 notation range to get (e.g., "Sheet1!A1:B10").'),
+ }
+ },
+ sheetsService.getRange
+ );
+
+ server.registerTool(
+ "sheets.find",
+ {
+ description: 'Finds Google Sheets spreadsheets by searching for a query. Supports pagination.',
+ inputSchema: {
+ query: z.string().describe('The text to search for in spreadsheets.'),
+ pageToken: z.string().optional().describe('The token for the next page of results.'),
+ pageSize: z.number().optional().describe('The maximum number of results to return.'),
+ }
+ },
+ sheetsService.find
+ );
+
+ server.registerTool(
+ "sheets.getMetadata",
+ {
+ description: 'Gets metadata about a Google Sheets spreadsheet.',
+ inputSchema: {
+ spreadsheetId: z.string().describe('The ID or URL of the spreadsheet.'),
+ }
+ },
+ sheetsService.getMetadata
+ );
+
+ server.registerTool(
+ "drive.search",
+ {
+ description: 'Searches for files and folders in Google Drive. The query can be a simple search term, a Google Drive URL, or a full query string. For more information on query strings see: https://developers.google.com/drive/api/guides/search-files',
+ inputSchema: {
+ query: z.string().optional().describe('A simple search term (e.g., "Budget Q3"), a Google Drive URL, or a full query string (e.g., "name contains \'Budget\' and owners in \'user@example.com\'").'),
+ pageSize: z.number().optional().describe('The maximum number of results to return.'),
+ pageToken: z.string().optional().describe('The token for the next page of results.'),
+ corpus: z.string().optional().describe('The corpus of files to search (e.g., "user", "domain").'),
+ unreadOnly: z.boolean().optional().describe('Whether to filter for unread files only.'),
+ sharedWithMe: z.boolean().optional().describe('Whether to search for files shared with the user.'),
+ }
+ },
+ driveService.search
+ );
+
+ server.registerTool(
+ "calendar.list",
+ {
+ description: 'Lists all of the user\'s calendars.',
+ inputSchema: {}
+ },
+ calendarService.listCalendars
+ );
+
+ server.registerTool(
+ "calendar.createEvent",
+ {
+ description: 'Creates a new event in a calendar.',
+ inputSchema: {
+ calendarId: z.string().describe('The ID of the calendar to create the event in.'),
+ summary: z.string().describe('The summary or title of the event.'),
+ start: z.object({
+ dateTime: z.string().describe('The start time in strict ISO 8601 format with seconds and timezone (e.g., 2024-01-15T10:30:00Z or 2024-01-15T10:30:00-05:00).'),
+ }),
+ end: z.object({
+ dateTime: z.string().describe('The end time in strict ISO 8601 format with seconds and timezone (e.g., 2024-01-15T11:30:00Z or 2024-01-15T11:30:00-05:00).'),
+ }),
+ attendees: z.array(z.string()).optional().describe('The email addresses of the attendees.'),
+ }
+ },
+ calendarService.createEvent
+ );
+
+ server.registerTool(
+ "calendar.listEvents",
+ {
+ description: 'Lists events from a calendar. Defaults to upcoming events.',
+ inputSchema: {
+ calendarId: z.string().describe('The ID of the calendar to list events from.'),
+ timeMin: z.string().optional().describe('The start time for the event search. Defaults to the current time.'),
+ timeMax: z.string().optional().describe('The end time for the event search.'),
+ attendeeResponseStatus: z.array(z.string()).optional().describe('The response status of the attendee.'),
+ }
+ },
+ calendarService.listEvents
+ );
+
+ server.registerTool(
+ "calendar.getEvent",
+ {
+ description: 'Gets the details of a specific calendar event.',
+ inputSchema: {
+ eventId: z.string().describe('The ID of the event to retrieve.'),
+ calendarId: z.string().optional().describe('The ID of the calendar the event belongs to. Defaults to the primary calendar.'),
+ }
+ },
+ calendarService.getEvent
+ );
+
+ server.registerTool(
+ "calendar.findFreeTime",
+ {
+ description: 'Finds a free time slot for multiple people to meet.',
+ inputSchema: {
+ attendees: z.array(z.string()).describe('The email addresses of the attendees.'),
+ timeMin: z.string().describe('The start time for the search in strict ISO 8601 format with seconds and timezone (e.g., 2024-01-15T09:00:00Z or 2024-01-15T09:00:00-05:00).'),
+ timeMax: z.string().describe('The end time for the search in strict ISO 8601 format with seconds and timezone (e.g., 2024-01-15T18:00:00Z or 2024-01-15T18:00:00-05:00).'),
+ duration: z.number().describe('The duration of the meeting in minutes.'),
+ }
+ },
+ calendarService.findFreeTime
+ );
+
+ server.registerTool(
+ "calendar.updateEvent",
+ {
+ description: 'Updates an existing event in a calendar.',
+ inputSchema: {
+ eventId: z.string().describe('The ID of the event to update.'),
+ calendarId: z.string().optional().describe('The ID of the calendar to update the event in.'),
+ summary: z.string().optional().describe('The new summary or title of the event.'),
+ start: z.object({
+ dateTime: z.string().describe('The new start time in strict ISO 8601 format with seconds and timezone (e.g., 2024-01-15T10:30:00Z or 2024-01-15T10:30:00-05:00).'),
+ }).optional(),
+ end: z.object({
+ dateTime: z.string().describe('The new end time in strict ISO 8601 format with seconds and timezone (e.g., 2024-01-15T11:30:00Z or 2024-01-15T11:30:00-05:00).'),
+ }).optional(),
+ attendees: z.array(z.string()).optional().describe('The new list of attendees for the event.'),
+ }
+ },
+ calendarService.updateEvent
+ );
+
+ server.registerTool(
+ "calendar.respondToEvent",
+ {
+ description: 'Responds to a meeting invitation (accept, decline, or tentative).',
+ inputSchema: {
+ eventId: z.string().describe('The ID of the event to respond to.'),
+ calendarId: z.string().optional().describe('The ID of the calendar containing the event.'),
+ responseStatus: z.enum(['accepted', 'declined', 'tentative']).describe('Your response to the invitation.'),
+ sendNotification: z.boolean().optional().describe('Whether to send a notification to the organizer (default: true).'),
+ responseMessage: z.string().optional().describe('Optional message to include with your response.'),
+ }
+ },
+ calendarService.respondToEvent
+ );
+
+ server.registerTool(
+ "chat.listSpaces",
+ {
+ description: 'Lists the spaces the user is a member of.',
+ inputSchema: {}
+ },
+ chatService.listSpaces
+ );
+
+ server.registerTool(
+ "chat.findSpaceByName",
+ {
+ description: 'Finds a Google Chat space by its display name.',
+ inputSchema: {
+ displayName: z.string().describe('The display name of the space to find.'),
+ }
+ },
+ chatService.findSpaceByName
+ );
+
+ server.registerTool(
+ "chat.sendMessage",
+ {
+ description: 'Sends a message to a Google Chat space.',
+ inputSchema: {
+ spaceName: z.string().describe('The name of the space to send the message to (e.g., spaces/AAAAN2J52O8).'),
+ message: z.string().describe('The message to send.'),
+ }
+ },
+ chatService.sendMessage
+ );
+
+ server.registerTool(
+ "chat.getMessages",
+ {
+ description: 'Gets messages from a Google Chat space.',
+ inputSchema: {
+ spaceName: z.string().describe('The name of the space to get messages from (e.g., spaces/AAAAN2J52O8).'),
+ unreadOnly: z.boolean().optional().describe('Whether to return only unread messages.'),
+ pageSize: z.number().optional().describe('The maximum number of messages to return.'),
+ pageToken: z.string().optional().describe('The token for the next page of results.'),
+ }
+ },
+ chatService.getMessages
+ );
+
+ server.registerTool(
+ "chat.sendDm",
+ {
+ description: 'Sends a direct message to a user.',
+ inputSchema: {
+ email: z.string().email().describe('The email address of the user to send the message to.'),
+ message: z.string().describe('The message to send.'),
+ }
+ },
+ chatService.sendDm
+ );
+
+ server.registerTool(
+ "chat.findDmByEmail",
+ {
+ description: 'Finds a Google Chat DM space by a user\'s email address.',
+ inputSchema: {
+ email: z.string().email().describe('The email address of the user to find the DM space with.'),
+ }
+ },
+ chatService.findDmByEmail
+ );
+
+ server.registerTool(
+ "chat.listThreads",
+ {
+ description: 'Lists threads from a Google Chat space in reverse chronological order.',
+ inputSchema: {
+ spaceName: z.string().describe('The name of the space to get threads from (e.g., spaces/AAAAN2J52O8).'),
+ pageSize: z.number().optional().describe('The maximum number of threads to return.'),
+ pageToken: z.string().optional().describe('The token for the next page of results.'),
+ }
+ },
+ chatService.listThreads
+ );
+
+ server.registerTool(
+ 'chat.setUpSpace',
+ {
+ description: 'Sets up a new Google Chat space with a display name and a list of members.',
+ inputSchema: {
+ displayName: z.string().describe('The display name of the space.'),
+ userNames: z.array(z.string()).describe('The user names of the members to add to the space (e.g. users/12345678)'),
+ }
+ },
+ chatService.setUpSpace
+ );
+
+
+ // Gmail tools
+ server.registerTool(
+ "gmail.search",
+ {
+ description: 'Search for emails in Gmail using query parameters.',
+ inputSchema: {
+ query: z.string().optional().describe('Search query (same syntax as Gmail search box, e.g., "from:someone@example.com is:unread").'),
+ maxResults: z.number().optional().describe(`Maximum number of results to return (default: ${GMAIL_SEARCH_MAX_RESULTS}).`),
+ pageToken: z.string().optional().describe('Token for the next page of results.'),
+ labelIds: z.array(z.string()).optional().describe('Filter by label IDs (e.g., ["INBOX", "UNREAD"]).'),
+ includeSpamTrash: z.boolean().optional().describe('Include messages from SPAM and TRASH (default: false).'),
+ }
+ },
+ gmailService.search
+ );
+
+ server.registerTool(
+ "gmail.get",
+ {
+ description: 'Get the full content of a specific email message.',
+ inputSchema: {
+ messageId: z.string().describe('The ID of the message to retrieve.'),
+ format: z.enum(['minimal', 'full', 'raw', 'metadata']).optional().describe('Format of the message (default: full).'),
+ }
+ },
+ gmailService.get
+ );
+
+ server.registerTool(
+ "gmail.modify",
+ {
+ description: `Modify a Gmail message. Supported modifications include:
+ - Add labels to a message.
+ - Remove labels from a message.
+There are a list of system labels that can be modified on a message:
+ - INBOX: removing INBOX label removes the message from inbox and archives the message.
+ - SPAM: adding SPAM label marks a message as spam.
+ - TRASH: adding TRASH label moves a message to trash.
+ - UNREAD: removing UNREAD label marks a message as read.
+ - STARRED: adding STARRED label marks a message as starred.
+ - IMPORTANT: adding IMPORTANT label marks a message as important.`,
+ inputSchema: {
+ messageId: z.string().describe('The ID of the message to add labels to and/or remove labels from.'),
+ addLabelIds: z.array(z.string()).max(100).optional().describe('A list of label IDs to add to the message. Limit to 100 labels.'),
+ removeLabelIds: z.array(z.string()).max(100).optional().describe('A list of label IDs to remove from the message. Limit to 100 labels.'),
+ }
+ },
+ gmailService.modify
+ );
+
+ server.registerTool(
+ "gmail.send",
+ {
+ description: 'Send an email message.',
+ inputSchema: emailComposeSchema
+ },
+ gmailService.send
+ );
+
+ server.registerTool(
+ "gmail.createDraft",
+ {
+ description: 'Create a draft email message.',
+ inputSchema: emailComposeSchema
+ },
+ gmailService.createDraft
+ );
+
+ server.registerTool(
+ "gmail.sendDraft",
+ {
+ description: 'Send a previously created draft email.',
+ inputSchema: {
+ draftId: z.string().describe('The ID of the draft to send.'),
+ }
+ },
+ gmailService.sendDraft
+ );
+
+ server.registerTool(
+ "gmail.listLabels",
+ {
+ description: 'List all Gmail labels in the user\'s mailbox.',
+ inputSchema: {}
+ },
+ gmailService.listLabels
+ );
+
+ // Time tools
+ server.registerTool(
+ "time.getCurrentDate",
+ {
+ description: 'Gets the current date.',
+ inputSchema: {}
+ },
+ timeService.getCurrentDate
+ );
+
+ server.registerTool(
+ "time.getCurrentTime",
+ {
+ description: 'Gets the current time.',
+ inputSchema: {}
+ },
+ timeService.getCurrentTime
+ );
+
+ server.registerTool(
+ "time.getTimeZone",
+ {
+ description: 'Gets the local timezone.',
+ inputSchema: {}
+ },
+ timeService.getTimeZone
+ );
+
+ // People tools
+ server.registerTool(
+ "people.getUserProfile",
+ {
+ description: 'Gets a user\'s profile information.',
+ inputSchema: {
+ userId: z.string().optional().describe('The ID of the user to get profile information for.'),
+ email: z.string().optional().describe('The email address of the user to get profile information for.'),
+ name: z.string().optional().describe('The name of the user to get profile information for.'),
+ }
+ },
+ peopleService.getUserProfile
+ );
+
+ server.registerTool(
+ "people.getMe",
+ {
+ description: 'Gets the profile information of the authenticated user.',
+ inputSchema: {}
+ },
+ peopleService.getMe
+ );
+
+ // 4. Connect the transport layer and start listening
+ const transport = new StdioServerTransport();
+ await server.connect(transport);
+
+ console.error("Google Workspace MCP Server is running (registerTool). Listening for requests...");
+}
+
+main().catch(error => {
+ console.error('A critical error occurred:', error);
+ process.exit(1);
+});
diff --git a/workspace-mcp-server/src/services/CalendarService.ts b/workspace-mcp-server/src/services/CalendarService.ts
new file mode 100644
index 00000000..d3df2d44
--- /dev/null
+++ b/workspace-mcp-server/src/services/CalendarService.ts
@@ -0,0 +1,523 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { calendar_v3, google } from 'googleapis';
+import { logToFile } from '../utils/logger';
+import { gaxiosOptions } from '../utils/GaxiosConfig';
+import { iso8601DateTimeSchema, emailArraySchema } from '../utils/validation';
+import { z } from 'zod';
+
+export class CalendarService {
+ private calendar: calendar_v3.Calendar | null = null;
+ private primaryCalendarId: string | null = null;
+
+ constructor(private authManager: any) {
+ }
+
+ private createValidationErrorResponse(error: unknown) {
+ const errorMessage = error instanceof Error ? error.message : 'Validation failed';
+ let helpMessage = 'Please use strict ISO 8601 format with seconds and timezone. Examples: 2024-01-15T10:30:00Z (UTC) or 2024-01-15T10:30:00-05:00 (EST)';
+
+ if (error instanceof z.ZodError && error.issues.some(issue => issue.path.includes('attendees') || issue.message.includes('email'))) {
+ helpMessage = 'Please ensure all attendee emails are in a valid format.';
+ }
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: 'Invalid input format',
+ details: errorMessage,
+ help: helpMessage
+ })
+ }]
+ };
+ }
+
+ async initialize() {
+ logToFile('Initializing CalendarService...');
+ this.calendar = await this.getCalendar();
+ logToFile('CalendarService initialized.');
+ }
+
+ private async getCalendar(): Promise {
+ if (this.calendar) {
+ return this.calendar;
+ }
+ logToFile('Getting authenticated client for calendar...');
+ const auth = await this.authManager.getAuthenticatedClient();
+ logToFile('Got auth client, creating calendar instance...');
+ const options = { ...gaxiosOptions, auth };
+ return google.calendar({ version: 'v3', ...options });
+ }
+
+ private async getPrimaryCalendarId(): Promise {
+ if (this.primaryCalendarId) {
+ return this.primaryCalendarId;
+ }
+ logToFile('Getting primary calendar ID...');
+ const calendar = await this.getCalendar();
+ const res = await calendar.calendarList.list();
+ const primaryCalendar = res.data.items?.find(c => c.primary);
+ if (primaryCalendar && primaryCalendar.id) {
+ logToFile(`Found primary calendar: ${primaryCalendar.id}`);
+ this.primaryCalendarId = primaryCalendar.id;
+ return primaryCalendar.id;
+ }
+ logToFile('No primary calendar found, defaulting to "primary"');
+ return 'primary';
+ }
+
+ listCalendars = async () => {
+ logToFile('listCalendars called');
+ try {
+ logToFile('Getting calendar instance...');
+ const calendar = await this.getCalendar();
+ logToFile('Making API call to calendar.calendarList.list()...');
+ const res = await calendar.calendarList.list();
+ logToFile(`Found ${res.data.items?.length} calendars.`);
+ const calendars = res.data.items || [];
+ logToFile(`Returning calendar data: ${JSON.stringify(calendars.map(c => ({ id: c?.id, summary: c?.summary })))}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(calendars.map(c => ({ id: c?.id, summary: c?.summary })))
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during calendar.list: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ createEvent = async (input: { calendarId?: string, summary: string, start: { dateTime: string }, end: { dateTime: string }, attendees?: string[] }) => {
+ const { calendarId, summary, start, end, attendees } = input;
+
+ // Validate datetime formats
+ try {
+ iso8601DateTimeSchema.parse(start.dateTime);
+ iso8601DateTimeSchema.parse(end.dateTime);
+ if (attendees) {
+ emailArraySchema.parse(attendees);
+ }
+ } catch (error) {
+ return this.createValidationErrorResponse(error);
+ }
+
+ const finalCalendarId = calendarId || await this.getPrimaryCalendarId();
+ logToFile(`Creating event in calendar: ${finalCalendarId}`);
+ logToFile(`Event summary: ${summary}`);
+ logToFile(`Event start: ${start.dateTime}`);
+ logToFile(`Event end: ${end.dateTime}`);
+ logToFile(`Event attendees: ${attendees?.join(', ')}`);
+ try {
+ const event = {
+ summary,
+ start,
+ end,
+ attendees: attendees?.map(email => ({ email }))
+ };
+ const calendar = await this.getCalendar();
+ const res = await calendar.events.insert({
+ calendarId: finalCalendarId,
+ requestBody: event,
+ });
+ logToFile(`Successfully created event: ${res.data.id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(res.data)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during calendar.createEvent: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ listEvents = async (input: { calendarId?: string, timeMin?: string, timeMax?: string, attendeeResponseStatus?: string[] }) => {
+ const { calendarId, timeMin = (new Date()).toISOString(), attendeeResponseStatus = ['accepted', 'tentative', 'needsAction'] } = input;
+
+ let timeMax = input.timeMax;
+ if (!timeMax) {
+ const thirtyDaysFromNow = new Date();
+ thirtyDaysFromNow.setDate(thirtyDaysFromNow.getDate() + 30);
+ timeMax = thirtyDaysFromNow.toISOString();
+ }
+
+ const finalCalendarId = calendarId || await this.getPrimaryCalendarId();
+ logToFile(`Listing events for calendar: ${finalCalendarId}`);
+ try {
+ const calendar = await this.getCalendar();
+ const res = await calendar.events.list({
+ calendarId: finalCalendarId,
+ timeMin,
+ timeMax,
+ singleEvents: true,
+ fields: 'items(id,summary,start,end,description,htmlLink,attendees,status)',
+ });
+
+ const events = res.data.items
+ ?.filter(event => event.status !== 'cancelled' && !!event.summary)
+ .filter(event => {
+ if (!event.attendees || event.attendees.length === 0) {
+ return true; // No attendees, so we can't filter, include it
+ }
+ if (event.attendees.length === 1 && event.attendees[0].self) {
+ return true; // I'm the only one, always include it
+ }
+ const self = event.attendees.find(a => a.self);
+ if (!self) {
+ return true; // We are not an attendee, include it
+ }
+ return attendeeResponseStatus.includes(self.responseStatus || 'needsAction');
+ });
+
+ logToFile(`Found ${events?.length} events after filtering.`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(events)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during calendar.listEvents: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ getEvent = async (input: { eventId: string, calendarId?: string }) => {
+ const { eventId, calendarId } = input;
+ const finalCalendarId = calendarId || await this.getPrimaryCalendarId();
+ logToFile(`Getting event ${eventId} from calendar: ${finalCalendarId}`);
+ try {
+ const calendar = await this.getCalendar();
+ const res = await calendar.events.get({
+ calendarId: finalCalendarId,
+ eventId,
+ });
+ logToFile(`Successfully retrieved event: ${res.data.id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(res.data)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = (error as any).response?.data?.error?.message || (error instanceof Error ? error.message : String(error));
+ logToFile(`Error during calendar.getEvent: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ updateEvent = async (input: { eventId: string, calendarId?: string, summary?: string, start?: { dateTime: string }, end?: { dateTime: string }, attendees?: string[] }) => {
+ const { eventId, calendarId, summary, start, end, attendees } = input;
+
+ // Validate datetime formats if provided
+ try {
+ if (start) {
+ iso8601DateTimeSchema.parse(start.dateTime);
+ }
+ if (end) {
+ iso8601DateTimeSchema.parse(end.dateTime);
+ }
+ if (attendees) {
+ emailArraySchema.parse(attendees);
+ }
+ } catch (error) {
+ return this.createValidationErrorResponse(error);
+ }
+
+ const finalCalendarId = calendarId || await this.getPrimaryCalendarId();
+ logToFile(`Updating event ${eventId} in calendar: ${finalCalendarId}`);
+
+ try {
+ const calendar = await this.getCalendar();
+
+ // Build request body with only the fields to update (patch semantics)
+ const requestBody: calendar_v3.Schema$Event = {};
+ if (summary !== undefined) requestBody.summary = summary;
+ if (start) requestBody.start = start;
+ if (end) requestBody.end = end;
+ if (attendees) requestBody.attendees = attendees.map(email => ({ email }));
+
+ const res = await calendar.events.update({
+ calendarId: finalCalendarId,
+ eventId,
+ requestBody,
+ });
+
+ logToFile(`Successfully updated event: ${res.data.id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(res.data)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during calendar.updateEvent: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ respondToEvent = async (input: { eventId: string, calendarId?: string, responseStatus: 'accepted' | 'declined' | 'tentative', sendNotification?: boolean, responseMessage?: string }) => {
+ const { eventId, calendarId, responseStatus, sendNotification = true, responseMessage } = input;
+ const finalCalendarId = calendarId || await this.getPrimaryCalendarId();
+
+ logToFile(`Responding to event ${eventId} in calendar: ${finalCalendarId} with status: ${responseStatus}`);
+ if (responseMessage) {
+ logToFile(`Response message: ${responseMessage}`);
+ }
+
+ try {
+ const calendar = await this.getCalendar();
+
+ // First, get the current event to find the attendee entry
+ const event = await calendar.events.get({
+ calendarId: finalCalendarId,
+ eventId,
+ });
+
+ if (!event.data.attendees || event.data.attendees.length === 0) {
+ logToFile('Event has no attendees');
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: 'Event has no attendees' })
+ }]
+ };
+ }
+
+ // Find the current user's attendee entry
+ const selfAttendee = event.data.attendees.find(a => a.self === true);
+ if (!selfAttendee) {
+ logToFile('User is not an attendee of this event');
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: 'You are not an attendee of this event' })
+ }]
+ };
+ }
+
+ // Update the response status for the current user
+ selfAttendee.responseStatus = responseStatus;
+ if (responseMessage !== undefined) {
+ selfAttendee.comment = responseMessage;
+ }
+
+ // Patch the event with the updated attendee list
+ const res = await calendar.events.patch({
+ calendarId: finalCalendarId,
+ eventId,
+ sendNotifications: sendNotification,
+ requestBody: {
+ attendees: event.data.attendees
+ }
+ });
+
+ logToFile(`Successfully responded to event: ${res.data.id} with status: ${responseStatus}`);
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ eventId: res.data.id,
+ summary: res.data.summary,
+ responseStatus,
+ message: `Successfully ${responseStatus} the meeting invitation${responseMessage ? ' with message' : ''}`
+ })
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during calendar.respondToEvent: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ findFreeTime = async (input: { attendees: string[], timeMin: string, timeMax: string, duration: number }) => {
+ const { attendees, timeMin, timeMax, duration } = input;
+
+ // Validate datetime formats
+ try {
+ iso8601DateTimeSchema.parse(timeMin);
+ iso8601DateTimeSchema.parse(timeMax);
+ // Note: attendees can include 'me' as a special value, so we don't validate as emails
+ } catch (error) {
+ return this.createValidationErrorResponse(error);
+ }
+
+ logToFile(`Finding free time for attendees: ${attendees.join(', ')}`);
+ logToFile(`Time range: ${timeMin} - ${timeMax}`);
+ logToFile(`Duration: ${duration} minutes`);
+
+ try {
+ const calendar = await this.getCalendar();
+ const items = await Promise.all(attendees.map(async (email) => {
+ if (email === 'me') {
+ const primaryId = await this.getPrimaryCalendarId();
+ return { id: primaryId };
+ }
+ return { id: email };
+ }));
+
+ const res = await calendar.freebusy.query({
+ requestBody: {
+ items,
+ timeMin,
+ timeMax,
+ },
+ });
+
+ const busyTimes = Object.values(res.data.calendars || {}).flatMap(cal => cal.busy || []);
+ if (busyTimes.length === 0) {
+ logToFile('No busy times found, returning the start of the time range.');
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ start: timeMin, end: new Date(new Date(timeMin).getTime() + duration * 60000).toISOString() })
+ }]
+ };
+ }
+
+ // Sort and merge overlapping busy intervals for better performance
+ const sortedBusyTimes = busyTimes
+ .filter(busy => busy.start && busy.end)
+ .map(busy => ({
+ start: new Date(busy.start!).getTime(),
+ end: new Date(busy.end!).getTime()
+ }))
+ .sort((a, b) => a.start - b.start);
+
+ const mergedBusyTimes: { start: number; end: number }[] = [];
+ for (const busy of sortedBusyTimes) {
+ if (mergedBusyTimes.length === 0) {
+ mergedBusyTimes.push(busy);
+ } else {
+ const last = mergedBusyTimes[mergedBusyTimes.length - 1];
+ if (busy.start <= last.end) {
+ // Overlapping or adjacent intervals - merge them
+ last.end = Math.max(last.end, busy.end);
+ } else {
+ mergedBusyTimes.push(busy);
+ }
+ }
+ }
+
+ const startTime = new Date(timeMin).getTime();
+ const endTime = new Date(timeMax).getTime();
+ const durationMs = duration * 60000;
+
+ // If no busy times, return the start of the range
+ if (mergedBusyTimes.length === 0) {
+ const slotEnd = new Date(startTime + durationMs);
+ logToFile(`No busy times, found free time: ${timeMin} - ${slotEnd.toISOString()}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ start: timeMin, end: slotEnd.toISOString() })
+ }]
+ };
+ }
+
+ // Check if we can fit the meeting before the first busy slot
+ if (startTime + durationMs <= mergedBusyTimes[0].start) {
+ const slotEnd = new Date(startTime + durationMs);
+ logToFile(`Found free time: ${timeMin} - ${slotEnd.toISOString()}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ start: timeMin, end: slotEnd.toISOString() })
+ }]
+ };
+ }
+
+ // Check gaps between busy slots
+ for (let i = 0; i < mergedBusyTimes.length - 1; i++) {
+ const gapStart = mergedBusyTimes[i].end;
+ const gapEnd = mergedBusyTimes[i + 1].start;
+
+ if (gapEnd - gapStart >= durationMs) {
+ const slotStart = new Date(gapStart);
+ const slotEnd = new Date(gapStart + durationMs);
+ logToFile(`Found free time: ${slotStart.toISOString()} - ${slotEnd.toISOString()}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ start: slotStart.toISOString(), end: slotEnd.toISOString() })
+ }]
+ };
+ }
+ }
+
+ // Check if we can fit after the last busy slot
+ const lastBusyEnd = mergedBusyTimes[mergedBusyTimes.length - 1].end;
+ if (lastBusyEnd + durationMs <= endTime) {
+ const slotStart = new Date(lastBusyEnd);
+ const slotEnd = new Date(lastBusyEnd + durationMs);
+ logToFile(`Found free time: ${slotStart.toISOString()} - ${slotEnd.toISOString()}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ start: slotStart.toISOString(), end: slotEnd.toISOString() })
+ }]
+ };
+ }
+
+ logToFile('No available free time found');
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: 'No available free time found' })
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during calendar.findFreeTime: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+}
diff --git a/workspace-mcp-server/src/services/ChatService.ts b/workspace-mcp-server/src/services/ChatService.ts
new file mode 100644
index 00000000..223ff6d9
--- /dev/null
+++ b/workspace-mcp-server/src/services/ChatService.ts
@@ -0,0 +1,433 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { google, chat_v1, people_v1, Auth } from 'googleapis';
+import { AuthManager } from '../auth/AuthManager';
+import { logToFile } from '../utils/logger';
+import { gaxiosOptions } from '../utils/GaxiosConfig';
+
+export class ChatService {
+ private chat: chat_v1.Chat;
+ private people: people_v1.People;
+ private authClient: Auth.OAuth2Client;
+
+ constructor(private authManager: AuthManager) {
+ this.chat = {} as chat_v1.Chat;
+ this.people = {} as people_v1.People;
+ this.authClient = {} as Auth.OAuth2Client;
+ }
+
+ public async initialize(): Promise {
+ this.authClient = await this.authManager.getAuthenticatedClient();
+ const options = { ...gaxiosOptions, auth: this.authClient };
+ this.chat = google.chat({
+ version: 'v1',
+ ...options,
+ });
+ this.people = google.people({
+ version: 'v1',
+ ...options,
+ });
+ }
+
+ private async _setupDmSpace(email: string): Promise {
+ const person = {
+ name: `users/${email}`,
+ type: 'HUMAN',
+ };
+
+ const setupResponse = await this.chat.spaces.setup({
+ requestBody: {
+ space: {
+ spaceType: 'DIRECT_MESSAGE',
+ },
+ memberships: [
+ {
+ member: person,
+ },
+ ],
+ },
+ });
+
+ const space = setupResponse.data;
+ if (!space) {
+ throw new Error('Could not find or create a DM space.');
+ }
+ return space;
+ }
+
+ public listSpaces = async () => {
+ logToFile('Listing chat spaces');
+ try {
+ const res = await this.chat.spaces.list({});
+ const spaces = res.data.spaces || [];
+ logToFile(`Successfully listed ${spaces.length} chat spaces.`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(spaces)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during chat.listSpaces: ${errorMessage}`);
+ if (error instanceof Error && error.stack) {
+ logToFile(`Stack trace: ${error.stack}`);
+ }
+ logToFile(`Full error object: ${JSON.stringify(error, null, 2)}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: 'An error occurred while listing chat spaces.',
+ details: errorMessage
+ })
+ }]
+ };
+ }
+ }
+
+ public sendMessage = async ({ spaceName, message }: { spaceName: string, message: string }) => {
+ logToFile(`Sending message to space: ${spaceName}`);
+ try {
+ const response = await this.chat.spaces.messages.create({
+ parent: spaceName,
+ requestBody: {
+ text: message,
+ },
+ });
+ logToFile(`Successfully sent message to space: ${spaceName}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(response.data)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during chat.sendMessage: ${errorMessage}`);
+ if (error instanceof Error && error.stack) {
+ logToFile(`Stack trace: ${error.stack}`);
+ }
+ logToFile(`Full error object: ${JSON.stringify(error, null, 2)}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: 'An error occurred while sending the message.',
+ details: errorMessage
+ })
+ }]
+ };
+ }
+ }
+
+ public findSpaceByName = async ({ displayName }: { displayName: string }) => {
+ logToFile(`Finding space with display name: ${displayName}`);
+ try {
+ // The Chat API's spaces.list method does not support filtering by
+ // displayName on the server. We must fetch all spaces and filter locally.
+ let pageToken: string | undefined = undefined;
+ let allSpaces: chat_v1.Schema$Space[] = [];
+
+ do {
+ const res: any = await this.chat.spaces.list({ pageToken });
+ const spaces = res.data.spaces || [];
+ allSpaces = allSpaces.concat(spaces);
+ pageToken = res.data.nextPageToken || undefined;
+ } while (pageToken);
+
+ const foundSpaces = allSpaces.filter(space => space.displayName === displayName);
+
+ if (foundSpaces.length > 0) {
+ logToFile(`Found ${foundSpaces.length} space(s) with display name: ${displayName}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(foundSpaces)
+ }]
+ };
+ } else {
+ logToFile(`No space found with display name: ${displayName}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: `No space found with display name: ${displayName}`
+ })
+ }]
+ };
+ }
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during chat.findSpaceByName: ${errorMessage}`);
+ if (error instanceof Error && error.stack) {
+ logToFile(`Stack trace: ${error.stack}`);
+ }
+ logToFile(`Full error object: ${JSON.stringify(error, null, 2)}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: 'An error occurred while finding the space.',
+ details: errorMessage
+ })
+ }]
+ };
+ }
+ }
+
+ public getMessages = async ({ spaceName, unreadOnly, pageSize, pageToken }: { spaceName: string, unreadOnly?: boolean, pageSize?: number, pageToken?: string }) => {
+ logToFile(`Listing messages for space: ${spaceName}`);
+ try {
+ if (unreadOnly) {
+ const person = await this.people.people.get({
+ resourceName: 'people/me',
+ personFields: 'metadata',
+ });
+
+ const userId = person.data.metadata?.sources?.find(s => s.type === 'PROFILE')?.id;
+
+ if (!userId) {
+ throw new Error('Could not determine user ID.');
+ }
+ const userMemberName = `users/${userId}`;
+
+ const membersRes = await this.chat.spaces.members.list({
+ parent: spaceName,
+ });
+ // Type assertion needed due to incomplete type definitions
+ const memberships = (membersRes.data as any).memberships || [];
+ const currentUserMember = memberships.find((m: any) => m.member?.name === userMemberName);
+
+ const lastReadTime = currentUserMember?.lastReadTime;
+
+ if (!lastReadTime) {
+ logToFile(`No last read time found for user in space: ${spaceName}`);
+ // This can happen if the user has never read messages in the space.
+ // In this case, all messages are unread.
+ const res = await this.chat.spaces.messages.list({ parent: spaceName, pageSize, pageToken });
+ const messages = res.data.messages || [];
+ logToFile(`Successfully listed ${messages.length} unread messages for space: ${spaceName}`);
+ return { content: [{ type: "text" as const, text: JSON.stringify({ messages, nextPageToken: res.data.nextPageToken }) }] };
+ }
+
+ const res = await this.chat.spaces.messages.list({
+ parent: spaceName,
+ filter: `createTime > "${lastReadTime}"`,
+ pageSize,
+ pageToken,
+ });
+
+ const messages = res.data.messages || [];
+ logToFile(`Successfully listed ${messages.length} unread messages for space: ${spaceName}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ messages, nextPageToken: res.data.nextPageToken })
+ }]
+ };
+
+ } else {
+ const res = await this.chat.spaces.messages.list({
+ parent: spaceName,
+ pageSize,
+ pageToken,
+ });
+ const messages = res.data.messages || [];
+ logToFile(`Successfully listed ${messages.length} messages for space: ${spaceName}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ messages, nextPageToken: res.data.nextPageToken })
+ }]
+ };
+ }
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during chat.getMessages: ${errorMessage}`);
+ if (error instanceof Error && error.stack) {
+ logToFile(`Stack trace: ${error.stack}`);
+ }
+ logToFile(`Full error object: ${JSON.stringify(error, null, 2)}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: 'An error occurred while listing messages.',
+ details: errorMessage
+ })
+ }]
+ };
+ }
+ }
+
+ public sendDm = async ({ email, message }: { email: string, message: string }) => {
+ logToFile(`chat.sendDm called with: email=${email}, message=${message}`);
+ try {
+ const space = await this._setupDmSpace(email);
+ const spaceName = space.name;
+
+ if (!spaceName) {
+ throw new Error('Could not determine the space name for the DM.');
+ }
+
+ // Send the message to the DM space.
+ const messageResponse = await this.chat.spaces.messages.create({
+ parent: spaceName,
+ requestBody: {
+ text: message,
+ },
+ });
+
+ logToFile(`Successfully sent DM to: ${email}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(messageResponse.data)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during chat.sendDm: ${errorMessage}`);
+ if (error instanceof Error && error.stack) {
+ logToFile(`Stack trace: ${error.stack}`);
+ }
+ logToFile(`Full error object: ${JSON.stringify(error, null, 2)}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: 'An error occurred while sending the DM.',
+ details: errorMessage
+ })
+ }]
+ };
+ }
+ }
+
+ public findDmByEmail = async ({ email }: { email: string }) => {
+ logToFile(`Finding DM space with user: ${email}`);
+ try {
+ const space = await this._setupDmSpace(email);
+ logToFile(`Found or created DM space: ${space.name}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(space)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during chat.findDmByEmail: ${errorMessage}`);
+ if (error instanceof Error && error.stack) {
+ logToFile(`Stack trace: ${error.stack}`);
+ }
+ logToFile(`Full error object: ${JSON.stringify(error, null, 2)}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: 'An error occurred while finding the DM space.',
+ details: errorMessage
+ })
+ }]
+ };
+ }
+ }
+
+ public listThreads = async ({ spaceName, pageSize, pageToken }: { spaceName: string, pageSize?: number, pageToken?: string }) => {
+ logToFile(`Listing threads for space: ${spaceName}`);
+ try {
+ const res = await this.chat.spaces.messages.list({
+ parent: spaceName,
+ pageSize,
+ pageToken,
+ orderBy: 'createTime desc',
+ });
+
+ const messages = res.data.messages || [];
+ const threads: chat_v1.Schema$Message[] = [];
+ const threadIds = new Set();
+
+ for (const message of messages) {
+ if (message.thread?.name && !threadIds.has(message.thread.name)) {
+ threads.push(message);
+ threadIds.add(message.thread.name);
+ }
+ }
+
+ logToFile(`Successfully listed ${threads.length} threads for space: ${spaceName}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ threads, nextPageToken: res.data.nextPageToken })
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during chat.listThreads: ${errorMessage}`);
+ if (error instanceof Error && error.stack) {
+ logToFile(`Stack trace: ${error.stack}`);
+ }
+ logToFile(`Full error object: ${JSON.stringify(error, null, 2)}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: 'An error occurred while listing threads.',
+ details: errorMessage
+ })
+ }]
+ };
+ }
+ }
+
+ public setUpSpace = async ({ displayName, userNames }: { displayName: string, userNames: string[] }) => {
+ logToFile(`Creating space with display name: ${displayName}`);
+ try {
+ const memberships = userNames.map(userName => ({
+ member: {
+ name: userName,
+ type: 'HUMAN',
+ },
+ }));
+
+ const response = await this.chat.spaces.setup({
+ requestBody: {
+ space: {
+ spaceType: 'SPACE',
+ displayName,
+ },
+ memberships: memberships,
+ },
+ });
+ logToFile(`Successfully created space: ${response.data.name}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(response.data)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during chat.createSpace: ${errorMessage}`);
+ if (error instanceof Error && error.stack) {
+ logToFile(`Stack trace: ${error.stack}`);
+ }
+ logToFile(`Full error object: ${JSON.stringify(error, null, 2)}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: 'An error occurred while creating the space.',
+ details: errorMessage
+ })
+ }]
+ };
+ }
+ }
+}
diff --git a/workspace-mcp-server/src/services/DocsService.ts b/workspace-mcp-server/src/services/DocsService.ts
new file mode 100644
index 00000000..3f2dcbcd
--- /dev/null
+++ b/workspace-mcp-server/src/services/DocsService.ts
@@ -0,0 +1,493 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { google, docs_v1, drive_v3, Auth } from 'googleapis';
+import { AuthManager } from '../auth/AuthManager';
+import { DriveService } from './DriveService';
+import { logToFile } from '../utils/logger';
+import { extractDocId } from '../utils/IdUtils';
+import { marked } from 'marked';
+import { Readable } from 'node:stream';
+import createDOMPurify from 'dompurify';
+import { JSDOM } from 'jsdom';
+import { gaxiosOptions, mediaUploadOptions } from '../utils/GaxiosConfig';
+import { buildDriveSearchQuery, MIME_TYPES } from '../utils/DriveQueryBuilder';
+import { extractDocumentId as validateAndExtractDocId } from '../utils/validation';
+import { parseMarkdownToDocsRequests, processMarkdownLineBreaks } from '../utils/markdownToDocsRequests';
+
+export class DocsService {
+ private docs: docs_v1.Docs;
+ private drive: drive_v3.Drive;
+ private purify: ReturnType;
+
+ constructor(private authManager: AuthManager, private driveService: DriveService) {
+ this.docs = {} as docs_v1.Docs;
+ this.drive = {} as drive_v3.Drive;
+ const window = new JSDOM('').window;
+ this.purify = createDOMPurify(window as any);
+ }
+
+ public async initialize(): Promise {
+ const auth: Auth.OAuth2Client = await this.authManager.getAuthenticatedClient();
+ const options = { ...gaxiosOptions, auth };
+ this.docs = google.docs({ version: 'v1', ...options });
+ this.drive = google.drive({ version: 'v3', ...options });
+ }
+
+ public create = async ({ title, folderName, markdown }: { title: string, folderName?: string, markdown?: string }) => {
+ logToFile(`[DocsService] Starting create with title: ${title}, folderName: ${folderName}, markdown: ${markdown ? 'true' : 'false'}`);
+ try {
+ const docInfo = await (async (): Promise<{ documentId: string; title: string; }> => {
+ if (markdown) {
+ logToFile('[DocsService] Creating doc with markdown');
+ const unsafeHtml = await marked.parse(markdown);
+ const html = this.purify.sanitize(unsafeHtml);
+
+ const fileMetadata = {
+ name: title,
+ mimeType: 'application/vnd.google-apps.document',
+ };
+
+ const media = {
+ mimeType: 'text/html',
+ body: Readable.from(html),
+ };
+
+ logToFile('[DocsService] Calling drive.files.create');
+ const file = await this.drive.files.create({
+ requestBody: fileMetadata,
+ media: media,
+ fields: 'id, name',
+ }, mediaUploadOptions);
+ logToFile('[DocsService] drive.files.create finished');
+ return { documentId: file.data.id!, title: file.data.name! };
+ } else {
+ logToFile('[DocsService] Creating blank doc');
+ logToFile('[DocsService] Calling docs.documents.create');
+ const doc = await this.docs.documents.create({
+ requestBody: { title },
+ });
+ logToFile('[DocsService] docs.documents.create finished');
+ return { documentId: doc.data.documentId!, title: doc.data.title! };
+ }
+ })();
+
+ if (folderName) {
+ logToFile(`[DocsService] Moving doc to folder: ${folderName}`);
+ await this._moveFileToFolder(docInfo.documentId, folderName);
+ logToFile(`[DocsService] Finished moving doc to folder: ${folderName}`);
+ }
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ documentId: docInfo.documentId,
+ title: docInfo.title,
+ })
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during docs.create: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ public insertText = async ({ documentId, text }: { documentId: string, text: string }) => {
+ logToFile(`[DocsService] Starting insertText for document: ${documentId}`);
+ try {
+ const id = extractDocId(documentId) || documentId;
+
+ // Parse markdown and generate formatting requests
+ const { plainText, formattingRequests } = parseMarkdownToDocsRequests(text, 1);
+ const processedText = processMarkdownLineBreaks(plainText);
+
+ // Build batch update requests
+ const requests: docs_v1.Schema$Request[] = [
+ {
+ insertText: {
+ location: { index: 1 },
+ text: processedText,
+ },
+ }
+ ];
+
+ // Add formatting requests if any
+ if (formattingRequests.length > 0) {
+ requests.push(...formattingRequests);
+ }
+
+ const res = await this.docs.documents.batchUpdate({
+ documentId: id,
+ requestBody: {
+ requests,
+ },
+ });
+
+ logToFile(`[DocsService] Finished insertText for document: ${id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ documentId: res.data.documentId!,
+ writeControl: res.data.writeControl!,
+ })
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[DocsService] Error during docs.insertText: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ public find = async ({ query, pageToken, pageSize = 10 }: { query: string, pageToken?: string, pageSize?: number }) => {
+ logToFile(`Searching for documents with query: ${query}`);
+ if (pageToken) {
+ logToFile(`Using pageToken: ${pageToken}`);
+ }
+ if (pageSize) {
+ logToFile(`Using pageSize: ${pageSize}`);
+ }
+ try {
+ const q = buildDriveSearchQuery(MIME_TYPES.DOCUMENT, query);
+ logToFile(`Executing Drive API query: ${q}`);
+
+ const res = await this.drive.files.list({
+ pageSize: pageSize,
+ fields: 'nextPageToken, files(id, name)',
+ q: q,
+ pageToken: pageToken,
+ });
+
+ const files = res.data.files || [];
+ const nextPageToken = res.data.nextPageToken;
+
+ logToFile(`Found ${files.length} files.`);
+ if (nextPageToken) {
+ logToFile(`Next page token: ${nextPageToken}`);
+ }
+ logToFile(`API Response: ${JSON.stringify(res.data, null, 2)}`);
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ files: files,
+ nextPageToken: nextPageToken
+ })
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during docs.find: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ public move = async ({ documentId, folderName }: { documentId: string, folderName: string }) => {
+ logToFile(`[DocsService] Starting move for document: ${documentId}`);
+ try {
+ const id = extractDocId(documentId) || documentId;
+ await this._moveFileToFolder(id, folderName);
+ logToFile(`[DocsService] Finished move for document: ${id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: `Moved document ${id} to folder ${folderName}`
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[DocsService] Error during docs.move: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ public getText = async ({ documentId }: { documentId: string }) => {
+ logToFile(`[DocsService] Starting getText for document: ${documentId}`);
+ try {
+ // Validate and extract document ID
+ const id = validateAndExtractDocId(documentId);
+ const res = await this.docs.documents.get({
+ documentId: id,
+ fields: 'body',
+ });
+
+ const body = res.data.body;
+ let text = '';
+ if (body && body.content) {
+ body.content.forEach(element => {
+ text += this._readStructuralElement(element);
+ });
+ }
+
+ logToFile(`[DocsService] Finished getText for document: ${id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: text
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[DocsService] Error during docs.getText: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ private _readStructuralElement(element: docs_v1.Schema$StructuralElement): string {
+ let text = '';
+ if (element.paragraph) {
+ element.paragraph.elements?.forEach(pElement => {
+ if (pElement.textRun && pElement.textRun.content) {
+ text += pElement.textRun.content;
+ }
+ });
+ } else if (element.table) {
+ element.table.tableRows?.forEach(row => {
+ row.tableCells?.forEach(cell => {
+ cell.content?.forEach(cellContent => {
+ text += this._readStructuralElement(cellContent);
+ });
+ });
+ });
+ }
+ return text;
+ }
+
+ public appendText = async ({ documentId, text }: { documentId: string, text: string }) => {
+ logToFile(`[DocsService] Starting appendText for document: ${documentId}`);
+ try {
+ const id = extractDocId(documentId) || documentId;
+ const res = await this.docs.documents.get({
+ documentId: id,
+ fields: 'body',
+ });
+
+ const body = res.data.body;
+ const lastElement = body?.content?.[body.content.length - 1];
+ const endIndex = lastElement?.endIndex || 1;
+
+ const locationIndex = Math.max(1, endIndex - 1);
+
+ // Parse markdown and generate formatting requests
+ const { plainText, formattingRequests } = parseMarkdownToDocsRequests(text, locationIndex);
+ const processedText = processMarkdownLineBreaks(plainText);
+
+ // Build batch update requests
+ const requests: docs_v1.Schema$Request[] = [
+ {
+ insertText: {
+ location: { index: locationIndex },
+ text: processedText,
+ },
+ }
+ ];
+
+ // Add formatting requests if any
+ if (formattingRequests.length > 0) {
+ requests.push(...formattingRequests);
+ }
+
+ await this.docs.documents.batchUpdate({
+ documentId: id,
+ requestBody: {
+ requests,
+ },
+ });
+
+ logToFile(`[DocsService] Finished appendText for document: ${id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: `Successfully appended text to document ${id}`
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[DocsService] Error during docs.appendText: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ public replaceText = async ({ documentId, findText, replaceText }: { documentId: string, findText: string, replaceText: string }) => {
+ logToFile(`[DocsService] Starting replaceText for document: ${documentId}`);
+ try {
+ const id = extractDocId(documentId) || documentId;
+
+ // Parse markdown to get plain text and formatting info
+ const { plainText, formattingRequests: originalFormattingRequests } = parseMarkdownToDocsRequests(replaceText, 0);
+ const processedText = processMarkdownLineBreaks(plainText);
+
+ // First, get the document to find where the text will be replaced
+ const docBefore = await this.docs.documents.get({
+ documentId: id,
+ fields: 'body',
+ });
+
+ // Find all occurrences of the text to be replaced
+ const documentText = this._getFullDocumentText(docBefore.data.body);
+ const occurrences: number[] = [];
+ let searchIndex = 0;
+ while ((searchIndex = documentText.indexOf(findText, searchIndex)) !== -1) {
+ occurrences.push(searchIndex + 1); // Google Docs uses 1-based indexing
+ searchIndex += findText.length;
+ }
+
+ // Build batch update requests
+ const requests: docs_v1.Schema$Request[] = [
+ {
+ replaceAllText: {
+ replaceText: processedText,
+ containsText: {
+ text: findText,
+ matchCase: true,
+ },
+ },
+ }
+ ];
+
+ // Calculate formatting positions for each replacement
+ // After replacement, we need to adjust indices based on text length difference
+ const lengthDiff = processedText.length - findText.length;
+ let cumulativeOffset = 0;
+
+ for (let i = 0; i < occurrences.length; i++) {
+ const occurrence = occurrences[i];
+ const adjustedPosition = occurrence + cumulativeOffset - 1; // Subtract 1 because parseMarkdownToDocsRequests expects 0-based
+
+ // Adjust formatting requests for this occurrence
+ for (const formatRequest of originalFormattingRequests) {
+ if (formatRequest.updateTextStyle) {
+ const adjustedRequest: docs_v1.Schema$Request = {
+ updateTextStyle: {
+ ...formatRequest.updateTextStyle,
+ range: {
+ startIndex: (formatRequest.updateTextStyle.range?.startIndex || 0) + adjustedPosition,
+ endIndex: (formatRequest.updateTextStyle.range?.endIndex || 0) + adjustedPosition
+ }
+ }
+ };
+ requests.push(adjustedRequest);
+ }
+ }
+
+ cumulativeOffset += lengthDiff;
+ }
+
+ await this.docs.documents.batchUpdate({
+ documentId: id,
+ requestBody: {
+ requests,
+ },
+ });
+
+ logToFile(`[DocsService] Finished replaceText for document: ${id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: `Successfully replaced text in document ${id}`
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[DocsService] Error during docs.replaceText: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ private _getFullDocumentText(body: docs_v1.Schema$Body | undefined): string {
+ let text = '';
+ if (body && body.content) {
+ body.content.forEach(element => {
+ text += this._readStructuralElement(element);
+ });
+ }
+ return text;
+ }
+
+
+
+ private async _moveFileToFolder(documentId: string, folderName: string): Promise {
+ try {
+ const findFolderResponse = await this.driveService.findFolder({ folderName });
+ const parsedResponse = JSON.parse(findFolderResponse.content[0].text);
+
+ if (parsedResponse.error) {
+ throw new Error(parsedResponse.error);
+ }
+
+ const folders = parsedResponse as { id: string, name: string }[];
+
+ if (folders.length === 0) {
+ throw new Error(`Folder not found: ${folderName}`);
+ }
+
+ if (folders.length > 1) {
+ logToFile(`Warning: Found multiple folders with name "${folderName}". Using the first one found.`);
+ }
+
+ const folderId = folders[0].id;
+ const file = await this.drive.files.get({
+ fileId: documentId,
+ fields: 'parents',
+ });
+
+ const previousParents = file.data.parents?.join(',');
+
+ await this.drive.files.update({
+ fileId: documentId,
+ addParents: folderId,
+ removeParents: previousParents,
+ fields: 'id, parents',
+ });
+ } catch (error) {
+ if (error instanceof Error) {
+ logToFile(`Error during _moveFileToFolder: ${error.message}`);
+ } else {
+ logToFile(`An unknown error occurred during _moveFileToFolder: ${JSON.stringify(error)}`);
+ }
+ throw error;
+ }
+ }
+}
diff --git a/workspace-mcp-server/src/services/DriveService.ts b/workspace-mcp-server/src/services/DriveService.ts
new file mode 100644
index 00000000..e6fd2dcc
--- /dev/null
+++ b/workspace-mcp-server/src/services/DriveService.ts
@@ -0,0 +1,234 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { google, drive_v3, Auth } from 'googleapis';
+import { AuthManager } from '../auth/AuthManager';
+import { logToFile } from '../utils/logger';
+import { gaxiosOptions } from '../utils/GaxiosConfig';
+import { escapeQueryString } from '../utils/DriveQueryBuilder';
+
+const MIN_DRIVE_ID_LENGTH = 25;
+
+const URL_PATTERNS = [
+ { pattern: /\/folders\/([a-zA-Z0-9-_]+)/, type: 'folder' as const },
+ { pattern: /\/file\/d\/([a-zA-Z0-9-_]+)/, type: 'file' as const },
+ { pattern: /\/document\/d\/([a-zA-Z0-9-_]+)/, type: 'file' as const },
+ { pattern: /\/spreadsheets\/d\/([a-zA-Z0-9-_]+)/, type: 'file' as const },
+ { pattern: /\/presentation\/d\/([a-zA-Z0-9-_]+)/, type: 'file' as const },
+ { pattern: /\/forms\/d\/([a-zA-Z0-9-_]+)/, type: 'file' as const },
+ { pattern: /[?&]id=([a-zA-Z0-9-_]+)/, type: 'unknown' as const }
+];
+
+export class DriveService {
+ private drive: drive_v3.Drive;
+
+ constructor(private authManager: AuthManager) {
+ this.drive = {} as drive_v3.Drive;
+ }
+
+ public async initialize(): Promise {
+ const auth: Auth.OAuth2Client = await this.authManager.getAuthenticatedClient();
+ const options = { ...gaxiosOptions, auth };
+ this.drive = google.drive({ version: 'v3', ...options });
+ }
+
+ public findFolder = async ({ folderName }: { folderName: string }) => {
+ logToFile(`Searching for folder with name: ${folderName}`);
+ try {
+ const query = `mimeType='application/vnd.google-apps.folder' and name = '${folderName}'`;
+ logToFile(`Executing Drive API query: ${query}`);
+ const res = await this.drive.files.list({
+ q: query,
+ fields: 'files(id, name)',
+ spaces: 'drive',
+ });
+
+ const folders = res.data.files || [];
+ logToFile(`Found ${folders.length} folders.`);
+ logToFile(`API Response: ${JSON.stringify(folders, null, 2)}`);
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(folders)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during drive.findFolder: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ public search = async ({ query, pageSize = 10, pageToken, corpus, unreadOnly, sharedWithMe }: { query?: string, pageSize?: number, pageToken?: string, corpus?: string, unreadOnly?: boolean, sharedWithMe?: boolean }) => {
+ let q = query;
+ let isProcessed = false;
+
+ // Check if query is a Google Drive URL
+ if (query && (query.includes('drive.google.com') || query.includes('docs.google.com'))) {
+ isProcessed = true;
+ logToFile(`Detected Google Drive URL in query: ${query}`);
+
+ let fileId: string | null = null;
+ let urlType: 'file' | 'folder' | 'unknown' = 'unknown';
+
+ for (const urlPattern of URL_PATTERNS) {
+ const match = query.match(urlPattern.pattern);
+ if (match) {
+ fileId = match[1];
+ urlType = urlPattern.type;
+ break;
+ }
+ }
+
+ if (fileId) {
+ let isFolder = urlType === 'folder';
+
+ if (urlType === 'unknown') {
+ try {
+ const file = await this.drive.files.get({ fileId, fields: 'mimeType' });
+ if (file.data.mimeType === 'application/vnd.google-apps.folder') {
+ isFolder = true;
+ }
+ } catch {
+ logToFile(`Could not determine type of ID from URL, treating as file: ${fileId}`);
+ }
+ }
+
+ if (isFolder) {
+ q = `'${fileId}' in parents`;
+ logToFile(`Extracted Folder ID from URL: ${fileId}, using query: ${q}`);
+ } else {
+ logToFile(`Extracted File ID from URL: ${fileId}, using files.get`);
+ try {
+ const res = await this.drive.files.get({
+ fileId: fileId,
+ fields: 'id, name, modifiedTime, viewedByMeTime, mimeType, parents',
+ });
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ files: [res.data],
+ nextPageToken: null
+ })
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during drive.files.get: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+ } else {
+ logToFile(`Could not extract file/folder ID from URL: ${query}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: "Invalid Drive URL. Please provide a valid Google Drive URL or a search query.",
+ details: "Could not extract file or folder ID from the provided URL."
+ })
+ }]
+ };
+ }
+ }
+
+ if (query && !isProcessed) {
+ const titlePrefix = 'title:';
+ const trimmedQuery = query.trim();
+
+ if (trimmedQuery.startsWith(titlePrefix)) {
+ let searchTerm = trimmedQuery.substring(titlePrefix.length).trim();
+ if ((searchTerm.startsWith("'") && searchTerm.endsWith("'")) ||
+ (searchTerm.startsWith('"') && searchTerm.endsWith('"'))) {
+ searchTerm = searchTerm.substring(1, searchTerm.length - 1);
+ }
+ q = `name contains '${escapeQueryString(searchTerm)}'`;
+ } else {
+ const driveIdPattern = new RegExp(`^[a-zA-Z0-9-_]{${MIN_DRIVE_ID_LENGTH},}$`);
+ if (driveIdPattern.test(trimmedQuery) && !trimmedQuery.includes(" ")) {
+ q = `'${trimmedQuery}' in parents`;
+ logToFile(`Detected Drive ID: ${trimmedQuery}, listing contents`);
+ } else {
+ const looksLikeQuery = /( and | or | not | contains | in |=)/.test(trimmedQuery);
+ if (!looksLikeQuery) {
+ const escapedQuery = escapeQueryString(trimmedQuery);
+ q = `fullText contains '${escapedQuery}'`;
+ }
+ }
+ }
+ }
+
+ if (sharedWithMe) {
+ logToFile('Searching for files shared with the user.');
+ if (q) {
+ q += " and sharedWithMe";
+ } else {
+ q = "sharedWithMe";
+ }
+ }
+
+ logToFile(`Executing Drive search with query: ${q}`);
+ if (corpus) {
+ logToFile(`Using corpus: ${corpus}`);
+ }
+ if (unreadOnly) {
+ logToFile('Filtering for unread files only.');
+ }
+
+ try {
+ const res = await this.drive.files.list({
+ q: q,
+ pageSize: pageSize,
+ pageToken: pageToken,
+ corpus: corpus as 'user' | 'domain' | undefined,
+ fields: 'nextPageToken, files(id, name, modifiedTime, viewedByMeTime, mimeType, parents)',
+ });
+
+ let files = res.data.files || [];
+ const nextPageToken = res.data.nextPageToken;
+
+ if (unreadOnly) {
+ files = files.filter(file => !file.viewedByMeTime);
+ }
+
+ logToFile(`Found ${files.length} files.`);
+ if (nextPageToken) {
+ logToFile(`Next page token: ${nextPageToken}`);
+ }
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ files: files,
+ nextPageToken: nextPageToken
+ })
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during drive.search: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/src/services/GmailService.ts b/workspace-mcp-server/src/services/GmailService.ts
new file mode 100644
index 00000000..3dddb95f
--- /dev/null
+++ b/workspace-mcp-server/src/services/GmailService.ts
@@ -0,0 +1,400 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { google, gmail_v1, Auth } from 'googleapis';
+import { AuthManager } from '../auth/AuthManager';
+import { logToFile } from '../utils/logger';
+import { MimeHelper } from '../utils/MimeHelper';
+import { GMAIL_SEARCH_MAX_RESULTS } from '../utils/constants';
+import { gaxiosOptions } from '../utils/GaxiosConfig';
+import { emailArraySchema } from '../utils/validation';
+
+// Type definitions for email parameters
+type SendEmailParams = {
+ to: string | string[];
+ subject: string;
+ body: string;
+ cc?: string | string[];
+ bcc?: string | string[];
+ isHtml?: boolean;
+};
+
+export class GmailService {
+ private gmail: gmail_v1.Gmail;
+
+ constructor(private authManager: AuthManager) {
+ this.gmail = {} as gmail_v1.Gmail;
+ }
+
+ public async initialize(): Promise {
+ const auth: Auth.OAuth2Client = await this.authManager.getAuthenticatedClient();
+ const options = { ...gaxiosOptions, auth };
+ this.gmail = google.gmail({ version: 'v1', ...options });
+ }
+
+ /**
+ * Helper method to handle errors consistently across all methods
+ */
+ private handleError(error: unknown, context: string) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error during ${context}: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+
+ public search = async ({
+ query,
+ maxResults = GMAIL_SEARCH_MAX_RESULTS,
+ pageToken,
+ labelIds,
+ includeSpamTrash = false
+ }: {
+ query?: string,
+ maxResults?: number,
+ pageToken?: string,
+ labelIds?: string[],
+ includeSpamTrash?: boolean
+ }) => {
+ try {
+ logToFile(`Gmail search - query: ${query}, maxResults: ${maxResults}`);
+
+ const response = await this.gmail.users.messages.list({
+ userId: 'me',
+ q: query,
+ maxResults,
+ pageToken,
+ labelIds,
+ includeSpamTrash
+ });
+
+ const messages = response.data.messages || [];
+ const nextPageToken = response.data.nextPageToken;
+ const resultSizeEstimate = response.data.resultSizeEstimate;
+
+ logToFile(`Found ${messages.length} messages, estimated total: ${resultSizeEstimate}`);
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ messages: messages.map(msg => ({
+ id: msg.id,
+ threadId: msg.threadId
+ })),
+ nextPageToken,
+ resultSizeEstimate
+ }, null, 2)
+ }]
+ };
+ } catch (error) {
+ return this.handleError(error, 'gmail.search');
+ }
+ }
+
+ public get = async ({
+ messageId,
+ format = 'full'
+ }: {
+ messageId: string,
+ format?: 'minimal' | 'full' | 'raw' | 'metadata'
+ }) => {
+ try {
+ logToFile(`Getting message ${messageId} with format: ${format}`);
+
+ const response = await this.gmail.users.messages.get({
+ userId: 'me',
+ id: messageId,
+ format
+ });
+
+ const message = response.data;
+
+ // Extract useful information based on format
+ if (format === 'metadata' || format === 'full') {
+ const headers = message.payload?.headers || [];
+ const getHeader = (name: string) => headers.find(h => h.name === name)?.value;
+
+ const subject = getHeader('Subject');
+ const from = getHeader('From');
+ const to = getHeader('To');
+ const date = getHeader('Date');
+
+ // Extract body for full format
+ let body = '';
+ if (format === 'full' && message.payload) {
+ body = this.extractBody(message.payload);
+ }
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ id: message.id,
+ threadId: message.threadId,
+ labelIds: message.labelIds,
+ snippet: message.snippet,
+ subject,
+ from,
+ to,
+ date,
+ body: body || message.snippet
+ }, null, 2)
+ }]
+ };
+ }
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(message, null, 2)
+ }]
+ };
+ } catch (error) {
+ return this.handleError(error, 'gmail.get');
+ }
+ }
+
+ public modify = async ({
+ messageId,
+ addLabelIds = [],
+ removeLabelIds = []
+ }: {
+ messageId: string,
+ addLabelIds?: string[],
+ removeLabelIds?: string[]
+ }) => {
+ try {
+ logToFile(`Modifying message ${messageId} with addLabelIds: ${addLabelIds}, removeLabelIds: ${removeLabelIds}`);
+
+ const response = await this.gmail.users.messages.modify({
+ userId: 'me',
+ id: messageId,
+ requestBody: {
+ addLabelIds,
+ removeLabelIds,
+ },
+ });
+
+ const message = response.data;
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(message, null, 2)
+ }]
+ };
+ } catch (error) {
+ return this.handleError(error, 'gmail.modify');
+ }
+ }
+
+ public send = async ({
+ to,
+ subject,
+ body,
+ cc,
+ bcc,
+ isHtml = false
+ }: SendEmailParams) => {
+ try {
+ // Validate email addresses
+ try {
+ emailArraySchema.parse(to);
+ if (cc) emailArraySchema.parse(cc);
+ if (bcc) emailArraySchema.parse(bcc);
+ } catch (error) {
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ error: 'Invalid email address format',
+ details: error instanceof Error ? error.message : 'Validation failed'
+ })
+ }]
+ };
+ }
+
+ logToFile(`Sending email to: ${to}, subject: ${subject}`);
+
+ // Create MIME message
+ const mimeMessage = MimeHelper.createMimeMessage({
+ to: Array.isArray(to) ? to.join(', ') : to,
+ subject,
+ body,
+ cc: cc ? (Array.isArray(cc) ? cc.join(', ') : cc) : undefined,
+ bcc: bcc ? (Array.isArray(bcc) ? bcc.join(', ') : bcc) : undefined,
+ isHtml
+ });
+
+ const response = await this.gmail.users.messages.send({
+ userId: 'me',
+ requestBody: {
+ raw: mimeMessage
+ }
+ });
+
+ logToFile(`Email sent successfully: ${response.data.id}`);
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ id: response.data.id,
+ threadId: response.data.threadId,
+ labelIds: response.data.labelIds,
+ status: 'sent'
+ }, null, 2)
+ }]
+ };
+ } catch (error) {
+ return this.handleError(error, 'gmail.send');
+ }
+ }
+
+ public createDraft = async ({
+ to,
+ subject,
+ body,
+ cc,
+ bcc,
+ isHtml = false
+ }: SendEmailParams) => {
+ try {
+ logToFile(`Creating draft - to: ${to}, subject: ${subject}`);
+
+ // Create MIME message
+ const mimeMessage = MimeHelper.createMimeMessage({
+ to: Array.isArray(to) ? to.join(', ') : to,
+ subject,
+ body,
+ cc: cc ? (Array.isArray(cc) ? cc.join(', ') : cc) : undefined,
+ bcc: bcc ? (Array.isArray(bcc) ? bcc.join(', ') : bcc) : undefined,
+ isHtml
+ });
+
+ const response = await this.gmail.users.drafts.create({
+ userId: 'me',
+ requestBody: {
+ message: {
+ raw: mimeMessage
+ }
+ }
+ });
+
+ logToFile(`Draft created successfully: ${response.data.id}`);
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ id: response.data.id,
+ message: {
+ id: response.data.message?.id,
+ threadId: response.data.message?.threadId,
+ labelIds: response.data.message?.labelIds
+ },
+ status: 'draft_created'
+ }, null, 2)
+ }]
+ };
+ } catch (error) {
+ return this.handleError(error, 'gmail.createDraft');
+ }
+ }
+
+ public sendDraft = async ({ draftId }: { draftId: string }) => {
+ try {
+ logToFile(`Sending draft: ${draftId}`);
+
+ const response = await this.gmail.users.drafts.send({
+ userId: 'me',
+ requestBody: {
+ id: draftId
+ }
+ });
+
+ logToFile(`Draft sent successfully: ${response.data.id}`);
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ id: response.data.id,
+ threadId: response.data.threadId,
+ labelIds: response.data.labelIds,
+ status: 'sent'
+ }, null, 2)
+ }]
+ };
+ } catch (error) {
+ return this.handleError(error, 'gmail.sendDraft');
+ }
+ }
+
+ public listLabels = async () => {
+ try {
+ logToFile(`Listing Gmail labels`);
+
+ const response = await this.gmail.users.labels.list({
+ userId: 'me'
+ });
+
+ const labels = response.data.labels || [];
+
+ logToFile(`Found ${labels.length} labels`);
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ labels: labels.map(label => ({
+ id: label.id,
+ name: label.name,
+ type: label.type,
+ messageListVisibility: label.messageListVisibility,
+ labelListVisibility: label.labelListVisibility
+ }))
+ }, null, 2)
+ }]
+ };
+ } catch (error) {
+ return this.handleError(error, 'gmail.listLabels');
+ }
+ }
+
+ private extractBody(payload: gmail_v1.Schema$MessagePart): string {
+ let body = '';
+
+ // Check for plain text or HTML in the main part
+ if (payload.body?.data) {
+ body = Buffer.from(payload.body.data, 'base64').toString('utf-8');
+ }
+
+ // Check parts for multipart messages
+ if (payload.parts) {
+ for (const part of payload.parts) {
+ if (part.mimeType === 'text/plain' && part.body?.data) {
+ body = Buffer.from(part.body.data, 'base64').toString('utf-8');
+ break; // Prefer plain text
+ } else if (part.mimeType === 'text/html' && part.body?.data && !body) {
+ body = Buffer.from(part.body.data, 'base64').toString('utf-8');
+ } else if (part.parts) {
+ // Recursive for nested parts
+ const nestedBody = this.extractBody(part);
+ if (nestedBody) {
+ body = nestedBody;
+ break;
+ }
+ }
+ }
+ }
+
+ return body;
+ }
+}
diff --git a/workspace-mcp-server/src/services/PeopleService.ts b/workspace-mcp-server/src/services/PeopleService.ts
new file mode 100644
index 00000000..deb95a1b
--- /dev/null
+++ b/workspace-mcp-server/src/services/PeopleService.ts
@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { google, people_v1 } from 'googleapis';
+import { Auth } from 'googleapis';
+import { AuthManager } from '../auth/AuthManager';
+import { logToFile } from '../utils/logger';
+import { gaxiosOptions } from '../utils/GaxiosConfig';
+
+export class PeopleService {
+ private people: people_v1.People;
+
+ constructor(private authManager: AuthManager) {
+ this.people = {} as people_v1.People;
+ }
+
+ public async initialize(): Promise {
+ const auth: Auth.OAuth2Client = await this.authManager.getAuthenticatedClient();
+ const options = { ...gaxiosOptions, auth };
+ this.people = google.people({ version: 'v1', ...options });
+ }
+
+ public getUserProfile = async ({ userId, email, name }: { userId?: string, email?: string, name?: string }) => {
+ logToFile(`[PeopleService] Starting getUserProfile with: userId=${userId}, email=${email}, name=${name}`);
+ try {
+ if (!userId && !email && !name) {
+ throw new Error('Either userId, email, or name must be provided.');
+ }
+ if (userId) {
+ const resourceName = userId.startsWith('people/') ? userId : `people/${userId}`;
+ const res = await this.people.people.get({
+ resourceName,
+ personFields: 'names,emailAddresses',
+ });
+ logToFile(`[PeopleService] Finished getUserProfile for user: ${userId}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ results: [{ person: res.data }] })
+ }]
+ };
+ } else if (email || name) {
+ const query = email || name;
+ const res = await this.people.people.searchDirectoryPeople({
+ query,
+ readMask: 'names,emailAddresses',
+ sources: ['DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT', 'DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE'],
+ });
+ logToFile(`[PeopleService] Finished getUserProfile search for: ${query}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(res.data)
+ }]
+ };
+ } else {
+ throw new Error('Either userId, email, or name must be provided.');
+ }
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[PeopleService] Error during people.getUserProfile: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ public getMe = async () => {
+ logToFile(`[PeopleService] Starting getMe`);
+ try {
+ const res = await this.people.people.get({
+ resourceName: 'people/me',
+ personFields: 'names,emailAddresses',
+ });
+ logToFile(`[PeopleService] Finished getMe`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(res.data)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[PeopleService] Error during people.getMe: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/src/services/SheetsService.ts b/workspace-mcp-server/src/services/SheetsService.ts
new file mode 100644
index 00000000..5c4db77f
--- /dev/null
+++ b/workspace-mcp-server/src/services/SheetsService.ts
@@ -0,0 +1,245 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { google, sheets_v4, drive_v3, Auth } from 'googleapis';
+import { AuthManager } from '../auth/AuthManager';
+import { logToFile } from '../utils/logger';
+import { extractDocId } from '../utils/IdUtils';
+import { gaxiosOptions } from '../utils/GaxiosConfig';
+import { buildDriveSearchQuery, MIME_TYPES } from '../utils/DriveQueryBuilder';
+
+export class SheetsService {
+ private sheets: sheets_v4.Sheets;
+ private drive: drive_v3.Drive;
+
+ constructor(private authManager: AuthManager) {
+ this.sheets = {} as sheets_v4.Sheets;
+ this.drive = {} as drive_v3.Drive;
+ }
+
+ public async initialize(): Promise {
+ const auth: Auth.OAuth2Client = await this.authManager.getAuthenticatedClient();
+ const options = { ...gaxiosOptions, auth };
+ this.sheets = google.sheets({ version: 'v4', ...options });
+ this.drive = google.drive({ version: 'v3', ...options });
+ }
+
+ public getText = async ({ spreadsheetId, format = 'text' }: { spreadsheetId: string, format?: 'text' | 'csv' | 'json' }) => {
+ logToFile(`[SheetsService] Starting getText for spreadsheet: ${spreadsheetId} with format: ${format}`);
+ try {
+ const id = extractDocId(spreadsheetId) || spreadsheetId;
+
+ // Get spreadsheet metadata
+ const spreadsheet = await this.sheets.spreadsheets.get({
+ spreadsheetId: id,
+ includeGridData: false,
+ });
+
+ let content = '';
+ const jsonData: Record = {};
+
+ // Add spreadsheet title (except for JSON format)
+ if (spreadsheet.data.properties?.title && format !== 'json') {
+ content += `Spreadsheet Title: ${spreadsheet.data.properties.title}\n\n`;
+ }
+
+ // Get all sheet names
+ const sheetNames = spreadsheet.data.sheets?.map(sheet => sheet.properties?.title) || [];
+
+ // Get data from all sheets
+ for (const sheetName of sheetNames) {
+ if (!sheetName) continue;
+
+ try {
+ const response = await this.sheets.spreadsheets.values.get({
+ spreadsheetId: id,
+ range: `'${sheetName}'`,
+ });
+
+ const values = response.data.values || [];
+
+ if (format === 'json') {
+ // Collect data for JSON structure
+ jsonData[sheetName] = values;
+ } else {
+ // Add sheet name as context
+ content += `Sheet Name: ${sheetName}\n`;
+
+ if (values.length === 0) {
+ content += '(Empty sheet)\n';
+ } else {
+ // Process each row
+ values.forEach((row) => {
+ if (format === 'csv') {
+ // Convert to CSV format
+ const csvRow = row.map(cell => {
+ // Escape quotes and wrap in quotes if contains comma or quotes
+ const cellStr = String(cell || '');
+ if (cellStr.includes(',') || cellStr.includes('"') || cellStr.includes('\n')) {
+ return `"${cellStr.replace(/"/g, '""')}"`;
+ }
+ return cellStr;
+ }).join(',');
+ content += csvRow + '\n';
+ } else {
+ // Plain text format with pipe separators for readability
+ content += row.map(cell => cell || '').join(' | ') + '\n';
+ }
+ });
+ }
+ content += '\n';
+ }
+ } catch (sheetError) {
+ logToFile(`[SheetsService] Error reading sheet ${sheetName}: ${sheetError}`);
+ if (format === 'json') {
+ // For JSON format, we'll skip sheets with errors
+ logToFile(`[SheetsService] Skipping sheet ${sheetName} in JSON output due to error`);
+ } else {
+ content += `Sheet Name: ${sheetName}\n(Error reading sheet)\n\n`;
+ }
+ }
+ }
+
+ if (format === 'json') {
+ // Generate clean JSON output from collected data
+ content = JSON.stringify(jsonData, null, 2);
+ }
+
+ logToFile(`[SheetsService] Finished getText for spreadsheet: ${id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: content.trim()
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[SheetsService] Error during sheets.getText: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ public getRange = async ({ spreadsheetId, range }: { spreadsheetId: string, range: string }) => {
+ logToFile(`[SheetsService] Starting getRange for spreadsheet: ${spreadsheetId}, range: ${range}`);
+ try {
+ const id = extractDocId(spreadsheetId) || spreadsheetId;
+
+ const response = await this.sheets.spreadsheets.values.get({
+ spreadsheetId: id,
+ range: range,
+ });
+
+ const values = response.data.values || [];
+
+ logToFile(`[SheetsService] Finished getRange for spreadsheet: ${id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ range: response.data.range,
+ values: values
+ })
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[SheetsService] Error during sheets.getRange: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ public find = async ({ query, pageToken, pageSize = 10 }: { query: string, pageToken?: string, pageSize?: number }) => {
+ logToFile(`[SheetsService] Searching for spreadsheets with query: ${query}`);
+ try {
+ const q = buildDriveSearchQuery(MIME_TYPES.SPREADSHEET, query);
+ logToFile(`[SheetsService] Executing Drive API query: ${q}`);
+
+ const res = await this.drive.files.list({
+ pageSize: pageSize,
+ fields: 'nextPageToken, files(id, name)',
+ q: q,
+ pageToken: pageToken,
+ });
+
+ const files = res.data.files || [];
+ const nextPageToken = res.data.nextPageToken;
+
+ logToFile(`[SheetsService] Found ${files.length} spreadsheets.`);
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ files: files,
+ nextPageToken: nextPageToken
+ })
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[SheetsService] Error during sheets.find: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ public getMetadata = async ({ spreadsheetId }: { spreadsheetId: string }) => {
+ logToFile(`[SheetsService] Starting getMetadata for spreadsheet: ${spreadsheetId}`);
+ try {
+ const id = extractDocId(spreadsheetId) || spreadsheetId;
+
+ const spreadsheet = await this.sheets.spreadsheets.get({
+ spreadsheetId: id,
+ includeGridData: false,
+ });
+
+ const metadata = {
+ spreadsheetId: spreadsheet.data.spreadsheetId,
+ title: spreadsheet.data.properties?.title,
+ sheets: spreadsheet.data.sheets?.map(sheet => ({
+ sheetId: sheet.properties?.sheetId,
+ title: sheet.properties?.title,
+ index: sheet.properties?.index,
+ rowCount: sheet.properties?.gridProperties?.rowCount,
+ columnCount: sheet.properties?.gridProperties?.columnCount,
+ })),
+ locale: spreadsheet.data.properties?.locale,
+ timeZone: spreadsheet.data.properties?.timeZone,
+ };
+
+ logToFile(`[SheetsService] Finished getMetadata for spreadsheet: ${id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(metadata)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[SheetsService] Error during sheets.getMetadata: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+}
diff --git a/workspace-mcp-server/src/services/SlidesService.ts b/workspace-mcp-server/src/services/SlidesService.ts
new file mode 100644
index 00000000..1bb35f18
--- /dev/null
+++ b/workspace-mcp-server/src/services/SlidesService.ts
@@ -0,0 +1,195 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { google, slides_v1, drive_v3, Auth } from 'googleapis';
+import { AuthManager } from '../auth/AuthManager';
+import { logToFile } from '../utils/logger';
+import { extractDocId } from '../utils/IdUtils';
+import { gaxiosOptions } from '../utils/GaxiosConfig';
+import { buildDriveSearchQuery, MIME_TYPES } from '../utils/DriveQueryBuilder';
+
+export class SlidesService {
+ private slides: slides_v1.Slides;
+ private drive: drive_v3.Drive;
+
+ constructor(private authManager: AuthManager) {
+ this.slides = {} as slides_v1.Slides;
+ this.drive = {} as drive_v3.Drive;
+ }
+
+ public async initialize(): Promise {
+ const auth: Auth.OAuth2Client = await this.authManager.getAuthenticatedClient();
+ const options = { ...gaxiosOptions, auth };
+ this.slides = google.slides({ version: 'v1', ...options });
+ this.drive = google.drive({ version: 'v3', ...options });
+ }
+
+ public getText = async ({ presentationId }: { presentationId: string }) => {
+ logToFile(`[SlidesService] Starting getText for presentation: ${presentationId}`);
+ try {
+ const id = extractDocId(presentationId) || presentationId;
+
+ // Get the presentation with all necessary fields
+ const presentation = await this.slides.presentations.get({
+ presentationId: id,
+ fields: 'title,slides(pageElements(shape(text,shapeProperties),table(tableRows(tableCells(text)))))',
+ });
+
+ let content = '';
+
+ // Add presentation title
+ if (presentation.data.title) {
+ content += `Presentation Title: ${presentation.data.title}\n\n`;
+ }
+
+ // Process each slide
+ if (presentation.data.slides) {
+ presentation.data.slides.forEach((slide, slideIndex) => {
+ content += `\n--- Slide ${slideIndex + 1} ---\n`;
+
+ if (slide.pageElements) {
+ slide.pageElements.forEach(element => {
+ // Extract text from shapes
+ if (element.shape && element.shape.text) {
+ const shapeText = this.extractTextFromTextContent(element.shape.text);
+ if (shapeText) {
+ content += shapeText + '\n';
+ }
+ }
+
+ // Extract text from tables
+ if (element.table && element.table.tableRows) {
+ content += '\n--- Table Data ---\n';
+ element.table.tableRows.forEach(row => {
+ const rowText: string[] = [];
+ if (row.tableCells) {
+ row.tableCells.forEach(cell => {
+ const cellText = cell.text ? this.extractTextFromTextContent(cell.text) : '';
+ rowText.push(cellText.trim());
+ });
+ }
+ content += rowText.join(' | ') + '\n';
+ });
+ content += '--- End Table Data ---\n';
+ }
+ });
+ }
+ content += '\n';
+ });
+ }
+
+ logToFile(`[SlidesService] Finished getText for presentation: ${id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: content.trim()
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[SlidesService] Error during slides.getText: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ private extractTextFromTextContent(textContent: slides_v1.Schema$TextContent): string {
+ let text = '';
+ if (textContent.textElements) {
+ textContent.textElements.forEach(element => {
+ if (element.textRun && element.textRun.content) {
+ text += element.textRun.content;
+ } else if (element.paragraphMarker) {
+ // Add newline for paragraph markers
+ text += '\n';
+ }
+ });
+ }
+ return text;
+ }
+
+ public find = async ({ query, pageToken, pageSize = 10 }: { query: string, pageToken?: string, pageSize?: number }) => {
+ logToFile(`[SlidesService] Searching for presentations with query: ${query}`);
+ try {
+ const q = buildDriveSearchQuery(MIME_TYPES.PRESENTATION, query);
+ logToFile(`[SlidesService] Executing Drive API query: ${q}`);
+
+ const res = await this.drive.files.list({
+ pageSize: pageSize,
+ fields: 'nextPageToken, files(id, name)',
+ q: q,
+ pageToken: pageToken,
+ });
+
+ const files = res.data.files || [];
+ const nextPageToken = res.data.nextPageToken;
+
+ logToFile(`[SlidesService] Found ${files.length} presentations.`);
+
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({
+ files: files,
+ nextPageToken: nextPageToken
+ })
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[SlidesService] Error during slides.find: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ public getMetadata = async ({ presentationId }: { presentationId: string }) => {
+ logToFile(`[SlidesService] Starting getMetadata for presentation: ${presentationId}`);
+ try {
+ const id = extractDocId(presentationId) || presentationId;
+
+ const presentation = await this.slides.presentations.get({
+ presentationId: id,
+ fields: 'presentationId,title,slides(objectId),pageSize,notesMaster,masters,layouts',
+ });
+
+ const metadata = {
+ presentationId: presentation.data.presentationId,
+ title: presentation.data.title,
+ slideCount: presentation.data.slides?.length || 0,
+ pageSize: presentation.data.pageSize,
+ hasMasters: !!presentation.data.masters?.length,
+ hasLayouts: !!presentation.data.layouts?.length,
+ hasNotesMaster: !!presentation.data.notesMaster,
+ };
+
+ logToFile(`[SlidesService] Finished getMetadata for presentation: ${id}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(metadata)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`[SlidesService] Error during slides.getMetadata: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+}
diff --git a/workspace-mcp-server/src/services/TimeService.ts b/workspace-mcp-server/src/services/TimeService.ts
new file mode 100644
index 00000000..65ef5144
--- /dev/null
+++ b/workspace-mcp-server/src/services/TimeService.ts
@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { logToFile } from '../utils/logger';
+
+export class TimeService {
+ constructor() {
+ logToFile('TimeService initialized.');
+ }
+
+ private async handleErrors(fn: () => Promise): Promise<{ content: [{ type: "text"; text: string; }] }> {
+ try {
+ const result = await fn();
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify(result)
+ }]
+ };
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error);
+ logToFile(`Error in TimeService: ${errorMessage}`);
+ return {
+ content: [{
+ type: "text" as const,
+ text: JSON.stringify({ error: errorMessage })
+ }]
+ };
+ }
+ }
+
+ getCurrentDate = async () => {
+ logToFile('getCurrentDate called');
+ return this.handleErrors(async () => {
+ return { date: new Date().toISOString().slice(0, 10) };
+ });
+ }
+
+ getCurrentTime = async () => {
+ logToFile('getCurrentTime called');
+ return this.handleErrors(async () => {
+ return { time: new Date().toISOString().slice(11, 19) };
+ });
+ }
+
+ getTimeZone = async () => {
+ logToFile('getTimeZone called');
+ return this.handleErrors(async () => {
+ return { timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone };
+ });
+ }
+}
diff --git a/workspace-mcp-server/src/utils/DriveQueryBuilder.ts b/workspace-mcp-server/src/utils/DriveQueryBuilder.ts
new file mode 100644
index 00000000..7fda7dce
--- /dev/null
+++ b/workspace-mcp-server/src/utils/DriveQueryBuilder.ts
@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Utility for building Google Drive API search queries
+ */
+
+/**
+ * Builds a Drive API search query for a specific MIME type with optional title filtering
+ * @param mimeType The MIME type to search for (e.g., 'application/vnd.google-apps.document')
+ * @param query The search query, may include 'title:' prefix for title-only searches
+ * @returns The formatted Drive API query string
+ */
+export function buildDriveSearchQuery(mimeType: string, query: string): string {
+ let searchTerm = query;
+ const titlePrefix = 'title:';
+ let q: string;
+
+ if (searchTerm.trim().startsWith(titlePrefix)) {
+ // Extract search term after 'title:' prefix
+ searchTerm = searchTerm.trim().substring(titlePrefix.length).trim();
+
+ // Remove surrounding quotes if present
+ if ((searchTerm.startsWith("'") && searchTerm.endsWith("'")) ||
+ (searchTerm.startsWith('"') && searchTerm.endsWith('"'))) {
+ searchTerm = searchTerm.substring(1, searchTerm.length - 1);
+ }
+
+ // Search by name (title) only
+ q = `mimeType='${mimeType}' and name contains '${escapeQueryString(searchTerm)}'`;
+ } else {
+ // Search full text content
+ q = `mimeType='${mimeType}' and fullText contains '${escapeQueryString(searchTerm)}'`;
+ }
+
+ return q;
+}
+
+/**
+ * Escapes special characters in a query string for Drive API
+ * @param str The string to escape
+ * @returns The escaped string
+ */
+export function escapeQueryString(str: string): string {
+ return str.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+// Export MIME type constants for convenience
+export const MIME_TYPES = {
+ DOCUMENT: 'application/vnd.google-apps.document',
+ PRESENTATION: 'application/vnd.google-apps.presentation',
+ SPREADSHEET: 'application/vnd.google-apps.spreadsheet',
+ FOLDER: 'application/vnd.google-apps.folder',
+} as const;
diff --git a/workspace-mcp-server/src/utils/GaxiosConfig.ts b/workspace-mcp-server/src/utils/GaxiosConfig.ts
new file mode 100644
index 00000000..1689b00c
--- /dev/null
+++ b/workspace-mcp-server/src/utils/GaxiosConfig.ts
@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { GaxiosOptions } from 'gaxios';
+import { logToFile } from './logger';
+
+export const gaxiosOptions: GaxiosOptions = {
+ retryConfig: {
+ retry: 3,
+ noResponseRetries: 3,
+ retryDelay: 1000,
+ httpMethodsToRetry: ['GET', 'HEAD', 'OPTIONS', 'DELETE', 'PUT'],
+ statusCodesToRetry: [
+ [429, 429],
+ [500, 599],
+ ],
+ onRetryAttempt: (err) => {
+ const config = err.config as GaxiosOptions;
+ logToFile(`Retrying request to ${config.url}, attempt #${config.retryConfig?.currentRetryAttempt}`);
+ logToFile(`Error: ${err.message}`);
+ }
+ },
+ timeout: 30000,
+};
+
+// Extended timeout for media upload operations
+export const mediaUploadOptions: GaxiosOptions = {
+ ...gaxiosOptions,
+ timeout: 60000, // 60 seconds for media uploads
+};
diff --git a/workspace-mcp-server/src/utils/IdUtils.ts b/workspace-mcp-server/src/utils/IdUtils.ts
new file mode 100644
index 00000000..33b037f4
--- /dev/null
+++ b/workspace-mcp-server/src/utils/IdUtils.ts
@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { logToFile } from './logger';
+
+const DOC_ID_REGEX = /\/d\/([a-zA-Z0-9-_]+)/;
+
+/**
+ * Extracts a Google Doc/Sheet/etc. ID from a Google Workspace URL.
+ *
+ * @param url The URL to parse.
+ * @returns The extracted document ID, or undefined if no ID could be found.
+ */
+export function extractDocId(url: string): string | undefined {
+ logToFile(`[IdUtils] Attempting to extract doc ID from URL: ${url}`);
+ if (!url || typeof url !== 'string') {
+ logToFile(`[IdUtils] Invalid input: URL is null or not a string.`);
+ return undefined;
+ }
+ const match = url.match(DOC_ID_REGEX);
+ if (match && match[1]) {
+ const docId = match[1];
+ logToFile(`[IdUtils] Successfully extracted doc ID: ${docId}`);
+ return docId;
+ }
+ logToFile(`[IdUtils] Could not extract doc ID from URL.`);
+ return undefined;
+}
diff --git a/workspace-mcp-server/src/utils/MimeHelper.ts b/workspace-mcp-server/src/utils/MimeHelper.ts
new file mode 100644
index 00000000..f67fff77
--- /dev/null
+++ b/workspace-mcp-server/src/utils/MimeHelper.ts
@@ -0,0 +1,188 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Helper class for creating RFC 2822 compliant MIME messages for Gmail API
+ */
+export class MimeHelper {
+ /**
+ * Creates a base64url-encoded MIME message for Gmail API
+ */
+ public static createMimeMessage({
+ to,
+ subject,
+ body,
+ from,
+ cc,
+ bcc,
+ replyTo,
+ isHtml = false
+ }: {
+ to: string;
+ subject: string;
+ body: string;
+ from?: string;
+ cc?: string;
+ bcc?: string;
+ replyTo?: string;
+ isHtml?: boolean;
+ }): string {
+ // Encode subject for UTF-8 support
+ const utf8Subject = `=?utf-8?B?${Buffer.from(subject).toString('base64')}?=`;
+
+ // Build message headers
+ const messageParts: string[] = [];
+
+ // Add From header if provided, otherwise Gmail will use the authenticated user
+ if (from) {
+ messageParts.push(`From: ${from}`);
+ }
+
+ messageParts.push(`To: ${to}`);
+
+ if (cc) {
+ messageParts.push(`Cc: ${cc}`);
+ }
+
+ if (bcc) {
+ messageParts.push(`Bcc: ${bcc}`);
+ }
+
+ if (replyTo) {
+ messageParts.push(`Reply-To: ${replyTo}`);
+ }
+
+ messageParts.push(`Subject: ${utf8Subject}`);
+
+ // Add content type based on whether it's HTML or plain text
+ if (isHtml) {
+ messageParts.push('Content-Type: text/html; charset=utf-8');
+ } else {
+ messageParts.push('Content-Type: text/plain; charset=utf-8');
+ }
+
+ messageParts.push(''); // Empty line between headers and body
+ messageParts.push(body);
+
+ // Join all parts with CRLF as per RFC 2822
+ const message = messageParts.join('\r\n');
+
+ // Encode to base64url format required by Gmail API
+ const encodedMessage = Buffer.from(message)
+ .toString('base64')
+ .replace(/\+/g, '-')
+ .replace(/\//g, '_')
+ .replace(/=+$/, '');
+
+ return encodedMessage;
+ }
+
+ /**
+ * Creates a MIME message with attachments
+ */
+ public static createMimeMessageWithAttachments({
+ to,
+ subject,
+ body,
+ from,
+ cc,
+ bcc,
+ attachments,
+ isHtml = false
+ }: {
+ to: string;
+ subject: string;
+ body: string;
+ from?: string;
+ cc?: string;
+ bcc?: string;
+ attachments?: Array<{
+ filename: string;
+ content: Buffer | string;
+ contentType?: string;
+ }>;
+ isHtml?: boolean;
+ }): string {
+ const boundary = `boundary_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+ const utf8Subject = `=?utf-8?B?${Buffer.from(subject).toString('base64')}?=`;
+
+ const messageParts: string[] = [];
+
+ // Headers
+ if (from) {
+ messageParts.push(`From: ${from}`);
+ }
+ messageParts.push(`To: ${to}`);
+ if (cc) {
+ messageParts.push(`Cc: ${cc}`);
+ }
+ if (bcc) {
+ messageParts.push(`Bcc: ${bcc}`);
+ }
+ messageParts.push(`Subject: ${utf8Subject}`);
+ messageParts.push('MIME-Version: 1.0');
+
+ if (!attachments || attachments.length === 0) {
+ // Simple message without attachments
+ return this.createMimeMessage({ to, subject, body, from, cc, bcc, isHtml });
+ }
+
+ // Multipart message with attachments
+ messageParts.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
+ messageParts.push('');
+
+ // Body part
+ messageParts.push(`--${boundary}`);
+ if (isHtml) {
+ messageParts.push('Content-Type: text/html; charset=utf-8');
+ } else {
+ messageParts.push('Content-Type: text/plain; charset=utf-8');
+ }
+ messageParts.push('');
+ messageParts.push(body);
+
+ // Attachments
+ for (const attachment of attachments) {
+ messageParts.push(`--${boundary}`);
+ messageParts.push(`Content-Type: ${attachment.contentType || 'application/octet-stream'}`);
+ messageParts.push('Content-Transfer-Encoding: base64');
+ messageParts.push(`Content-Disposition: attachment; filename="${attachment.filename}"`);
+ messageParts.push('');
+
+ const content = typeof attachment.content === 'string'
+ ? attachment.content
+ : attachment.content.toString('base64');
+
+ // Add content in chunks of 76 characters as per MIME spec
+ const chunks = content.match(/.{1,76}/g) || [];
+ messageParts.push(...chunks);
+ }
+
+ // End boundary
+ messageParts.push(`--${boundary}--`);
+
+ const message = messageParts.join('\r\n');
+
+ // Encode to base64url
+ return Buffer.from(message)
+ .toString('base64')
+ .replace(/\+/g, '-')
+ .replace(/\//g, '_')
+ .replace(/=+$/, '');
+ }
+
+ /**
+ * Decodes a base64url-encoded string (inverse of encoding)
+ */
+ public static decodeBase64Url(encoded: string): string {
+ // Add back padding if needed
+ let base64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+ while (base64.length % 4) {
+ base64 += '=';
+ }
+ return Buffer.from(base64, 'base64').toString('utf-8');
+ }
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/src/utils/constants.ts b/workspace-mcp-server/src/utils/constants.ts
new file mode 100644
index 00000000..882c66e6
--- /dev/null
+++ b/workspace-mcp-server/src/utils/constants.ts
@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export const GMAIL_SEARCH_MAX_RESULTS = 100;
diff --git a/workspace-mcp-server/src/utils/logger.ts b/workspace-mcp-server/src/utils/logger.ts
new file mode 100644
index 00000000..e4523edd
--- /dev/null
+++ b/workspace-mcp-server/src/utils/logger.ts
@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+// Navigate up two levels from src/utils to get to the project root
+const projectRoot = path.join(__dirname, '..', '..');
+const logFilePath = path.join(projectRoot, 'logs', 'server.log');
+
+async function ensureLogDirectoryExists() {
+ try {
+ await fs.mkdir(path.dirname(logFilePath), { recursive: true });
+ } catch (error) {
+ // If we can't create the log directory, log to console as a fallback.
+ console.error('Could not create log directory:', error);
+ }
+}
+
+// Ensure the directory exists when the module is loaded.
+ensureLogDirectoryExists();
+
+let isLoggingEnabled = false;
+
+export function setLoggingEnabled(enabled: boolean) {
+ isLoggingEnabled = enabled;
+}
+
+export function logToFile(message: string) {
+ if (!isLoggingEnabled) {
+ return;
+ }
+ const timestamp = new Date().toISOString();
+ const logMessage = `${timestamp} - ${message}\n`;
+
+ fs.appendFile(logFilePath, logMessage).catch(err => {
+ // Fallback to console if file logging fails
+ console.error('Failed to write to log file:', err);
+ });
+}
diff --git a/workspace-mcp-server/src/utils/markdownToDocsRequests.ts b/workspace-mcp-server/src/utils/markdownToDocsRequests.ts
new file mode 100644
index 00000000..6a5b21f7
--- /dev/null
+++ b/workspace-mcp-server/src/utils/markdownToDocsRequests.ts
@@ -0,0 +1,239 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { docs_v1 } from 'googleapis';
+import { marked } from 'marked';
+import { JSDOM } from 'jsdom';
+
+interface FormatRange {
+ start: number;
+ end: number;
+ type: 'bold' | 'italic' | 'code' | 'link' | 'heading';
+ url?: string;
+ headingLevel?: number;
+ isParagraph?: boolean;
+}
+
+interface ParsedMarkdown {
+ plainText: string;
+ formattingRequests: docs_v1.Schema$Request[];
+}
+
+/**
+ * Parses markdown text and generates Google Docs API requests for formatting.
+ * Uses the marked library to convert to HTML, then parses the HTML to extract formatting.
+ */
+export function parseMarkdownToDocsRequests(markdown: string, startIndex: number): ParsedMarkdown {
+ // Split markdown into lines to handle block elements like headings
+ const lines = markdown.split('\n');
+ const htmlParts: string[] = [];
+
+ for (const line of lines) {
+ // Check if this is a heading line
+ const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+ if (headingMatch) {
+ const level = headingMatch[1].length;
+ const content = headingMatch[2];
+ // Parse inline content within the heading
+ try {
+ const inlineHtml = marked.parseInline(content) as string;
+ htmlParts.push(`${inlineHtml}`);
+ } catch (error) {
+ console.error('Markdown parsing failed for heading, falling back to raw content:', error);
+ htmlParts.push(`${content}`);
+ }
+ } else if (line.trim()) {
+ // For non-heading, non-empty lines, use parseInline
+ try {
+ const inlineHtml = marked.parseInline(line) as string;
+ htmlParts.push(`${inlineHtml}
`);
+ } catch (error) {
+ console.error('Markdown parsing failed for line, falling back to raw content:', error);
+ htmlParts.push(`${line}
`);
+ }
+ } else {
+ // Empty lines become paragraph breaks
+ htmlParts.push('');
+ }
+ }
+
+ // Convert markdown to HTML - handle both block and inline elements
+ const html = htmlParts.join('\n');
+
+ // If no conversion happened, return plain text
+ if (!html || html === markdown) {
+ return {
+ plainText: markdown,
+ formattingRequests: []
+ };
+ }
+
+ // Parse HTML to extract text and formatting
+ // Create a wrapper div to handle inline HTML that might not have a parent element
+ const dom = new JSDOM(`${html}
`);
+ const document = dom.window.document;
+ const wrapper = document.querySelector('div');
+
+ const formattingRanges: FormatRange[] = [];
+ let plainText = '';
+ let currentPos = 0;
+
+ // Recursive function to process nodes
+ function processNode(node: Node) {
+ if (node.nodeType === 3) { // Text node
+ const text = node.textContent || '';
+ plainText += text;
+ currentPos += text.length;
+ } else if (node.nodeType === 1) { // Element node
+ const element = node as HTMLElement;
+ const tagName = element.tagName.toLowerCase();
+
+ const start = currentPos;
+
+ // Process children first to get the text content
+ for (const child of Array.from(node.childNodes)) {
+ processNode(child);
+ }
+
+ const end = currentPos;
+
+ // Record formatting based on tag
+ if (tagName === 'strong' || tagName === 'b') {
+ formattingRanges.push({ start, end, type: 'bold' });
+ } else if (tagName === 'em' || tagName === 'i') {
+ formattingRanges.push({ start, end, type: 'italic' });
+ } else if (tagName === 'code') {
+ formattingRanges.push({ start, end, type: 'code' });
+ } else if (tagName === 'a') {
+ const href = element.getAttribute('href') || '';
+ formattingRanges.push({ start, end, type: 'link', url: href });
+ } else if (tagName.match(/^h[1-6]$/)) {
+ const level = parseInt(tagName.charAt(1));
+ // Mark the entire paragraph range for heading style
+ formattingRanges.push({ start, end, type: 'heading', headingLevel: level, isParagraph: true });
+ } else if (tagName === 'p') {
+ // Add newline after paragraph content if not the last element
+ const nextSibling = element.nextSibling;
+ if (nextSibling && nextSibling.nodeType === 1) {
+ plainText += '\n';
+ currentPos += 1;
+ }
+ }
+ }
+ }
+
+ // Process all nodes
+ if (wrapper) {
+ for (const child of Array.from(wrapper.childNodes)) {
+ processNode(child);
+ }
+ } else {
+ // If parsing failed, just use the plain markdown (no formatting)
+ plainText = markdown;
+ }
+
+ // Generate formatting requests
+ const formattingRequests: docs_v1.Schema$Request[] = [];
+
+ for (const range of formattingRanges) {
+ const textStyle: docs_v1.Schema$TextStyle = {};
+ const fields: string[] = [];
+
+ if (range.type === 'bold') {
+ textStyle.bold = true;
+ fields.push('bold');
+ } else if (range.type === 'italic') {
+ textStyle.italic = true;
+ fields.push('italic');
+ } else if (range.type === 'code') {
+ textStyle.weightedFontFamily = {
+ fontFamily: 'Courier New',
+ weight: 400
+ };
+ textStyle.backgroundColor = {
+ color: {
+ rgbColor: {
+ red: 0.95,
+ green: 0.95,
+ blue: 0.95
+ }
+ }
+ };
+ fields.push('weightedFontFamily', 'backgroundColor');
+ } else if (range.type === 'link' && range.url) {
+ textStyle.link = {
+ url: range.url
+ };
+ textStyle.foregroundColor = {
+ color: {
+ rgbColor: {
+ red: 0.06,
+ green: 0.33,
+ blue: 0.80
+ }
+ }
+ };
+ textStyle.underline = true;
+ fields.push('link', 'foregroundColor', 'underline');
+ } else if (range.type === 'heading' && range.headingLevel && range.isParagraph) {
+ // Use updateParagraphStyle for headings as per Google Docs API best practices
+ const headingStyles: { [key: number]: string } = {
+ 1: 'HEADING_1',
+ 2: 'HEADING_2',
+ 3: 'HEADING_3',
+ 4: 'HEADING_4',
+ 5: 'HEADING_5',
+ 6: 'HEADING_6'
+ };
+
+ const namedStyleType = headingStyles[range.headingLevel] || 'HEADING_1';
+
+ // Create a separate updateParagraphStyle request for headings
+ formattingRequests.push({
+ updateParagraphStyle: {
+ paragraphStyle: {
+ namedStyleType: namedStyleType
+ },
+ range: {
+ startIndex: startIndex + range.start,
+ endIndex: startIndex + range.end
+ },
+ fields: 'namedStyleType'
+ }
+ });
+
+ // Skip the normal text style formatting for headings
+ continue;
+ }
+
+ if (fields.length > 0) {
+ formattingRequests.push({
+ updateTextStyle: {
+ range: {
+ startIndex: startIndex + range.start,
+ endIndex: startIndex + range.end
+ },
+ textStyle: textStyle,
+ fields: fields.join(',')
+ }
+ });
+ }
+ }
+
+ return {
+ plainText,
+ formattingRequests
+ };
+}
+
+/**
+ * Handles line breaks and paragraphs in markdown text
+ */
+export function processMarkdownLineBreaks(text: string): string {
+ // Convert double line breaks to paragraph breaks
+ // Single line breaks remain as-is
+ return text.replace(/\n\n+/g, '\n\n');
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/src/utils/open-wrapper.ts b/workspace-mcp-server/src/utils/open-wrapper.ts
new file mode 100644
index 00000000..3575e860
--- /dev/null
+++ b/workspace-mcp-server/src/utils/open-wrapper.ts
@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * This module acts as a drop-in replacement for the 'open' package.
+ * It intercepts browser launch requests and either:
+ * 1. Opens the browser securely using our secure-browser-launcher
+ * 2. Prints the URL to console if browser launch should be skipped or fails
+ */
+
+import { openBrowserSecurely, shouldLaunchBrowser } from './secure-browser-launcher';
+
+// Create a mock child process object that matches what open returns
+const createMockChildProcess = () => ({
+ unref: () => {},
+ ref: () => {},
+ pid: 123,
+ stdout: null,
+ stderr: null,
+ stdin: null,
+ channel: null,
+ connected: false,
+ exitCode: 0,
+ killed: false,
+ signalCode: null,
+ spawnargs: [],
+ spawnfile: '',
+});
+
+const openWrapper = async (url: string): Promise => {
+ // Check if we should launch the browser
+ if (!shouldLaunchBrowser()) {
+ console.log(`Browser launch not supported. Please open this URL in your browser: ${url}`);
+ return createMockChildProcess();
+ }
+
+ // Try to open the browser securely
+ try {
+ await openBrowserSecurely(url);
+ return createMockChildProcess();
+ } catch {
+ console.log(`Failed to open browser. Please open this URL in your browser: ${url}`);
+ return createMockChildProcess();
+ }
+};
+
+// Use standard ES Module export and let the compiler generate the CommonJS correct output.
+export default openWrapper;
\ No newline at end of file
diff --git a/workspace-mcp-server/src/utils/paths.ts b/workspace-mcp-server/src/utils/paths.ts
new file mode 100644
index 00000000..0b2e7781
--- /dev/null
+++ b/workspace-mcp-server/src/utils/paths.ts
@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import path from 'node:path';
+
+// Construct an absolute path to the project root.
+// __dirname will be /path/to/project/src (in dev) or /path/to/project/dist (in prod).
+// In both cases, going up one level gives us the project root.
+export const PROJECT_ROOT = path.join(__dirname, '..', '..');
+export const ENCRYPTED_TOKEN_PATH = path.join(
+ PROJECT_ROOT,
+ 'gemini-cli-workspace-token.json',
+);
+export const ENCRYPTION_MASTER_KEY_PATH = path.join(
+ PROJECT_ROOT,
+ '.gemini-cli-workspace-master-key',
+);
diff --git a/workspace-mcp-server/src/utils/secure-browser-launcher.ts b/workspace-mcp-server/src/utils/secure-browser-launcher.ts
new file mode 100644
index 00000000..6126d44e
--- /dev/null
+++ b/workspace-mcp-server/src/utils/secure-browser-launcher.ts
@@ -0,0 +1,232 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { execFile, ExecFileOptions } from 'node:child_process';
+import { platform } from 'node:os';
+import { URL } from 'node:url';
+
+
+function withTimeout(promise: Promise, ms: number): Promise {
+ let timeoutId: NodeJS.Timeout;
+ const timeout = new Promise((_, reject) => {
+ timeoutId = setTimeout(() => reject(new Error('Timeout')), ms);
+ });
+ return Promise.race([promise, timeout]).finally(() => clearTimeout(timeoutId));
+}
+
+/**
+ * Validates that a URL is safe to open in a browser.
+ * Only allows HTTP and HTTPS URLs to prevent command injection.
+ *
+ * @param url The URL to validate
+ * @throws Error if the URL is invalid or uses an unsafe protocol
+ */
+function validateUrl(url: string): void {
+ let parsedUrl: URL;
+
+ try {
+ parsedUrl = new URL(url);
+ } catch {
+ throw new Error('Invalid URL');
+ }
+
+ // Only allow HTTP and HTTPS protocols
+ if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+ throw new Error(
+ `Unsafe protocol: ${parsedUrl.protocol}. Only HTTP and HTTPS are allowed.`
+ );
+ }
+
+ // Additional validation: ensure no newlines or control characters
+ if (/[\r\n\x00-\x1F]/.test(url)) {
+ throw new Error('URL contains invalid characters');
+ }
+}
+
+/**
+ * Opens a URL in the default browser using platform-specific commands.
+ * This implementation avoids shell injection vulnerabilities by:
+ * 1. Validating the URL to ensure it's HTTP/HTTPS only
+ * 2. Using execFile instead of exec to avoid shell interpretation
+ * 3. Passing the URL as an argument rather than constructing a command string
+ *
+ * @param url The URL to open
+ * @param execFileFn The function to execute a command. Defaults to node's execFile.
+ * @throws Error if the URL is invalid or if opening the browser fails
+ */
+export async function openBrowserSecurely(
+ url: string,
+ execFileFn: typeof execFile = execFile
+): Promise {
+ // Validate the URL first
+ validateUrl(url);
+
+ const platformName = platform();
+ let command: string;
+ let args: string[];
+
+ switch (platformName) {
+ case 'darwin':
+ // macOS
+ command = 'open';
+ args = [url];
+ break;
+
+ case 'win32':
+ // Windows - use PowerShell with Start-Process
+ // This avoids the cmd.exe shell which is vulnerable to injection
+ command = 'powershell.exe';
+ args = [
+ '-NoProfile',
+ '-NonInteractive',
+ '-WindowStyle',
+ 'Hidden',
+ '-Command',
+ `Start-Process '${url.replace(/'/g, "''")}'`,
+ ];
+ break;
+
+ case 'linux':
+ case 'freebsd':
+ case 'openbsd':
+ // Linux and BSD variants
+ // Try xdg-open first, fall back to other options
+ command = 'xdg-open';
+ args = [url];
+ break;
+
+ default:
+ throw new Error(`Unsupported platform: ${platformName}`);
+ }
+
+ const options: Record = {
+ // Don't inherit parent's environment to avoid potential issues
+ env: {
+ ...process.env,
+ // Ensure we're not in a shell that might interpret special characters
+ SHELL: undefined,
+ },
+ // Detach the browser process so it doesn't block
+ detached: true,
+ stdio: 'ignore',
+ };
+
+ const tryCommand = (cmd: string, cmdArgs: string[]): Promise => {
+ return new Promise((resolve, reject) => {
+ const child = execFileFn(
+ cmd,
+ cmdArgs,
+ options as ExecFileOptions,
+ (error) => {
+ if (error) {
+ // This callback handles errors after the process has run,
+ // but for our case, the 'error' event is more important for spawn failures.
+ reject(error);
+ }
+ }
+ );
+
+ // The 'error' event is critical. It fires if the command cannot be found or spawned.
+ child.on('error', (error) => {
+ reject(error);
+ });
+
+ // If the process spawns successfully, 'xdg-open' and similar commands
+ // exit almost immediately. We don't need to wait for the browser to close.
+ // We can consider the job done if the process exits with code 0.
+ child.on('exit', (code) => {
+ if (code === 0) {
+ resolve();
+ } else {
+ reject(new Error(`Process exited with code ${code}`));
+ }
+ });
+ });
+ };
+
+ try {
+ await withTimeout(tryCommand(command, args), 5000);
+ } catch (error) {
+ // For Linux, try fallback commands if xdg-open fails
+ if (
+ (platformName === 'linux' ||
+ platformName === 'freebsd' ||
+ platformName === 'openbsd') &&
+ command === 'xdg-open'
+ ) {
+ const fallbackCommands = [
+ 'gnome-open',
+ 'kde-open',
+ 'firefox',
+ 'chromium',
+ 'google-chrome',
+ ];
+
+ for (const fallbackCommand of fallbackCommands) {
+ try {
+ await withTimeout(tryCommand(fallbackCommand, [url]), 5000);
+ return; // Success!
+ } catch {
+ // Try next command
+ continue;
+ }
+ }
+ }
+
+ // Re-throw the error if all attempts failed
+ throw new Error(
+ `Failed to open browser: ${
+ error instanceof Error ? error.message : 'Unknown error'
+ }`
+ );
+ }
+}
+
+/**
+ * Checks if the current environment should attempt to launch a browser.
+ * This is the same logic as in browser.ts for consistency.
+ *
+ * @returns True if the tool should attempt to launch a browser
+ */
+export function shouldLaunchBrowser(): boolean {
+ // A list of browser names that indicate we should not attempt to open a
+ // web browser for the user.
+ const browserBlocklist = ['www-browser'];
+ const browserEnv = process.env.BROWSER;
+ if (browserEnv && browserBlocklist.includes(browserEnv)) {
+ return false;
+ }
+
+ // Common environment variables used in CI/CD or other non-interactive shells.
+ if (process.env.CI || process.env.DEBIAN_FRONTEND === 'noninteractive') {
+ return false;
+ }
+
+ // The presence of SSH_CONNECTION indicates a remote session.
+ // We should not attempt to launch a browser unless a display is explicitly available
+ // (checked below for Linux).
+ const isSSH = !!process.env.SSH_CONNECTION;
+
+ // On Linux, the presence of a display server is a strong indicator of a GUI.
+ if (platform() === 'linux') {
+ // These are environment variables that can indicate a running compositor on Linux.
+ const displayVariables = ['DISPLAY', 'WAYLAND_DISPLAY', 'MIR_SOCKET'];
+ const hasDisplay = displayVariables.some((v) => !!process.env[v]);
+ if (!hasDisplay) {
+ return false;
+ }
+ }
+
+ // If in an SSH session on a non-Linux OS (e.g., macOS), don't launch browser.
+ // The Linux case is handled above (it's allowed if DISPLAY is set).
+ if (isSSH && platform() !== 'linux') {
+ return false;
+ }
+
+ // For non-Linux OSes, we generally assume a GUI is available
+ // unless other signals (like SSH) suggest otherwise.
+ return true;
+}
diff --git a/workspace-mcp-server/src/utils/validation.ts b/workspace-mcp-server/src/utils/validation.ts
new file mode 100644
index 00000000..a33d499b
--- /dev/null
+++ b/workspace-mcp-server/src/utils/validation.ts
@@ -0,0 +1,182 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod';
+
+/**
+ * Email validation schema
+ * Validates email format according to RFC 5322
+ */
+export const emailSchema = z.string().email('Invalid email format');
+
+/**
+ * Validates multiple email addresses (for CC/BCC fields)
+ */
+export const emailArraySchema = z.union([
+ emailSchema,
+ z.array(emailSchema)
+]);
+
+/**
+ * ISO 8601 datetime validation schema
+ * Accepts formats like:
+ * - 2024-01-15T10:30:00Z
+ * - 2024-01-15T10:30:00-05:00
+ * - 2024-01-15T10:30:00.000Z
+ */
+export const iso8601DateTimeSchema = z.string().refine(
+ (val) => {
+ const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?(Z|[+-]\d{2}:\d{2})$/;
+ if (!iso8601Regex.test(val)) return false;
+
+ // Additional check: ensure it's a valid date
+ const date = new Date(val);
+ return !isNaN(date.getTime());
+ },
+ {
+ message: 'Invalid ISO 8601 datetime format. Expected format: YYYY-MM-DDTHH:mm:ss[.sss][Z|±HH:mm]'
+ }
+);
+
+/**
+ * Google Drive document/file ID validation
+ * Google IDs are typically alphanumeric strings with hyphens and underscores
+ */
+export const googleDocumentIdSchema = z.string().regex(
+ /^[a-zA-Z0-9_-]+$/,
+ 'Invalid document ID format. Document IDs should only contain letters, numbers, hyphens, and underscores'
+);
+
+/**
+ * Google Drive URL validation
+ * Accepts various Google Workspace URLs and extracts the document ID
+ */
+export const googleWorkspaceUrlSchema = z.string().regex(
+ /^https:\/\/(docs|drive|sheets|slides)\.google\.com\/.+\/d\/([a-zA-Z0-9_-]+)/,
+ 'Invalid Google Workspace URL format'
+);
+
+/**
+ * Folder name validation
+ * Prevents problematic characters in folder names
+ */
+export const folderNameSchema = z.string()
+ .min(1, 'Folder name cannot be empty')
+ .max(255, 'Folder name too long (max 255 characters)')
+ .refine(
+ (val) => !(/[<>:"/\\|?*\x00-\x1F]/.test(val)),
+ 'Folder name contains invalid characters'
+ );
+
+/**
+ * Calendar ID validation
+ * Can be 'primary' or an email address
+ */
+export const calendarIdSchema = z.union([
+ z.literal('primary'),
+ emailSchema
+]);
+
+/**
+ * Search query sanitization
+ * Escapes potentially dangerous characters from search queries
+ * Preserves quotes for exact phrase searching
+ */
+export const searchQuerySchema = z.string()
+ .transform((val) => {
+ // Escape backslashes first, then escape quotes
+ // This preserves the ability to search for exact phrases
+ return val
+ .replace(/\\/g, '\\\\') // Escape backslashes
+ .replace(/'/g, "\\'") // Escape single quotes
+ .replace(/"/g, '\\"'); // Escape double quotes
+ });
+
+/**
+ * Page size validation for pagination
+ */
+export const pageSizeSchema = z.number()
+ .int('Page size must be an integer')
+ .min(1, 'Page size must be at least 1')
+ .max(100, 'Page size cannot exceed 100');
+
+
+/**
+ * Helper function to validate email
+ */
+export function validateEmail(email: string): { success: boolean; error?: string } {
+ try {
+ emailSchema.parse(email);
+ return { success: true };
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ return { success: false, error: error.errors[0].message };
+ }
+ return { success: false, error: 'Invalid email format' };
+ }
+}
+
+/**
+ * Helper function to validate ISO 8601 datetime
+ */
+export function validateDateTime(datetime: string): { success: boolean; error?: string } {
+ try {
+ iso8601DateTimeSchema.parse(datetime);
+ return { success: true };
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ return { success: false, error: error.errors[0].message };
+ }
+ return { success: false, error: 'Invalid datetime format' };
+ }
+}
+
+/**
+ * Helper function to validate Google document ID
+ */
+export function validateDocumentId(id: string): { success: boolean; error?: string } {
+ try {
+ googleDocumentIdSchema.parse(id);
+ return { success: true };
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ return { success: false, error: error.errors[0].message };
+ }
+ return { success: false, error: 'Invalid document ID' };
+ }
+}
+
+/**
+ * Helper function to extract document ID from URL or return the ID if already valid
+ */
+export function extractDocumentId(urlOrId: string): string {
+ // First check if it's already a valid ID
+ if (googleDocumentIdSchema.safeParse(urlOrId).success) {
+ return urlOrId;
+ }
+
+ // Try to extract from URL
+ const urlMatch = urlOrId.match(/\/d\/([a-zA-Z0-9_-]+)/);
+ if (urlMatch && urlMatch[1]) {
+ return urlMatch[1];
+ }
+
+ throw new Error('Invalid document ID or URL');
+}
+
+/**
+ * Validation error class for consistent error handling
+ */
+export class ValidationError extends Error {
+ constructor(
+ message: string,
+ public field: string,
+ public value: unknown
+ ) {
+ super(message);
+ this.name = 'ValidationError';
+ }
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/tsconfig.json b/workspace-mcp-server/tsconfig.json
new file mode 100644
index 00000000..83e60126
--- /dev/null
+++ b/workspace-mcp-server/tsconfig.json
@@ -0,0 +1,16 @@
+{
+ "extends": "../tsconfig.json",
+ "compilerOptions": {
+ "rootDir": "./src",
+ "outDir": "./dist"
+ },
+ "include": [
+ "src/**/*"
+ ],
+ "exclude": [
+ "dist",
+ "node_modules",
+ "src/**/*.test.ts",
+ "src/**/*.spec.ts"
+ ]
+}
\ No newline at end of file
diff --git a/workspace-mcp-server/tsconfig.test.json b/workspace-mcp-server/tsconfig.test.json
new file mode 100644
index 00000000..4885ae80
--- /dev/null
+++ b/workspace-mcp-server/tsconfig.test.json
@@ -0,0 +1,11 @@
+{
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "strict": false,
+ "noImplicitAny": false
+ },
+ "include": [
+ "src/**/*.test.ts",
+ "src/**/*.spec.ts"
+ ]
+}
\ No newline at end of file