AI导哈

日历管理服务器

一个基于Cloudflare Workers的模型上下文协议(MCP)服务器，集成了WorkOS AuthKit进行身份验证，提供自动日历管理、预约安排、电子邮件通知和报告检索功能。

  • by EmaadAkhter
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 EmaadAkhter/google-calendar-mcp

使用说明

集成AuthKit的MCP服务器

一个基于Cloudflare Workers构建的综合模型上下文协议（MCP）服务器，它与WorkOS AuthKit集成用于身份验证，并提供自动化的日历管理、预约安排、电子邮件通知和报告检索功能。

🌟 特点

核心功能

  • OAuth 认证使用WorkOS AuthKit实现安全的认证流程
  • Google日历集成全面的日历管理，支持亚洲/加尔各答时区
  • 自动提醒在会议前30分钟发送电子邮件提醒的后台服务
  • 电子邮件通知通过Gmail API实现自动预约确认和提醒
  • 报告管理通过联系信息检索用户报告

可用工具

📅 预约管理

  • 安排预约创建包含全面用户信息的新预约
  • 取消预约通过标题、日期或用户信息取消现有预约
  • 重新安排预约将预约移动到新的日期/时间
  • 获取用户预约检索特定用户的即将预约事项
  • 推荐预约时间在特定日期查找可用的45分钟时间段

📧 电子邮件工具

  • 发送预约邮件发送包含会议详情的预约确认邮件

📊 报表工具

  • 通过联系人获取报告使用电话号码或电子邮件检索用户报告
  • 直接测试APIAPI端点测试的诊断工具

🕐 实用工具

  • 获取当前日期获取当前UTC日期，格式为YYYY-MM-DD

🏗️ 项目结构

.
├── src/
│   ├── automation/
│   │   └── calendarreminder.ts      # Automated reminder service
│   ├── tools/
│   │   ├── appointment.ts            # Shared appointment utilities
│   │   ├── cancelAppointmentTool.ts  # Cancel appointment tool
│   │   ├── date.ts                   # Date utility tool
│   │   ├── getUserAppointmentsTool.ts # Get user appointments
│   │   ├── mail.ts                   # Email utilities and tools
│   │   ├── recommendAppointmentTimesTool.ts # Availability checker
│   │   ├── report.ts                 # Report retrieval tools
│   │   ├── rescheduleAppointmentTool.ts # Reschedule appointments
│   │   └── scheduleAppointmentTool.ts # Schedule new appointments
│   ├── authkit-handler.ts            # OAuth authorization flow
│   ├── index.ts                      # Main entry point and server setup
│   └── props.ts                      # TypeScript type definitions
├── .dev.vars.example                 # Example environment variables
├── .gitignore                        # Git ignore rules
├── README.md                         # This file
├── biome.json                        # Biome configuration
├── package.json                      # Node.js dependencies
└── package-lock.json                 # Locked dependencies

🚀 开始使用

先决条件

  • Node.js 18 或更高版本
  • npm 或 yarn 包管理器
  • Cloudflare Workers 账户
  • 已配置AuthKit的WorkOS账户
  • 启用日历和Gmail API的Google Cloud项目

安装

  1. 克隆仓库

    git clone <repository-url>
cd <project-directory>

  2. 安装依赖项

    npm install

  3. 配置环境变量

    创建一个 .dev.vars 基于文件的（或：以文件为基础的） .dev.vars.example：

    cp .dev.vars.example .dev.vars

    所需的环境变量：

    WORKOS_CLIENT_ID=your_workos_client_id
WORKOS_CLIENT_SECRET=your_workos_client_secret
GOOGLE_ACCESS_TOKEN=your_google_oauth_token

  4. 配置 Cloudflare Worker

    更新您的 wrangler.jsonc （或 wrangler.toml（与）以下内容一起：

    • KV 命名空间绑定
    • 持久对象绑定
    • 特定环境的设置

发展

在本地运行开发服务器：

npm run dev

服务器将在 http://localhost:8787 （或您配置的端口）。

部署

部署到Cloudflare Workers：

npm run deploy

或者直接使用 Wrangler：

npx wrangler deploy

🔧 配置

Google日历与Gmail设置

  1. 创建一个Google云项目

  2. 启用所需API

    • 谷歌日历API
    • Gmail API

  3. 创建OAuth 2.0凭据

    • 导航至“APIs和服务”>“凭据”
    • 创建OAuth 2.0客户端ID
    • 添加授权重定向URI

  4. 生成访问令牌

    • 使用 OAuth 2.0 Playground 或您自己的流程
    • 所需范围：
      • https://www.googleapis.com/auth/calendar
      • https://www.googleapis.com/auth/gmail.send
    • 添加令牌到 .dev.vars as（作为） GOOGLE_ACCESS_TOKEN

