项目简介

mcp-servers 是一个由 Mindstone 团队维护的 MCP (Model Context Protocol) 服务器集合，旨在为 AI 助手提供与各种企业服务和生产力工具集成的能力。该项目采用模块化架构，每个连接器（Connector）独立封装一个外部服务的集成逻辑，通过 MCP 协议与主机应用（如 Claude Desktop、Claude Code、Goose、Continue.dev 等）进行通信 资料来源：[README.md:1]。

MCP 协议是一种标准化的人机交互协议，允许 AI 模型通过统一的工具接口调用外部系统功能。该仓库中的所有连接器都遵循这一协议规范，实现了从简单的邮件发送到复杂的 CRM 数据操作的各类工具 资料来源：[README.md:1-5]。

项目架构

整体架构设计

项目采用 Monorepo 单体仓库结构，所有连接器位于 connectors/ 目录下，每个连接器都是一个独立的 Node.js 模块，拥有自己的 package.json、TypeScript 源码和构建配置。这种设计使得各服务集成可以独立开发、测试和发布，同时共享统一的代码规范和最佳实践 资料来源：[package.json:1-20]。

graph TD
    subgraph "MCP Host Layer"
        A[MCP Host<br/>Claude Desktop/Code<br/>Goose/Continue.dev]
    end
    
    subgraph "Connectors Layer"
        B[Office Connector]
        C[Google Workspace<br/>Connector]
        D[HubSpot Connector]
        E[Microsoft Teams<br/>Connector]
        F[Zendesk Connector]
        G[Google Analytics<br/>Connector]
        H[Napkin Connector]
        I[Nano Banana<br/>Connector]
        J[Microsoft SharePoint<br/>Connector]
    end
    
    subgraph "External Services"
        K[Microsoft 365]
        L[Google Workspace]
        M[HubSpot CRM]
        N[Various APIs]
    end
    
    A --> B
    A --> C
    A --> D
    A --> E
    A --> F
    A --> G
    A --> H
    A --> J
    
    B --> K
    C --> L
    D --> M
    E --> K
    F --> N
    G --> L
    J --> K

连接器目录结构

每个连接器遵循统一的项目结构，保证了代码的可维护性和一致性：

资料来源：[connectors/_template/package.json:1-30]

核心连接器一览

Microsoft Office 连接器

@mindstone/mcp-server-office 提供了对 Microsoft Office 套件的深度集成，支持 Word、Excel 和 PowerPoint 三大应用。该连接器提供了超过 53 个工具，涵盖文档操作、数据处理和演示管理三大领域 资料来源：[connectors/office/README.md:1-100]。

#### Word 工具（17个）

#### Excel 工具（22个）

资料来源：[connectors/office/README.md:1-80]

Google Workspace 连接器

@mindstone/mcp-server-google-workspace 集成了 Gmail、日历、Drive、Docs、Sheets、Slides、Contacts、Tasks 和 Forms 等 Google 服务。该连接器的最新版本 v0.1.2 引入了一个重要的行为变更：增加了 handleComposeWorkspaceEmail 的输入验证机制，在 to、subject、body 参数为空时不再静默使用默认值，而是抛出 McpError(InvalidParams) 错误 资料来源：[connectors/google-workspace/package.json:8-15]。

⚠️ 社区关注点：此变更在 Issue #67 和 PR #66 中讨论，是一次行为变更（Behaviour-changing），可能影响依赖旧行为的上游应用 资料来源：[社区上下文:#67]。

HubSpot 连接器

HubSpot CRM 连接器提供了全面的客户关系管理功能，包括联系人、公司、交易、工单、任务等核心模块的操作。连接器通过 src/tools/definitions.ts 导出了完整的工具定义列表，并通过 applyCohortHygieneAnnotations 函数为每个工具自动添加安全注解，包括 destructiveHint（破坏性提示）、openWorldHint（开放世界提示）等元数据 资料来源：[connectors/hubspot/src/tools/definitions.ts:1-50]。

资料来源：[connectors/hubspot/README.md:1-80]

Microsoft Teams 连接器

Microsoft 365 Teams 连接器允许通过 MCP 协议与 Microsoft Teams 进行交互。该连接器依赖 Microsoft Entra (Azure AD) 进行身份验证，需要配置 MS_CLIENT_ID 和 MS_CONFIG_DIR 环境变量 资料来源：[connectors/microsoft-teams/README.md:1-50]。

其他连接器

资料来源：[connectors/google-analytics/README.md:1], [connectors/zendesk/README.md:1], [connectors/napkin/README.md:1], [connectors/nano-banana/README.md:1]

技术规范

运行时要求

所有连接器均要求 Node.js 版本 18 或更高版本，使用 TypeScript 作为开发语言，并采用 ESM (ES Modules) 模块系统 资料来源：[connectors/google-workspace/package.json:25]。

{
  "engines": {
    "node": ">=18"
  },
  "type": "module"
}

构建流程

项目采用统一的构建脚本，通过 npm run build 命令执行以下步骤：

1. 清理 dist/ 目录
2. TypeScript 编译
3. 复制资源文件（如工具定义 JSON）
4. 设置可执行权限
5. 生成工具注解

npm install
npm run build

资料来源：[connectors/google-workspace/package.json:15-20]

许可证

该项目采用 FSL-1.1-MIT（Functional Source License, Version 1.1, with MIT future license）许可证。FSL 是一种"竞争性使用"许可证，在非竞争性用途下保持开源免费，在转换日期后自动转换为 MIT 许可证 资料来源：[connectors/napkin/README.md:1]。

安装与配置

MCP 主机配置示例

#### Claude Desktop / Cursor

