🚀 谷歌工作区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\\.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 支持
- 其他谷歌服务集成
测试策略
单元测试方法
-
简化 mocking
- 使用静态 mock 响应以确保测试可预测
- 避免在单元测试中进行复杂的端到端模拟
- 每次仅测试一个功能模块
- 对外部依赖（如 OAuth、文件系统）使用简单实现
-
测试组织
- 按功能将测试分组（例如，账号操作、文件操作）
- 使用清晰且描述性的测试名称
- 保持测试专注和隔离
- 在每次测试之间重置 mock 和模块
-
Mock 管理
- 使用
jest.resetModules()确保干净状态 - 在 mock 修改后重新加载模块
- 显式跟踪 mock 函数调用
- 验证函数调用和结果两者兼顾
- 使用
-
文件系统测试
- 使用简单 JSON 结构
- 注重数据正确性而非格式
- 测试错误场景（如缺失文件、无效 JSON）
- 无需了解实现细节即可验证文件操作
-
Token 处理
- 使用静态响应模拟 token 验证
- 分别测试成功和失败情形
- 忽略 OAuth 复杂性，专注于账号管理器的 token 处理逻辑
执行测试
# 运行所有测试
npm test
# 运行指定测试文件
npm test path/to/test.ts
# 带覆盖率运行测试
npm test -- --coverage
# CI 构建执行所有带 coverage 的测试
npm run test:ci
最佳实践
-
身份验证
- 在 MCP 设置中安全存储凭证
- 使用最小必需权限范围
- 正确处理 token 刷新
-
错误处理
- 检查响应状态码
- 适当处理认证错误
- 建立完整的日志记录机制
-
配置管理
- 避免在生产环境中暴露凭证
- 定期更新 API 密钥
- 使用环境变量管理敏感信息
-
性能优化
- 合理设置请求超时时间
- 实施速率限制以防止过载
- 使用缓存减少 API 请求次数
📄 许可证
本项目采用 MIT License。