项目简介

Google Workspace MCP 是一个基于 Model Context Protocol (MCP) 的开源集成项目，旨在为 AI 代理提供与 Google Workspace 应用交互的标准化接口。通过该 MCP 服务器，AI 代理可以安全地访问和管理 Google Docs、Sheets、Slides、Gmail、Calendar、Drive、Chat、Forms、Tasks、Contacts 等 Workspace 服务。

该项目由 Taylor Wilsdon 开发和维护，采用 FastMCP 框架构建，支持 OAuth 2.0 认证、灵活的权限控制、多账户管理和跨平台部署。资料来源：README.md:1-50

核心功能

多服务集成

Google Workspace MCP 提供了对以下 Google Workspace 服务的完整或部分支持：

工具分层架构

项目采用三层工具分层设计，通过 core/tool_tiers.yaml 配置文件管理：

• Core（核心层）：包含每个服务的基本读写操作，是最常用的功能集合
• Extended（扩展层）：提供更高级的功能，如格式化、评论管理、批量操作
• Complete（完整层）：包含所有可用工具，提供最全面的功能覆盖

# 工具分层示例
sheets:
  core:
    - create_spreadsheet
    - read_sheet_values
    - modify_sheet_values
  extended:
    - list_spreadsheets
    - get_spreadsheet_info
  complete:
    - create_sheet
    - append_table_rows

资料来源：core/tool_tiers.yaml:1-80

技术架构

系统架构图

graph TB
    subgraph "客户端层"
        MCP_Client["MCP 客户端<br/>(Claude Desktop / VS Code / 其他)"]
    end
    
    subgraph "认证层"
        OAuth["OAuth 2.0 认证"]
        GoogleProvider["GoogleProvider"]
        Session["会话管理"]
    end
    
    subgraph "服务层"
        Server["FastMCP Server"]
        Registry["工具注册表"]
    end
    
    subgraph "Google Workspace API"
        Drive_API["Drive API"]
        Docs_API["Docs API"]
        Sheets_API["Sheets API"]
        Gmail_API["Gmail API"]
        Calendar_API["Calendar API"]
        Chat_API["Chat API"]
    end
    
    MCP_Client --> Server
    Server --> Registry
    Registry --> OAuth
    OAuth --> GoogleProvider
    Server --> Drive_API
    Server --> Docs_API
    Server --> Sheets_API
    Server --> Gmail_API
    Server --> Calendar_API
    Server --> Chat_API

核心组件

资料来源：core/server.py:1-50

服务装饰器

项目使用 require_google_service 装饰器实现服务级别的访问控制：

@require_google_service("drive", "drive_read")
async def list_drives(service, user_google_email: str) -> str:
    """列出用户可访问的所有云端硬盘"""
    ...

该装饰器确保只有在 OAuth 授权包含相应范围时，工具才能执行。资料来源：auth/service_decorator.py

认证与授权

OAuth 2.0 认证流程

sequenceDiagram
    participant User as 用户
    participant Client as MCP 客户端
    participant Server as Workspace MCP
    participant Google as Google OAuth
    
    User->>Client: 发起请求
    Client->>Server: 调用工具
    Server->>Server: 检查凭据有效性
    alt 凭据无效或过期
        Server->>Google: 重定向到授权页面
        User->>Google: 完成登录授权
        Google->>Server: 返回授权码
        Server->>Google: 交换访问令牌
        Google->>Server: 返回令牌和刷新令牌
        Server->>Server: 存储凭据
    end
    Server->>Google: 调用 API
    Google->>Client: 返回数据

多账户支持

项目支持多个 Google 账户的凭据管理，通过 OAuth state 参数区分不同会话。客户端可通过 user_google_email 参数指定目标账户：

@require_google_service("drive", "drive_read")
async def list_drives(service, user_google_email: str) -> str:
    """列出指定用户的云端硬盘"""
    ...

资料来源：auth/oauth_config.py

部署模式

本地部署

通过 pip 或 uv 安装后直接运行：

pip install workspace-mcp
python -m workspace_mcp

或使用 uv：

uv run main.py

Docker 部署

提供官方 Docker 镜像：

docker pull ghcr.io/taylorwilsdon/workspace-mcp:latest
docker run -p 8000:8000 \
  -e GOOGLE_CLIENT_ID=your_client_id \
  -e GOOGLE_CLIENT_SECRET=your_client_secret \
  ghcr.io/taylorwilsdon/workspace-mcp:latest

Kubernetes 部署

通过 Helm Chart 部署到 Kubernetes 集群：

helm install workspace-mcp ./helm-chart/workspace-mcp \
  --set secrets.googleOAuth.clientId=your_client_id \
  --set secrets.googleOAuth.clientSecret=your_client_secret

支持的配置项：

资料来源：helm-chart/workspace-mcp/README.md:1-50

工具注册机制

条件工具注册

项目实现了基于层级的条件工具注册系统：

# core/tool_registry.py
def conditional_tool(server, tool_name: str):
    def decorator(func: Callable) -> Callable:
        if is_tool_enabled(tool_name):
            return server.tool()(func)
        else:
            return func  # 跳过注册

通过 set_enabled_tools() 可在运行时动态启用/禁用工具集：

set_enabled_tools({"docs", "sheets", "gmail"})  # 仅启用文档、表格和邮件

资料来源：core/tool_registry.py:1-50

工具注解

每个工具都包含详细的 MCP 注解，帮助客户端理解工具行为：

READ_COMMENT_ANNOTATIONS = ToolAnnotations(
    readOnlyHint=True,
    destructiveHint=False,
    idempotentHint=True,
    openWorldHint=True,
)

API 启用检测

项目实现了智能的 API 启用状态检测：

# core/api_enablement.py
API_ENABLEMENT_LINKS = {
    "drive": "https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com",
    "gmail": "https://console.cloud.google.com/flows/enableapi?apiid=gmail.googleapis.com",
    # ... 更多 API
}

当用户尝试使用未启用的 API 时，系统会生成包含直接启用链接的错误消息。资料来源：core/api_enablement.py:1-80

Google Apps Script 集成

功能概述

Apps Script 模块提供 17+ 工具，支持完整的脚本生命周期管理：

资料来源：gappsscript/README.md:1-100

使用模式

典型 AI 代理工作流：

graph LR
    A[检查] --> B[分析]
    B --> C[生成]
    C --> D[更新]
    D --> E[执行]
    E --> F[部署]
    F --> G[监控]

CLI 工具

项目提供命令行界面便于调试和集成：

# 列出所有可用工具
workspace-cli list

# 调用指定工具
workspace-cli call list_drives

配置通过环境变量管理：

资料来源：core/cli.py:1-80

已知问题与限制

根据社区反馈，以下问题需要注意：

认证相关

• 问题 #810：OAuth callback 将凭据存储在 google-<state> 会话中，与 MCP 会话未绑定，导致重新认证后每次工具调用都重新提示授权
• 问题 #667：Windows 系统上 Python 子进程在父进程异常终止后可能继续运行，导致端口 8000-8004 被占用

工具范围问题

• 问题 #809：delete_script_project 和 create_version 工具声明了未在 SCOPE_GROUPS 中注册的范围别名（drive_full、script_full），导致 _resolve_scopes 失败

功能缺失

• 问题 #568：缺少 import_to_google_slides 工具，无法将 PPTX 转换为原生 Google Slides 格式
• 问题 #820：Office 文件上传时的自动格式转换功能不完整

版本历史

快速开始

前置要求

1. Python 3.10+
2. Google Cloud Console 项目
3. 已启用相关 Google Workspace API
4. 配置 OAuth 2.0 凭据

安装步骤

# 克隆仓库
git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp

# 安装依赖
pip install -e .

# 配置环境变量
export GOOGLE_CLIENT_ID=your_client_id
export GOOGLE_CLIENT_SECRET=your_client_secret

# 运行服务器
python main.py

相关资源

• 官方文档：https://workspacemcp.com
• GitHub 仓库：https://github.com/taylorwilsdon/google_workspace_mcp
• 问题追踪：https://github.com/taylorwilsdon/google_workspace_mcp/issues
• FastMCP 文档：https://gofastmcp.com

环境要求

资料来源：README.md

安装方式

方式一：pip 安装

# 安装稳定版本
pip install workspace-mcp

# 或从源码安装最新版本
git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp
pip install -e .

资料来源：README.md

方式二：Docker 部署

# 构建镜像
docker build -t workspace-mcp .

# 运行容器
docker run -p 8000:8000 \
  -e GOOGLE_CLIENT_ID=your_client_id \
  -e GOOGLE_CLIENT_SECRET=your_client_secret \
  workspace-mcp

资料来源：Dockerfile

方式三：Docker Compose 本地开发

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

资料来源：docker-compose.yml

Google Cloud Console 配置

在运行服务前，需要完成 Google Cloud 项目配置：

步骤 1：创建项目

1. 访问 Google Cloud Console
2. 创建新项目或选择现有项目
3. 记录项目 ID

步骤 2：启用 API

根据需要启用的功能，启用以下 API：

步骤 3：创建 OAuth 2.0 凭据

1. 进入 APIs & Services > Credentials
2. 点击 Create Credentials > OAuth client ID
3. 选择应用类型：

• Web application：适用于服务器部署
• Desktop app：适用于本地桌面应用

1. 配置授权重定向 URI：

• 本地开发：http://localhost:8000/oauth2callback
• 生产环境：http://your-domain:8000/oauth2callback

步骤 4：配置 OAuth 同意屏幕

1. 设置应用名称
2. 添加需要申请的 OAuth 作用域
3. 添加测试用户（如果是内部应用）

资料来源：README.md

服务配置

环境变量

资料来源：README.md

Helm Chart 部署（Kubernetes）

# 添加 Helm 仓库
helm repo add workspace-mcp https://taylorwilsdon.github.io/google_workspace_mcp

# 安装
helm install workspace-mcp workspace-mcp/workspace-mcp \
  --set secrets.googleOAuth.clientId=your_client_id \
  --set secrets.googleOAuth.clientSecret=your_client_secret

关键配置参数：

资料来源：helm-chart/workspace-mcp/README.md

启动服务

基本启动

# 设置环境变量
export GOOGLE_CLIENT_ID=your_client_id
export GOOGLE_CLIENT_SECRET=your_client_secret

# 启动服务
python main.py

启用特定工具

# 只启用 Docs 和 Sheets 工具
python main.py --tools docs sheets

# 列出所有可用工具
python main.py --tools help

指定配置文件

python main.py --config /path/to/config.yaml

资料来源：README.md

工具层级架构

MCP 工具按功能分为三个层级，便于渐进式使用：

graph TD
    A[工具层级] --> B[Core 核心层]
    A --> C[Extended 扩展层]
    A --> D[Complete 完整层]
    
    B --> B1[基础读写操作]
    B --> B2[列表查询功能]
    
    C --> C1[格式化和样式]
    C --> C2[批量操作]
    C --> C3[高级查询]
    
    D --> D1[调试工具]
    D --> D2[评论管理]
    D --> D3[复杂转换]

资料来源：core/tool_tiers.yaml

