Google Workspace

🚀 谷歌工作区MCP项目

本项目 google-workspace-mcp 是用于谷歌工作区的工具，提供账号管理、邮件处理、日历操作等功能，能帮助开发者更便捷地与谷歌服务集成。

🚀 快速开始

本项目可通过 npm 进行安装，安装后根据配置说明进行配置，即可使用各功能模块。

📦 安装指南

项目依赖

运行以下命令安装项目依赖：

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