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 提供支持