Google Workspace

🚀 谷歌工作區 MCP 項目

谷歌工作區 MCP 項目是一個用於集成谷歌工作區服務的工具，可實現賬號操作、郵件處理、日曆操作等功能，幫助開發者更便捷地使用谷歌工作區的各項服務。

🚀 快速開始

本項目提供了一系列功能用於與谷歌工作區服務進行交互，以下是使用前的安裝和配置步驟。

📦 安裝指南

項目依賴

運行以下命令安裝項目依賴：

npm install google-workspace-mcp --save

配置說明

賬號管理器實例

使用以下代碼創建賬號管理器實例：

import { AccountManager } from 'google-workspace-mcp';

const accountManager = new AccountManager({
  configPath: './config',
  scopes: ['https://www.googleapis.com/auth/gmail.readonly']
});

默認配置路徑

• Windows: C:\Users\<CurrentUser>\.mcp\google-workspace-mcp
• macOS/Linux: ~/.mcp/google-workspace-mcp

💻 使用示例

基礎用法

賬號操作

await accountManager.authenticate('user123', {
  type: 'password',
  credentials: {
    username: 'your_username',
    password: 'your_password'
  }
});

郵件處理

const gmail = accountManager.getGmailService('user123');
const inbox = await gmail.inbox.list();

日曆操作

const calendar = accountManager.getCalendarService('user123');
const events = await calendar.calendar.events.list('primary');

📚 詳細文檔

詳細信息請查閱 API 文檔。

✨ 主要特性

未來規劃

新增服務

• Admin SDK 支持
• 其他谷歌服務集成

測試策略

單元測試方法

1. 簡化 mocking

   • 使用靜態 mock 響應以確保測試可預測
   • 避免在單元測試中進行復雜的端到端模擬
   • 每次僅測試一個功能模塊
   • 對外部依賴（如 OAuth、文件系統）使用簡單實現

2. 測試組織

   • 按功能將測試分組（例如，賬號操作、文件操作）
   • 使用清晰且描述性的測試名稱
   • 保持測試專注和隔離
   • 在每次測試之間重置 mock 和模塊

3. Mock 管理

   • 使用 jest.resetModules() 確保乾淨狀態
   • 在 mock 修改後重新加載模塊
   • 顯式跟蹤 mock 函數調用
   • 驗證函數調用和結果兩者兼顧

4. 文件系統測試

   • 使用簡單 JSON 結構
   • 注重數據正確性而非格式
   • 測試錯誤場景（如缺失文件、無效 JSON）
   • 無需瞭解實現細節即可驗證文件操作

5. Token 處理

   • 使用靜態響應模擬 token 驗證
   • 分別測試成功和失敗情形
   • 忽略 OAuth 複雜性，專注於賬號管理器的 token 處理邏輯

執行測試

# 運行所有測試
npm test

# 運行指定測試文件
npm test path/to/test.ts

# 帶覆蓋率運行測試
npm test -- --coverage

# CI 構建執行所有帶 coverage 的測試
npm run test:ci

最佳實踐

1. 身份驗證

   • 在 MCP 設置中安全存儲憑證
   • 使用最小必需權限範圍
   • 正確處理 token 刷新

2. 錯誤處理

   • 檢查響應狀態碼
   • 適當處理認證錯誤
   • 建立完整的日誌記錄機制

3. 配置管理

   • 避免在生產環境中暴露憑證
   • 定期更新 API 密鑰
   • 使用環境變量管理敏感信息

4. 性能優化

   • 合理設置請求超時時間
   • 實施速率限制以防止過載
   • 使用緩存減少 API 請求次數

📄 許可證

本項目採用 MIT License。

項目地址

• GitHub: https://github.com/yourusername/google-workspace-mcp
• npm: https://www.npmjs.com/package/google-workspace-mcp