使用说明

Google Drive MCP服务器

通过模型上下文协议（MCP）实现AI驱动的Google Drive集成，提供智能文件管理、内容分析和组织洞察。

🚀 特性

核心MCP工具

list_files -列出具有高级过滤和分页功能的文件和文件夹
get_file_content -提取和检索包含元数据的文件内容
search_files -带有相关性评分和过滤的全文搜索
analyze_content -基于人工智能的内容分析，具有摘要和分类功能
get_organization_insights -通过可操作的建议推动组织分析

关键能力

🔐 安全的OAuth2身份验证 使用Google Drive API
📊 内容分析 -人工智能支持的摘要、分类和关键字提取
🔍 高级搜索 -带有相关性评分和过滤的全文搜索
📁 组织洞察 -重复检测和结构优化
⚡ 性能优化 -智能缓存和速率限制
🛡️ 生产就绪 -全面的错误处理和记录

📋 先决条件

Node.js 18.0.0或更高
谷歌云项目 启用驱动器API
OAuth2凭据 从谷歌云控制台

🛠️ 安装

1.克隆和安装依赖项

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

2.谷歌云设置

创建谷歌云项目
- 首选谷歌云控制台
- 创建新项目或选择现有项目

启用Google Drive API

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

创建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`	✅	-	谷歌OAuth2客户端ID
`GOOGLE_CLIENT_SECRET`	✅	-	Google OAuth2客户端密码
`GOOGLE_REDIRECT_URI`	✅	-	OAuth2 重定向 URI
`SESSION_SECRET`	✅	-	会话加密密钥（32+个字符）
`NODE_ENV`	❌	`development`	环境模式
`LOG_LEVEL`	❌	`info`	日志记录级别（错误、警告、信息、调试）
`CACHE_TTL`	❌	`300`	缓存TTL（秒）
`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部署

构建Docker镜像
```
docker build -t gdrive-sparc-mcp .
```

运行容器

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

生产部署

环境设置

# 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"

流程管理

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

健康监测

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

🔍 监控和日志记录

日志级别

错误 -仅限错误条件
警告 -警告和错误条件
信息 -信息、警告和错误消息（默认）
调试 -所有消息，包括调试信息

性能指标

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

健康检查

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

🛡️ 安全

认证

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

数据保护

没有持久存储用户数据
加密会话管理
限速和防止滥用
输入验证和净化

最佳实践

定期安全更新
环境变量保护
安全通信（HTTPS在生产中）
安全事件的审核日志记录

🐛 故障排除

常见问题

配置错误

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

身份验证问题

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

性能问题

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

连接问题

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

调试模式

# Enable debug logging
export LOG_LEVEL=debug
npm start

支持

检查文档
审查故障排除指南
在GitHub上提交问题

📚 文档

🤝 贡献

分叉存储库
创建特征分支(git checkout -b feature/amazing-feature)
提交更改(git commit -m 'Add amazing feature')
推送到分支(git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

模型上下文协议对于MCP规范
Google Drive API 用于文件访问功能
SPARC开发团队开发方法论

版本: 1.0.0
最后更新: 2025-01-30
维护者：SPARC开发团队