{
  "mcpServers": {
    "Microsoft Office": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-office"],
      "env": {
        "MCP_OFFICE_SIDECAR_STATE": "/path/to/sidecar-state.json"
      }
    },
    "Google Workspace": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-google-workspace"]
    },
    "HubSpot": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-hubspot"],
      "env": {
        "HUBSPOT_CONFIG_PATH": "/path/to/hubspot/config"
      }
    }
  }
}

资料来源：[connectors/office/README.md:100-120]

本地开发配置

{
  "mcpServers": {
    "Microsoft Office": {
      "command": "node",
      "args": ["/path/to/repo/connectors/office/dist/index.js"],
      "env": {
        "MCP_OFFICE_SIDECAR_STATE": ""
      }
    }
  }
}

资料来源：[connectors/office/README.md:130-140]

工具注解系统

连接器实现了 MCP 工具注解系统，为每个工具提供元数据提示，帮助 MCP 主机做出更好的决策：

annotations: {
  readOnlyHint: false,
  destructiveHint: true,
  idempotentHint: false,
  openWorldHint: true,
}

资料来源：[connectors/office/src/index.ts:1-50]

错误处理机制

连接器实现了统一的错误处理系统，根据错误类型返回用户友好的错误消息：

资料来源：[connectors/office/src/shared/appBridge/shared/errors.ts:1-30]

常见问题排查

资料来源：[connectors/zendesk/README.md:40-50]

社区与贡献

相关社区资源

• Issue #67 - google-workspace v0.1.2 发布审批：引入了 handleComposeWorkspaceEmail 的输入验证变更，要求 to、subject、body 参数必须提供有效值，否则抛出 McpError(InvalidParams) 错误 资料来源：[社区上下文:#67]

版本迁移

项目维护者提供了 MIGRATION.md 文档，详细记录了各版本之间的 breaking changes 和升级路径。建议在升级连接器版本前仔细阅读该文档 资料来源：[MIGRATION.md:1]。

另请参阅

• Microsoft Office 连接器文档
• Google Workspace 连接器文档
• HubSpot 连接器文档
• Microsoft Teams 连接器文档
• Google Analytics 连接器文档
• Zendesk 连接器文档
• 迁移指南

概述

connectors/_template 目录提供了一个标准化的 MCP（Model Context Protocol）连接器开发模板，用于快速创建新的集成连接器。本模板定义了 Mindstone mcp-servers 项目中所有连接器的通用架构、最佳实践和代码组织规范。

模板目的

MCP 连接器模板的主要目的是：

• 统一开发标准：为所有新的连接器提供一致的代码结构和命名规范
• 加速开发：新连接器开发者可以直接复用模板框架，专注于业务逻辑实现
• 降低维护成本：标准化结构便于团队协作和代码审查
• 保证质量：内置错误处理、日志记录和安全最佳实践

资料来源：connectors/google-workspace/package.json:14-17

架构设计

整体架构

MCP 连接器采用标准的三层架构模式，通过标准输入输出（stdio）与主机应用通信。

graph TD
    subgraph MCP主机应用
        A[Claude Desktop / Cursor / Goose]
    end
    
    subgraph MCP连接器
        B[server.ts - MCP服务器核心]
        C[bridge.ts - 主机桥接层]
        D[tools/ - 工具定义]
        E[modules/ - 业务模块]
        F[types.ts - 类型定义]
        G[utils.ts - 工具函数]
    end
    
    subgraph 外部服务
        H[第三方API]
        I[OAuth服务]
    end
    
    A -->|"stdio JSON-RPC"| B
    B --> C
    C -->|"HTTP API"| H
    C -->|"OAuth"| I
    B --> D
    D --> E
    E --> F
    E --> G
    
    style A fill:#e1f5fe
    style H fill:#fff3e0
    style I fill:#f3e5f5

核心组件职责

资料来源：connectors/microsoft-sharepoint/README.md

工具注册模式

工具定义结构

每个 MCP 工具通过 server.registerTool() 方法注册，包含以下关键属性：

server.registerTool(TOOL_NAMES.toolName, {
  title: '工具显示名称',
  description: '工具功能描述',
  inputSchema: {
    type: "object",
    properties: {
      // 参数定义
    },
    required: ["必需参数"]
  },
  annotations: {
    readOnlyHint: false,        // 是否只读操作
    destructiveHint: false,     // 是否破坏性操作
    idempotentHint: false,      // 是否幂等操作
    openWorldHint: false        // 是否访问外部世界
  }
}, async (input) => {
  // 工具实现逻辑
});

资料来源：connectors/office/src/index.ts:1-50

工具分类注解

MCP 工具根据操作性质使用不同的注解标记：

认证与配置

环境变量配置

模板连接器支持以下标准环境变量：

资料来源：connectors/microsoft-teams/README.md

OAuth认证流程

对于需要OAuth的连接器（如Microsoft 365、Google Workspace），模板提供标准认证流程：

sequenceDiagram
    participant U as 用户
    participant H as MCP主机
    participant C as 连接器
    participant A as OAuth Provider
    
    U->>H: 触发认证工具
    H->>C: 调用 authenticate_* 工具
    C->>A: 请求OAuth授权
    A->>U: 显示授权页面
    U->>A: 确认授权
    A->>C: 返回授权码
    C->>A: 交换访问令牌
    A->>C: 返回令牌
    C->>C: 写入凭据文件 (mode 0600)
    C-->>H: 认证成功响应

错误处理规范

连接器使用结构化错误响应格式，便于主机应用进行错误恢复：

{
  error: '错误描述',
  errorCode: 'ERROR_CODE',
  suggestion: '修复建议',
  action_required?: '需要用户操作',
  next_step?: '下一步建议'
}

资料来源：connectors/microsoft-sharepoint/README.md

包配置规范

package.json 结构