各服务工具层级

资料来源：core/tool_tiers.yaml

OAuth 认证流程

首次认证流程

sequenceDiagram
    participant User as 用户
    participant MCP as MCP Server
    participant Google as Google OAuth
    participant AI as AI Agent

    User->>MCP: 发起请求（需要认证）
    MCP->>User: 返回授权 URL
    User->>Google: 访问授权页面
    Google->>User: 显示登录/授权页面
    User->>Google: 完成登录授权
    Google->>MCP: 重定向回调 + Authorization Code
    MCP->>Google: 交换访问令牌
    Google->>MCP: 返回 Access Token + Refresh Token
    MCP->>MCP: 存储凭据
    MCP->>AI: 认证成功，继续处理请求

OAuth 2.1 增强功能（v1.21.1+）

最新版本包含以下改进：

• 自动打开浏览器：首次认证时自动打开授权页面
• login_hint 支持：预填充用户邮箱，减少手动输入
• 硬化的主机绑定：修复了遗留认证模式下的主机绑定问题

# 设置默认用户邮箱（可选）
export [email protected]

资料来源：README.md

常见认证问题

CLI 命令行工具

服务提供独立的 CLI 客户端用于测试和调用工具：

# 列出所有可用工具
workspace-cli list

# 调用指定工具
workspace-cli call get_doc_content document_id=xxx

# 指定 MCP 服务器地址
workspace-cli --url http://localhost:8001 list

资料来源：core/cli.py

CLI 环境变量

Apps Script 集成

MCP 支持完整的 Apps Script 项目管理：

核心功能

• 列出和查看 Apps Script 项目
• 创建新的独立脚本或绑定脚本
• 更新脚本内容（添加/修改 JavaScript 文件）
• 执行脚本函数
• 管理部署和版本

工作流程示例

graph LR
    A[创建项目] --> B[编写脚本]
    B --> C[测试执行]
    C --> D{测试结果}
    D -->|成功| E[创建部署]
    D -->|失败| F[调试修复]
    F --> B
    E --> G[设置触发器]

触发器代码生成

# 生成时间触发器代码
# In MCP client: "生成一个每分钟执行的触发器代码"

生成的代码示例：

function createTimeDrivenTriggers() {
  ScriptApp.newTrigger('myFunction')
    .timeBased()
    .everyMinutes(1)
    .create();
}

资料来源：gappsscript/README.md

故障排除

常见问题

日志查看

# Docker 环境
docker logs <container_id>

# 直接运行
python main.py  # 输出到 stdout

# 使用 journalctl (systemd)
journalctl -u workspace-mcp -f

健康检查

# 检查服务健康状态
curl http://localhost:8000/health

# Kubernetes 环境
kubectl get pods -l app=workspace-mcp
kubectl describe pod <pod_name>

安全建议

1. 保护凭据：不要将 GOOGLE_CLIENT_SECRET 提交到代码仓库
2. 最小权限：只申请必要的 OAuth 作用域
3. 生产环境：使用 HTTPS 和强密码保护
4. 定期轮换：定期更换 OAuth 客户端密钥
5. 监控日志：启用审计日志，记录所有操作

下一步

• 阅读 工具参考文档 了解各工具的详细用法
• 查看 API 文档 了解 REST API 接口
• 参考 示例项目 获取使用案例
• 加入 社区讨论 获取帮助

概述

Google Workspace MCP 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在为 AI 代理提供与 Google Workspace 各服务的交互能力。该系统通过 FastMCP 框架实现工具注册、OAuth 认证管理和 HTTP 传输支持，允许 AI 代理以标准化方式操作 Google Docs、Sheets、Slides、Gmail、Drive、Calendar、Tasks、Contacts、Apps Script 等服务。

系统的核心设计目标包括：

• 模块化工具架构：通过分层机制（core/extended/complete）组织工具，按需加载
• 统一认证管理：集中处理 Google OAuth 2.0 认证流程，支持多用户场景
• 服务解耦：各服务模块独立实现，通过装饰器模式与认证层解耦
• 可配置性：支持通过环境变量、配置文件和命令行参数灵活定制行为

核心架构组件

1. 服务器入口与初始化

系统的启动入口采用分层架构模式：

graph TD
    A[main.py] --> B[fastmcp_server.py]
    B --> C[core/server.py]
    C --> D[auth/oauth_config.py]
    C --> E[core/tool_registry.py]
    C --> F[各服务模块]

fastmcp_server.py 负责初始化 FastMCP 实例并注册所有工具，而 core/server.py 包含主要的服务器配置和工具定义逻辑。 资料来源：fastmcp_server.py:1-50

2. 工具注册与条件加载机制

系统采用了装饰器模式与条件注册相结合的架构，实现精细化的工具管理：

#### 2.1 工具注册表 (Tool Registry)

core/tool_registry.py 提供了全局工具注册表，支持基于白名单的工具条件加载：

资料来源：core/tool_registry.py:1-60

条件注册的典型用法：

@conditional_tool(server, tool_name="get_doc_content")
@require_google_service("docs", "drive_read")
async def get_doc_content(...) -> ...:
    ...

#### 2.2 工具层级加载器 (Tool Tier Loader)

core/tool_tier_loader.py 实现了基于 YAML 配置的分层工具加载机制：

层级配置示例（core/tool_tiers.yaml）：

docs:
  core:
    - get_doc_content
    - create_doc
  extended:
    - export_doc_to_pdf
    - search_docs
  complete:
    - insert_doc_image
    - batch_update_doc

资料来源：core/tool_tier_loader.py:1-80

3. 认证与权限管理

#### 3.1 服务依赖装饰器

auth/service_decorator.py 提供了 require_google_service 装饰器，确保在执行工具前验证用户是否已授权所需的服务作用域：

@require_google_service("drive", "drive_read")
async def get_doc_content(service, user_google_email: str, document_id: str) -> ...:
    ...

该装饰器自动解析工具声明的作用域别名，并验证 OAuth 令牌是否包含相应权限。

#### 3.2 作用域解析机制

系统支持作用域别名机制，允许工具声明简化的作用域引用：

已知问题：delete_script_project 和 create_version 工具声明的别名 (drive_full, script_full) 未在 SCOPE_GROUPS 中注册，会导致永久认证失败。资料来源：Issue #809

4. 服务模块架构

#### 4.1 模块组织结构

gappsscript/          # Apps Script 服务
  - projects.py       # 项目管理工具
  - deployments.py    # 部署管理工具
  - versions.py       # 版本管理工具
  - executions.py     # 执行监控工具

core/
  - comments.py       # 通用评论管理（Docs/Sheets/Slides）
  - docs.py           # Google Docs 服务
  - sheets.py         # Google Sheets 服务
  - slides.py         # Google Slides 服务
  - drive.py          # Google Drive 服务
  - gmail.py          # Gmail 服务
  - calendar.py       # Calendar 服务
  - tasks.py          # Tasks 服务
  - contacts.py       # Contacts 服务
  - search.py         # Search 服务

#### 4.2 通用评论模块

core/comments.py 实现了一个工厂模式，为 Docs、Sheets、Slides 提供统一的评论管理接口：

graph LR
    A[list_document_comments] --> B[create_comment_tools]
    A --> C[manage_document_comment]
    B --> D[Drive API]
    C --> D

支持的操作包括：

• create：创建新评论
• reply：回复评论
• resolve：解决评论

资料来源：core/comments.py:1-100

5. 日志与错误处理

#### 5.1 增强日志格式化器

core/log_formatter.py 提供了视觉增强的日志格式化，支持：

• ANSI 颜色编码（DEBUG: 青色, INFO: 绿色, WARNING: 黄色, ERROR: 红色）
• 服务前缀标识
• 消息内容增强

#### 5.2 HTTP 错误处理

core/utils.py 中的 handle_http_errors 装饰器统一处理 API 错误，提供友好的错误信息和 API 启用指导。

core/api_enablement.py 实现了智能错误分析，可从错误详情中提取 API 服务名称和项目 ID，生成直接的可点击启用链接。

6. 传输与部署架构

#### 6.1 支持的传输方式

#### 6.2 OAuth 回调机制

系统使用硬编码的回调端口范围（8000-8004）处理 OAuth 授权流程。已知问题：在 Windows 环境下，当父进程非正常终止时，Python 子进程可能无法正确退出，导致端口泄漏。资料来源：Issue #816

#### 6.3 Helm Chart 部署

支持 Kubernetes 部署，配置项包括：

资料来源：helm-chart/workspace-mcp/README.md

工作流程

工具调用完整流程

sequenceDiagram
    participant MCP as MCP 客户端
    participant Server as FastMCP Server
    participant Auth as 认证层
    participant Service as 服务模块
    participant Google as Google API

    MCP->>Server: 调用工具 (如 get_doc_content)
    Server->>Auth: require_google_service 检查
    Auth->>Auth: 解析作用域别名
    Auth->>Auth: 验证 OAuth 令牌权限
    Alt 未授权
        Auth-->>MCP: 返回认证错误，触发 OAuth 流程
    Else 已授权
        Auth->>Service: 注入授权服务实例
        Service->>Google: 发送 API 请求
        Google-->>Service: 返回数据
        Service-->>Server: 处理并返回结果
        Server-->>MCP: 返回工具响应
    End

工具条件加载流程

graph TD
    A[启动时读取配置] --> B{检查 tools.enabled}
    B -->|为空| C[加载全部工具]
    B -->|有配置| D[解析 YAML 层级配置]
    D --> E{工具是否在 core 层?}
    E -->|是| F[无条件注册]
    E -->|否| G{工具是否在 extended 层?}
    G -->|是| H{启用 extended?}
    H -->|否| I[跳过注册]
    H -->|是| F
    G -->|否| J{工具是否在 complete 层?}
    J -->|是| K{启用 complete?}
    K -->|否| I
    K -->|是| F

配置体系

环境变量配置

OAuth 2.1 与传统模式

v1.21.1 版本增强了 OAuth 登录体验，系统支持：

• 自动打开浏览器进行 OAuth 授权
• login_hint 参数支持预填充用户邮箱
• 传统模式下强化主机绑定

已知限制与问题

扩展阅读

• Apps Script 模块文档
• CLI 工具使用指南
• 最新版本发布说明

系统概述

google_workspace_mcp 采用 OAuth 2.0 协议与 Google Workspace API 进行身份认证和授权。该系统支持两种认证模式：

• OAuth 2.1 (Streamable HTTP)：支持 MCP 传输协议优化的现代认证流程
• 传统 OAuth 2.0：向后兼容的传统认证模式

核心认证模块位于 auth/ 目录下，包含 OAuth 回调服务、凭证存储、作用域管理、会话中间件等组件。

graph TB
    subgraph "认证层"
        A[MCP Client] --> B[OAuth 回调服务]
        B --> C[凭证存储]
        C --> D[作用域解析器]
    end
    
    subgraph "权限层"
        D --> E[服务装饰器]
        E --> F[Google API 服务]
    end
    
    subgraph "会话层"
        G[MCP Session] --> H[会话中间件]
        H --> C
    end