WorkOS AuthKit 设置

  1. 创建WorkOS账户

  2. 配置应用程序

    • 创建一个新的AuthKit应用程序
    • 设置重定向URI以匹配您的部署：
      http://localhost:8787/callback (for development)
https://your-worker.workers.dev/callback (for production)

  3. 获取凭据

    • 复制客户端ID和客户端密钥
    • 添加到 .dev.vars：
      WORKOS_CLIENT_ID=client_xxx
WORKOS_CLIENT_SECRET=sk_xxx

Cloudflare Workers 配置

  1. 创建KV命名空间

    wrangler kv:namespace create "OAUTH_KV"
wrangler kv:namespace create "OAUTH_KV" --preview

  2. 创建持久对象

    • 确保 MCP_OBJECT 已正确配置于 wrangler.jsonc

  3. 添加绑定 更新你的 wrangler.jsonc：

    {
  "kv_namespaces": [
    {
      "binding": "OAUTH_KV",
      "id": "your-kv-namespace-id"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "name": "MCP_OBJECT",
        "class_name": "MyMCP"
      }
    ]
  }
}

API 参考

预约安排

预约

scheduleAppointment({
  userName: "John Doe",
  userEmail: "john@example.com",
  userPhone: "+911234567890",
  summary: "Product Consultation",
  description: "Discuss new features",
  appointmentType: "online", // or "offline"
  date: "tomorrow",
  startTime: "10:00",
  attendees: ["jane@example.com"],
  checkAvailability: true,
  sendReminder: true
})

推荐可用时间

recommendAppointmentTimes({
  date: "2024-11-15" // or "tomorrow", "next week"
})

取消预约

cancelAppointment({
  summary: "Product Consultation",
  date: "2024-10-26",
  userName: "John Doe",
  userEmail: "john@example.com",
  exactMatch: false
})

重新安排预约

rescheduleAppointment({
  summary: "Product Consultation",
  currentDate: "2024-10-26",
  userEmail: "john@example.com",
  newDate: "next week",
  newStartTime: "14:00",
  newSummary: "Product Demo", // optional
  checkAvailability: true,
  forceProceed: true
})

获取用户预约

getUserAppointments({
  userName: "John Doe",
  userEmail: "john@example.com",
  userPhone: "+911234567890"
})

报告检索

按联系人获取报告

get_report_by_contact({
  phone: "+911234567890",
  email: "john@example.com",
  limit: 10
})

日期表达式

该系统支持自然语言日期表达式：

  • "today" - 当前日期
  • "tomorrow" - 第二天
  • "yesterday" - 前一天
  • "10 days from now" - 提前10天日期
  • "in 5 days" - 提前5天告知日期
  • "5 days ago" - 5天前的日期
  • "next week" - 提前7天告知日期
  • "next month" - 提前一个月告知日期
  • "YYYY-MM-DD" - 具体日期（例如，“2024-12-25”）

🤖 自动化功能

日历提醒服务

后台提醒服务会自动：

  • 支票 每两分钟安排一次即将召开的会议
  • 发送 会议前30分钟发送电子邮件提醒（时间窗口±5分钟）
  • 轨迹/音轨 使用键值存储发送提醒，以避免重复
  • 手柄；把手 相应地拒绝了参会者
  • 格式 包含会议详情和时间的电子邮件

配置常量：

REMINDER_MINUTES = 30        // Send reminder 30 min before
CHECK_INTERVAL_MS = 120000   // Check every 2 minutes

当工作者初始化时，服务自动启动并在后台持续运行。

🔒 安全

  • OAuth 2.0 认证通过 WorkOS AuthKit
  • 安全令牌管理存储在Cloudflare KV中并加密
  • 基于环境的机密信息没有硬编码的凭据
  • 基于权限的访问根据全局信息，翻译目标语言为中文。原文内容“Scoped API access tokens”翻译为中文是“作用域限定的API访问令牌”
  • 输入验证对所有工具输入进行Zod模式验证

🛠️ 开发

类型安全

  • 全面支持TypeScript，并启用严格模式
  • 使用Zod进行模式验证以实现运行时类型检查
  • 全面的类型定义在 props.ts

代码质量

  • 生物群系（或生物群落） 用于代码检查和格式化
  • 配置于 biome.json
  • 运行检查：
    npm run lint
npm run format

测试

# Test locally
npm run dev