{
  "name": "@mindstone/mcp-server-{connector-name}",
  "version": "0.1.0",
  "mcpName": "io.github.mindstone/mcp-server-{name}",
  "description": "连接器功能描述",
  "license": "FSL-1.1-MIT",
  "type": "module",
  "bin": {
    "mcp-server-{name}": "dist/index.js"
  },
  "engines": {
    "node": ">=18"
  },
  "scripts": {
    "build": "shx rm -rf dist && tsc && shx chmod +x dist/index.js",
    "start": "node dist/index.js",
    "test": "vitest run"
  }
}

资料来源：connectors/google-workspace/package.json:8-27

目录结构

connectors/
└── {connector-name}/
    ├── src/
    │   ├── index.ts          # 入口文件
    │   ├── server.ts         # MCP服务器
    │   ├── bridge.ts         # 桥接层
    │   ├── types.ts          # 类型定义
    │   ├── utils.ts          # 工具函数
    │   ├── tools/            # 工具实现
    │   │   ├── definitions/  # 工具Schema定义
    │   │   └── handlers/     # 工具处理器
    │   └── modules/          # 业务模块
    ├── dist/                 # 编译输出
    ├── package.json
    ├── tsconfig.json
    ├── README.md
    └── LICENSE

构建与部署

构建流程

cd connectors/{connector-name}
npm install
npm run build

编译过程执行以下操作：

1. 清理 dist/ 目录
2. TypeScript 编译
3. 复制静态资源（如工具Schema定义）
4. 设置可执行权限

运行模式

连接器支持三种运行模式：

输入验证最佳实践

必填参数校验

根据社区反馈（Issue #67），新版模板强调fail-closed（失败即止）输入验证策略：

// 错误示例 - 静默默认值
if (!input.to) input.to = "";  // 不推荐

// 正确示例 - 显式验证
if (!input.to || !input.subject || !input.body) {
  throw new McpError(InvalidParams, "Missing required fields: to, subject, body");
}

验证规则

日志记录规范

日志级别使用

日志输出位置

• stdio会话：所有日志必须输出到 stderr（console.error）
• 禁止：在stdio模式下使用 console.log，会破坏JSON-RPC协议

资料来源：connectors/zendesk/README.md

主机配置示例

Claude Desktop 配置

{
  "mcpServers": {
    "{ConnectorName}": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-{name}"],
      "env": {
        "{CONFIG_VAR}": "配置值"
      }
    }
  }
}

本地开发配置

{
  "mcpServers": {
    "{ConnectorName}": {
      "command": "node",
      "args": ["/path/to/connectors/{name}/dist/index.js"],
      "env": {
        "{CONFIG_VAR}": "配置值"
      }
    }
  }
}

常见问题排查

许可证

本模板及所有基于模板创建的连接器采用 FSL-1.1-MIT（Functional Source License, Version 1.1, with MIT future licence）许可证。

资料来源：connectors/zendesk/README.md

另请参阅

• Microsoft Office 连接器 - 完整的Office集成示例
• Microsoft Teams 连接器 - OAuth认证模式示例
• Google Workspace 连接器 - 多种服务集成示例
• HubSpot 连接器 - 复杂业务逻辑处理示例

概述

mcp-servers 是一个 MCP (Model Context Protocol) 服务器集合，为 AI 助手提供与各种企业服务和工具集成的能力。该项目采用模块化连接器架构，每个连接器对应一个外部服务（如 Google Workspace、Microsoft 365、HubSpot 等），通过 MCP 协议向 AI 主机暴露标准化的工具接口。

资料来源：connectors/google-workspace/package.json

整体架构

graph TD
    subgraph MCP主机层
        A[MCP Host<br/>Claude Desktop/Cursor]
    end
    
    subgraph 连接器层
        B[Google Workspace<br/>Connector]
        C[Microsoft 365<br/>Connector]
        D[HubSpot<br/>Connector]
        E[Office<br/>Connector]
        F[其他连接器]
    end
    
    subgraph 共享包层
        G[mcp-server-microsoft-shared]
    end
    
    subgraph 外部服务层
        H[Google APIs]
        I[Microsoft Graph API]
        J[HubSpot API]
        K[Office 应用程序]
    end
    
    A --> B
    A --> C
    A --> D
    A --> E
    A --> F
    
    C --> G
    E --> G
    
    B --> H
    C --> I
    D --> J
    E --> K
    G --> I

连接器架构

连接器目录结构

每个连接器都是一个独立的 Node.js 模块，具有相似的目录结构：

资料来源：connectors/google-workspace/src/tools/server.ts

工具注册模式

工具通过标准化的注册流程暴露给 MCP 主机：

graph LR
    A[工具定义<br/>definitions.ts] --> B[工具元数据<br/>ToolMetadata]
    B --> C[注册表<br/>registry.ts]
    C --> D[MCP 服务器<br/>index.ts]
    D --> E[MCP 主机]
    
    F[处理函数<br/>handlers.ts] --> C
    G[类型定义<br/>types.ts] --> B

工具元数据结构（ToolMetadata）包含以下核心属性：

资料来源：connectors/hubspot/src/tools/definitions.ts

行为注解系统

每个工具都通过注解系统声明其行为特征，帮助 AI 代理做出安全决策：

// 强制破坏性标记示例
const DESTRUCTIVE_TOOL_NAME_PATTERN = /^(create|update|delete|trash|remove|send)/;
const FORCE_DESTRUCTIVE_TOOL_SET = new Set(['rebel_office_word_insert_text']);

function applyCohortHygieneAnnotations(tool: ToolMetadata): ToolMetadata {
  const shouldForceDestructiveHint =
    DESTRUCTIVE_TOOL_NAME_PATTERN.test(tool.name) ||
    FORCE_DESTRUCTIVE_TOOL_SET.has(tool.name);
  // ...
}