OAuth 2.0 认证流程

标准授权码流程

sequenceDiagram
    participant MCP as MCP Client
    participant Server as OAuth Callback Server
    participant Google as Google OAuth
    participant Store as Credential Store
    
    MCP->>Server: 发起认证请求
    Server->>Google: 重定向到授权页面
    Google-->>User: 显示授权确认页面
    User->>Google: 授权同意
    Google->>Server: 回调并返回授权码
    Server->>Google: 交换授权码为令牌
    Google-->>Server: 返回 access_token & refresh_token
    Server->>Store: 存储凭证
    Store-->>Server: 凭证存储成功
    Server-->>MCP: 认证完成

关键组件

凭证存储机制

存储结构

凭证存储采用分层架构，按用户和会话隔离存储：

# 凭证存储路径结构
~/.config/google_workspace_mcp/
├── credentials/
│   ├── google-{state_hash}.json    # 按 OAuth state 隔离
│   └── {user_email}/
│       └── credentials.json         # 按用户隔离

存储格式

{
  "access_token": "ya29.xxx",
  "refresh_token": "1//xxx",
  "token_uri": "https://oauth2.googleapis.com/token",
  "client_id": "xxx.apps.googleusercontent.com",
  "client_secret": "xxx",
  "scopes": ["https://www.googleapis.com/auth/drive"],
  "expiry": "2024-01-15T10:30:00Z"
}

资料来源：auth/credential_store.py:1-50

作用域管理

作用域分组

系统使用作用域别名简化权限配置：

SCOPE_GROUPS = {
    "drive_read": ["https://www.googleapis.com/auth/drive.readonly"],
    "drive_full": ["https://www.googleapis.com/auth/drive"],
    "docs_read": ["https://www.googleapis.com/auth/documents.readonly"],
    "docs_full": ["https://www.googleapis.com/auth/documents"],
    # ...
}

作用域解析

_resolve_scopes() 函数负责将工具声明的作用域别名转换为实际 OAuth 作用域：

graph LR
    A[工具声明作用域] --> B[作用域别名]
    B --> C[SCOPE_GROUPS 查找]
    C --> D[展开为完整 URI]
    D --> E[合并去重]
    E --> F[请求令牌]

已知问题

Issue #809：部分工具声明的作用域别名未在 SCOPE_GROUPS 中注册，导致认证失败：

• delete_script_project 使用 drive_full 和 script_full 别名
• create_version 使用相同的别名
• _resolve_scopes 解析失败，返回空作用域列表

资料来源：auth/scopes.py:1-100

会话绑定机制

MCP Session 中间件

McpSessionMiddleware 负责将 MCP 会话 ID 与 OAuth 凭证关联：

class McpSessionMiddleware:
    def __init__(self, app, credential_store):
        self.credential_store = credential_store
        # 将 MCP session ID 映射到用户凭证

关键问题

Issue #810：OAuth 回调将凭证存储在 google-{state} 键下，而非 MCP session ID：

# 当前实现（存在问题）
credential_key = f"google-{state}"

# 期望实现
credential_key = mcp_session_id

这导致重新认证后的工具调用无法找到有效凭证，触发重复认证提示。

资料来源：auth/mcp_session_middleware.py:1-80

OAuth 回调端口管理

端口分配策略

系统按顺序尝试端口 8000-8004 进行 OAuth 回调：

# 端口范围
CALLBACK_PORTS = range(8000, 8005)  # 8000, 8001, 8002, 8003, 8004

端口解析器

PortResolver 负责查找可用端口并防止冲突：

graph TD
    A[请求端口] --> B{端口 8000 可用?}
    B -->|是| C[返回 8000]
    B -->|否| D{端口 8001 可用?}
    D -->|是| E[返回 8001]
    D -->|否| F{端口 8002 可用?}
    F -->|是| G[返回 8002]
    F -->|否| H[...]
    H -->|全部占用| I[抛出异常]

Windows 端口泄漏问题

Issue #816：Windows 环境下父进程异常终止时，Python 子进程可能继续存活并占用回调端口：

Issue #667：孤儿 Python 进程持有端口 8000，导致后续认证出现 "invalid state" 错误。

资料来源：auth/port_resolver.py:1-60

服务装饰器

`@require_google_service` 装饰器

此装饰器确保工具调用前已完成所需 OAuth 认证：

@require_google_service("drive", "drive_read")
@handle_http_errors("list_drive_files", is_read_only=True, service_type="drive")
async def list_drive_files(service, user_google_email: str, ...):
    # 服务已验证，凭证有效
    pass

装饰器参数

只读模式

启用只读模式时，系统使用受限作用域：

# auth/oauth_config.py
is_read_only_mode()  # 检查是否启用只读模式
get_all_read_only_scopes()  # 获取所有只读作用域

资料来源：auth/service_decorator.py:1-100

多账户支持

账户解析机制

系统支持存储和管理多个 Google 账户的凭证：

# 凭证存储支持多账户
def store_credentials(user_email: str, credentials: dict):
    """按用户邮箱存储独立凭证"""
    
def get_credentials(user_email: str) -> dict:
    """获取指定用户的凭证"""

客户端选择

用户通过 user_google_email 参数指定操作的目标账户：

async def list_drive_files(
    service,
    user_google_email: str,  # 指定目标用户
    folder_id: Optional[str] = None,
):

文档缺口

Issue #815：文档提到"多用户支持"但未详细说明工作流程和示例，实际使用方式不够清晰。

配置选项

环境变量

Helm Chart 配置

# helm-chart/values.yaml
secrets:
  googleOAuth:
    clientId: ""      # 必需
    clientSecret: ""  # 必需
    userEmail: ""     # 单用户模式

singleUserMode: false

env:
  MCP_ENABLE_OAUTH21: "true"

资料来源：helm-chart/workspace-mcp/README.md:1-50

OAuth 2.1 增强功能

v1.21.1 版本对 OAuth 登录体验进行了优化：

自动打开浏览器

认证流程可自动打开系统默认浏览器：

# 包含 login_hint 支持
auth_url = build_authorization_url(login_hint="[email protected]")

传统模式主机绑定

增强了在传统认证模式下的主机地址绑定稳定性。

故障排除

常见错误

端口耗尽处理

```bash # Windows taskkill /F /IM python.exe

1. 手动终止残留进程：

# Linux/macOS pkill -f workspace-mcp ```

1. 重启服务以释放端口

清除凭证

删除凭证文件以重新进行完整认证流程：

rm -rf ~/.config/google_workspace_mcp/credentials/

架构图总览

graph TB
    subgraph "客户端层"
        MCP[MCP Client / Claude Code]
    end
    
    subgraph "服务层"
        Server[MCP Server<br/>workspace-mcp]
        OAuthCallback[OAuth Callback<br/>Server :8000-8004]
    end
    
    subgraph "认证层"
        GoogleAuth[GoogleAuth]
        CredentialStore[CredentialStore]
        ScopeResolver[Scope Resolver]
        SessionMiddleware[Session Middleware]
    end
    
    subgraph "Google"
        GoogleOAuth[Google OAuth<br/>2.0 / 2.1]
        GoogleAPIs[Google Workspace<br/>APIs]
    end
    
    MCP <--> Server
    Server <--> OAuthCallback
    OAuthCallback <--> GoogleOAuth
    Server --> GoogleAuth
    Server --> CredentialStore
    Server --> ScopeResolver
    Server --> SessionMiddleware
    GoogleAuth --> GoogleAPIs

相关资源

• Apps Script OAuth 作用域文档
• Google OAuth 2.0 文档
• FastMCP OAuth 集成

更新日志

概述

Gmail 集成是 google_workspace_mcp 项目中用于与 Gmail API 交互的核心功能模块。该集成通过 MCP (Model Context Protocol) 协议提供工具化的 Gmail 访问能力，使 AI 代理能够执行邮件读取、发送、搜索和管理等操作。

核心功能范围

根据 core/tool_tiers.yaml 中的定义，Gmail 集成包含以下功能层级：

资料来源：core/tool_tiers.yaml:1-15

架构设计

模块依赖关系

graph TD
    A[MCP Client] --> B[gmail_tools.py]
    B --> C[gmail_helpers.py]
    C --> D[Gmail API]
    B --> E[attachment_storage.py]
    E --> F[Local File Storage]
    C --> G[core/utils.py]
    G --> H[XML/Content Parsing]

工具分层架构

Gmail 工具按照功能完整度分为三个层级：

graph LR
    subgraph Core[核心层 - Core]
        C1[get_gmail_message]
        C2[search_gmail]
        C3[send_email]
        C4[create_draft]
        C5[get_thread]
        C6[list_threads]
    end
    
    subgraph Extended[扩展层 - Extended]
        E1[batch_get_gmail_message]
        E2[manage_labels]
    end
    
    subgraph Complete[完整层 - Complete]
        F1[trash_message]
        F2[batch_delete_messages]
        F3[modify_message]
    end

核心工具详解

1. get_gmail_message

获取单封邮件的完整信息，包括发件人、收件人、主题、正文、附件等。

参数配置：

2. search_gmail

支持复杂的邮件搜索功能，使用 Gmail 搜索语法。

常用搜索操作符：

3. send_email

发送邮件功能，支持普通文本和富文本格式。

发送参数：

附件处理系统

attachment_storage 模块

core/attachment_storage.py 负责管理 Gmail 附件的本地存储和检索。

sequenceDiagram
    participant U as User
    participant M as MCP Server
    participant S as Attachment Storage
    participant F as File System
    participant G as Gmail API
    
    U->>M: 请求邮件附件
    M->>G: 获取附件信息
    G-->>M: 附件元数据
    M->>S: 存储附件
    S->>F: 写入文件
    F-->>S: 存储确认
    S-->>M: 返回文件路径
    M-->>U: 提供下载链接

Windows 文件名兼容性处理

v1.21.0 版本修复了 Windows 系统上的文件名兼容性问题：

问题背景：

• Windows 文件系统对文件名有严格限制
• 保留设备名称（CON、PRN、AUX、NUL 等）无法使用
• 特殊字符（:, *, ?, <, >, | 等）被禁止

处理逻辑（资料来源：core/attachment_storage.py）：

# 保留设备名称映射
WINDOWS_RESERVED_NAMES = [
    'CON', 'PRN', 'AUX', 'NUL',
    'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
    'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9'
]

# 特殊字符过滤
INVALID_CHARS = r'[<>:"|?*\x00-\x1f]'

修复后，Gmail 附件的文件名将自动进行：

1. 移除非法字符
2. 替换 Windows 保留名称
3. 显示实际保存的文件名（而非原始文件名）

OAuth 认证与作用域

Gmail 所需 OAuth 作用域

Gmail 集成需要以下 OAuth 作用域：

认证流程

graph LR
    A[启动 MCP Server] --> B{检查缓存凭证}
    B -->|无/过期| C[发起 OAuth 流程]
    B -->|有效| E[执行工具调用]
    C --> D[浏览器授权]
    D --> C
    C --> F[保存凭证]
    F --> E

日志与调试

日志格式化

