Google Drive MCP Server

Google Drive MCP 服务

通过 Model Context Protocol（MCP）提供 AI 驱动的 Google Drive 集成，实现智能文件管理、内容分析和组织洞察。

🚀 功能

核心 MCP 工具

• list_files - 通过高级筛选和分页列出文件与文件夹
• get_file_content - 提取并获取文件内容及元数据
• search_files - 支持相关性评分和筛选的全文搜索
• analyze_content - AI 驱动的内容分析，提供摘要和分类
• get_organization_insights - 分析 Drive 组织结构并提供可操作的建议

主要能力

• 🔐 安全的 OAuth2 身份验证，使用 Google Drive API
• 📊 内容分析 - AI 驱动的摘要、分类和关键词提取
• 🔍 高级搜索 - 支持相关性评分和筛选的全文搜索
• 📁 组织洞察 - 检测重复项并优化结构
• ⚡ 性能优化 - 智能缓存和速率限制
• 🛡️ 适用于生产环境 - 全面的错误处理和日志记录

📋 前置条件

• Node.js 18.0.0 或更高版本
• Google Cloud 项目，并已启用 Drive API
• 来自 Google Cloud Console 的 OAuth2 凭据

🛠️ 安装

1. 克隆并安装依赖项

git clone <repository-url>
cd gdrive-sparc-mcp
npm install

2. 设置 Google Cloud

1. 创建 Google Cloud 项目

   • 前往 Google Cloud Console
   • 创建新项目或选择现有项目

2. 启用 Google Drive API

   # Using gcloud CLI
   gcloud services enable drive.googleapis.com
   

3. 创建 OAuth2 凭据

   • 前往“API 和服务”>“凭据”
   • 点击“创建凭据”>“OAuth 2.0 客户端 ID”
   • 应用类型：“Web 应用”
   • 添加已获授权的重定向 URI：http://localhost:3000/auth/callback
   • 下载凭据 JSON 文件

3. 配置环境

根据模板创建 .env 文件：

cp .env.example .env

配置所需的环境变量：

# Google OAuth Configuration (Required)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback

# Session Configuration (Required)
SESSION_SECRET=your-secure-session-secret-at-least-32-characters

# Optional Configuration
NODE_ENV=production
LOG_LEVEL=info
CACHE_TTL=300
CACHE_MAX_SIZE=1000
RATE_LIMIT_WINDOW=60000
RATE_LIMIT_MAX_REQUESTS=100

4. 构建并启动

# Build TypeScript
npm run build

# Start server
npm start

# Or for development
npm run dev

🔧 配置

环境变量

变量	必需	默认值	说明
GOOGLE_CLIENT_ID	✅	-	Google OAuth2 客户端 ID
GOOGLE_CLIENT_SECRET	✅	-	Google OAuth2 客户端密钥
GOOGLE_REDIRECT_URI	✅	-	OAuth2 重定向 URI
SESSION_SECRET	✅	-	会话加密密钥（32 个字符以上）
NODE_ENV	❌	development	环境模式
LOG_LEVEL	❌	info	日志级别（error、warn、info、debug）
CACHE_TTL	❌	300	缓存生存时间（秒）
CACHE_MAX_SIZE	❌	1000	最大缓存条目数
RATE_LIMIT_WINDOW	❌	60000	速率限制时间窗口（ms）
RATE_LIMIT_MAX_REQUESTS	❌	100	每个时间窗口的最大请求数

Google Drive API 范围

服务会请求以下 OAuth2 范围：

• https://www.googleapis.com/auth/drive.readonly - 读取 Google Drive 文件
• https://www.googleapis.com/auth/userinfo.profile - 基本个人资料信息

📖 用法

MCP 客户端集成

将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "gdrive-sparc-mcp": {
      "command": "node",
      "args": ["path/to/gdrive-sparc-mcp/dist/server.js"]
    }
  }
}

工具示例

列出文件

{
  "name": "list_files",
  "arguments": {
    "folderId": "optional-folder-id",
    "recursive": true,
    "maxResults": 50,
    "orderBy": "modifiedTime"
  }
}

