` 标签 |
| 回复时不包含历史消息内容 | 在 body 中手动添加引用内容 |
资料来源：[connectors/google-workspace/src/tools/definitions/gmail.ts:1-30]()
### 速率限制处理
当遇到速率限制时，连接器返回结构化错误响应：
```json
{
"ok": false,
"action_required": "Google Workspace rate limit reached",
"next_step": "Back off before retrying, reduce the request size if possible"
}
```
## 认证流程模式
### Microsoft 365 多连接器认证共享
Microsoft 365 系列连接器（Mail、Teams、SharePoint）采用共享认证基础设施：
```mermaid
sequenceDiagram
participant Host as MCP Host
participant Mail as microsoft-mail
participant Teams as microsoft-teams
participant Graph as Microsoft Graph API
Host->>Mail: authenticate_microsoft_account
Mail->>Graph: OAuth Flow
Graph-->>Mail: tokens
Mail-->>Host: Write to ${MS_CONFIG_DIR}
Host->>Teams: authenticate_sharepoint (增量授权)
Teams->>Mail: 读取共享配置
Mail-->>Teams: credentials/
Teams-->>Host: 复用 Mail 的基础会话
```
**关键安全设计：**
- Teams 和 SharePoint 连接器复用 Mail 连接器建立的认证会话
- 所有连接器共享 `MS_CONFIG_DIR` 中的令牌存储
- 主机应用统一管理令牌刷新，`MICROSOFT_DISABLE_REFRESH=1` 确保单点刷新权威
资料来源：[connectors/microsoft-mail/README.md:Requirements]()
### Google Workspace 认证流程
Google Workspace 连接器支持两种认证模式：
| 模式 | 检测条件 | 描述 |
|------|----------|------|
| bridge | `MCP_HOST_BRIDGE_STATE` 已设置 | 主机应用管理 OAuth |
| standalone_oauth | `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` 已设置 | 本地 OAuth（浏览器重定向） |
| manual_token | `GOOGLE_ACCESS_TOKEN` 已设置 | 静态访问令牌 |
| unconfigured | 无认证环境变量 | 工具返回设置引导信息 |
**优先级**：bridge > standalone_oauth > manual_token > unconfigured
资料来源：[connectors/google-workspace/README.md:Tools (94)]()
## 安全审计与监控
### 成功响应包装
所有工具的成功响应遵循统一的成功结果格式：
```json
{
"ok": true,
"result": { ... }
}
```
### 错误响应结构
业务错误和验证错误返回以下结构，确保主机恢复层能够采取行动：
```json
{
"ok": false,
"error": "Human-readable error description",
"action_required": "What user needs to do",
"next_step": "Specific recovery guidance"
}
```
### 超时保护
每个工具调用都配置了超时保护：
- Microsoft Graph 请求默认超时 60 秒（可配置，最高 300 秒）
- Gemini API 请求默认超时 180 秒
- 所有超时使用 AbortController 信号管理
## 部署安全建议
### 本地开发环境
```bash
# 使用 npx 直接运行（自动处理依赖）
npx -y @mindstone/mcp-server-google-workspace
```
### 云端部署
| 安全措施 | 实现方式 |
|----------|----------|
| 令牌刷新控制 | 设置 `MICROSOFT_DISABLE_REFRESH=1` |
| 主机管理认证 | 配置 `MCP_HOST_BRIDGE_STATE` |
| 网络隔离 | 服务间通信使用 TLS |
| 日志脱敏 | 敏感信息不写入日志 |
### Claude Desktop 配置示例
```json
{
"mcpServers": {
"GoogleWorkspace": {
"command": "node",
"args": ["/path/to/connectors/google-workspace/dist/index.js"],
"env": {
"GOOGLE_CLIENT_ID": "your-client-id",
"GOOGLE_CLIENT_SECRET": "your-client-secret",
"ACCOUNTS_PATH": "/absolute/path/to/accounts.json",
"CREDENTIALS_PATH": "/absolute/path/to/credentials"
}
}
}
}
```
## 相关文档
- [Google Workspace 连接器](../google-workspace/) — Gmail、日历、Drive、Docs、Sheets、Slides 集成
- [Microsoft 365 Mail](../microsoft-mail/) — Outlook 邮件集成
- [Microsoft Teams](../microsoft-teams/) — Teams 消息和频道集成
- [Microsoft SharePoint](../microsoft-sharepoint/) — SharePoint 文件集成
- [Slack 连接器](../slack/) — Slack 工作区集成
## 参考资料
- TokenProvider 安全实现：[packages/mcp-server-microsoft-shared/README.md](https://github.com/mindstone/mcp-servers/blob/main/packages/mcp-server-microsoft-shared/README.md)
- Google Workspace 认证流程：[connectors/google-workspace/src/tools/server.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/tools/server.ts)
- Gmail 输入验证：[connectors/google-workspace/src/tools/definitions/gmail.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/tools/definitions/gmail.ts)
- Slack 错误代码体系：[connectors/slack/src/types.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/slack/src/types.ts)
- Microsoft 共享认证库：[packages/mcp-server-microsoft-shared/README.md](https://github.com/mindstone/mcp-servers/blob/main/packages/mcp-server-microsoft-shared/README.md)
---
## Google Workspace 连接器
### 相关页面
相关主题：[生产力工具连接器](#productivity-connectors), [Microsoft 365 连接器套件](#microsoft-connectors)
相关源码文件
以下源码文件用于生成本页说明：
- [connectors/google-workspace/package.json](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/package.json)
- [connectors/google-workspace/src/tools/definitions/index.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/tools/definitions/index.ts)
- [connectors/google-workspace/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/README.md)
- [connectors/google-workspace/src/tools/definitions/gmail.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/tools/definitions/gmail.ts)
- [connectors/google-workspace/src/tools/drive-handlers.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/tools/drive-handlers.ts)
- [connectors/google-workspace/src/modules/slides/types.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/modules/slides/types.ts)
- [connectors/google-workspace/src/api/validators/parameter.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/api/validators/parameter.ts)
Hi Alice,
会议要点：
` 标签换行 |
资料来源：[connectors/google-workspace/src/tools/definitions/gmail.ts:1-35](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/tools/definitions/gmail.ts)
### Drive 工具
Drive 工具支持多种文件操作，包括上传、下载、搜索和权限管理：
#### 文件搜索参数
```typescript
interface DriveSearchArgs {
email?: string;
options: FileSearchOptions;
return_json?: boolean;
returnJson?: boolean;
}
```
#### 文件上传参数
```typescript
interface DriveUploadArgs {
email?: string;
options: FileUploadOptions;
}
```
#### 错误处理
Drive 工具内置完善的错误恢复机制：
```typescript
function formatDriveRecoveryError(operation: string, error: unknown): DriveRecoveryResponse {
const statusText = error instanceof Error ? error.message : 'Unknown error';
return {
ok: false,
action_required: `Drive ${operation} failed${statusText}`,
next_step: `${message}. Check Google Workspace authentication and Drive permissions, then retry.`,
};
}
```
资料来源：[connectors/google-workspace/src/tools/drive-handlers.ts:1-30](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/tools/drive-handlers.ts)
### Slides 工具类型定义
```typescript
export interface ReadPresentationOptions {
maxChars?: number;
includeNotes?: boolean;
returnJson?: boolean; // 默认: false (人类可读文本)
}
export interface BatchUpdatePresentationOptions {
requests: SlidesRequest[];
writeControl?: SlidesWriteControl;
returnJson?: boolean;
}
export interface ThumbnailOptions {
mimeType?: 'PNG';
thumbnailSize?: 'SMALL' | 'MEDIUM' | 'LARGE';
}
export interface CreatePresentationOptions {
title: string;
}
```
资料来源：[connectors/google-workspace/src/modules/slides/types.ts:14-35](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/modules/slides/types.ts)
---
## 配置与部署
### 环境变量配置
| 变量名 | 必填 | 说明 |
|--------|------|------|
| `GOOGLE_CLIENT_ID` | 是 | Google OAuth 客户端 ID |
| `GOOGLE_CLIENT_SECRET` | 是 | Google OAuth 客户端密钥 |
| `ACCOUNTS_PATH` | 是 | accounts.json 文件路径 |
| `ENABLE_GOOGLE_TASKS_FORMS` | 否 | 启用 Tasks 和 Forms 功能（默认禁用） |
资料来源：[connectors/google-workspace/README.md:50-58](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/README.md)
### Claude Desktop 配置示例
```json
{
"mcpServers": {
"Google Workspace": {
"command": "npx",
"args": [
"-y",
"@mindstone/mcp-server-google-workspace"
],
"env": {
"GOOGLE_CLIENT_ID": "your-client-id",
"GOOGLE_CLIENT_SECRET": "your-client-secret",
"ACCOUNTS_PATH": "/path/to/accounts.json"
}
}
}
}
```
### 快速开始
#### 构建项目
```bash
cd Hi Alice, 会议要点：相关源码文件
以下源码文件用于生成本页说明：
- [packages/mcp-server-microsoft-shared/src/graphClient.ts](https://github.com/mindstone/mcp-servers/blob/main/packages/mcp-server-microsoft-shared/src/graphClient.ts)
- [packages/mcp-server-microsoft-shared/README.md](https://github.com/mindstone/mcp-servers/blob/main/packages/mcp-server-microsoft-shared/README.md)
- [connectors/microsoft-mail/src/mail.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-mail/src/mail.ts)
- [connectors/microsoft-calendar/src/calendar.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-calendar/src/calendar.ts)
- [connectors/microsoft-files/src/files.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-files/src/files.ts)
- [connectors/microsoft-teams/src/teams.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/src/teams.ts)
- [connectors/microsoft-sharepoint/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-sharepoint/README.md)
- [connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md)
authenticate_microsoft_account]
B --> C[MS Graph OAuth 2.0
Microsoft Entra ID]
C --> D[credentials/accounts.json
credentials/tokens.json]
D --> E[共享认证文件]
E --> F[mcp-server-microsoft-teams]
E --> G[mcp-server-microsoft-sharepoint]
E --> H[mcp-server-microsoft-files]
```
资料来源：[packages/mcp-server-microsoft-shared/README.md](https://github.com/mindstone/mcp-servers/blob/main/packages/mcp-server-microsoft-shared/README.md)
### Graph API 客户端封装
所有连接器通过统一的 Graph 客户端与 Microsoft Graph API 交互。共享包提供了标准化的请求处理、错误转换和超时管理机制。
```mermaid
classDiagram
class GraphClient {
+get(endpoint: string)
+post(endpoint: string, body: object)
+patch(endpoint: string, body: object)
+delete(endpoint: string)
+uploadStream(endpoint: string, stream: Readable)
}
class MailConnector {
+send_email()
+read_emails()
+create_draft()
}
class TeamsConnector {
+send_channel_message()
+list_channels()
+create_meeting()
}
class SharePointConnector {
+list_sites()
+upload_file()
+search_sharepoint()
}
GraphClient <-- MailConnector : 使用
GraphClient <-- TeamsConnector : 使用
GraphClient <|-- SharePointConnector : 使用
```
资料来源：[packages/mcp-server-microsoft-shared/src/graphClient.ts](https://github.com/mindstone/mcp-servers/blob/main/packages/mcp-server-microsoft-shared/src/graphClient.ts)
## 认证与配置
### 必需环境变量
| 变量名 | 描述 | 资料来源 |
|--------|------|----------|
| `MS_CLIENT_ID` | Microsoft Entra（Azure AD）应用程序客户端 ID | [connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md) |
| `MS_CONFIG_DIR` | Microsoft 配置目录路径（包含 `credentials/` 和 `accounts.json`） | [connectors/microsoft-sharepoint/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-sharepoint/README.md) |
### 可选环境变量
| 变量名 | 描述 | 默认值 | 资料来源 |
|--------|------|--------|----------|
| `MS_ACCOUNT_EMAIL` | 多账户模式下指定账户邮箱 | `accounts.json` 中第一个账户 | [connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md) |
| `MS_MCP_PACKAGE_ID` | 错误响应中的逻辑包标识符 | 服务特定默认值 | [connectors/microsoft-sharepoint/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-sharepoint/README.md) |
| `MICROSOFT_REQUEST_TIMEOUT_MS` | Microsoft Graph 请求超时时间（最大 300000ms） | `60000` | [connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md) |
| `MICROSOFT_DISABLE_REFRESH` | 设为 `1` 禁用令牌刷新，工具以 `auth_required` 响应失败关闭 | 未设置 | [connectors/microsoft-mail/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-mail/README.md) |
### MCP 主机配置示例
```json
{
"mcpServers": {
"Microsoft365Mail": {
"command": "npx",
"args": ["-y", "@mindstone/mcp-server-microsoft-mail"],
"env": {
"MS_CLIENT_ID": "your-entra-application-client-id",
"MS_CONFIG_DIR": "/absolute/path/to/microsoft-config"
}
},
"Microsoft365Teams": {
"command": "npx",
"args": ["-y", "@mindstone/mcp-server-microsoft-teams"],
"env": {
"MS_CLIENT_ID": "your-entra-application-client-id",
"MS_CONFIG_DIR": "/absolute/path/to/microsoft-config"
}
},
"Microsoft365SharePoint": {
"command": "npx",
"args": ["-y", "@mindstone/mcp-server-microsoft-sharepoint"],
"env": {
"MS_CLIENT_ID": "your-entra-application-client-id",
"MS_CONFIG_DIR": "/absolute/path/to/microsoft-config"
}
}
}
}
```
资料来源：[connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md)
### 认证流程
```mermaid
sequenceDiagram
participant User as 用户
participant Host as MCP 主机
participant Mail as mcp-server-microsoft-mail
participant Graph as Microsoft Graph
participant Entra as Microsoft Entra ID
User->>Host: 调用 authenticate_microsoft_account
Host->>Mail: 执行认证工具
Mail->>Entra: 发起 OAuth 授权请求
Entra-->>User: 显示登录页面
User->>Entra: 输入凭据并授权
Entra-->>Mail: 返回授权码/令牌
Mail->>Graph: 使用令牌调用 API
Graph-->>Mail: 验证成功
Mail->>Mail: 保存 credentials/accounts.json
Mail-->>Host: 认证成功
```
## Microsoft Mail 连接器
`mcp-server-microsoft-mail` 是 Microsoft 365 连接器套件的核心组件，负责邮件、日历和联系人的基础认证。
### 主要工具
| 工具名称 | 功能 | 资料来源 |
|----------|------|----------|
| `authenticate_microsoft_account` | 发起 Microsoft 365 OAuth 授权流程 | [connectors/microsoft-mail/src/mail.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-mail/src/mail.ts) |
| `send_email` | 发送邮件，支持纯文本和 HTML 格式 | [connectors/microsoft-mail/src/mail.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-mail/src/mail.ts) |
| `read_emails` | 读取邮件，支持分页和过滤器 | [connectors/microsoft-mail/src/mail.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-mail/src/mail.ts) |
| `create_draft` | 创建草稿邮件 | [connectors/microsoft-mail/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-mail/README.md) |
### 安全注意事项
- 令牌文件以 `0600` 权限模式写入主机，由共享库以严格模式读取
- 云端表面默认设置 `MICROSOFT_DISABLE_REFRESH=1`，避免单次使用刷新令牌的竞争
- 成功响应使用标准 `successResult` 格式；错误响应返回 `isError:true` 并包含 `action_required` 和 `next_step` 字段
资料来源：[connectors/microsoft-mail/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-mail/README.md)
## Microsoft Teams 连接器
`mcp-server-microsoft-teams` 提供 Microsoft Teams 消息、频道和会议的管理能力。
### 主要工具
| 工具类别 | 工具示例 | 功能描述 | 资料来源 |
|----------|----------|----------|----------|
| 消息 | `send_channel_message`, `reply_to_message` | 发送频道消息和回复 | [connectors/microsoft-teams/src/teams.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/src/teams.ts) |
| 频道 | `list_channels`, `get_channel` | 浏览和管理团队频道 | [connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md) |
| 会议 | `create_meeting`, `get_meeting` | 创建和获取 Teams 会议 | [connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md) |
| 成员 | `list_members`, `add_member` | 团队成员管理 | [connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md) |
### 与邮件连接器的认证共享
Teams 连接器复用 `mcp-server-microsoft-mail` 写入的凭据，无需单独认证：
> Sign in via `@mindstone/mcp-server-microsoft-mail`'s `authenticate_microsoft_account` first; the Teams tools then reuse the credentials it writes to `${MS_CONFIG_DIR}/`.
资料来源：[connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md)
## Microsoft SharePoint 连接器
`mcp-server-microsoft-sharepoint` 提供 SharePoint Online 网站、文档库和列表的管理能力。
### 主要工具
| 工具类别 | 工具名称 | 功能描述 | 资料来源 |
|----------|----------|----------|----------|
| 文档库 | `list_library_items`, `download_library_item`, `upload_file_to_library` | 文档库文件管理 | [connectors/microsoft-sharepoint/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-sharepoint/README.md) |
| 共享 | `copy_library_item`, `rename_library_item`, `create_sharing_link` | 文档共享和操作 | [connectors/microsoft-sharepoint/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-sharepoint/README.md) |
| 页面 | `list_site_pages`, `read_site_page` | SharePoint 页面浏览 | [connectors/microsoft-sharepoint/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-sharepoint/README.md) |
| 列表 | `list_lists`, `list_list_items`, `create_list_item` | SharePoint 列表操作 | [connectors/microsoft-sharepoint/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-sharepoint/README.md) |
| 搜索 | `search_sharepoint` | 跨站点搜索内容 | [connectors/microsoft-sharepoint/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-sharepoint/README.md) |
### 增量认证
SharePoint 连接器需要额外的 `Sites.Read.All` 权限范围：
> Sign in via `@mindstone/mcp-server-microsoft-mail`'s `authenticate_microsoft_account` first to negotiate the base session, then call this server's `authenticate_sharepoint` to request the additional SharePoint `Sites.Read.All` scope on top.
资料来源：[connectors/microsoft-sharepoint/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-sharepoint/README.md)
## Microsoft Calendar 连接器
`mcp-server-microsoft-calendar` 提供日历事件的完整 CRUD 操作能力。
### 主要工具
| 工具名称 | 功能描述 | 资料来源 |
|----------|----------|----------|
| `list_events` | 列出日历事件，支持日期范围过滤 | [connectors/microsoft-calendar/src/calendar.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-calendar/src/calendar.ts) |
| `create_event` | 创建日历事件 | [connectors/microsoft-calendar/src/calendar.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-calendar/src/calendar.ts) |
| `update_event` | 更新现有事件 | [connectors/microsoft-calendar/src/calendar.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-calendar/src/calendar.ts) |
| `delete_event` | 删除日历事件 | [connectors/microsoft-calendar/src/calendar.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-calendar/src/calendar.ts) |
## Microsoft Files 连接器
`mcp-server-microsoft-files` 提供 OneDrive 个人云存储的文件管理能力。
### 主要工具
| 工具名称 | 功能描述 | 资料来源 |
|----------|----------|----------|
| `list_files` | 列出 OneDrive 文件和文件夹 | [connectors/microsoft-files/src/files.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-files/src/files.ts) |
| `upload_file` | 上传文件到 OneDrive | [connectors/microsoft-files/src/files.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-files/src/files.ts) |
| `download_file` | 下载 OneDrive 文件 | [connectors/microsoft-files/src/files.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-files/src/files.ts) |
| `search_files` | 搜索 OneDrive 文件 | [connectors/microsoft-files/src/files.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-files/src/files.ts) |
## 错误处理
### 错误响应格式
所有 Microsoft 365 连接器采用统一的错误响应格式：
```json
{
"isError": true,
"data": {
"ok": false,
"error": "错误消息描述",
"errorCode": "ERROR_CODE",
"action_required": "需要的操作步骤",
"next_step": "下一步建议"
}
}
```
### 认证错误处理
| 错误场景 | 响应代码 | 处理方式 | 资料来源 |
|----------|----------|----------|----------|
| 令牌过期 | `auth_required` | 主机驱动重新认证 | [connectors/microsoft-mail/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-mail/README.md) |
| 刷新禁用 | `MICROSOFT_DISABLE_REFRESH=1` | 工具以 `auth_required` 失败关闭 | [connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md) |
| 令牌文件损坏 | `INVALID_TOKEN_FILE` | 共享库失败关闭 | [connectors/microsoft-mail/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-mail/README.md) |
### 超时管理
每个工具的 Graph API 调用使用组合超时信号：
> Per-tool Graph calls run under a composed caller + cohort timeout signal via `.options({signal})` plus a `Promise.race` wrapper for defence-in-depth.
资料来源：[connectors/microsoft-sharepoint/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-sharepoint/README.md)
## 常见故障排除
| 症状 | 可能原因 | 解决方案 | 资料来源 |
|------|----------|--------|----------|
| 连接器启动失败 | 未执行构建 | 运行 `npm install && npm run build` | [connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md) |
| 认证错误或空结果 | 配置文件路径错误或凭据无效 | 检查 `MS_CONFIG_DIR` 和 `accounts.json` | [connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md) |
| MCP 主机报告协议问题 | stdio 会话中的标准输出噪音 | 确保没有 `console.log` 调用（所有日志使用 `console.error`） | [connectors/zendesk/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/zendesk/README.md) |
| 请求超时 | Graph API 响应缓慢 | 调整 `MICROSOFT_REQUEST_TIMEOUT_MS` 环境变量 | [connectors/microsoft-sharepoint/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-sharepoint/README.md) |
## 社区相关问题
### Google Workspace 输入验证增强
虽然此问题针对 Google Workspace 连接器，但它反映了 Microsoft 365 连接器套件中类似的最佳实践趋势：
> **行为变更。** 为 `handleComposeWorkspaceEmail` 添加了之前不存在的 fail-closed 输入验证门。当 `to`/`subject`/`body` 本应被静默默认为空值时，抛出 `McpError(InvalidParams)`。
Microsoft 365 连接器套件同样遵循严格的输入验证模式，确保 API 调用的参数完整性。
资料来源：[社区上下文 #67](https://github.com/mindstone/mcp-servers/issues/67)
## 本地开发
### 构建所有连接器
```bash
cd 相关源码文件
以下源码文件用于生成本页说明：
- [connectors/office/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/office/README.md)
- [connectors/office/src/index.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/office/src/index.ts)
- [connectors/office/src/shared/office/errors.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/office/src/shared/office/errors.ts)
- [connectors/google-workspace/src/tools/definitions/gmail.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/tools/definitions/gmail.ts)
- [connectors/google-workspace/src/resources/compose-email-template.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-workspace/src/resources/compose-email-template.ts)
- [connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md)
- [connectors/microsoft-mail/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-mail/README.md)
- [connectors/hubspot/src/tools/definitions.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/hubspot/src/tools/definitions.ts)
- [connectors/hubspot/src/tools/marketing-handlers.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/hubspot/src/tools/marketing-handlers.ts)
- [connectors/zendesk/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/zendesk/README.md)
- [connectors/napkin/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/napkin/README.md)
- [connectors/elevenlabs/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/elevenlabs/README.md)
- [connectors/google-analytics/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/google-analytics/README.md)
(Claude Desktop/Cursor等)"] <-->|"JSON-RPC over stdio"| B["MCP 连接器服务器"]
B --> C["第三方 API / SDK"]
B --> D["认证凭据存储"]
C --> E["外部服务
(Office 365/Google等)"]
```
### Office 连接器架构
Office 连接器采用特殊的 Sidecar（边车）架构设计，包含两个主要组件：
1. **MCP 服务器端** (`dist/index.js`) — 通过 stdio 与 MCP 主机通信
2. **Sidecar 进程** — 一个独立的 Node.js 进程，负责与 Office 加载项（Add-in）建立 WebSocket 连接
Sidecar 架构的核心特点包括：
- MCP 服务器通过环境变量 `MCP_OFFICE_SIDECAR_STATE` 指向的 JSON 文件获取 sidecar 的端口和令牌
- Sidecar 进程负责维护与 Office 应用程序的连接状态
- 错误转换层（`errors.ts`）将核心错误映射为 Office 品牌化消息
资料来源：[connectors/office/src/shared/office/errors.ts:1-50](https://github.com/mindstone/mcp-servers/blob/main/connectors/office/src/shared/office/errors.ts)
```mermaid
graph TD
A["MCP 主机"] <-->|"stdio"| B["MCP Office 服务器
dist/index.js"]
B <-->|"port + token
sidecar-state.json"| C["Sidecar 进程"]
C <-->|"WebSocket"| D["Office 加载项"]
D <-->|"Office.js API"| E["Office 应用
(Word/Excel/PowerPoint)"]
F["环境变量"] --> B
G["环境变量"] --> C
```
### 认证与凭据管理
Microsoft 产品线连接器采用共享的认证体系：
| 环境变量 | 描述 |
|----------|------|
| `MS_CLIENT_ID` | Microsoft Entra (Azure AD) 应用程序客户端 ID |
| `MS_CONFIG_DIR` | 包含凭据和账户信息的配置目录路径 |
| `MS_ACCOUNT_EMAIL` | 多账户模式下的指定账户邮箱 |
| `MS_MCP_PACKAGE_ID` | 错误响应中显示的逻辑包 ID |
| `MICROSOFT_REQUEST_TIMEOUT_MS` | 上游 Microsoft Graph 请求超时（最大 300000ms） |
| `MICROSOFT_DISABLE_REFRESH` | 设为 `1` 禁用令牌刷新，强制主机驱动重新认证 |
资料来源：[connectors/microsoft-teams/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/microsoft-teams/README.md)
云端表面默认设置 `MICROSOFT_DISABLE_REFRESH=1`，使桌面会话成为唯一的刷新令牌权威，避免单次使用刷新令牌的竞争条件。
## 工具分类与功能
### Office 连接器工具集
Office 连接器提供 **53 个工具**，分为以下类别：
#### 设置工具（2 个）
| 工具名称 | 功能描述 |
|----------|----------|
| `rebel_office_setup` | 安装或修复（或卸载）Office 加载项 |
| `rebel_office_status` | 检查 Word、Excel、PowerPoint 的连接状态 |
#### Word 工具（17 个）
| 工具名称 | 功能描述 |
|----------|----------|
| `rebel_office_word_read_document` | 按段落分页读取活动 Word 文档正文 |
| `rebel_office_word_get_document_structure` | 获取文档的标题/章节大纲 |
| `rebel_office_word_get_selection` | 获取当前选中的文本和位置 |
| `rebel_office_word_find_text` | 搜索文本出现位置并返回周围上下文 |
| `rebel_office_word_insert_text` | 在指定位置插入文本或替换选中内容（破坏性） |
| `rebel_office_word_replace_text` | 在文档中查找并替换文本（破坏性） |
| `rebel_office_word_format_text` | 应用字体、颜色、高亮或对齐格式（破坏性） |
| `rebel_office_word_insert_table` | 插入带表头和行的表格（破坏性） |
| `rebel_office_word_insert_image` | 从文件路径或 base64 数据插入图片（破坏性） |
| `rebel_office_word_insert_break` | 插入分页符或分节符（破坏性） |
| `rebel_office_word_set_header_footer` | 设置页眉或页脚文本和对齐方式（破坏性） |
| `rebel_office_word_get_properties` | 获取文档元数据（标题、作者、计数） |
| `rebel_office_word_get_comments` | 读取评论和回复线程 |
| `rebel_office_word_add_comment` | 在选中文本上添加评论或回复线程（破坏性） |
| `rebel_office_word_resolve_comment` | 按 ID 解决或删除评论（破坏性） |
| `rebel_office_word_get_tracked_changes` | 读取追踪的更改（修订） |
| `rebel_office_word_accept_reject_changes` | 批量或按 ID 接受或拒绝追踪的更改（破坏性） |
资料来源：[connectors/office/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/office/README.md)
#### Excel 工具（22 个）
| 工具名称 | 功能描述 |
|----------|----------|
| `rebel_office_excel_read_range` | 从 A1 范围或命名范围读取单元格值 |
| `rebel_office_excel_write_range` | 将二维值数组写入范围（破坏性） |
| `rebel_office_excel_get_worksheets` | 列出工作表及其位置和使用范围 |
| `rebel_office_excel_add_worksheet` | 在指定位置添加新工作表（破坏性） |
| `rebel_office_excel_delete_worksheet` | 删除工作表及其所有数据（破坏性） |
| `rebel_office_excel_read_table` | 从命名 Excel 表格读取行 |
| `rebel_office_excel_create_table` | 将范围转换为命名 Excel 表格（破坏性） |
| `rebel_office_excel_set_formula` | 设置单元格公式 |
#### PowerPoint 工具（14 个）
| 工具名称 | 功能描述 |
|----------|----------|
| `rebel_office_powerpoint_get_presentation` | 获取幻灯片列表和基本信息 |
| `rebel_office_powerpoint_get_slide` | 获取单张幻灯片内容 |
| `rebel_office_powerpoint_add_slide` | 在指定位置添加幻灯片（破坏性） |
| `rebel_office_powerpoint_delete_slide` | 删除幻灯片（破坏性） |
| `rebel_office_powerpoint_insert_text` | 在形状或文本框中插入文本（破坏性） |
| `rebel_office_powerpoint_add_shape` | 添加几何形状（破坏性） |
| `rebel_office_powerpoint_update_text` | 更新形状或布局占位符中的文本（破坏性） |
| `rebel_office_powerpoint_get_speaker_notes` | 读取一张或所有幻灯片的演讲者备注 |
| `rebel_office_powerpoint_set_speaker_notes` | 为幻灯片设置或替换演讲者备注（破坏性） |
| `rebel_office_powerpoint_get_presentation_properties` | 获取演示文稿元数据、尺寸和布局 |
### HubSpot 连接器工具集
HubSpot 连接器提供全面的 CRM 功能，包括以下工具类别：
| 类别 | 工具数量 | 主要功能 |
|------|----------|----------|
| 账户管理 | ✓ | 获取账户信息 |
| 联系人 | ✓ | 列表、获取、创建、更新、删除、搜索 |
| 公司 | ✓ | 列表、获取、创建、更新、删除、搜索 |
| 交易 | ✓ | 完整生命周期管理 |
| 工单 | ✓ | 创建、更新、关闭、评论 |
| 营销表单 | ✓ | 列表、获取、提交处理 |
| 分析报告 | ✓ | 报告生成、数据聚合 |
资料来源：[connectors/hubspot/src/tools/definitions.ts:1-30](https://github.com/mindstone/mcp-servers/blob/main/connectors/hubspot/src/tools/definitions.ts)
HubSpot 错误处理采用统一的错误解析机制，根据错误类型返回结构化的错误信息：
```typescript
// 错误类型映射
if (error.statusCode === 404) {
return {
error: `${context.feature} not found`,
errorCode: 'NOT_FOUND',
suggestion: `Verify the ${context.feature} ID is correct.`
};
}
```
资料来源：[connectors/hubspot/src/tools/marketing-handlers.ts:1-30](https://github.com/mindstone/mcp-servers/blob/main/connectors/hubspot/src/tools/marketing-handlers.ts)
### Google Workspace 连接器
Google Workspace 连接器的 Gmail 功能支持以下操作：
| 工具名称 | 功能描述 |
|----------|----------|
| `handleComposeWorkspaceEmail` | 撰写并发送邮件（支持纯文本和 HTML 格式） |
| `create_draft` | 保存新的独立草稿邮件 |
**重要变更（v0.1.2）：**
> ⚠️ **行为变更** — PR #66 在 `handleComposeWorkspaceEmail` 中添加了 fail-closed（故障关闭）输入验证门控，此前该门控不存在。当 `to`/`subject`/`body` 本应静默默认为空值时，现在会抛出 `McpError(InvalidParams)`。
资料来源：[PR #66](https://github.com/mindstone/mcp-servers/pull/66)、[社区讨论 #67](https://github.com/mindstone/mcp-servers/issues/67)
#### Gmail 工具使用示例
**纯文本邮件：**
```json
{
"to": ["alice@example.com"],
"subject": "会议通知",
"body": "Hi Alice,\\n\\n我们明天3点能见面吗？\\n\\n谢谢，\\nBob"
}
```
**HTML 格式邮件：**
```json
{
"to": ["alice@example.com"],
"subject": "会议纪要",
"body": "
",
"is_html": true
}
```
**回复邮件：**
```json
{
"to": ["original-sender@example.com"],
"subject": "Re: 会议安排",
"body": "听起来不错！\n\nOn Mon, Jan 6, 2026 at 10:00 AM, Alice 相关源码文件
以下源码文件用于生成本页说明：
- [connectors/hubspot/src/tools/definitions.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/hubspot/src/tools/definitions.ts)
- [connectors/hubspot/src/tools/marketing-handlers.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/hubspot/src/tools/marketing-handlers.ts)
- [connectors/hubspot/src/tools/input-limits.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/hubspot/src/tools/input-limits.ts)
- [connectors/zendesk/README.md](https://github.com/mindstone/mcp-servers/blob/main/connectors/zendesk/README.md)
- [connectors/freshdesk/src/tools/tickets.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/freshdesk/src/tools/tickets.ts)
- [connectors/outreach/src/tools/prospects.ts](https://github.com/mindstone/mcp-servers/blob/main/connectors/outreach/src/tools/prospects.ts)
Claude/AI Agent] -->|MCP Protocol| B[CRM/客服连接器]
B --> C[平台 API 客户端]
C --> D[HubSpot API]
C --> E[Salesforce API]
C --> F[Zendesk API]
C --> G[Freshdesk API]
C --> H[Outreach API]
I[配置文件
accounts.json] --> B
J[环境变量] --> B
```
## HubSpot 连接器
### 功能范围
HubSpot 连接器是最全面的 CRM 连接器，提供了对 HubSpot CRM 几乎所有核心对象的访问能力。工具按照功能分为多个类别：
**资料来源：** [connectors/hubspot/src/tools/definitions.ts:1-50]()
### 工具分类
| 类别 | 工具数量 | 主要功能 |
|------|----------|----------|
| 账户工具 | 3 | 账户创建、读取、更新 |
| 联系人工具 | 5 | 联系人 CRUD、搜索、关联 |
| 公司工具 | 4 | 公司管理、域名匹配 |
| 交易工具 | 5 | 交易阶段、管道、关闭操作 |
| 工单工具 | 4 | 工单创建、状态更新、评论 |
| 线索工具 | 3 | 线索识别、转换 |
| 任务工具 | 4 | 任务创建、关联 |
| 备注工具 | 3 | 备注关联、CRM 对象关联 |
| 关联工具 | 6 | 对象间关联管理 |
| 属性工具 | 4 | 自定义属性读取 |
| 所有者工具 | 2 | 用户/所有者查询 |
| 管道工具 | 3 | 交易管道配置 |
| 互动工具 | 5 | 邮件、会议、日志 |
| 产品工具 | 3 | 产品目录管理 |
| 方案行工具 | 3 | 交易方案行项 |
| 表单工具 | 2 | 表单列表和详情 |
| 分析工具 | 2 | 分析数据查询 |
| 营销邮件工具 | 3 | 营销邮件管理 |
| 列表工具 | 2 | 静态列表操作 |
| 知识库工具 | 2 | 知识库文章 |
| 文件工具 | 2 | 文件上传下载 |
| 工作流工具 | 2 | 工作流触发 |
| 对话工具 | 2 | 会话管理 |
### 工具注解机制
HubSpot 连接器实现了智能的工具注解系统，根据工具的性质自动添加安全提示注解：
```typescript
function applyCohortHygieneAnnotations(tool: ToolMetadata): ToolMetadata {
const shouldForceDestructiveHint =
DESTRUCTIVE_TOOL_NAME_PATTERN.test(tool.name) ||
FORCE_DESTRUCTIVE_TOOL_SET.has(tool.name);
const openWorldHint = !LOCAL_ONLY_TOOL_SET.has(tool.name);
return {
...tool,
requiresAuth: !AUTH_EXEMPT_TOOL_SET.has(tool.name),
annotations: {
...tool.annotations,
destructiveHint: shouldForceDestructiveHint ? true : tool.annotations?.destructiveHint,
openWorldHint,
},
};
}
```
**资料来源：** [connectors/hubspot/src/tools/definitions.ts:60-75]()
### 输入限制
为防止 API 限流和数据量过大，HubSpot 连接器定义了严格的输入限制：
| 参数类型 | 限制值 | 说明 |
|----------|--------|------|
| `limit` | 最大 100 | 单次请求返回记录数上限 |
| `properties` | 最大 200 | 单次请求指定属性数上限 |
| 批量操作 | 100 条/批次 | 大批量操作需分批处理 |
**资料来源：** [connectors/hubspot/src/tools/input-limits.ts]()
### 错误处理
HubSpot 连接器实现了结构化的错误处理机制，针对不同类型的 API 错误返回标准化的错误响应：
```typescript
if (error.statusCode === 404) {
return {
error: `${context.feature} not found`,
errorCode: 'NOT_FOUND',
suggestion: `Verify the ${context.feature} ID is correct.`
};
}
```
**资料来源：** [connectors/hubspot/src/tools/marketing-handlers.ts:50-60]()
## Zendesk 连接器
### 功能范围
Zendesk 连接器专注于客服工单管理，提供了完整的工单生命周期管理能力。
### 核心工具
| 工具名称 | 功能描述 | 操作类型 |
|----------|----------|----------|
| `list_zendesk_tickets` | 列出工单，支持状态和分页过滤 | 只读 |
| `get_zendesk_ticket` | 获取单个工单详情 | 只读 |
| `create_zendesk_ticket` | 创建新工单 | 写入 |
| `update_zendesk_ticket` | 更新工单状态、优先级等 | 写入 |
| `list_zendesk_users` | 列出终端用户和支持人员 | 只读 |
| `list_zendesk_macros` | 列出或搜索宏 | 只读 |
| `get_zendesk_macro` | 获取宏详情 | 只读 |
| `apply_zendesk_macro` | 预览并应用宏到工单 | 写入 |
### 配置要求
Zendesk 连接器需要通过 `ZENDESK_CONFIG_PATH` 环境变量指定配置目录，配置目录中需包含 `accounts.json` 文件：
```json
{
"subdomain": "your-company",
"email": "admin@example.com",
"api_token": "your-api-token"
}
```
**资料来源：** [connectors/zendesk/README.md]()
### 常见故障排查
| 症状 | 可能原因 | 解决方案 |
|------|----------|----------|
| 连接器启动失败 | 尚未构建 | 运行 `npm install && npm run build` |
| 认证错误或空结果 | 配置路径错误或凭据无效 | 检查 `ZENDESK_CONFIG_PATH` 和 `accounts.json` |
| MCP 协议问题 | stdio 会话中有 stdout 噪声 | 确保使用 `console.error` 进行日志输出 |
## Freshdesk 连接器
### 功能范围
Freshdesk 连接器提供了工单管理、客户服务和知识库访问能力。
### 核心工具
| 类别 | 工具名称 | 功能描述 |
|------|----------|----------|
| 工单 | `freshdesk_create_ticket` | 创建新客服工单 |
| 工单 | `freshdesk_list_tickets` | 列出工单，支持多种过滤条件 |
| 工单 | `freshdesk_get_ticket` | 获取工单详情 |
| 工单 | `freshdesk_update_ticket` | 更新工单状态或属性 |
| 工单 | `freshdesk_delete_ticket` | 删除工单 |
| 对话 | `freshdesk_create_reply` | 在工单下创建回复 |
| 对话 | `freshdesk_get_conversation` | 获取工单对话历史 |
| 解决方案 | `freshdesk_list_solutions` | 列出知识库文章 |
| 解决方案 | `freshdesk_get_solution` | 获取解决方案详情 |
| 客户 | `freshdesk_get_contact` | 获取客户/联系人信息 |
**资料来源：** [connectors/freshdesk/src/tools/tickets.ts]()
### 数据流示意
```mermaid
graph LR
A[MCP Host] -->|create_ticket| B[Freshdesk Connector]
B --> C[Freshdesk REST API]
C --> D{工单创建成功?}
D -->|是| E[返回工单 ID]
D -->|否| F[返回错误信息]
```
## Outreach 连接器
### 功能范围
Outreach 连接器专注于销售外展流程，支持潜在客户管理和序列自动化。
### 核心工具
| 工具名称 | 功能描述 | 操作类型 |
|----------|----------|----------|
| `list_outreach_prospects` | 列出潜在客户 | 只读 |
| `get_outreach_prospect` | 获取潜在客户详情 | 只读 |
| `create_outreach_prospect` | 创建新潜在客户 | 写入 |
| `update_outreach_prospect` | 更新潜在客户信息 | 写入 |
| `list_outreach_sequences` | 列出外展序列 | 只读 |
| `enroll_outreach_sequence` | 将潜在客户加入序列 | 写入 |
**资料来源：** [connectors/outreach/src/tools/prospects.ts]()
## 通用配置模式
### 配置文件结构
CRM 和客服连接器普遍采用基于文件的配置模式：
```
config-directory/
├── accounts.json # 账户凭据配置
└── credentials/ # 敏感凭据存储
└── *.token.json # OAuth 令牌文件
```
### 账户配置文件格式
```json
{
"subdomain": "平台子域",
"email": "管理员邮箱",
"api_token": "API 令牌"
}
```
### 环境变量配置
| 环境变量 | 连接器 | 说明 |
|----------|--------|------|
| `ZENDESK_CONFIG_PATH` | Zendesk | 配置文件目录路径 |
| `MS_CONFIG_DIR` | Microsoft 365 | Microsoft 配置目录 |
| `HUBSPOT_ACCESS_TOKEN` | HubSpot | HubSpot 私有应用访问令牌 |
## 安全最佳实践
### 令牌文件权限
所有包含敏感凭据的文件必须设置严格的文件权限：
- 令牌文件权限：`0600`（仅所有者可读写）
- 配置目录权限：`0700`（仅所有者可访问）
### 云端部署注意事项
在云端部署场景下，建议禁用连接器自身的令牌刷新能力：
```bash
MICROSOFT_DISABLE_REFRESH=1 # Microsoft 连接器
```
这样可以确保桌面会话是唯一的刷新令牌权威，避免单次使用刷新令牌的竞争条件。
**资料来源：** [connectors/microsoft-mail/README.md]()
## 输入验证与故障关闭
根据社区反馈（Issue #67），部分连接器已实现故障关闭（fail-closed）的输入验证机制。这确保了无效输入不会被静默接受并使用默认值，而是会抛出明确的 `McpError(InvalidParams)` 错误。
这种验证机制应用于：
- 必填字段的空值检查
- 必填参数的默认值检测
- 数据类型验证
## 性能优化建议
### 避免 API 限流
1. **合理设置分页大小**：单次请求量不超过平台限制
2. **使用批量工具**：需要处理多条记录时优先使用批量接口
3. **添加请求间隔**：高频操作间添加适当延迟
### 数据量控制
| 连接器 | 单次查询上限 | 建议 |
|--------|-------------|------|
| HubSpot | 100 条/页 | 使用游标分页遍历大结果集 |
| Zendesk | 100 条/页 | 结合时间过滤减少数据量 |
| Freshdesk | 30 条/页 | 使用服务端过滤 |
## 故障排查指南
### 认证失败
1. 验证 `accounts.json` 中的凭据是否正确
2. 检查 API 令牌是否有效且未过期
3. 确认配置文件路径正确设置
### 工具执行失败
1. 检查工具名称拼写是否正确
2. 验证参数类型和必填字段
3. 查看连接器日志确认错误详情
### 数据不同步
1. 确认目标平台的数据更新状态
2. 检查 Webhook 是否正常工作
3. 验证 OAuth 刷新令牌有效性
## 相关连接器
- [Google Workspace 连接器](./google-workspace) — 邮件和日历集成
- [Microsoft 365 Mail 连接器](./microsoft-mail) — Outlook 邮件操作
- [Office 连接器](./office) — 文档处理能力
## 参考资料
- HubSpot API 文档：https://developers.hubspot.com/docs/api/overview
- Zendesk API 文档：https://developer.zendesk.com/api-reference/
- Freshdesk API 文档：https://developers.freshdesk.com/api/
- Outreach API 文档：https://api.outreach.io/api/v2/
---
---
## Doramagic 踩坑日志
项目：mindstone/mcp-servers
摘要：发现 13 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: ci(pages): release commits to main bypass the catalogue-drift gate。
## 1. 安全/权限坑 · 失败模式：security_permissions: ci(pages): release commits to main bypass the catalogue-drift gate
- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: ci(pages): release commits to main bypass the catalogue-drift gate
- 对用户的影响：Developers may expose sensitive permissions or credentials: ci(pages): release commits to main bypass the catalogue-drift gate
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: ci(pages): release commits to main bypass the catalogue-drift gate. Context: Observed when using node
- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/mindstone/mcp-servers/issues/55
- 证据：failure_mode_cluster:github_issue | fmev_666f4299f397eb35a75616d6d577d2f2 | https://github.com/mindstone/mcp-servers/issues/55 | ci(pages): release commits to main bypass the catalogue-drift gate
## 2. 安全/权限坑 · 来源证据：Publish approval: google-workspace v0.1.2
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Publish approval: google-workspace v0.1.2
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_cda254fc0c504be3b3868bae771fc8e6 | https://github.com/mindstone/mcp-servers/issues/67 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 3. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `mcp-servers` 与安装入口 `@mindstone/mcp-server-google-workspace` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npx @mindstone/mcp-server-google-workspace`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | mcp_registry:io.github.mindstone/mcp-server-google-workspace:0.1.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.mindstone%2Fmcp-server-google-workspace/versions/0.1.2 | repo=mcp-servers; install=@mindstone/mcp-server-google-workspace
## 4. 安装坑 · 失败模式：installation: Publish approval: google-workspace v0.1.2
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Publish approval: google-workspace v0.1.2
- 对用户的影响：Developers may fail before the first successful local run: Publish approval: google-workspace v0.1.2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Publish approval: google-workspace v0.1.2. Context: Observed when using node
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_ceadd6904b4ab0cf84ff4f94f1151954 | https://github.com/mindstone/mcp-servers/issues/67 | Publish approval: google-workspace v0.1.2
## 5. 安装坑 · 失败模式：installation: Publish approval: hubspot v0.2.0
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Publish approval: hubspot v0.2.0
- 对用户的影响：Developers may fail before the first successful local run: Publish approval: hubspot v0.2.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Publish approval: hubspot v0.2.0. Context: Observed when using node
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_340ebf69d011beb0ee55df9cc658fe46 | https://github.com/mindstone/mcp-servers/issues/63 | Publish approval: hubspot v0.2.0
## 6. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:io.github.mindstone/mcp-server-google-workspace:0.1.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.mindstone%2Fmcp-server-google-workspace/versions/0.1.2 | README/documentation is current enough for a first validation pass.
## 7. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.mindstone/mcp-server-google-workspace:0.1.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.mindstone%2Fmcp-server-google-workspace/versions/0.1.2 | last_activity_observed missing
## 8. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:io.github.mindstone/mcp-server-google-workspace:0.1.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.mindstone%2Fmcp-server-google-workspace/versions/0.1.2 | no_demo; severity=medium
## 9. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:io.github.mindstone/mcp-server-google-workspace:0.1.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.mindstone%2Fmcp-server-google-workspace/versions/0.1.2 | no_demo; severity=medium
## 10. 安全/权限坑 · 来源证据：Publish approval: hubspot v0.2.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Publish approval: hubspot v0.2.0
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_31605309e751483ebe4289c7e27a9335 | https://github.com/mindstone/mcp-servers/issues/63 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 11. 安全/权限坑 · 来源证据：ci(pages): release commits to main bypass the catalogue-drift gate
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ci(pages): release commits to main bypass the catalogue-drift gate
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_67be881bdf36428099e1bc23b99554c8 | https://github.com/mindstone/mcp-servers/issues/55 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 12. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.mindstone/mcp-server-google-workspace:0.1.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.mindstone%2Fmcp-server-google-workspace/versions/0.1.2 | issue_or_pr_quality=unknown
## 13. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.mindstone/mcp-server-google-workspace:0.1.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.mindstone%2Fmcp-server-google-workspace/versions/0.1.2 | release_recency=unknown