Gmail 工具使用统一的日志格式，便于问题排查：

日志格式化器定义于 core/log_formatter.py，提供：

• 带颜色的终端输出
• 统一的日志前缀
• 结构化的错误信息

CLI 命令行工具

使用方法

# 列出可用工具
workspace-cli list

# 调用 Gmail 工具
workspace-cli call get_gmail_message [email protected] message_id=123abc

配置方式：

与其他模块的集成

Gmail 与 Drive 集成

Gmail 附件可以方便地与 Drive 模块协同工作：

graph LR
    A[Gmail 附件] --> B[attachment_storage]
    B --> C[Drive 文件系统]
    C --> D[create_drive_file]
    D --> E[Google Drive 存储]

Gmail 与 Comments 集成

邮件对话（Threads）可以配合评论系统进行协作管理。

已知限制与注意事项

API 配额限制

安全最佳实践

1. 凭证保护：确保 client_secret.json 文件安全存储
2. 最小权限：仅请求所需的 OAuth 作用域
3. 会话管理：使用 login_hint 参数优化多账户场景

社区反馈与改进

相关 Issue

版本更新历史

快速入门指南

首次配置步骤

1. 在 Google Cloud Console 创建项目
2. 启用 Gmail API
3. 配置 OAuth 同意屏幕
4. 下载客户端凭据 JSON 文件
5. 配置 MCP 服务器环境变量

基础使用示例

用户: "搜索张三发来的所有未读邮件"
AI: 调用 search_gmail with query="from:张三 is:unread"
AI: 返回搜索结果列表
AI: "找到 3 封未读邮件..."

用户: "给 [email protected] 发送测试邮件，主题是 MCP 测试"
AI: 调用 send_email 工具
AI: 返回发送结果

核心功能概述

Drive 集成的主要功能包括：

• 文件管理：创建、读取、更新、删除 Google Drive 文件和文件夹
• 格式转换：支持 Office 文件（DOCX、XLSX、PPTX）上传时自动转换为原生 Google 格式（Docs、Sheets、Slides）
• 快捷方式：创建指向其他文件的快捷方式，实现单一文件多位置显示
• 权限控制：管理文件访问权限和共享设置
• 搜索功能：全文搜索 Drive 文件内容
• 元数据操作：修改文件名、描述、封面等文件属性

资料来源：gdrive/drive_tools.py:1-50

工具分层架构

Drive 工具按照功能复杂度分为三个层级，采用分层加载机制控制可用工具集。

层级结构

资料来源：core/tool_tiers.yaml()

分层加载机制

工具分层通过 ToolTierLoader 类实现，支持按需加载特定层级的工具：

class ToolTierLoader:
    def __init__(self, config_path: Optional[str] = None):
        if config_path is None:
            config_path = Path(__file__).parent / "tool_tiers.yaml"
        self.config_path = Path(config_path)

配置通过 YAML 文件定义，支持按服务分组加载工具集合。启动时可指定 --tier 参数选择加载核心集、扩展集或完整集。

资料来源：core/tool_tier_loader.py:1-40

核心工具详解

create_drive_file

创建 Google Drive 文件，支持普通上传和格式转换上传。

主要参数：

格式转换逻辑：

当 convert 参数为 true 或指定 target_mime_type 时，系统会调用 Google Drive 的导入功能：

# Office 文件到 Google 格式的转换映射
CONVERSION_MAP = {
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": 
        "application/vnd.google-apps.document",
    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": 
        "application/vnd.google-apps.spreadsheet",
    "application/vnd.openxmlformats-officedocument.presentationml.presentation": 
        "application/vnd.google-apps.presentation",
}

这解决了社区提出的问题：用户希望上传 PPTX 文件后获得原生的可编辑 Google Slides 格式。

资料来源：gdrive/drive_tools.py:100-200

import_to_google_doc

专门用于将本地文档文件导入为 Google Docs 格式。

支持的源格式：

• DOCX（Microsoft Word）
• ODT（OpenDocument Text）
• RTF（Rich Text Format）
• HTML
• Markdown

特性：

• 保留文档格式和样式
• 支持图片导入
• 返回新创建的 Google Doc ID

资料来源：core/utils.py:50-100

list_drive_files

列出 Drive 文件和文件夹，支持分页和过滤。

高级选项：

• folder_id: 仅列出指定文件夹内容
• order_by: 排序方式（name, createdTime, modifiedTime, quotaBytesUsed）
• include_items_from_all_drives: 是否包含共享 Drive 内容
• supports_all_drives: 是否支持共享 Drive
• drive_id: 限定特定共享 Drive

返回字段：

@dataclass
class DriveFile:
    id: str
    name: str
    mime_type: str
    created_time: Optional[str] = None
    modified_time: Optional[str] = None
    size: Optional[str] = None
    drive_id: Optional[str] = None
    parents: Optional[List[str]] = None
    shared: bool = False

资料来源：gdrive/drive_helpers.py:50-150

create_drive_shortcut

创建 Drive 文件快捷方式，这是社区强烈要求的功能。由于 Google Drive 在 2020 年 9 月移除了多父级支持，文件只能有单一父文件夹，因此快捷方式成为实现"同一文件多位置显示"的标准方案。

参数：

使用场景：

• 将项目文件同时显示在"项目"和"归档"文件夹
• 创建指向团队共享文件夹的快捷方式
• 无需复制文件内容即可多位置访问

资料来源：社区 issue #819

权限与认证

OAuth 作用域

Drive 集成使用以下 OAuth 作用域：

已知问题

Issue #809：未注册的作用域别名导致认证失败

drive_full 和 script_full 作用域别名未在 SCOPE_GROUPS 中注册，导致 delete_script_project 和 create_version 工具在调用时出现永久性认证失败。

# 问题代码示意
def _resolve_scopes(self, scopes):
    # drive_full 和 script_full 未在 SCOPE_GROUPS 中定义
    # 导致解析失败

资料来源：auth/scopes.py:100-150

高级功能

文件内容提取

get_drive_file_as_text 工具支持从 Office 文件中提取文本内容：

# 支持的文件格式
TEXT_EXTRACTION_MIMES = [
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
]

提取逻辑：

1. 下载文件为 ZIP 压缩包
2. 解析内部 XML 结构
3. 从相应命名空间提取文本：

• Word: http://schemas.openxmlformats.org/wordprocessingml/2006/main
• Excel: 遍历工作表单元格
• PowerPoint: http://schemas.openxmlformats.org/drawingml/2006/main

资料来源：core/utils.py:200-300

批量操作

通过 MCP 协议的工具调用，Agent 可以编排复杂的批量操作序列：

graph TD
    A[开始] --> B[列出源文件夹文件]
    B --> C{文件类型判断}
    C -->|DOCX| D[调用 import_to_google_doc]
    C -->|PPTX| E[调用 create_drive_file + convert]
    C -->|XLSX| F[调用 create_drive_file + convert]
    D --> G[设置文件权限]
    E --> G
    F --> G
    G --> H[记录到索引表]
    H --> I[发送完成通知]

配置文件结构

Drive 工具的行为可通过配置文件进行定制：

# tool_tiers.yaml
drive:
  core:
    - create_drive_file
    - read_drive_file
    - update_drive_file
    - delete_drive_file
    - list_drive_files
  extended:
    - get_drive_file_info
    - share_drive_file
    - copy_drive_file
    - create_drive_folder
  complete:
    - search_drive_files
    - export_drive_file
    - import_to_google_doc
    - create_drive_shortcut
    - get_drive_file_permissions

资料来源：core/tool_tiers.yaml()

最佳实践

文件命名

• 避免使用 Windows 保留设备名称（CON、PRN、AUX、NUL 等）
• 移除特殊字符（:、*、?、<、>、|）
• v1.21.0 已修复 Windows 系统文件名兼容性问题

性能优化

• 使用 include_items_from_all_drives: false 以提升列表查询速度
• 避免在单个请求中处理超过 1000 个文件
• 使用 pageSize 参数控制分页大小

格式转换建议

限制与已知问题

快速开始

列出 Drive 文件

用户: "显示我的 Drive 根目录文件"
Agent 调用: list_drive_files(parent_id=None)

上传并转换文件

用户: "将 report.xlsx 转换为 Google Sheets"
Agent 调用: create_drive_file(
    name="report.xlsx",
    file_path="/path/to/report.xlsx",
    convert=True,
    target_mime_type="application/vnd.google-apps.spreadsheet"
)

创建文件快捷方式

用户: "在'归档'文件夹中创建'报告'文件的快捷方式"
Agent 调用: create_drive_shortcut(
    name="报告 - 归档副本",
    target_id="1abc123...",
    parent_id="archive_folder_id"
)

概述

Docs/Sheets/Slides 集成是 Google Workspace MCP (Model Context Protocol) 中用于与 Google 文档、电子表格和演示文稿进行交互的核心模块。该集成提供了完整的 CRUD 操作支持，包括创建、读取、更新、删除文档内容，以及管理文档评论和批量操作。

这三个应用共享相似的架构模式：

• 统一使用 Drive API 进行文件操作
• 通过专用 API（Docs API、Sheets API、Slides API）进行内容操作
• 支持评论管理（通过 Drive API 实现）
• 共享工具层级（core、extended、complete）配置

资料来源：core/tool_tiers.yaml:1-80

架构设计

模块组成

graph TD
    subgraph "Docs/Sheets/Slides 集成架构"
        A[用户请求] --> B[MCP Server]
        B --> C{工具层级解析}
        C -->|core| D[核心工具集]
        C -->|extended| E[扩展工具集]
        C -->|complete| F[完整工具集]
        
        D --> G[Docs API / Sheets API / Slides API]
        E --> G
        F --> G
        
        G --> H[Google Drive API]
        H --> I[Google Cloud]
        
        G --> J[批量操作管理器]
        J --> K[评论管理系统]
        K --> H
    end

工具层级结构

每个应用（Docs、Sheets、Slides）都采用三层工具层级设计：

资料来源：core/tool_tiers.yaml:1-80

工具层级详细配置

Docs 工具层级

docs:
  core:
    - get_doc_content      # 获取文档内容
    - create_doc          # 创建文档
    - modify_doc_text     # 修改文档文本
  extended:
    - export_doc_to_pdf    # 导出为PDF
    - search_docs          # 搜索文档
    - find_and_replace_doc # 查找替换
    - list_docs_in_folder  # 列出文件夹中的文档
    - insert_doc_elements  # 插入元素
    - update_paragraph_style # 更新段落样式
    - get_doc_as_markdown  # 获取Markdown格式
    - list_document_comments # 列出评论
    - manage_document_comment # 管理评论
  complete:
    - insert_doc_image     # 插入图片
    - update_doc_headers_footers # 更新页眉页脚
    - batch_update_doc     # 批量更新
    - inspect_doc_structure # 检查文档结构
    - create_table_with_data # 创建表格
    - debug_table_structure  # 调试表格结构
    - manage_doc_tab       # 管理文档标签

资料来源：core/tool_tiers.yaml:6-28

Sheets 工具层级

