MCP Calender Agent

🚀 基于 MCP 的 iCal 服务器

本项目是一个基于 MCP 协议的 iCal 服务器，可实现日历事件的创建、查询和管理。与原始实现不同，它采用全新架构设计，借助 OpenAI 代理处理自然语言请求，还简化了客户端集成。

🚀 快速开始

本项目是基于 MCP 协议的 iCal 服务器实现，主要具备日历事件的创建、查询和管理功能。采用全新架构，利用 OpenAI 代理处理自然语言请求，简化了客户端集成。

✨ 主要特性

• 单点接入：仅需一个 MCP 工具即可完成所有日历操作。
• 智能代理：内置 OpenAI 代理，负责解析自然语言请求并翻译为具体的操作指令。
• 上下文感知：支持会话级别的上下文跟踪，提升交互体验。
• 简化集成：客户端只需调用一个工具，降低了集成复杂度。

📦 安装指南

环境要求

• Python 3.8 或更高版本。
• OpenAI 账户及 API Key。
• macOS 系统（由于依赖于 PyObjC）。

安装步骤

# 克隆仓库
git clone https://github.com/yourusername/mcp-ical.git
cd mcp-ical

# 安装依赖
pip install openai pyobjc

💻 使用示例

基础用法

1. 配置 OpenAI API Key

创建或编辑配置文件 config.json，添加以下内容：

{
    "openai_api_key": "your-api-key-here"
}

2. 启动服务

uv run mcp-ical

3. 示例用法

发送请求："/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-ical" mcp-ical

📚 详细文档

功能模块

核心组件

1. 日历代理（CalendarAgent）
   • 负责解析自然语言指令并生成对应的操作。
   • 使用 OpenAI 的 Agent SDK 实现。
   • 支持多种交互方式：文本、语音等。
2. 事件管理器（EventManager）
   • 处理具体的日历操作，如创建、更新和删除事件。
   • 与 macOS 系统的日历服务集成。
   • 提供详细的日志记录和错误处理。

技术架构

1. 请求流程

客户端 -> CalendarAgent -> EventManager -> 系统日历

2. 核心依赖

• OpenAI SDK：用于实现智能代理功能。
• PyObjC：用于与 macOS 系统的日历服务交互。

已知问题

循环事件问题

• 非标准循环模式可能无法正确设置。
• 更强的 LLM 模型可以提升效果。
• 全天循环事件的提醒时间可能偏移一天。

如何贡献

欢迎任何形式的反馈和贡献，请按照以下步骤操作：

1. Fork 本仓库到您的账户。
2. 创建功能分支（例如：feature/new-feature）。
3. 提交您的更改。
4. 推送分支到远程仓库。
5. 提交 Pull Request 到主分支。

🔧 技术细节

请求流程

客户端 -> CalendarAgent -> EventManager -> 系统日历

核心依赖

• OpenAI SDK：用于实现智能代理功能。
• PyObjC：用于与 macOS 系统的日历服务交互。

📄 许可证

本项目遵循 MIT 许可证，具体内容请参阅 LICENSE 文件。

致谢

• 原始项目：基于 Omar - V2 的 mcp - ical
• 协议支持：使用 Model Context Protocol
• 日历集成：依赖于 PyObjC
• 智能代理：由 OpenAI Agent SDK 提供支持