AI导哈

日历上下文服务器

一个与Google Calendar智能集成的MCP服务器，通过分析用户查询、获取相关日历数据并将其格式化为简洁的上下文，以增强AI助手的响应能力。

  • by Darshil4154
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Darshil4154/MCP-server--datathon-main

使用说明

谷歌日历MCP服务器

模型上下文协议（MCP）服务器，与谷歌日历智能集成，为人工智能模型提供上下文感知响应。该服务器分析用户查询，获取相关日历数据，并将其格式化为简洁的上下文，以增强AI助手的功能。

概述

谷歌日历MCP服务器充当“智能上下文引擎”，它：

  • 截距 用户查询日历信息
  • 分析 查询以了解需要什么日历上下文
  • 获取 来自Google日历API的相关数据
  • 组装 将数据转换为格式化的“上下文包”
  • 交付 用于超相关响应的AI模型的上下文

特性

查询分析功能

  • 检测时间参考（今天、明天、下周、特定日期）
  • 识别意图类型（可用性检查、计划摘要、冲突检测）
  • 从自然语言中提取日期/时间参数

日历数据获取

  • 即将发生的事件（接下来的N个事件，特定日期的事件）
  • 活动详细信息（标题、时间、与会者、地点、描述）
  • 可用性窗口
  • 冲突检测
  • 会议纪要

上下文格式

  • 简明的活动总结
  • 可用性状态
  • 冲突警报
  • 时间感知格式

数据源

此MCP服务器连接到 谷歌日历API 以获取日历事件并基于用户的日程提供个性化上下文。

先决条件

  • Python 3.10或更高版本
  • 启用Google日历API的Google云项目
  • 来自谷歌云控制台的OAuth 2.0凭据

安装

  1. 克隆或下载此存储库

  2. 创建虚拟环境 （推荐）：

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. 安装依赖项:

    pip install -r requirements.txt

  4. 设置Google日历API凭据:

    a.前往 谷歌云控制台

    b.创建新项目或选择现有项目

    c.启用Google日历API：

    • 导航到“API和服务”>“库”
    • 搜索“Google日历API”
    • 点击“启用”

    d.配置OAuth同意屏幕：

    • 转到“API和服务”>“OAuth同意屏幕”
    • 选择“外部”（除非您有Google Workspace帐户）
    • 填写所需信息
    • 添加作用域： https://www.googleapis.com/auth/calendar.readonly
    • 关键的：在“测试用户”下，单击“添加用户”并添加您的电子邮件地址(darshilrayjada4154@gmail.com)
    • 备注：如果不将电子邮件添加为测试用户，则在尝试身份验证时将收到“错误403:access_denied”

    e.创建OAuth 2.0凭据：

    • 转到“API和服务”>“凭据”
    • 点击“创建凭据”>“OAuth客户端ID”
    • 选择“桌面应用程序”作为应用程序类型
    • 下载凭据JSON文件

    f.放置凭证文件：

    • 将下载的文件重命名为 credentials.json
    • 把它放在 config/ 目录
    • 文件应位于： config/credentials.json

    g。 配置授权重定向URI （重要）：

    • 返回“API和服务”>“凭据”
    • 点击您的OAuth 2.0客户端ID（您刚刚创建的ID）
    • 在“授权重定向URI”下，单击“添加URI”
    • 添加以下重定向URI：
      • http://localhost:8080/
      • http://localhost:8081/
      • http://localhost/
      • http://127.0.0.1:8080/
    • 点击“保存”
    • 备注：这一步至关重要！如果没有这些重定向uri，您将收到“redirect_uri_mismatch”错误。

  5. 配置环境变量 （可选）：

    cp .env.example .env
# Edit .env if you need to customize paths

用法

运行服务器

启动MCP服务器：

python main.py

或者：

python -m src.server

首次运行时，服务器将：

  1. 打开浏览器窗口进行Google OAuth身份验证
  2. 要求您登录并授予日历访问权限
  3. 保存身份验证令牌以备将来使用

MCP工具

服务器提供以下工具：

1. get_calendar_context

分析查询并返回格式化日历上下文的主要工具。

示例提示：

  • “我明天下午两点有空吗？”
  • “这周我有什么会议？”
  • “下周一我有什么冲突吗？”

2. check_availability

检查用户是否在特定日期和时间可用。

参数：

  • date：检查日期（YYYY-MM-DD格式或自然语言，如“明天”）
  • time：检查时间（HH:MM格式或自然语言，如“下午2点”）-可选
  • duration_hours：时间段的持续时间（以小时为单位）（默认值：1.0）

例子：

check_availability(date="2024-12-15", time="14:00", duration_hours=1.0)

3. get_upcoming_events