sheets:
  core:
    - create_spreadsheet  # 创建电子表格
    - read_sheet_values   # 读取表格值
    - modify_sheet_values # 修改表格值
  extended:
    - list_spreadsheets   # 列出电子表格
    - get_spreadsheet_info # 获取电子表格信息
    - format_sheet_range  # 格式化范围
    - list_sheet_tables   # 列出表格
  complete:
    - create_sheet        # 创建工作表
    - append_table_rows   # 追加行
    - resize_sheet_dimensions # 调整尺寸
    - move_sheet_rows     # 移动行
    - list_spreadsheet_comments # 列出评论
    - manage_spreadsheet_comment # 管理评论
    - manage_conditional_formatting # 条件格式

资料来源：core/tool_tiers.yaml:29-49

Slides 工具层级

slides:
  core:
    - create_presentation  # 创建演示文稿
    - get_presentation    # 获取演示文稿
  extended:
    - batch_update_presentation # 批量更新
    - get_page            # 获取页面
    - get_page_thumbnail  # 获取页面缩略图
  complete:
    - list_presentation_comments # 列出评论
    - manage_presentation_comment # 管理评论

资料来源：core/tool_tiers.yaml:50-62

工具层级加载器

ToolTierLoader 类

ToolTierLoader 类负责从 YAML 配置文件加载和管理工具层级：

class ToolTierLoader:
    """Loads and manages tool tiers from configuration."""
    
    def __init__(self, config_path: Optional[str] = None):
        if config_path is None:
            config_path = Path(__file__).parent / "tool_tiers.yaml"
        self.config_path = Path(config_path)
        self._tiers_config: Optional[Dict] = None

资料来源：core/tool_tier_loader.py:19-33

配置加载流程

sequenceDiagram
    participant U as 用户
    participant T as ToolTierLoader
    participant F as 文件系统
    participant Y as YAML解析器
    participant S as MCP Server

    U->>T: 初始化 ToolTierLoader
    T->>F: 读取 tool_tiers.yaml
    F-->>T: YAML内容
    T->>Y: yaml.safe_load()
    Y-->>T: 解析后的配置字典
    T->>S: 注册工具层级
    S-->>U: 工具就绪

评论管理系统

统一评论架构

Docs、Sheets、Slides 的评论功能通过统一的 core/comments.py 模块实现，所有评论操作都通过 Drive API 进行：

def create_comment_tools(app_name: str, file_id_param: str):
    """
    Factory function to create comment management tools for a specific Google Workspace app.
    """
    list_func_name = f"list_{app_name}_comments"
    manage_func_name = f"manage_{app_name}_comment"

资料来源：core/comments.py:42-56

支持的操作

资料来源：core/comments.py:30-43

评论注解

评论工具使用 MCP ToolAnnotations 来标记工具特性：

READ_COMMENT_ANNOTATIONS = ToolAnnotations(
    readOnlyHint=True,
    destructiveHint=False,
    idempotentHint=True,
    openWorldHint=True,
)

MANAGE_COMMENT_ANNOTATIONS = ToolAnnotations(
    readOnlyHint=False,
    destructiveHint=False,
    idempotentHint=False,
    openWorldHint=True,
)

资料来源：core/comments.py:25-38

批量操作管理器

BatchOperationManager

批量操作管理器（BatchOperationManager）提供了对 Docs 进行批量修改的能力，包括：

• 批量替换文本
• 批量插入元素
• 批量更新样式

资料来源：gappsscript/README.md:80-100

典型工作流程

graph LR
    A[读取文档结构] --> B[分析内容]
    B --> C[生成修改方案]
    C --> D[执行批量操作]
    D --> E{成功?}
    E -->|是| F[返回结果]
    E -->|否| G[错误处理]
    G --> H[重试或回滚]

Office 文件文本提取

支持的格式

系统支持从以下 Office 格式中提取文本内容：

资料来源：core/utils.py:80-120

文本提取逻辑

# 对于 PowerPoint: 提取 <a:t> 标签中的文本
# 对于 Word: 提取 <w:t> 标签中的文本
# 对于 Excel: 遍历每个工作表(member)
if elem.tag.endswith("}t") and elem.text:
    cleaned_text = elem.text.strip()
    if cleaned_text:
        member_texts.append(cleaned_text)

资料来源：core/utils.py:95-110

文本合并规则

从不同成员（工作表/幻灯片）提取的内容使用双换行符分隔：

text = "\n\n".join(pieces).strip()

资料来源：core/utils.py:113-115

与 Apps Script 的集成

跨应用自动化

Apps Script 模块能够与 Docs、Sheets、Slides 进行深度集成，实现跨应用的工作流自动化：

资料来源：gappsscript/README.md:20-35

自动化示例

用户: "创建一个每周一早上9点运行的脚本"
需求:
1. 从 '销售' 电子表格读取数据
2. 计算周报数据
3. 生成总结文档
4. 邮件发送给团队

资料来源：gappsscript/README.md:50-70

社区相关问题

已知问题

功能建议

社区用户希望实现：

• PPTX 文件上传时自动转换为原生 Google Slides 格式
• XLSX 文件上传时自动转换为原生 Google Sheets 格式
• 类似于 import_to_google_doc 的转换功能

资料来源：github.com/taylorwilsdon/google_workspace_mcp/issues/568 资料来源：github.com/taylorwilsdon/google_workspace_mcp/issues/820

配置与部署

工具层级过滤

在部署时可以通过配置启用特定的工具层级：

# 核心层级 - 仅基础功能
# extended 层级 - 包含格式化、搜索等
# complete 层级 - 包含所有功能

环境变量配置

资料来源：helm-chart/workspace-mcp/README.md:30-45

使用限制与注意事项

API 配额限制

常见错误处理

@handle_http_errors(list_func_name, is_read_only=True, service_type="drive")
async def list_comments(service, user_google_email: str, document_id: str):
    # 错误处理装饰器确保 HTTP 错误被正确捕获和处理

资料来源：core/comments.py:58-62

日志系统

服务前缀映射

资料来源：core/log_formatter.py:40-55

日志格式化

增强型日志格式化器提供：

• ANSI 颜色支持（终端兼容）
• 层级前缀标识
• 工具层级加载信息优化显示

总结

Docs/Sheets/Slides 集成构成了 Google Workspace MCP 的文档处理核心，提供了：

1. 统一架构：三层工具层级设计（core/extended/complete）支持渐进式功能暴露
2. 评论管理：统一的评论系统通过 Drive API 实现跨应用评论功能
3. 批量操作：BatchOperationManager 支持复杂文档修改
4. 文件转换：Office 文件文本提取支持多格式解析
5. Apps Script 集成：支持跨应用自动化工作流

该集成设计遵循了 Google Workspace API 的最佳实践，通过 MCP 协议为 AI 代理提供了一套完整的文档操作能力。

概述

Google Workspace MCP (Model Context Protocol) 不仅提供核心的文档、电子表格和邮箱功能，还包含一系列重要的协作与效率工具。这些服务包括日历管理（Calendar）、联系人管理（Contacts）、即时通讯（Chat）、任务管理（Tasks）、表单收集（Forms）、自定义搜索（Search）以及 Apps Script 自动化脚本。本页面将详细说明这些服务的功能、工具层级和使用方法。

服务架构概览

Google Workspace MCP 的工具按照功能层级进行组织，分为 core（核心）、extended（扩展）和 complete（完整）三个层级：

graph TD
    A[Google Workspace MCP] --> B[核心服务]
    A --> C[协作服务]
    A --> D[自动化服务]
    
    B --> B1[Docs 文档]
    B --> B2[Sheets 表格]
    B --> B3[Gmail 邮箱]
    B --> B4[Drive 云盘]
    
    C --> C1[Calendar 日历]
    C --> C2[Contacts 联系人]
    C --> C3[Chat 即时通讯]
    C --> C4[Tasks 任务]
    C --> C5[Forms 表单]
    
    D --> D1[Search 搜索]
    D --> D2[Apps Script]
    
    style C1 fill:#f9f,stroke:#333,stroke-width:2px
    style C2 fill:#f9f,stroke:#333,stroke-width:2px
    style C3 fill:#f9f,stroke:#333,stroke-width:2px
    style C4 fill:#f9f,stroke:#333,stroke-width:2px
    style C5 fill:#f9f,stroke:#333,stroke-width:2px
    style D1 fill:#ff9,stroke:#333,stroke-width:2px
    style D2 fill:#ff9,stroke:#333,stroke-width:2px

工具层级配置

根据 tool_tiers.yaml 中的配置，各服务的工具层级分布如下：

资料来源：core/tool_tiers.yaml:1-75

Calendar 日历服务

功能概述

Calendar 日历服务是 Google Workspace 协作功能的核心组件之一，允许 AI 代理创建、读取、更新和删除日历事件。该服务支持个人日历和团队日历管理，包括会议安排、提醒设置和事件权限控制。

核心工具列表

典型使用场景

graph LR
    A[用户请求] --> B{事件是否存在?}
    B -->|不存在| C[create_calendar_event]
    B -->|存在| D{需要更新?}
    D -->|是| E[update_calendar_event]
    D -->|否| F[get_calendar_event]
    C --> G[返回事件详情]
    E --> G
    F --> G

场景示例：安排团队会议

用户："明天下午3点安排一个与产品团队的会议，讨论Q4路线图"
AI代理：
1. 调用 list_calendar_events 检查团队成员可用性
2. 调用 create_calendar_event 创建会议邀请
3. 返回会议详情和日历链接

Contacts 联系人服务

功能概述

Contacts 联系人服务提供 Google Workspace 联系人目录的访问能力，支持搜索、查看和管理个人联系人及组织联系人。该服务对于需要与用户交互的 AI 代理尤为重要，例如发送邮件或消息时需要验证收件人信息。

核心工具列表

联系人数据结构

# 联系人数据模型字段
Contact {
    resource_name: str,        # 联系人资源名称
    display_name: str,        # 显示名称
    email_addresses: List[EmailAddress],  # 邮箱地址
    phone_numbers: List[PhoneNumber],      # 电话号码
    organizations: List[Organization],    # 组织信息
    relations: List[Relation],             # 关系人
    bio: str,               # 个人简介
    photos: List[Photo],    # 照片
}

资料来源：gcontacts/contacts_tools.py

Chat 即时通讯服务

功能概述

Google Chat 是 Google Workspace 的企业级即时通讯工具，Chat 服务允许 AI 代理在 Spaces（聊天室）中发送消息、获取历史记录和附件。对于团队协作场景，AI 代理可以直接在 Chat 中与用户和群组进行交互。

核心工具列表

Chat 工作流程

sequenceDiagram
    participant User as 用户
    participant AI as AI代理
    participant Chat as Google Chat API
    
    User->>AI: 请求发送消息
    AI->>AI: 验证 Space ID 和权限
    AI->>Chat: POST /v1/spaces/{spaceId}/messages
    Chat-->>AI: 消息发送成功
    AI-->>User: 返回消息详情

多账户支持说明