搜索文件

{
  "name": "search_files",
  "arguments": {
    "query": "project proposal",
    "filters": {
      "mimeTypes": ["application/pdf", "application/vnd.google-apps.document"]
    },
    "options": {
      "maxResults": 20,
      "includeSnippets": true
    }
  }
}

分析内容

{
  "name": "analyze_content",
  "arguments": {
    "fileIds": ["file-id-1", "file-id-2"],
    "analysisOptions": {
      "enableSummarization": true,
      "enableCategorization": true,
      "enableKeywordExtraction": true
    }
  }
}

获取组织洞察

{
  "name": "get_organization_insights",
  "arguments": {
    "scope": {
      "folderId": "optional-folder-id",
      "includeSubfolders": true,
      "fileLimit": 1000
    },
    "analysisOptions": {
      "enableDuplicateDetection": true,
      "enableStructureAnalysis": true
    }
  }
}

🧪 测试

运行测试

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suite
npm test -- tests/auth/auth-service.test.ts

# Run integration tests
npm test -- tests/integration/

测试服务

测试 MCP 服务功能：

# Test server startup and tool listing
node test-server.js

🚀 部署

Docker 部署

1. 构建 Docker 镜像

   docker build -t gdrive-sparc-mcp .
   

2. 运行容器

   docker run -d \
     --name gdrive-mcp \
     -p 3000:3000 \
     --env-file .env \
     gdrive-sparc-mcp
   

生产环境部署

1. 环境设置

   # Set production environment
   export NODE_ENV=production
   export LOG_LEVEL=warn
   
   # Configure production secrets
   export SESSION_SECRET="your-production-session-secret"
   export GOOGLE_CLIENT_ID="your-production-client-id"
   export GOOGLE_CLIENT_SECRET="your-production-client-secret"
   

2. 进程管理

   # Using PM2
   npm install -g pm2
   pm2 start dist/server.js --name gdrive-mcp
   pm2 save
   pm2 startup
   

3. 运行状况监控

   # Check server health
   curl -X POST http://localhost:3000 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   

🔍 监控和日志记录

日志级别

• error - 仅错误情况
• warn - 警告和错误情况
• info - 信息、警告和错误消息（默认）
• debug - 所有消息，包括调试信息

性能指标

• 请求/响应时间
• 缓存命中/未命中率
• 速率限制统计信息
• 身份验证成功/失败率

健康检查

• 配置验证
• Google API 连通性
• 缓存系统状态
• 内存和性能指标

🛡️ 安全

身份验证

• 使用 Google 的安全 OAuth2 流程
• 基于会话的身份验证
• 自动刷新令牌
• 安全存储凭据

数据保护

• 不会持久化存储用户数据
• 加密会话管理
• 速率限制和滥用防护
• 输入验证和净化

最佳实践

• 定期进行安全更新
• 保护环境变量
• 安全通信（生产环境中使用 HTTPS）
• 对安全事件进行审计日志记录

🐛 故障排除

常见问题

配置错误

# Check configuration validation
npm run build && node dist/server.js

身份验证问题

• 验证 Google Cloud 凭据
• 检查 OAuth2 重定向 URI 配置
• 确保已启用 Drive API

性能问题

• 监控缓存命中率
• 检查速率限制设置
• 检查日志级别和输出

连接问题

• 验证网络连接
• 检查防火墙设置
• 验证环境变量

调试模式

# Enable debug logging
export LOG_LEVEL=debug
npm start

支持

• 查看文档
• 查阅故障排除指南
• 在 GitHub 上提交问题

📚 文档

• 功能需求
• 领域模型
• API 规范
• 实现架构
• 测试与部署

🤝 贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

🙏 致谢

• 感谢 Model Context Protocol 提供 MCP 规范
• 感谢 Google Drive API 提供文件访问功能
• 感谢 SPARC Development Team 提供开发方法论

---

版本：1.0.0
最后更新：2025-01-30
维护者：SPARC Development Team