资料来源：connectors/hubspot/src/tools/definitions.ts

Microsoft 共享包架构

mcp-server-microsoft-shared 是一个共享包，为所有 Microsoft 服务连接器提供通用功能。

graph TD
    subgraph mcp-server-microsoft-shared
        A[GraphClient]
        B[TokenProvider]
        C[类型定义]
    end
    
    subgraph Microsoft 连接器
        D[microsoft-teams]
        E[microsoft-sharepoint]
        F[microsoft-mail]
        G[office]
    end
    
    A --> D
    A --> E
    A --> F
    B --> D
    B --> E
    B --> F
    C --> D
    C --> E
    C --> F
    C --> G

Graph 客户端

GraphClient 封装了 Microsoft Graph API 的调用逻辑，提供标准化的请求/响应处理：

export class GraphClient {
  constructor(tokenProvider: TokenProvider, options?: ClientOptions);
  
  async get<T>(path: string, params?: Record<string, string>): Promise<T>;
  async post<T>(path: string, data: unknown): Promise<T>;
  async patch<T>(path: string, data: unknown): Promise<T>;
  async delete(path: string): Promise<void>;
}

资料来源：packages/mcp-server-microsoft-shared/src/graphClient.ts

令牌提供者

TokenProvider 负责 OAuth2 令牌的生命周期管理：

资料来源：packages/mcp-server-microsoft-shared/src/tokenProvider.ts

配置目录结构

Microsoft 连接器使用标准化的配置目录结构：

${MS_CONFIG_DIR}/
├── accounts.json          # 账户配置
├── credentials/           # OAuth 凭据存储
└── token-cache.json       # 令牌缓存

资料来源：connectors/microsoft-teams/README.md

Office 连接器架构

Office 连接器采用Sidecar 模式，通过独立的进程（sidecar）与 Office 应用程序通信。

graph TD
    subgraph MCP层
        A[MCP Server<br/>index.ts]
    end
    
    subgraph Sidecar进程
        B[Sidecar Server<br/>端口+令牌]
        C[Word Bridge]
        D[Excel Bridge]
        E[PowerPoint Bridge]
    end
    
    subgraph Office应用程序
        F[Word]
        G[Excel]
        H[PowerPoint]
    end
    
    A -->|"MCP_OFFICE_SIDECAR_STATE"| B
    B --> C
    B --> D
    B --> E
    C --> F
    D --> G
    E --> H

Sidecar 状态文件

Sidecar 状态文件（JSON）包含 MCP 服务器与 sidecar 进程通信所需的连接信息：

{
  "port": 12345,
  "token": "xxx-xxx-xxx"
}

资料来源：connectors/office/README.md

错误代码体系

Office 连接器定义了完整的错误代码体系：

export function toUserMessage(code: ErrorCode, label: string): string {
  switch (code) {
    case 'NOT_FOUND':
      return `I couldn't find that. Double-check the ID or selection and try again.`;
    case 'TIMEOUT':
      return `The operation timed out — the app was busy, try a smaller scope or try again.`;
    // ...
  }
}

资料来源：connectors/office/src/shared/appBridge/shared/errors.ts

认证与授权

Google Workspace 认证

Google Workspace 连接器使用 OAuth2 授权码流程：

sequenceDiagram
    participant AI as AI 代理
    participant MCP as MCP Server
    participant Google as Google APIs
    
    AI->>MCP: authenticate_workspace_account(email)
    MCP->>AI: 请求 auth_code
    Note over AI: 用户在浏览器完成授权
    AI->>MCP: authenticate_workspace_account(auth_code)
    MCP->>Google: 交换 access_token
    Google-->>MCP: access_token + refresh_token
    MCP->>MCP: 存储账户配置
    MCP-->>AI: 认证成功

资料来源：connectors/google-workspace/src/tools/types.ts

Google Analytics 认证

Google Analytics 连接器使用 Application Default Credentials (ADC)：

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/analytics.readonly,\
https://www.googleapis.com/auth/cloud-platform

资料来源：connectors/google-analytics/README.md

工具分类与组织

Google Workspace 工具分类

HubSpot 工具分类

资料来源：connectors/hubspot/README.md

Office 工具分类

资料来源：connectors/office/README.md

响应格式标准

所有 MCP 工具返回统一的标准响应格式：

export interface McpToolResponse {
  content: {
    type: 'text';
    text: string;
  }[];
  isError?: boolean;
  _meta?: Record<string, unknown>;
}

资料来源：connectors/google-workspace/src/tools/types.ts

输入验证与错误处理

Fail-Closed 验证模式

从 v0.1.2 开始，Google Workspace 连接器采用Fail-Closed（故障关闭）验证策略：

行为变更：在 handleComposeWorkspaceEmail 中新增了 fail-closed 输入验证门控。当 to/subject/body 参数为空时，不再静默使用默认值，而是抛出 McpError(InvalidParams) 错误。

资料来源：PR #66，社区讨论见 Issue #67

常见故障排除

资料来源：connectors/zendesk/README.md

部署模式

npx 模式（推荐）

{
  "mcpServers": {
    "Google Workspace": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-google-workspace"]
    }
  }
}

本地开发模式

{
  "mcpServers": {
    "Microsoft365Teams": {
      "command": "node",
      "args": ["/path/to/connectors/microsoft-teams/dist/index.js"],
      "env": {
        "MS_CLIENT_ID": "your-entra-application-client-id",
        "MS_CONFIG_DIR": "/absolute/path/to/microsoft-config"
      }
    }
  }
}

许可证

所有连接器采用 FSL-1.1-MIT（Functional Source License, Version 1.1, with MIT future licence）许可证。软件在 2030-04-08 自动转换为 MIT 许可证。

资料来源：connectors/google-workspace/package.json

相关文档