社区 Issue #815 指出，文档中提及"多用户支持"但未详细说明工作原理。在 Chat 服务中，多账户场景下不同客户端会如何解析账户绑定是一个需要关注的配置问题。当 AI 代理需要向特定用户的 Space 发送消息时，应明确指定用户身份或使用 user_google_email 参数进行身份验证。

Tasks 任务管理服务

功能概述

Google Tasks 是 Google Workspace 的轻量级任务管理工具。Tasks 服务允许 AI 代理创建待办事项、列出任务列表、管理任务完成状态。这对于将 AI 工作流与用户个人任务管理集成非常有用。

核心工具列表

社区需求

根据社区讨论（Issue #69），Google Tasks 是用户呼声较高的功能需求。尽管当前实现已覆盖基本功能，但社区成员期望 AI 能够：

• 创建任务和待办事项
• 列出需要处理的工作
• 标记任务完成

Forms 表单服务

功能概述

Google Forms 是 Google Workspace 的表单收集工具，Forms 服务允许 AI 代理创建表单、收集响应和查看分析数据。这对于调查、反馈收集和预约管理等场景非常实用。

核心工具列表

表单创建流程

graph TD
    A[定义表单问题] --> B[create_form 创建表单]
    B --> C[获取表单ID]
    C --> D[batch_update_form 添加问题]
    D --> E[set_publish_settings 配置发布]
    E --> F[表单可分享使用]

Search 自定义搜索服务

功能概述

Search 服务集成了 Google Custom Search API，允许 AI 代理执行网络搜索并返回结构化结果。这对于需要获取外部信息的 AI 工作流非常有用。

核心工具列表

使用限制

自定义搜索需要配置 Google Custom Search Engine (CSE)，包括：

• API 密钥（用于 Google Search API 访问）
• 搜索引擎 ID（Search Engine ID）

Apps Script 自动化服务

功能概述

Apps Script 是 Google Workspace 的自动化引擎，Apps Script 服务提供了完整的脚本项目管理能力。通过 MCP 工具，AI 代理可以创建、编辑、执行和部署 Apps Script 项目，实现复杂的跨应用工作流自动化。

资料来源：gappsscript/README.md

核心工具列表

Apps Script 能力矩阵

graph TD
    subgraph 项目管理
        A1[创建项目] --> A2[编辑代码]
        A2 --> A3[版本控制]
        A3 --> A4[删除项目]
    end
    
    subgraph 执行与部署
        B1[执行函数] --> B2[查看执行日志]
        B2 --> B3[创建部署]
        B3 --> B4[版本回滚]
    end
    
    subgraph 触发器
        C1[时间触发] --> C2[事件触发]
        C2 --> C3[生成触发代码]
    end
    
    A3 --> B3
    C3 --> A2

已知问题

根据社区 Issue #809，delete_script_project 和 create_version 工具声明的 scope 别名（drive_full、script_full）未在 SCOPE_GROUPS 中注册。这会导致 _resolve_scopes 失败，引发永久性认证失败。遇到此问题时，用户可能需要手动调整 OAuth 作用域配置。

API 启用管理

当用户尝试使用某个服务但未启用相应 API 时，系统会生成包含启用链接的错误消息。以下是各服务对应的 API 和启用链接：

资料来源：core/api_enablement.py:1-50

日志记录与调试

这些服务共享统一的日志格式化系统，便于调试和监控：

# 日志前缀映射
LOG_PREFIXES = {
    "gcalendar.calendar_tools": "[CALENDAR]",
    "gcontacts.contacts_tools": "[CONTACTS]",
    "gchat.chat_tools": "[CHAT]",
    "gtasks.tasks_tools": "[TASKS]",
    "gforms.forms_tools": "[FORMS]",
    "gsearch.search_tools": "[SEARCH]",
    "gappsscript.apps_script_tools": "[APPSCRIPT]",
}

资料来源：core/log_formatter.py:40-55

服务依赖关系

graph LR
    Calendar -->|日历事件| Drive
    Forms -->|响应存储| Drive
    AppsScript -->|访问| Docs
    AppsScript -->|访问| Sheets
    AppsScript -->|访问| Gmail
    Chat -->|附件| Drive
    
    style Drive fill:#9f9,stroke:#333,stroke-width:2px

常见问题与故障排除

1. API 未启用错误

症状：调用工具时返回 "API has not been used in project" 错误

解决方案：

1. 访问错误消息中的启用链接
2. 选择正确的 Google Cloud 项目
3. 点击启用按钮
4. 等待 1-2 分钟让更改生效
5. 重新尝试调用工具

2. 权限不足

症状：返回 "Insufficient Permission" 错误

解决方案：

1. 验证 OAuth scopes 已正确授权
2. 检查 SCOPE_GROUPS 配置是否包含所需作用域
3. 如有必要，重新进行身份验证

3. Apps Script 函数未找到

症状：run_script_function 返回 "Function not found"

排查步骤：

1. 检查函数名称拼写
2. 确认函数存在于脚本中
3. 确保函数不是 private（私有）函数
4. 验证函数签名符合 Apps Script API 要求

4. OAuth 重授权循环

根据社区反馈（Issue #810），在 streamable-HTTP 传输模式下，OAuth 回调可能将凭证存储在 google-<state> 会话中，导致每次工具调用后都需要重新授权。这与 MCP 会话的绑定机制有关。

总结

Calendar/Contacts/Chat 及其他服务构成了 Google Workspace MCP 的协作和自动化能力基础。这些服务使 AI 代理能够：

通过这些服务的组合使用，AI 代理可以为用户提供完整的 Google Workspace 协作体验，实现从个人效率工具到企业级自动化解决方案的各种用例。

概述

Google Workspace MCP 支持多种部署方式，包括本地开发、Docker容器化部署和Kubernetes集群部署。本指南涵盖从开发环境到生产环境的完整部署流程，帮助用户根据实际需求选择合适的部署方案。

Workspace MCP 的核心功能通过 FastMCP 框架实现，支持OAuth 2.0/2.1认证、工具分层加载、多账户管理等企业级特性。部署时需要关注认证凭证配置、网络可达性、资源限制和安全性配置等关键要素。

部署架构

系统组件架构

graph TD
    A[用户/MCP客户端] --> B[Workspace MCP 服务]
    B --> C[Google OAuth 2.0 Provider]
    C --> D[Google Workspace APIs]
    
    E[(OAuth 凭证存储)] -.-> B
    F[Kubernetes/Docker 运行时] --> B
    
    subgraph 部署模式
        G[本地开发模式]
        H[Docker 单节点部署]
        I[Kubernetes 集群部署]
    end

认证流程架构

sequenceDiagram
    participant User as 用户
    participant MCP as Workspace MCP
    participant OAuth as Google OAuth
    participant API as Google APIs
    
    User->>MCP: 请求工具调用
    MCP->>OAuth: 发起OAuth认证
    OAuth->>User: 浏览器登录
    User->>OAuth: 完成认证
    OAuth->>MCP: 返回凭证
    MCP->>API: 授权请求
    API-->>MCP: 返回数据
    MCP-->>User: 返回结果

环境要求

硬件与系统要求

软件依赖

• Python 3.10+
• Docker 20.10+ (容器部署)
• Kubernetes 1.24+ (集群部署)
• Helm 3.8+ (Kubernetes包管理)

Docker 部署

Dockerfile 配置

Workspace MCP 提供优化的 Docker 镜像，采用多阶段构建以减小镜像体积：

# 使用多阶段构建
FROM python:3.10-slim as builder

# 安装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 生产镜像
FROM python:3.10-slim
COPY --from=builder /usr/local/lib/python3.10/site-packages /usr/local/lib/python3.10/site-packages
COPY . /app
WORKDIR /app
USER non-root-user

CMD ["python", "main.py"]

Docker Compose 配置

基础部署配置：

version: '3.8'

services:
  workspace-mcp:
    build: .
    container_name: workspace-mcp
    environment:
      - GOOGLE_OAUTH_CLIENT_ID=${GOOGLE_OAUTH_CLIENT_ID}
      - GOOGLE_OAUTH_CLIENT_SECRET=${GOOGLE_OAUTH_CLIENT_SECRET}
      - MCP_ENABLE_OAUTH21=true
    ports:
      - "8000:8000"
    volumes:
      - ./credentials:/app/credentials
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

启动命令

# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

Kubernetes 部署

Helm Chart 架构

graph LR
    A[Helm] --> B[workspace-mcp Chart]
    B --> C[Deployment]
    B --> D[Service]
    B --> E[ConfigMap]
    B --> F[Secret]
    B --> G[Ingress]
    B --> H[HPA]

安装步骤

#### 1. 添加 Helm 仓库

# 如果已克隆仓库
cd helm-chart/workspace-mcp

# 或从远程安装（如适用）
helm repo add workspace-mcp https://taylorwilsdon.github.io/google_workspace_mcp

#### 2. 配置 OAuth 凭证

创建 Kubernetes Secret 存储敏感信息：

kubectl create secret generic workspace-mcp-secrets \
  --from-literal=GOOGLE_OAUTH_CLIENT_ID="your-client-id" \
  --from-literal=GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret" \
  --from-literal=GOOGLE_OAUTH_USER_EMAIL="[email protected]"

#### 3. 安装 Chart

# 使用本地 Chart
helm install workspace-mcp ./helm-chart/workspace-mcp \
  --set secrets.googleOAuth.clientId="your-client-id" \
  --set secrets.googleOAuth.clientSecret="your-client-secret" \
  --set secrets.googleOAuth.userEmail="[email protected]"

# 使用自定义配置
helm install workspace-mcp ./helm-chart/workspace-mcp \
  --values ./custom-values.yaml

配置参数

Helm Chart 配置选项

工具层级配置

通过 tools.enabled 参数可以限制启用的工具，支持按服务分组：

tools:
  enabled:
    # 核心文档工具
    - gdocs
    # 核心表格工具
    - gsheets
    # Gmail 工具
    - gmail
    # 日历工具
    - gcalendar

可用服务分组：

Google OAuth 配置

创建 OAuth 凭证

1. 访问 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用所需的 Google Workspace API：

• Google Drive API
• Google Docs API
• Google Sheets API
• Gmail API
• Calendar API
• Apps Script API

1. 配置 OAuth 同意屏幕：

• 选择用户类型（内部/外部）
• 填写应用信息
• 配置授权域名

1. 创建 OAuth 2.0 客户端凭证：

• 应用类型：Web 应用
• 配置授权重定向 URI

OAuth 回调配置

OAuth 2.1 支持

v1.21.1 版本引入了 OAuth 2.1 支持，通过 MCP_ENABLE_OAUTH21=true 环境变量启用。新版本包含以下改进：

• 自动打开浏览器进行 OAuth 认证
• 支持 login_hint 参数预填充用户邮箱
• 改进的主机绑定安全性

安全配置

容器安全设置

Workspace MCP 镜像采用安全强化配置：

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  readOnlyRootFilesystem: true
  capabilities:
    drop:
      - ALL

网络策略

建议配置 Kubernetes NetworkPolicy 限制网络访问：

networkPolicy:
  enabled: true
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: mcp-client
  egress:
    - to:
        - podSelector:
            matchLabels:
              app: workspace-mcp