获取即将到来的日历事件。

参数：

  • days：展望未来的天数（默认值：7）
  • max_results：要返回的最大事件数（默认值：10）

例子：

get_upcoming_events(days=7, max_results=10)

4. detect_conflicts

检测特定日期的日程安排冲突。

参数：

  • date：检查日期（YYYY-MM-DD格式或自然语言，如“明天”）

例子：

detect_conflicts(date="2024-12-15")

示例用例

示例1：可用性检查

查询“我明天下午2点有空吗？”

上下文：“用户明天的日历显示：下午1:00-2:30的“团队会议”。用户下午2点没有空。”

AI响应：“不，看起来你明天下午1点到2点30分有一个‘团队会议’，所以你下午2点没有空。”

示例2：进度汇总

查询：“我这周有什么会议？”

上下文：“未来7天的日程安排：12月9日星期一-‘项目审查’（上午10:00-上午11:00），‘客户电话’（下午3:00-下午4:00）；12月10日星期二-‘站立’（上午9:00-上午9:30）”

AI响应：“本周你有：周一上午10点进行‘项目审查’，下午3点进行‘客户拜访’；周二上午9点进行‘站立’。”

示例3：冲突检测

查询：“下周一我有什么冲突吗？”

上下文“12月16日星期一没有发现冲突。您安排了2个活动：“午餐会”（中午12:00-下午1:00）；“代码审查”（下午4:00-5:00）

AI响应：“下周一未检测到冲突。您有两个活动：中午12点的“午餐会”和下午4点的“代码审查”。”

项目结构

mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py              # Main MCP server implementation
│   ├── query_analyzer.py      # Query parsing and intent detection
│   ├── calendar_client.py     # Google Calendar API wrapper
│   ├── context_formatter.py   # Data formatting and summarization
│   └── utils.py               # Helper functions
├── config/
│   ├── credentials.json       # Google OAuth credentials (not in repo)
│   └── credentials.json.example # Example credentials file
├── requirements.txt
├── README.md
├── .env.example               # Environment variables template
└── .gitignore

错误处理

该服务器包括全面的错误处理功能，用于：

  • API速率限制：检测并报告速率限制错误，并显示有用消息
  • 身份验证失败：为重新身份验证提供明确的指导
  • 网络超时：优雅地处理连接问题
  • 日期/时间解析无效：解析失败时恢复默认值
  • 缺少凭证：清除缺少配置文件的错误消息

安全说明

  • 永不承诺 credentials.json 或 token.json 到版本控制
  • 这 .gitignore 文件配置为排除敏感文件
  • OAuth令牌存储在本地并自动刷新
  • 服务器仅请求对您的日历进行只读访问

故障排除

身份验证问题

重定向URI不匹配错误（错误400）

如果您看到类似“redirect_uri_mismatch”或“错误400:redirect_uri _mismatch“的错误：

  1. 首选 谷歌云控制台
  2. 导航到： API和服务 > 凭证
  3. 点击您的OAuth 2.0客户端ID
  4. 在...之下 “授权重定向URI”，添加：
    • http://localhost:8080/
    • http://localhost:8081/
    • http://localhost/
    • http://127.0.0.1:8080/
  5. 点击 “保存”
  6. 再次尝试身份验证

拒绝访问错误（错误403）

如果您看到“错误403:access_denied”或“MCP Desktop尚未完成谷歌验证过程”：

  1. 首选 谷歌云控制台
  2. 导航到： API和服务 > OAuth同意屏幕
  3. 向下滚动到 “测试用户” 章节
  4. 点击 “添加用户”
  5. 添加您的电子邮件地址（您用于登录的电子邮件地址）
  6. 点击 “添加”
  7. 再次尝试身份验证

一般身份验证问题

  • 确保 credentials.json 是在 config/ 目录
  • 删除 config/token.json 如果看到身份验证错误，请重新进行身份验证
  • 验证OAuth同意屏幕是否配置正确
  • 重要：确保您已在OAuth同意屏幕中将您的电子邮件添加为测试用户（如果应用程序处于测试模式，则需要）

API错误

  • 检查Google日历API是否已在您的Google Cloud项目中启用
  • 验证您是否已授予必要的权限
  • 确保您的Google帐户有活动日历

导入错误

  • 确保安装了所有依赖项： pip install -r requirements.txt
  • 验证您使用的是Python 3.10或更高版本
  • 检查您是否从项目根目录运行

发展

运行测试

# Add your test commands here when tests are implemented
python -m pytest tests/

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 提交拉取请求

许可证

该项目是为“构建自己的MCP挑战赛”而创建的。

致谢

联系

如有疑问或问题，请在存储库中打开问题。

相关 MCP