google-calendar-mcp-server: Instructions file for Claude Code

Google Calendar MCP Server 开发指导

项目概述

这是一个基于 Model Context Protocol (MCP) 的 Google Calendar 集成服务，提供了完整的日历事件管理功能。项目使用 TypeScript 开发，通过 MCP SDK 与 Claude 集成，支持单一和批量操作，并具备企业级的错误处理和重试机制。

核心架构

技术栈

• TypeScript: ES模块 (ESNext)
• MCP SDK: @modelcontextprotocol/sdk v0.4.0+
• Google APIs: googleapis v126.0.1+
• 验证库: Zod v3.22.4+
• 运行时: Node.js 18+

项目结构

google_chrome_calendar_server/
├── src/
│   ├── index.ts              # MCP Server 主入口
│   ├── services/
│   │   ├── auth.ts           # OAuth2 认证服务
│   │   ├── calendar.ts       # Google Calendar API 封装
│   │   └── config.ts         # 配置管理
│   ├── tools/
│   │   ├── create-event.ts   # 创建事件工具
│   │   ├── update-event.ts   # 更新事件工具
│   │   ├── delete-event.ts   # 删除事件工具
│   │   ├── list-events.ts    # 列表事件工具
│   │   ├── search-events.ts  # 搜索事件工具
│   │   ├── batch-create-events.ts  # 批量创建
│   │   ├── batch-update-events.ts  # 批量更新
│   │   └── batch-delete-events.ts  # 批量删除
│   ├── utils/
│   │   ├── validation.ts     # 输入验证
│   │   ├── error.ts          # 错误处理
│   │   └── retry.ts          # 重试机制
│   └── types/
│       └── calendar.ts       # 类型定义
├── config/
│   ├── config.json           # 应用配置
│   ├── credentials.json      # Google OAuth2 凭证
│   └── token.json           # OAuth2 令牌（自动生成）
└── dist/                     # 编译输出目录

关键实现细节

1. Google Calendar API 特性

更新事件的重要注意事项

Google Calendar API 在更新事件时要求提供完整的事件数据，而不是仅提供更改的字段。必须先获取现有事件，然后合并更新：

async updateEvent(input: UpdateEventInput): Promise<CalendarEvent> {
  // 先获取现有事件数据 - 这是关键步骤！
  const existingEvent = await this.calendar.events.get({
    calendarId: this.configManager.getDefaultCalendarId(),
    eventId: input.eventId,
  });

  // 保留所有现有数据，仅更新提供的字段
  const updateData = {
    summary: existingEvent.data.summary,
    start: existingEvent.data.start,
    end: existingEvent.data.end,
    // ... 其他必需字段
  };

  // 应用更新
  if (input.summary !== undefined) updateData.summary = input.summary;
  // ... 更多字段更新
}