凭证管理

健康检查

Helm Chart 包含内置健康检查配置：

healthCheck:
  liveness:
    enabled: true
    path: /health
    initialDelaySeconds: 30
    periodSeconds: 10
  readiness:
    enabled: true
    path: /health
    initialDelaySeconds: 5
    periodSeconds: 5

健康检查端点：

• Liveness Probe: 验证应用进程存活
• Readiness Probe: 验证服务是否可接收流量

高可用配置

水平 Pod 自动扩缩容

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80

多副本部署

replicaCount: 3

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchExpressions:
              - key: app
                operator: In
                values:
                  - workspace-mcp
          topologyKey: kubernetes.io/hostname

故障排除

常见部署问题

#### 1. OAuth 认证失败

问题症状：部署后首次访问出现认证错误

排查步骤：

# 检查日志
kubectl logs -f deployment/workspace-mcp

# 验证 Secret 配置
kubectl get secret workspace-mcp-secrets -o yaml

# 检查 OAuth 回调 URI 配置是否匹配

解决方案：

• 确认 Google Cloud Console 中的回调 URI 与实际部署地址匹配
• 验证 GOOGLE_OAUTH_CLIENT_ID 和 GOOGLE_OAUTH_CLIENT_SECRET 正确配置

#### 2. 端口冲突

问题症状：Port 8000 already in use 错误

背景：在 Windows 系统上，如果父进程异常终止，Python 子进程可能残留并占用端口。资料来源：issue #816

排查步骤：

# Linux/Mac
lsof -i :8000
kill -9 <PID>

# Windows
netstat -ano | findstr :8000
taskkill /PID <PID> /F

#### 3. 孤儿进程导致认证失败

问题症状：每次认证尝试都返回 "invalid state" 错误

原因：之前的 workspace-mcp 进程未正确终止，仍持有 OAuth 回调端口

解决方案：

# 终止所有相关进程
pkill -f "python.*main.py"
# 或在 Windows 上
taskkill /IM python.exe /F

验证部署

# 检查 Pod 状态
kubectl get pods -l app=workspace-mcp

# 检查服务状态
kubectl get svc workspace-mcp

# 测试健康端点
kubectl port-forward svc/workspace-mcp 8000:8000
curl http://localhost:8000/health

升级指南

Helm 升级

# 拉取最新 Chart
helm repo update

# 升级部署
helm upgrade workspace-mcp ./helm-chart/workspace-mcp \
  --set secrets.googleOAuth.clientId="your-client-id" \
  --set secrets.googleOAuth.clientSecret="your-client-secret"

版本兼容性

监控与日志

日志配置

Workspace MCP 使用增强日志格式化器：

env:
  LOG_LEVEL: INFO
  LOG_FORMAT: enhanced

日志前缀映射：

资源监控

resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: 500m
    memory: 512Mi

相关资源

• 官方文档
• GitHub 仓库
• 问题反馈
• 版本发布

概述

Google Workspace MCP 提供两套访问接口：一是通过 MCP 协议与 AI 代理交互，二是通过命令行界面（CLI）直接调用工具。工具层级系统（Tool Tiers）则允许用户根据需要选择性加载不同功能集的工具，从最小化的核心工具到完整功能集的分层架构。

CLI 工具位于 core/cli.py 模块，提供持久化 OAuth 令牌缓存的独立命令行接口。工具层级系统由 core/tool_tiers.yaml 配置文件定义，通过 core/tool_tier_loader.py 模块加载解析，实现条件化工具注册机制。

工具层级架构

三层设计

工具系统按照功能完整性和使用频率划分为三个层级：

这种分层设计使用户能够根据部署场景和安全策略选择合适的工具集。例如，在只读场景下可仅启用核心工具，减少权限暴露。

服务与工具映射

工具按服务类型分组，每个服务在不同层级包含不同数量的工具：

docs:
  core:
    - get_doc_content
    - create_doc
    - modify_doc_text
  extended:
    - export_doc_to_pdf
    - search_docs
    - find_and_replace_doc
  complete:
    - insert_doc_image
    - batch_update_doc

sheets:
  core:
    - create_spreadsheet
    - read_sheet_values
    - modify_sheet_values
  extended:
    - list_spreadsheets
    - get_spreadsheet_info
  complete:
    - create_sheet
    - append_table_rows

资料来源：core/tool_tiers.yaml:1-30

层级加载机制

ToolTierLoader 类

ToolTierLoader 类负责从 YAML 配置文件加载层级定义：

class ToolTierLoader:
    def __init__(self, config_path: Optional[str] = None):
        if config_path is None:
            config_path = Path(__file__).parent / "tool_tiers.yaml"
        self.config_path = Path(config_path)

资料来源：core/tool_tier_loader.py:25-32

层级解析流程

graph TD
    A[加载 tool_tiers.yaml] --> B[resolve_tools_from_tier tier services]
    B --> C{指定服务过滤?}
    C -->|是| D[筛选指定服务的工具]
    C -->|否| E[获取所有服务工具]
    D --> F[返回工具名称列表]
    E --> F
    F --> G[映射到服务名称]
    G --> H[日志记录加载结果]

resolve_tools_from_tier 函数根据指定层级和服务返回对应的工具列表和服务名称：

def resolve_tools_from_tier(
    tier: TierLevel, services: Optional[List[str]] = None
) -> tuple[List[str], List[str]]:
    loader = ToolTierLoader()
    tools = loader.get_tools_up_to_tier(tier, services)
    service_names = loader.get_services_for_tools(tools)
    return tools, sorted(service_names)

资料来源：core/tool_tier_loader.py:104-117

条件化工具注册

ToolRegistry 模块

core/tool_registry.py 实现了条件化工具注册机制，允许基于已启用工具集合动态注册工具：

def conditional_tool(server, tool_name: str):
    def decorator(func: Callable) -> Callable:
        if is_tool_enabled(tool_name):
            logger.debug(f"Registering tool: {tool_name}")
            return server.tool()(func)
        else:
            logger.debug(f"Tool disabled: {tool_name}")
            return func  # No-op decorator

资料来源：core/tool_registry.py:43-53

启用工具管理

工具注册状态通过全局变量管理：

_enabled_tools: Optional[Set[str]] = None

def set_enabled_tools(tool_names: Optional[Set[str]]):
    global _enabled_tools
    _enabled_tools = tool_names

def is_tool_enabled(tool_name: str) -> bool:
    if _enabled_tools is None:
        return True  # 所有工具默认启用
    return tool_name in _enabled_tools

资料来源：core/tool_registry.py:10-25

CLI 命令行工具

基本用法

workspace-cli 是 MCP 服务器的命令行客户端，位于 core/cli.py：

# 列出可用工具
workspace-cli list

# 调用指定工具
workspace-cli call <tool_name> [args...]

资料来源：core/cli.py:48-60

环境配置

CLI 支持通过环境变量或参数指定 MCP 服务器地址：

parser.add_argument(
    "--url",
    default=os.getenv("WORKSPACE_MCP_URL", DEFAULT_URL),
    help=f"MCP server URL (default: {DEFAULT_URL})",
)

资料来源：core/cli.py:32-35

工具调用格式

# 格式：tool_name key=value key2=value2
workspace-cli call create_doc title="我的文档" content="# Hello"

# 列出所有可用工具
workspace-cli list

服务与层级对应关系

完整服务映射表

资料来源：core/tool_tiers.yaml

Apps Script 工具层级详解

Apps Script 提供最丰富的工具集，支持脚本项目的完整生命周期管理：

Core 层级（7个工具）

• list_script_projects - 列出所有项目
• get_script_project - 获取项目详情
• get_script_content - 获取文件内容
• create_script_project - 创建新项目
• update_script_content - 更新文件
• run_script_function - 执行函数
• generate_trigger_code - 生成触发器代码

Extended 层级（10个工具）

• create_deployment - 创建部署
• list_deployments - 列出部署
• update_deployment - 更新部署
• delete_deployment - 删除部署
• delete_script_project - 删除项目
• list_versions - 列出版本
• create_version - 创建版本快照

Complete 层级（17个工具）

包含执行历史监控、指标分析等高级功能。

资料来源：gappsscript/README.md

配置与集成

Helm Chart 配置

在 Kubernetes 部署中，可通过 values.yaml 控制工具启用：

tools:
  enabled: []  # 空数组表示启用全部工具

# 启用指定工具
tools:
  enabled:
    - list_script_projects
    - get_script_project

资料来源：helm-chart/workspace-mcp/README.md

OAuth 与权限模式

工具层级系统与权限模式集成，支持只读模式限制：

from auth.scopes import is_read_only_mode, get_all_read_only_scopes

def conditional_tool(server, tool_name: str):
    # 检查工具是否在只读允许范围内

资料来源：core/tool_registry.py:1-10

常见问题

工具未注册

如果某工具不可用，检查：

1. 层级配置是否包含该工具
2. 服务模块是否正确导入
3. 权限范围是否满足

Windows 平台注意

在 Windows 上，OAuth 回调端口（8000-8004）可能因进程未正常退出而被占用。如遇连接问题，参考 v1.21.0 版本的 Windows 文件名兼容性修复。

已知问题：未注册的作用域别名

Apps Script 模块中的 delete_script_project 和 create_version 工具声明了未在 SCOPE_GROUPS 中注册的作用域别名（drive_full, script_full），可能导致权限解析失败。详见 GitHub Issue #809。

最佳实践

生产环境部署

1. 最小权限原则：根据实际需求选择合适的工具层级，避免启用完整工具集
2. 层级渐进式启用：先启用 core 层级，测试通过后再扩展
3. 日志监控：利用增强日志格式化（core/log_formatter.py）追踪工具调用

开发调试

1. 使用 workspace-cli list 查看当前启用的工具
2. 通过 CLI 直接调用工具进行快速测试
3. 查看工具注册日志确认加载状态

Pitfall Log / 踩坑日志

项目：taylorwilsdon/google_workspace_mcp

摘要：发现 31 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature Request] Add import_to_google_slides tool for PPTX conversion。

1. 安装坑 · 来源证据：[Feature Request] Add import_to_google_slides tool for PPTX conversion

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Add import_to_google_slides tool for PPTX conversion
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f871a29d45124aa7b0a5ddf0927e595a | https://github.com/taylorwilsdon/google_workspace_mcp/issues/568 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安全/权限坑 · 失败模式：security_permissions: Add content replacement support to `update_drive_file` (re-import with format conversion)

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Add content replacement support to update_drive_file (re-import with format conversion)
• 对用户的影响：Developers may expose sensitive permissions or credentials: Add content replacement support to update_drive_file (re-import with format conversion)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Add content replacement support to update_drive_file (re-import with format conversion). Context: Observed during version upgrade or migration.
• 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/taylorwilsdon/google_workspace_mcp/issues/604
• 证据：failure_mode_cluster:github_issue | fmev_3c8303e858d6e3babf62908a594c01d5 | https://github.com/taylorwilsdon/google_workspace_mcp/issues/604 | Add content replacement support to update_drive_file (re-import with format conversion)