# Test specific endpoints
curl http://localhost:8787/authorize

📝 环境变量

变量 描述 必填 示例
中文翻译 英文原文 中文翻译 英文原文
WORKOS_CLIENT_SECRET sk_xxx WorkOS 密钥 是
GOOGLE_ACCESS_TOKEN ya29.xxx Google OAuth 访问令牌 是

|

在生产环境中设置秘密（或配置）

echo "your_secret_value" | wrangler secret put GOOGLE_ACCESS_TOKEN
echo "your_client_secret" | wrangler secret put WORKOS_CLIENT_SECRET

对于生产环境部署，请使用 Wrangler 密钥：

🌐 时区支持 所有预约均使用 亚洲/加尔各答（印度标准时间）

默认时区。

  • 其工作原理：
  • 用户输入的时间被解释为印度标准时间（IST）
  • 日历存储事件时包含正确的时区信息
  • 显示时间采用印度标准时间（IST）格式

系统处理UTC转换时的5:30时区偏移

  • 时间格式示例： "14:30" 输入：
  • （小时:分钟，24小时制） "02:30 PM IST"

显示：

📊 报告API集成https://dimt-api.onrender.com/api连接到外部报告API（

):

  • 特点：
  • 通过电话号码或电子邮件搜索
  • 返回客户端信息和报告历史
  • 包括报告元数据、文件路径和时间戳

支持可配置限制的分页功能

🤝 贡献（或：参与贡献）

  1. 我们欢迎投稿！请按照以下步骤操作：
  2. 为仓库创建分支（或：克隆仓库）git checkout -b feature/amazing-feature创建一个特性分支 (
  3. )
  4. 做出你的更改npm run lint运行代码规范检查和类型检查（
  5. ）git commit -m 'Add amazing feature'提交您的更改（
  6. ）git push origin feature/amazing-feature推送到分支（
  7. ）

提交一个拉取请求

  • 编码规范
  • 遵循TypeScript的最佳实践
  • 使用Biome进行格式化
  • 为公共函数添加 JSDoc 注释

为所有API调用包含错误处理

🐛 故障排除

常见问题

Error: Invalid client credentials
  • 认证错误 .dev.vars
  • ✅ 在（系统/应用中）验证 WorkOS 凭据
  • ✅ 检查重定向URI是否完全匹配

✅ 确保回调端点可访问

Error: Google Calendar API error: 401
  • 日历API错误
  • 确认已启用Google日历API
  • ✅ 验证访问令牌是否有效且未过期
  • ✅ 检查令牌是否具有正确的范围

✅ 如有需要，请重新生成令牌

Error: Gmail API error: 403
  • 电子邮件发送失败
  • 确保在Google Cloud中已启用Gmail API gmail.send ✅ 验证访问令牌是否已
  • 范围
  • ✅ 检查电子邮件格式是否正确

✅ 验证发件人邮箱是否已授权

Warning: Time slot unavailable
  • 时间冲突 recommendAppointmentTimes ✅ 使用
  • 寻找空闲时段
  • ✅ 检查现有预约

✅ 在会议之间预留15分钟的缓冲时间

Error: KV namespace not found
  • KV存储问题
  • ✅ 使用 Wrangler 创建 KV 命名空间 wrangler.jsonc
  • ✅ 更新命名空间ID

✅ 使用更新后的配置进行部署

调试模式

// In index.ts
console.log("Debug info:", { env, props, request });

在开发环境中启用详细日志记录：

wrangler tail

检查Cloudflare Workers日志：

📞 支持

📧 电子邮件：support@yourproject.com

🔄 版本历史

  • v1.0.0 - 初始发布
  • ✅ 使用 WorkOS AuthKit 进行 OAuth 认证
  • ✅ 与Google日历集成
  • ✅ 预约安排、取消、重新安排
  • ✅ 自动邮件提醒
  • ✅ 报告检索系统
  • ✅ 自然语言日期解析

✅ 支持时区（印度标准时间）

📄 许可证 这个项目遵循MIT许可证授权——详见 许可证

文件中有详细信息。

  • 🙏 致谢 WorkOS（可译为“工作操作系统”或根据具体语境简化为“工作系统”，但“WorkOS”作为专有名词，通常直接保留原样）
  • 用于AuthKit集成 Cloudflare Workers（云防护网络工作者）
  • 用于无服务器基础设施 模型上下文协议
  • 针对MCP框架

用于日历和电子邮件功能的Google日历和Gmail API

使用 Cloudflare Workers、WorkOS AuthKit 和 Model Context Protocol 构建，倾注热爱

相关 MCP