项目介绍
技术文档摘要
VaultAssist - 个人 Google Workspace MCP 服务器
一个提供全面 Google Workspace 集成的 模型上下文协议（MCP）服务器，为您的个人 AI 助手提供金库级别的安全性。
使用 Next.js、TypeScript、Better Auth 和 Vercel 的 MCP SDK 构建，此服务器通过安全的 OAuth 2.1 身份验证和高级会话管理以及图数据库集成，实现对 Gmail、Google Drive、日历、表格、幻灯片和任务的自然语言控制。
概览
VaultAssist 在 AI 助手与 Google Workspace 服务之间充当安全桥梁，通过金库保护的认证 API 实现无缝自动化和数据访问。服务器支持多个用户，每个用户的资料、会话和 Google Workspace 访问完全隔离。Better Auth 提供强大的用户会话管理，PostgreSQL 确保持久的按用户数据存储，而 图数据库 则在您的个人数据生态系统中实现智能的用户特定关系映射。
graph TB
subgraph "客户端层"
VSCode[VS Code MCP 客户端]
Other[其他 MCP 客户端]
end
subgraph "VaultAssist MCP 服务器 (Next.js)"
Auth[Better Auth<br/>OAuth 2.1 + MCP 插件]
Router[MCP 处理器<br/>Vercel SDK + 动态路由]
subgraph "工具注册表"
Gmail[Gmail 工具]
Drive[驱动工具]
Docs[文档工具]
Calendar[日历工具]
Sheets[表格工具]
Slides[幻灯片工具]
Tasks[任务工具]
Memory[记忆工具]
Sequential[顺序思维]
end
subgraph "核心服务"
OAuth[Google OAuth 客户端]
Schema[Zod 验证]
DB[数据库层]
GraphDB[图数据库<br/>关系和上下文]
SessionMgmt[高级会话<br/>管理]
end
end
subgraph "Google API"
GmailAPI[Gmail API]
DriveAPI[驱动 API]
DocsAPI[文档 API]
CalendarAPI[日历 API]
SheetsAPI[表格 API]
SlidesAPI[幻灯片 API]
TasksAPI[任务 API]
end
subgraph "基础设施"
PostgresDB[(PostgreSQL 数据库<br/>用户数据及会话)]
GraphStore[(图数据库<br/>关系和记忆)]
GoogleCloud[Google Cloud 控制台<br/>OAuth 2.1 凭据]
VercelSDK[Vercel MCP SDK<br/>& 库]
end
%% 客户端连接
VSCode --> Router
Other --> Router
%% 认证流程
Router --> Auth
Auth --> GoogleCloud
Auth --> DB
Auth --> SessionMgmt
DB --> PostgresDB
SessionMgmt --> GraphStore
%% 工具注册和执行
Router --> Gmail
Router --> Drive
Router --> Docs
Router --> Calendar
Router --> Sheets
Router --> Slides
Router --> Tasks
Router --> Memory
Router --> Sequential
%% 服务层与 MCP SDK 集成
Gmail --> OAuth
Drive --> OAuth
Docs --> OAuth
Calendar --> OAuth
Sheets --> OAuth
Slides --> OAuth
Tasks --> OAuth
Memory --> GraphDB
Sequential --> GraphDB
%% 外部 API 调用
OAuth --> GmailAPI
OAuth --> DriveAPI
OAuth --> DocsAPI
OAuth --> CalendarAPI
OAuth --> SheetsAPI
OAuth --> SlidesAPI
OAuth --> TasksAPI
%% 数据验证和 MCP SDK
Gmail --> Schema
Drive --> Schema
Docs --> Schema
Calendar --> Schema
Sheets --> Schema
Slides --> Schema
Tasks --> Schema
Memory --> Schema
Sequential --> Schema
%% MCP SDK 集成
Router --> VercelSDK
Schema --> VercelSDK
Auth --> VercelSDK
%% 图数据库关系
GraphDB --> PostgresDB
GraphDB --> GraphStore
%% 样式
classDef clientNodes fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000000
classDef serverNodes fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000000
classDef apiNodes fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000000
classDef infraNodes fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#000000
class VSCode,Other clientNodes
class Auth,Router,Gmail,Drive,Docs,Calendar,Sheets,Slides,Tasks,Memory,Sequential,OAuth,Schema,DB,GraphDB,SessionMgmt serverNodes
class GmailAPI,DriveAPI,DocsAPI,CalendarAPI,SheetsAPI,SlidesAPI,TasksAPI apiNodes
class PostgresDB,GraphStore,GoogleCloud,VercelSDK infraNodes
特性
安全
- 使用加密令牌存储的 OAuth 2.1 身份验证
- 安全的会话管理和自动令牌刷新
- 使用 Zod 模式进行输入验证和 CORS 保护
- 基于环境的秘密管理
- 多用户隔离：每个用户都有完全隔离的工作区，严格分离会话、令牌和数据。不可能跨用户访问。所有 Google Workspace API 调用和记忆图都按用户分区以确保最大隐私。
Google Workspace 覆盖范围
- Gmail：完整的电子邮件管理，包括搜索、标签和批量操作
- Drive：文件操作，支持 Office 格式和 URL 导入
- Docs：创建、编辑、搜索和批量更新 Google 文档，具有高级内容操作
- Calendar：事件管理，包括 Google Meet 和附件
- Sheets：电子表格操作，具有灵活的数据 I/O
- Slides：演示管理，包括批量更新
- Tasks：完成任务和任务列表管理，具有层次结构
智能上下文管理
- 图数据库集成，用于跨个人数据的关系映射
- 长期上下文保留的记忆持久性
- 复杂任务管理的顺序思维模式
- 跨平台数据关联和洞察
开发者体验
- 使用 Vercel MCP SDK 构建，以获得最佳性能和可靠性
- 全面的 TypeScript 实现和 Zod 验证
- 清晰职责分离的模块化架构
- PostgreSQL 数据库，带有 Drizzle ORM 和图数据库集成
- 支持多种 MCP 传输方法，如可流式传输的 HTTP & SSE（已弃用）
架构
多用户架构及隔离访问
VaultAssist 设计用于安全的多用户操作。每个用户通过 OAuth 2.1 进行身份验证，并分配一个唯一的加密会话。所有 Google Workspace API 调用严格代表经过身份验证的用户执行，确保：
- 数据隔离：用户数据、令牌和记忆图按用户分区并加密。任何用户都无法访问另一个用户的数据或会话。
- 会话安全：会话由 Better Auth 管理，提供高级会话隔离和每个用户的自动令牌刷新。
- 按用户 API 访问：所有 Google API 操作均限于经过身份验证的用户帐户，没有共享凭据。
- 数据库和图分区：PostgreSQL 和图数据库条目按用户键入和隔离，防止跨用户数据泄露。
这种架构使 VaultAssist 能够安全地同时为多个用户提供服务，具有强烈的隐私和访问控制保证。
项目结构
mcp-server/
├── src/
│ ├── app/
│ │ ├── api/[transport]/ # MCP 端点，带工具注册表
│ │ ├── auth/ # 身份验证页面
│ │ └── dashboard/ # 用户仪表板
│ ├── lib/
│ │ ├── auth.ts # Better Auth 配置
│ │ ├── db/ # 数据库模式和操作
│ │ └── toolset/google/ # Google API 实现
│ └── components/ # UI 组件
├── drizzle/ # 数据库迁移
└── package.json
示例
https://github.com/user-attachments/assets/d0bf7f21-8044-4308-a029-1b8c13c439c9
先决条件
- Node v22+ 和包管理器（bun、npm 等）
- PostgreSQL 数据库（本地或云）
- Neo4j 数据库（Aura 或自托管）
- Redis 实例（Upstash 或自托管）
- Google Cloud 项目，带有 OAuth 2.1 凭据
- 兼容 MCP 的客户端（VS Code 等）
- Docker
设置与安装
1. 克隆并安装依赖项
git clone https://github.com/3xCaffeine/mcp-server.git
cd mcp-server
bun install # 或 npm install, pnpm install, yarn install
2. 数据库设置
设置您的 PostgreSQL 数据库并配置环境变量：
# 复制环境模板
cp .env.example .env
3. Google Cloud 控制台设置
- 创建 Google Cloud 项目
- 启用 API：
- Gmail API
- Google Drive API
- Google Calendar API
- Google Sheets API
- Google Slides API
- Google Tasks API
- 创建 OAuth 2.1 凭据：
- 转到 APIs & Services → 凭据
- 单击 创建凭据 → OAuth 客户端 ID
- 选择 Web 应用程序
- 添加授权重定向 URI：
http://localhost:3000/api/auth/callback/google
- 下载凭据并添加到
.env
4. 数据库迁移
# 生成并运行迁移
bun run drizzle:generate
bun run drizzle:migrate
# 可选：打开 Drizzle Studio 查看数据库
bun run drizzle:studio
5. 开发服务器
# 启动开发服务器
bun dev
访问 http://localhost:3000/dashboard 以访问 Web 接口。
部署步骤
- 检查 Caddy 配置并使用 Docker Compose 启动服务。
cd mcp-server/deployment/
docker compose up -d
MCP 客户端配置
打开 VS Code 命令面板 > MCP: 打开用户配置，并将以下内容粘贴到 mcp.json 配置中。
VS Code MCP 客户端
{
"servers": {
"google-workspace": {
"url": "https://mcp.rycerz.es:3000/api/mcp",
"type": "http"
}
},
"inputs": []
}
认证流程
- 初始设置：用户访问
/auth并使用 Google 登录 - OAuth 流程：Better Auth 处理增强安全性的 Google OAuth 2.1 流程
- 令牌存储：访问/刷新令牌安全存储在 PostgreSQL 中并进行加密
- MCP 会话：Better Auth MCP 插件管理具有金库级别安全性的会话令牌
- API 访问：每次工具调用都使用存储的令牌访问 Google API
- 图集成：用户交互映射到图数据库以进行上下文管理
可用工具
Gmail 工具
| 工具 | 描述 |
|---|---|
search_gmail_emails | 使用 Gmail 查询语法搜索邮件 |
read_gmail_email | 通过消息 ID 读取完整邮件内容 |
send_gmail_email | 发送带有附件和格式化的邮件 |
draft_gmail_email | 创建邮件草稿 |
modify_gmail_email | 从邮件中添加/删除标签 |
delete_gmail_email | 永久删除邮件 |
list_gmail_labels | 列出所有 Gmail 标签 |
create_gmail_label | 创建自定义标签 |
update_gmail_label | 修改现有标签 |
delete_gmail_label | 删除自定义标签 |
get_or_create_gmail_label | 获取现有或创建新标签 |
batch_modify_gmail_emails | 批量标签操作 |
batch_delete_gmail_emails | 批量删除邮件 |
Google Drive 工具
| 工具 | 描述 |
|---|---|
search_drive_files | 使用 Drive 查询语法搜索文件 |
get_drive_file_content | 读取文件内容（支持 Office 格式） |
list_drive_items | 列出目录中的文件和文件夹 |
create_drive_file | 从内容或 URL 创建文件 |
Google Docs 工具
| 工具 | 描述 |
|---|---|
search_docs | 使用 Drive API 按名称搜索 Google 文档 |
get_doc_content | 检索 Google 文档或 Drive 文件（.docx 等）的内容 |
list_docs_in_folder | 列出特定 Drive 文件夹内的 Google 文档 |
create_doc | 创建新的 Google 文档，并可选插入初始内容 |
modify_doc_text | 修改 Google 文档中的文本 - 插入/替换文本并应用格式 |
find_and_replace_doc | 在整个 Google 文档中查找和替换文本 |
insert_doc_elements | 插入表格、列表或分页符等结构元素 |
insert_doc_image | 从 Drive 或 URL 将图像插入 Google 文档 |
update_doc_headers_footers | 更新 Google 文档中的页眉或页脚 |
batch_update_doc | 在单个原子批处理更新中执行多个文档操作 |
inspect_doc_structure | 查找安全插入点并理解文档结构 |
create_table_with_data | 创建表格并填充数据 |
debug_table_structure | 调试表格布局和单元格位置 |
Google Calendar 工具
| 工具 | 描述 |
|---|---|
list_calendars | 列出可访问的日历 |
get_events | 使用过滤器检索事件 |
create_event | 创建带有 Google Meet 和附件的事件 |
modify_event | 更新现有事件 |
delete_event | 删除事件 |
get_event | 获取详细事件信息 |
Google Sheets 工具
| 工具 | 描述 |
|---|---|
list_spreadsheets | 列出可访问的电子表格 |
get_spreadsheet_info | 获取电子表格元数据 |
read_sheet_values | 读取单元格范围 |
modify_sheet_values | 写入/更新/清除单元格 |
create_spreadsheet | 创建新的电子表格 |
create_sheet | 向现有文件添加工作表 |
Google Slides 工具
| 工具 | 描述 | |------|