3. 安全/权限坑 · 来源证据：Add content replacement support to `update_drive_file` (re-import with format conversion)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add content replacement support to update_drive_file (re-import with format conversion)
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_80d9501239cf445d97725797177e9bee | https://github.com/taylorwilsdon/google_workspace_mcp/issues/604 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安全/权限坑 · 来源证据：Windows: workspace-mcp Python child survives ungraceful parent termination, leaks OAuth callback port (8000-8004 exhaus…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows: workspace-mcp Python child survives ungraceful parent termination, leaks OAuth callback port (8000-8004 exhausted after 5 crashes)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_36a1aade8bf74121947b6fbe430ec6a1 | https://github.com/taylorwilsdon/google_workspace_mcp/issues/816 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 google_workspace_mcp 与安装入口 workspace-mcp 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：uvx workspace-mcp
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | github_repo:973788136 | https://github.com/taylorwilsdon/google_workspace_mcp | repo=google_workspace_mcp; install=workspace-mcp

6. 安装坑 · 失败模式：installation: Unregistered scope aliases `drive_full` and `script_full` cause permanent auth-failure on `de...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Unregistered scope aliases drive_full and script_full cause permanent auth-failure on delete_script_project and create_version
• 对用户的影响：Developers may fail before the first successful local run: Unregistered scope aliases drive_full and script_full cause permanent auth-failure on delete_script_project and create_version
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Unregistered scope aliases drive_full and script_full cause permanent auth-failure on delete_script_project and create_version. Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_e7cb2e2b3e59870680f53a03ba2ecf81 | https://github.com/taylorwilsdon/google_workspace_mcp/issues/809 | Unregistered scope aliases drive_full and script_full cause permanent auth-failure on delete_script_project and create_version

7. 安装坑 · 失败模式：installation: v1.17.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.17.1
• 对用户的影响：Upgrade or migration may change expected behavior: v1.17.1
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.17.1. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_212825a3c03db512b74b1674278bd9c0 | https://github.com/taylorwilsdon/google_workspace_mcp/releases/tag/v1.17.1 | v1.17.1

8. 配置坑 · 失败模式：configuration: Re-auth loop: OAuth callback stores credentials under `google-<state>` session, never bound t...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Re-auth loop: OAuth callback stores credentials under google-<state> session, never bound to the live MCP session — every tool call after re-auth re-prompts
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Re-auth loop: OAuth callback stores credentials under google-<state> session, never bound to the live MCP session — every tool call after re-auth re-prompts
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Re-auth loop: OAuth callback stores credentials under google-<state> session, never bound to the live MCP session — every tool call after re-auth re-prompts. Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_6c9d034c0e1c92375af2d9eaa8490794 | https://github.com/taylorwilsdon/google_workspace_mcp/issues/810 | Re-auth loop: OAuth callback stores credentials under google-<state> session, never bound to the live MCP session — every tool call after re-auth re-prompts

9. 配置坑 · 失败模式：configuration: Scary Mode

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Scary Mode
• 对用户的影响：Upgrade or migration may change expected behavior: Scary Mode
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Scary Mode. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_f7ece854c6d958a3a069caa7373df268 | https://github.com/taylorwilsdon/google_workspace_mcp/releases/tag/v1.18.0 | Scary Mode

10. 配置坑 · 失败模式：configuration: Windows: workspace-mcp Python child survives ungraceful parent termination, leaks OAuth callb...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Windows: workspace-mcp Python child survives ungraceful parent termination, leaks OAuth callback port (8000-8004 exhausted after 5 crashes)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Windows: workspace-mcp Python child survives ungraceful parent termination, leaks OAuth callback port (8000-8004 exhausted after 5 crashes)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows: workspace-mcp Python child survives ungraceful parent termination, leaks OAuth callback port (8000-8004 exhausted after 5 crashes). Context: Observed when using python, windows, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_c2dc89d9e3e849d9cddbb644aa4b75c1 | https://github.com/taylorwilsdon/google_workspace_mcp/issues/816 | Windows: workspace-mcp Python child survives ungraceful parent termination, leaks OAuth callback port (8000-8004 exhausted after 5 crashes)

11. 配置坑 · 失败模式：configuration: docs: explain how multiple accounts are resolved by chat clients

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: docs: explain how multiple accounts are resolved by chat clients
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: docs: explain how multiple accounts are resolved by chat clients
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: docs: explain how multiple accounts are resolved by chat clients. Context: Observed during installation or first-run setup.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_373216a0ef880973a052e78391fffab8 | https://github.com/taylorwilsdon/google_workspace_mcp/issues/815 | docs: explain how multiple accounts are resolved by chat clients

12. 配置坑 · 失败模式：configuration: v1.17.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.17.3
• 对用户的影响：Upgrade or migration may change expected behavior: v1.17.3
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.17.3. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_23ae9dba36e9bcb4f30c233e5a6d4f3d | https://github.com/taylorwilsdon/google_workspace_mcp/releases/tag/v1.17.3 | v1.17.3

13. 配置坑 · 失败模式：configuration: v1.20.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.20.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.20.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.20.0. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_335f77ccce1a25fdb7bb7210e1812380 | https://github.com/taylorwilsdon/google_workspace_mcp/releases/tag/v1.20.0 | v1.20.0

14. 配置坑 · 失败模式：configuration: v1.20.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.20.1
• 对用户的影响：Upgrade or migration may change expected behavior: v1.20.1
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.20.1. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_cf32907b41b3d9932942b000c4911686 | https://github.com/taylorwilsdon/google_workspace_mcp/releases/tag/v1.20.1 | v1.20.1

15. 配置坑 · 失败模式：configuration: v1.20.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.20.3
• 对用户的影响：Upgrade or migration may change expected behavior: v1.20.3
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.20.3. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_e6f9983131253c5196a0cc80fccdd25f | https://github.com/taylorwilsdon/google_workspace_mcp/releases/tag/v1.20.3 | v1.20.3

16. 配置坑 · 失败模式：configuration: v1.20.4

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.20.4
• 对用户的影响：Upgrade or migration may change expected behavior: v1.20.4
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.20.4. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_f3468cf79495c8fe79a956d1869cedb1 | https://github.com/taylorwilsdon/google_workspace_mcp/releases/tag/v1.20.4 | v1.20.4

17. 配置坑 · 失败模式：configuration: v1.21.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.21.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.21.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.21.0. Context: Observed when using windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_8511fb78f35540ce59157311860e4ef2 | https://github.com/taylorwilsdon/google_workspace_mcp/releases/tag/v1.21.0 | v1.21.0

18. 配置坑 · 来源证据：run_script_function broken after FastMCP v3 upgrade — parameters list received as JSON string

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：run_script_function broken after FastMCP v3 upgrade — parameters list received as JSON string
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_97ef2c42407f47709e72d3dba61ae3ab | https://github.com/taylorwilsdon/google_workspace_mcp/issues/712 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

19. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:973788136 | https://github.com/taylorwilsdon/google_workspace_mcp | README/documentation is current enough for a first validation pass.

20. 维护坑 · 失败模式：migration: feat(drive): add a create_drive_shortcut tool (files.create with shortcutDetails.targetId)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: feat(drive): add a create_drive_shortcut tool (files.create with shortcutDetails.targetId)
• 对用户的影响：Developers may hit a documented source-backed failure mode: feat(drive): add a create_drive_shortcut tool (files.create with shortcutDetails.targetId)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: feat(drive): add a create_drive_shortcut tool (files.create with shortcutDetails.targetId). Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_2ec87f1d72214674879309753defc8a1 | https://github.com/taylorwilsdon/google_workspace_mcp/issues/819 | feat(drive): add a create_drive_shortcut tool (files.create with shortcutDetails.targetId)

21. 维护坑 · 来源证据：feat(drive): Office→Google conversion on upload (pptx→Slides, xlsx→Sheets) — target mimeType ≠ media mimeType

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：feat(drive): Office→Google conversion on upload (pptx→Slides, xlsx→Sheets) — target mimeType ≠ media mimeType
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_30ea68889f9a4e4da2c609ff3d03088c | https://github.com/taylorwilsdon/google_workspace_mcp/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。

22. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:973788136 | https://github.com/taylorwilsdon/google_workspace_mcp | last_activity_observed missing

23. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:973788136 | https://github.com/taylorwilsdon/google_workspace_mcp | no_demo; severity=medium

24. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:973788136 | https://github.com/taylorwilsdon/google_workspace_mcp | no_demo; severity=medium

25. 安全/权限坑 · 来源证据：Re-auth loop: OAuth callback stores credentials under `google-<state>` session, never bound to the live MCP session — e…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Re-auth loop: OAuth callback stores credentials under google-<state> session, never bound to the live MCP session — every tool call after re-auth re-prompts
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_70dcca3c374840d3bf8827dd387e1b97 | https://github.com/taylorwilsdon/google_workspace_mcp/issues/810 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

26. 安全/权限坑 · 来源证据：Unregistered scope aliases `drive_full` and `script_full` cause permanent auth-failure on `delete_script_project` and `…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Unregistered scope aliases drive_full and script_full cause permanent auth-failure on delete_script_project and create_version
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ecdc714d95d44a269de52e7dfa33a6d1 | https://github.com/taylorwilsdon/google_workspace_mcp/issues/809 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

27. 安全/权限坑 · 来源证据：docs: explain how multiple accounts are resolved by chat clients

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：docs: explain how multiple accounts are resolved by chat clients
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_cfa9fa150ca8402baa139651788b227a | https://github.com/taylorwilsdon/google_workspace_mcp/issues/815 | 来源类型 github_issue 暴露的待验证使用条件。

28. 能力坑 · 失败模式：conceptual: [Feature Request] Add import_to_google_slides tool for PPTX conversion

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: [Feature Request] Add import_to_google_slides tool for PPTX conversion
• 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature Request] Add import_to_google_slides tool for PPTX conversion
• 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_a6cc303a74645a267da4d766f12cb139 | https://github.com/taylorwilsdon/google_workspace_mcp/issues/568 | [Feature Request] Add import_to_google_slides tool for PPTX conversion

29. 能力坑 · 失败模式：conceptual: feat(drive): Office→Google conversion on upload (pptx→Slides, xlsx→Sheets) — target mimeType...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: feat(drive): Office→Google conversion on upload (pptx→Slides, xlsx→Sheets) — target mimeType ≠ media mimeType
• 对用户的影响：Developers may hit a documented source-backed failure mode: feat(drive): Office→Google conversion on upload (pptx→Slides, xlsx→Sheets) — target mimeType ≠ media mimeType
• 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_b24e630634d2e4b6a4475a89ac58c670 | https://github.com/taylorwilsdon/google_workspace_mcp/issues/820 | feat(drive): Office→Google conversion on upload (pptx→Slides, xlsx→Sheets) — target mimeType ≠ media mimeType

30. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:973788136 | https://github.com/taylorwilsdon/google_workspace_mcp | issue_or_pr_quality=unknown

31. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:973788136 | https://github.com/taylorwilsdon/google_workspace_mcp | release_recency=unknown