• Google Workspace 连接器
• Microsoft 365 Teams 连接器
• Microsoft SharePoint 连接器
• HubSpot 连接器
• Microsoft Office 连接器
• Google Analytics 连接器

概述

mcp-servers 仓库支持多种认证模式，以适配不同的外部服务和协议。认证模式分为三大类：

1. OAuth2 认证 — 适用于 Google Workspace、HubSpot、Microsoft 365 等需要 OAuth2 授权的云服务
2. 令牌认证 — 适用于 Slack 等使用静态 API Token 的服务
3. IMAP/SMTP 认证 — 适用于邮件服务的基础凭证认证

每种认证模式都由独立的模块处理，遵循统一的错误处理规范和账户管理接口。认证成功后，凭证会被持久化到本地配置文件，供后续请求复用。

资料来源：connectors/google-workspace/src/modules/accounts/oauth.ts:1-50

概述

mcp-servers 项目采用多层次的安全加固机制，涵盖供应链安全、凭证管理、输入验证、错误处理和发布流程等多个方面。这些机制共同构成了一个纵深防御体系，确保连接器在各种场景下的安全性。

项目核心安全原则包括：

• 失败安全（Fail-Closed）：默认拒绝未授权或不安全的操作
• 最小权限：仅请求必要的权限和作用域
• 原子性操作：确保敏感操作的完整性
• 透明审计：记录关键安全事件便于追踪

资料来源：SECURITY.md:1-20

概述

MCP 服务器项目为多个第三方服务（Google Workspace、Microsoft 365、Slack 等）提供 MCP（Model Context Protocol）集成。每个连接器都需要处理 OAuth 认证流程，项目采用统一的安全策略来保护令牌和用户凭据。

graph TD
    A[MCP Host Application] -->|OAuth Flow| B[第三方服务提供商]
    B -->|Access Token + Refresh Token| A
    A -->|写入令牌文件| C[Token Storage]
    C -->|读取令牌| D[MCP Connector]
    D -->|API调用| B
    
    C -.->|安全加固| E[权限控制 0o600]
    C -.->|安全加固| F[原子写入]
    C -.->|安全加固| G[符号链接防护]

令牌安全管理

令牌存储架构

所有 MCP 连接器采用统一的令牌存储结构，由主机应用管理 OAuth 流程并写入令牌文件，连接器仅读取这些文件而不发起 OAuth 请求。

graph LR
    A[主机应用 OAuth] -->|写入| B[Config Directory]
    B --> C[accounts.json]
    B --> D[credentials/]
    D --> E[${sanitised-email}.token.json]
    
    style B fill:#f9f,color:#000
    style E fill:#ff9,color:#000

令牌文件存储路径配置通过环境变量指定：

原子写入与权限控制

mcp-server-microsoft-shared 包实现了生产级的令牌安全机制：

• 原子写入：使用临时文件加重命名的模式（temp-file + rename），确保写入过程不会留下不完整的令牌文件
• 权限控制：令牌文件权限设置为 0o600（仅所有者读写），目录权限设置为 0o700
• 强制同步：使用 fsync 强制将数据写入磁盘
• 符号链接防护：拒绝跟随符号链接，防止目录遍历攻击
• 陈旧清理：初始化时执行陈旧临时文件扫描和清理

资料来源：packages/mcp-server-microsoft-shared/README.md:安全 notes

令牌刷新控制

云端部署场景下，主机应用需要完全控制令牌刷新流程：

// MICROSOFT_DISABLE_REFRESH=1 时，令牌刷新被禁用
// TokenProvider.getAccessToken 抛出 MicrosoftRefreshDisabledError
// 连接器捕获该错误并返回结构化的 auth_required 响应

资料来源：packages/mcp-server-microsoft-shared/README.md:Configuration

认证错误处理

统一错误响应格式

所有连接器采用统一的认证错误响应结构，确保 MCP Host 能够正确处理认证失败：

{
  status: 'auth_required',
  user_action: { id: 'google.connect_account' },
  agent_action: {
    instruction: "Connect Google Workspace to continue. The user will be redirected to Google's sign-in."
  },
  setupToolName: 'authenticate_workspace_account'
}

HTTP 状态码映射

资料来源：connectors/google-workspace/src/tools/server.ts:1-50

Slack 连接器错误代码

Slack 连接器定义了详细的错误代码体系：

资料来源：connectors/slack/src/types.ts:1-40

输入验证与故障安全

Gmail 邮件撰写验证

Google Workspace 连接器实现了 fail-closed（故障关闭）输入验证机制，在 handleComposeWorkspaceEmail 函数中添加了严格参数校验：

// 验证逻辑：以下字段不能为空或默认值
// - to: 收件人地址
// - subject: 邮件主题
// - body: 邮件正文

// 验证失败时抛出 McpError(InvalidParams)
// 避免静默发送空值邮件

常见错误避免：

资料来源：connectors/google-workspace/src/tools/definitions/gmail.ts:1-30

速率限制处理

当遇到速率限制时，连接器返回结构化错误响应：

{
  "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）采用共享认证基础设施：

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 > standalone_oauth > manual_token > unconfigured

资料来源：connectors/google-workspace/README.md:Tools (94)

安全审计与监控

成功响应包装

所有工具的成功响应遵循统一的成功结果格式：

{
  "ok": true,
  "result": { ... }
}

错误响应结构

业务错误和验证错误返回以下结构，确保主机恢复层能够采取行动：

{
  "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 信号管理

部署安全建议

本地开发环境

# 使用 npx 直接运行（自动处理依赖）
npx -y @mindstone/mcp-server-google-workspace

云端部署

Claude Desktop 配置示例

{
  "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 连接器 — Gmail、日历、Drive、Docs、Sheets、Slides 集成
• Microsoft 365 Mail — Outlook 邮件集成
• Microsoft Teams — Teams 消息和频道集成
• Microsoft SharePoint — SharePoint 文件集成
• Slack 连接器 — Slack 工作区集成

参考资料

• TokenProvider 安全实现：packages/mcp-server-microsoft-shared/README.md
• Google Workspace 认证流程：connectors/google-workspace/src/tools/server.ts
• Gmail 输入验证：connectors/google-workspace/src/tools/definitions/gmail.ts
• Slack 错误代码体系：connectors/slack/src/types.ts
• Microsoft 共享认证库：packages/mcp-server-microsoft-shared/README.md

概述

Google Workspace 连接器是 Mindstone MCP 服务器项目中的一个核心组件，为 MCP (Model Context Protocol) 主机提供与 Google Workspace 服务的集成能力。该连接器支持 Gmail、Calendar、Drive、Docs、Sheets、Slides、Contacts、Tasks 和 Forms 等多项 Google Workspace 服务的操作，使 AI 代理能够代表用户执行各种办公任务。

资料来源：connectors/google-workspace/package.json:4-5

核心特性

资料来源：connectors/google-workspace/src/tools/definitions/index.ts:1-15

概述

Microsoft 365 连接器套件是 mcp-servers 项目中用于与 Microsoft 365 服务集成的 MCP（Model Context Protocol）服务器集合。该套件通过 Microsoft Graph API 提供对 Microsoft 365 核心服务的标准化访问能力。

套件包含多个独立的 MCP 连接器，分别对应不同的 Microsoft 365 服务：

架构设计

共享认证层

Microsoft 365 连接器套件采用共享认证架构，所有连接器共享同一套 OAuth 2.0 认证体系。核心认证逻辑封装在 mcp-server-microsoft-shared 包中：

graph TD
    A[主机应用 Host Application] --> B[mcp-server-microsoft-mail<br/>authenticate_microsoft_account]
    B --> C[MS Graph OAuth 2.0<br/>Microsoft Entra ID]
    C --> D[credentials/accounts.json<br/>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

Graph API 客户端封装

所有连接器通过统一的 Graph 客户端与 Microsoft Graph API 交互。共享包提供了标准化的请求处理、错误转换和超时管理机制。

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

认证与配置

必需环境变量

可选环境变量

MCP 主机配置示例

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

认证流程

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 连接器套件的核心组件，负责邮件、日历和联系人的基础认证。

主要工具

安全注意事项

• 令牌文件以 0600 权限模式写入主机，由共享库以严格模式读取
• 云端表面默认设置 MICROSOFT_DISABLE_REFRESH=1，避免单次使用刷新令牌的竞争
• 成功响应使用标准 successResult 格式；错误响应返回 isError:true 并包含 action_required 和 next_step 字段

资料来源：connectors/microsoft-mail/README.md

Microsoft Teams 连接器

mcp-server-microsoft-teams 提供 Microsoft Teams 消息、频道和会议的管理能力。

主要工具

与邮件连接器的认证共享

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

Microsoft SharePoint 连接器

mcp-server-microsoft-sharepoint 提供 SharePoint Online 网站、文档库和列表的管理能力。

主要工具

增量认证

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

Microsoft Calendar 连接器

mcp-server-microsoft-calendar 提供日历事件的完整 CRUD 操作能力。

主要工具

Microsoft Files 连接器

mcp-server-microsoft-files 提供 OneDrive 个人云存储的文件管理能力。

主要工具

错误处理

错误响应格式

所有 Microsoft 365 连接器采用统一的错误响应格式：

{
  "isError": true,
  "data": {
    "ok": false,
    "error": "错误消息描述",
    "errorCode": "ERROR_CODE",
    "action_required": "需要的操作步骤",
    "next_step": "下一步建议"
  }
}

认证错误处理

超时管理

每个工具的 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

常见故障排除

社区相关问题

Google Workspace 输入验证增强

虽然此问题针对 Google Workspace 连接器，但它反映了 Microsoft 365 连接器套件中类似的最佳实践趋势：

行为变更。 为 handleComposeWorkspaceEmail 添加了之前不存在的 fail-closed 输入验证门。当 to/subject/body 本应被静默默认为空值时，抛出 McpError(InvalidParams)。

Microsoft 365 连接器套件同样遵循严格的输入验证模式，确保 API 调用的参数完整性。

资料来源：社区上下文 #67

本地开发

构建所有连接器

cd <path-to-repo>/connectors/microsoft-mail
npm install
npm run build

cd <path-to-repo>/connectors/microsoft-teams
npm install
npm run build

cd <path-to-repo>/connectors/microsoft-sharepoint
npm install
npm run build

本地运行配置

{
  "mcpServers": {
    "Microsoft365Mail": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/microsoft-mail/dist/index.js"],
      "env": {
        "MS_CLIENT_ID": "your-entra-application-client-id",
        "MS_CONFIG_DIR": "/absolute/path/to/microsoft-config"
      }
    }
  }
}

资料来源：connectors/microsoft-teams/README.md

相关连接器

• Microsoft Office 连接器 — Word、Excel、PowerPoint 桌面集成
• Google Workspace 连接器 — Gmail、Google Calendar、Google Drive 集成
• HubSpot 连接器 — CRM、销售和营销自动化
• 共享认证库 — Microsoft 365 认证核心组件

许可证

所有 Microsoft 365 连接器使用 FSL-1.1-MIT — 功能源许可证，版本 1.1，附带 MIT 未来许可证。软件将于 2030 年 4 月 8 日转换为 MIT 许可证。

概述

生产力工具连接器（P roductivity Tools Connectors）是 mindstone/mcp-servers 仓库中的一组 MCP（Model Context Protocol）服务器实现，用于将各种主流办公软件和 SaaS 平台与 AI 助手进行集成。这些连接器通过标准化的 MCP 协议暴露工具接口，使 AI 助手能够直接操控目标系统的数据和功能，无需用户手动切换应用程序。

仓库中的连接器覆盖以下主要类别：

所有连接器均采用 FSL-1.1-MIT 许可证，功能源代码许可证版本 1.1，附带 MIT 未来许可证，软件将于 2030 年 4 月 8 日转换为 MIT 许可证。

架构设计

MCP 服务器通用模式

每个连接器都是一个独立的 Node.js 包，通过标准输入/输出（stdio）协议与 MCP 主机进行通信。服务器接收 JSON-RPC 格式的请求并返回结构化响应。

graph TD
    A["MCP 主机<br/>(Claude Desktop/Cursor等)"] <-->|"JSON-RPC over stdio"| B["MCP 连接器服务器"]
    B --> C["第三方 API / SDK"]
    B --> D["认证凭据存储"]
    C --> E["外部服务<br/>(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

graph TD
    A["MCP 主机"] <-->|"stdio"| B["MCP Office 服务器<br/>dist/index.js"]
    B <-->|"port + token<br/>sidecar-state.json"| C["Sidecar 进程"]
    C <-->|"WebSocket"| D["Office 加载项"]
    D <-->|"Office.js API"| E["Office 应用<br/>(Word/Excel/PowerPoint)"]
    
    F["环境变量"] --> B
    G["环境变量"] --> C

认证与凭据管理

Microsoft 产品线连接器采用共享的认证体系：

资料来源：connectors/microsoft-teams/README.md

云端表面默认设置 MICROSOFT_DISABLE_REFRESH=1，使桌面会话成为唯一的刷新令牌权威，避免单次使用刷新令牌的竞争条件。

工具分类与功能

Office 连接器工具集

Office 连接器提供 53 个工具，分为以下类别：

#### 设置工具（2 个）

#### Word 工具（17 个）

资料来源：connectors/office/README.md

#### Excel 工具（22 个）

#### PowerPoint 工具（14 个）

HubSpot 连接器工具集

HubSpot 连接器提供全面的 CRM 功能，包括以下工具类别：

资料来源：connectors/hubspot/src/tools/definitions.ts:1-30

HubSpot 错误处理采用统一的错误解析机制，根据错误类型返回结构化的错误信息：

// 错误类型映射
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

Google Workspace 连接器

Google Workspace 连接器的 Gmail 功能支持以下操作：

重要变更（v0.1.2）：

⚠️ 行为变更 — PR #66 在 handleComposeWorkspaceEmail 中添加了 fail-closed（故障关闭）输入验证门控，此前该门控不存在。当 to/subject/body 本应静默默认为空值时，现在会抛出 McpError(InvalidParams)。

资料来源：PR #66、社区讨论 #67

#### Gmail 工具使用示例

纯文本邮件：

{
  "to": ["[email protected]"],
  "subject": "会议通知",
  "body": "Hi Alice,\\n\\n我们明天3点能见面吗？\\n\\n谢谢，\\nBob"
}

HTML 格式邮件：

{
  "to": ["[email protected]"],
  "subject": "会议纪要",
  "body": "<p>Hi Alice,</p><p>会议要点：</p><ul><li>预算已批准</li><li>发布日期：3月1日</li></ul>",
  "is_html": true
}

回复邮件：

{
  "to": ["[email protected]"],
  "subject": "Re: 会议安排",
  "body": "听起来不错！\n\nOn Mon, Jan 6, 2026 at 10:00 AM, Alice <[email protected]> wrote:\n> 明天我们还见面吗？",
  "reply_to_message_id": "18c5a2b3d4e5f6g7"
}

资料来源：connectors/google-workspace/src/tools/definitions/gmail.ts

其他专业连接器

#### Zendesk 连接器

资料来源：connectors/zendesk/README.md

#### Google Analytics 连接器

资料来源：connectors/google-analytics/README.md

#### AI/视觉工具连接器

NanoBanana 特殊配置：

资料来源：connectors/nano-banana/README.md

工具注解系统

MCP 连接器使用标准化的注解系统来标记工具的行为特性：

annotations: {
  readOnlyHint: true,
  destructiveHint: false,
  idempotentHint: true,
  openWorldHint: false,
}

资料来源：connectors/office/src/index.ts

对于名称包含 delete、remove、destroy 等模式或被列入 FORCE_DESTRUCTIVE_HINT 集合的工具，系统自动强制设置 destructiveHint: true。

错误处理机制

统一错误响应格式

连接器采用统一的错误响应结构，便于 MCP 主机进行错误恢复：

{
  error: '错误描述',
  errorCode: 'ERROR_CODE',
  suggestion: '用户友好的修复建议',
  details: { /* 可选的详细信息 */ }
}

Office 错误代码映射

资料来源：connectors/office/src/shared/office/errors.ts:20-40

HubSpot 错误处理

快速开始

安装与构建

# 进入连接器目录
cd connectors/<connector-name>

# 安装依赖
npm install

# 构建项目
npm run build

本地运行

# 直接运行编译后的 JavaScript
node dist/index.js

MCP 主机配置

#### Claude Desktop 配置示例

{
  "mcpServers": {
    "Microsoft Office": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-office"],
      "env": {
        "MCP_OFFICE_SIDECAR_STATE": ""
      }
    },
    "HubSpot": {
      "command": "node",
      "args": ["/path/to/repo/connectors/hubspot/dist/index.js"],
      "env": {
        "HUBSPOT_CONFIG_PATH": "/path/to/config"
      }
    }
  }
}

配置参考

Office 连接器环境变量

HubSpot 连接器环境变量

accounts.json 格式：

{
  "subdomain": "your-company",
  "email": "[email protected]",
  "apiKey": "your-private-app-token"
}

Microsoft 产品连接器环境变量

安全注意事项

所有连接器的成功响应遵循标准 successResult 格式；业务错误返回 isError: true 和 { ok: false, error, action_required, next_step } 有效载荷，便于主机恢复层处理。

故障排查

常见问题与解决方案

Office 连接器烟雾测试

MCP_OFFICE_SIDECAR_STATE=/tmp/rebel-office-smoke/sidecar-state.json \
  node dist/index.js

发送 listTools MCP 请求到标准输入，应返回完整的工具清单。服务器无需活动的 sidecar 即可响应 listTools 请求。

Zendesk 连接器烟雾测试

在 MCP 主机中运行：

列出我的待处理 Zendesk 工单

如果失败，请确认：

• dist/index.js 存在（运行 npm run build）
• ZENDESK_CONFIG_PATH 指向可读目录
• accounts.json 包含有效的子域、邮箱和 API 令牌

参见

• Microsoft Office 架构文档
• HubSpot 连接器源码
• Google Workspace Gmail 工具定义
• Office 错误处理模块
• MCP 协议官方文档

概述

MCP Servers 仓库提供了一系列专注于客户关系管理（CRM）和客服系统的连接器，使 AI 代理能够与主流 CRM 平台和客服工具进行交互。这些连接器通过 Model Context Protocol (MCP) 标准接口暴露工具函数，实现对客户数据、工单、线索、交易等业务对象的读取和操作。

支持的平台：

架构概览

CRM 与客服连接器遵循统一的技术架构模式，每个连接器都是一个独立的 MCP 服务器，通过标准输入输出（stdio）进行通信。

graph TD
    A[MCP Host<br/>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[配置文件<br/>accounts.json] --> B
    J[环境变量] --> B

HubSpot 连接器

功能范围

HubSpot 连接器是最全面的 CRM 连接器，提供了对 HubSpot CRM 几乎所有核心对象的访问能力。工具按照功能分为多个类别：

资料来源： connectors/hubspot/src/tools/definitions.ts:1-50

工具分类

工具注解机制

HubSpot 连接器实现了智能的工具注解系统，根据工具的性质自动添加安全提示注解：

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 连接器定义了严格的输入限制：

资料来源： connectors/hubspot/src/tools/input-limits.ts

错误处理

HubSpot 连接器实现了结构化的错误处理机制，针对不同类型的 API 错误返回标准化的错误响应：

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 连接器专注于客服工单管理，提供了完整的工单生命周期管理能力。

核心工具

配置要求

Zendesk 连接器需要通过 ZENDESK_CONFIG_PATH 环境变量指定配置目录，配置目录中需包含 accounts.json 文件：

{
  "subdomain": "your-company",
  "email": "[email protected]",
  "api_token": "your-api-token"
}

资料来源： connectors/zendesk/README.md

常见故障排查

Freshdesk 连接器

功能范围

Freshdesk 连接器提供了工单管理、客户服务和知识库访问能力。

核心工具

资料来源： connectors/freshdesk/src/tools/tickets.ts

数据流示意

graph LR
    A[MCP Host] -->|create_ticket| B[Freshdesk Connector]
    B --> C[Freshdesk REST API]
    C --> D{工单创建成功?}
    D -->|是| E[返回工单 ID]
    D -->|否| F[返回错误信息]

Outreach 连接器

功能范围

Outreach 连接器专注于销售外展流程，支持潜在客户管理和序列自动化。

核心工具

资料来源： connectors/outreach/src/tools/prospects.ts

通用配置模式

配置文件结构

CRM 和客服连接器普遍采用基于文件的配置模式：

config-directory/
├── accounts.json          # 账户凭据配置
└── credentials/           # 敏感凭据存储
    └── *.token.json       # OAuth 令牌文件

账户配置文件格式

{
  "subdomain": "平台子域",
  "email": "管理员邮箱",
  "api_token": "API 令牌"
}

环境变量配置

安全最佳实践

令牌文件权限

所有包含敏感凭据的文件必须设置严格的文件权限：

• 令牌文件权限：0600（仅所有者可读写）
• 配置目录权限：0700（仅所有者可访问）

云端部署注意事项

在云端部署场景下，建议禁用连接器自身的令牌刷新能力：

MICROSOFT_DISABLE_REFRESH=1  # Microsoft 连接器

这样可以确保桌面会话是唯一的刷新令牌权威，避免单次使用刷新令牌的竞争条件。

资料来源： connectors/microsoft-mail/README.md

输入验证与故障关闭

根据社区反馈（Issue #67），部分连接器已实现故障关闭（fail-closed）的输入验证机制。这确保了无效输入不会被静默接受并使用默认值，而是会抛出明确的 McpError(InvalidParams) 错误。

这种验证机制应用于：

• 必填字段的空值检查
• 必填参数的默认值检测
• 数据类型验证

性能优化建议

避免 API 限流

1. 合理设置分页大小：单次请求量不超过平台限制
2. 使用批量工具：需要处理多条记录时优先使用批量接口
3. 添加请求间隔：高频操作间添加适当延迟

数据量控制

故障排查指南

认证失败

1. 验证 accounts.json 中的凭据是否正确
2. 检查 API 令牌是否有效且未过期
3. 确认配置文件路径正确设置

工具执行失败

1. 检查工具名称拼写是否正确
2. 验证参数类型和必填字段
3. 查看连接器日志确认错误详情

数据不同步

1. 确认目标平台的数据更新状态
2. 检查 Webhook 是否正常工作
3. 验证 OAuth 刷新令牌有效性

相关连接器

• Google Workspace 连接器 — 邮件和日历集成
• Microsoft 365 Mail 连接器 — Outlook 邮件操作
• 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/

Pitfall Log / 踩坑日志

项目：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