# kristofferv98
## 基本信息
- Slug: `kristofferv98-mcp_calender_agent`
- Source: modelscope
- Publisher: @kristofferv98/Mcp_calender_agent
- Categories: calendar-management / autonomous-agents
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@kristofferv98/Mcp_calender_agent
## 简介
暂无描述。
## MCP Server 详情

# MCP iCal 服务器

<div align="center">

🗓️ macOS 日历管理的代理驱动方案

[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![MCP 兼容](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)

</div>

> 该项目基于 [Omar-V2/mcp-ical](https://github.com/Omar-V2/mcp-ical.git)，并使用基于代理的方法重新实现了用户交互层。

## 🌟 概览

通过专用的人工智能代理，改变您与 macOS 日历的互动方式！此 MCP iCal 服务器利用 OpenAI Agent SDK 提供了一个强大且统一的日历操作入口点。

与传统的 MCP 实现不同，该服务器采用基于代理的方法：
- 🧠 **单一工具接口**：只有一个 MCP 工具 (`send_to_calendar_agent`)，它将任务委托给一个专门的日历代理
- 🤖 **有状态对话**：代理在同一个会话中的请求之间保持上下文
- 🔄 **零配置操作**：自然语言处理由专门的代理自动处理


你：“下周我的日程是什么？”
Claude：“让我查一下……”
[日历代理处理请求并返回清晰的日程]

你：“明天中午和 Sarah 安排一个午餐会议”
Claude：“事件已创建：与 Sarah 的午餐，明天中午 12:00”


## ✨ 功能

### 📅 事件创建
立即将自然语言转换为日历事件！


“安排下星期四下午 1 点在 Bistro Garden 的团队午餐”
↓
📎 创建：团队午餐
   📅 星期四，下午 1:00
   📍 Bistro Garden


#### 支持的功能：
- 自定义日历选择
- 地点和备注
- 智能提醒
- 循环事件

#### 高级用户示例：

🔄 循环事件：
“每周一上午 9 点设置我的团队同步，并提前 15 分钟提醒”

📝 详细事件：
“在工程日历中安排明天下午 2 到 4 点的产品评审会议，
添加关于审查 Q1 指标的备注，并提前 1 小时提醒我”

📱 多日历支持：
“在我的个人日历中添加下周三下午 3 点的牙医预约”


### 🔍 智能日程管理和可用性
通过自然查询快速访问您的日程：


“下周我的日程是什么？”
↓
📊 以智能格式显示您的即将到来的事件

“下周二我什么时候可以安排一个两小时的会议？”
↓
🕒 找到的可用时间：
   • 周二上午 10:00 - 中午 12:00
   • 周二下午 2:00 - 下午 4:00


### ✏️ 智能事件更新
自然地修改事件：


“将明天的团队会议改到下午 3 点”
↓
✨ 会议重新安排到下午 3:00


#### 更新功能：
- 时间和日期修改
- 日历转移
- 地点更新
- 添加备注
- 提醒调整
- 循环模式更改

### 📊 日历管理
- 查看所有可用日历
- 智能日历建议
- 无缝集成 Google 日历（当与 iCloud 配置时）

> 💡 **专业提示**：由于您可以在自定义日历中创建事件，如果您将 Google 日历与 iCloud 日历同步，您可以使用此 MCP 服务器在 Google 日历中创建事件！只需在创建或更新事件时指定 Google 日历即可。

## 🚀 快速开始

> 💡 **注意**：虽然这些说明侧重于使用 Claude for Desktop 设置 MCP 服务器，但此服务器可以与任何兼容 MCP 的客户端一起使用。有关使用不同客户端的更多详细信息，请参阅 [MCP 文档](https://modelcontextprotocol.io/quickstart/client)。

### 前提条件
- [uv 包管理器](https://github.com/astral-sh/uv)
- 配置了 Calendar 应用程序的 macOS
- 一个 MCP 客户端 - 推荐使用 [Claude for desktop](https://claude.ai/download)- OpenAI API 密钥（设置为 `OPENAI_API_KEY` 环境变量）

### 安装

虽然此 MCP 服务器可以与任何兼容 MCP 的客户端一起使用，但以下说明是针对桌面版 Claude 的。

1. **克隆和设置**
bash
# 克隆仓库
git clone https://github.com/yourusername/mcp-ical.git
cd mcp-ical

# 安装依赖
uv sync


2. **使用 API 密钥配置桌面版 Claude**

创建或编辑 `~/Library/Application Support/Claude/claude_desktop_config.json` 并将您的 OpenAI API 密钥作为环境变量包含在内：

json
{
    "mcpServers": {
        "mcp-ical": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-ical",
                "run",
                "mcp-ical"
            ],
            "env": {
                "OPENAI_API_KEY": "your-api-key-here"
            }
        }
    }
}


3. **启动 Claude 以访问日历**

> ⚠️ **重要**：Claude 必须从终端启动才能正确请求日历权限。直接从 Finder 启动不会触发权限提示。

bash
/Applications/Claude.app/Contents/MacOS/Claude


4. **开始使用！**

尝试：“下周我的日程安排是什么？”


> 🔑 **注意**：当您首次使用与日历相关的命令时，macOS 将提示授予日历访问权限。只有按照上述方式从终端启动 Claude 时才会出现此提示。

## 🧪 测试

> ⚠️ **警告**：测试将创建临时日历和事件。虽然清理是自动的，但仅应在开发环境中运行测试。

bash
# 安装开发依赖
uv sync --dev

# 运行测试套件
uv run pytest tests


## 🧠 工作原理

此实现使用了一种独特的架构：

1. 向客户端暴露一个单一的 MCP 工具 (`send_to_calendar_agent`)
2. 当调用时，该工具将请求传递给使用 OpenAI Agent SDK 构建的专业日历代理
3. 代理处理自然语言请求并调用适当的日历操作
4. 结果被格式化并返回给客户端

这种方法提供了几个优点：
- **简化客户端集成**：只需调用一个工具
- **改进上下文处理**：代理维护会话状态
- **更自然的交互**：专业代理理解特定于日历的术语和意图

## ❓ 此项目与原始项目的不同之处

此实现保留了 [Omar-V2/mcp-ical](https://github.com/Omar-V2/mcp-ical.git) 中大部分核心日历功能，但完全重新实现了用户交互层：

1. **单一入口点**：我们实现了一个单一入口点，该入口点将请求委托给由 OpenAI 支持的代理，而不是直接向客户端暴露多个 MCP 工具
2. **基于代理的处理**：添加了 OpenAI 代理来处理自然语言理解和转换为日历操作
3. **有状态的对话**：在同一会话中的请求之间添加了对话上下文跟踪
4. **简化的客户端集成**：客户端只需要知道一个工具，而不需要了解多个日历操作

核心日历操作（事件创建、列表等）和 macOS 集成基本保持不变。

## 🐛 已知问题

### 重复事件
- 非标准的重复计划可能无法始终正确设置
- 更强大的 LLM 模型可以获得更好的结果
- 重复全天事件的提醒时间可能会有一天的偏差

## 🤝 贡献

欢迎反馈和贡献！以下是您可以帮助的方式：

1. 叉取仓库
2. 创建您的功能分支
3. 提交您的更改
4. 推送到分支
5. 打开拉取请求

## 📝 许可证

此项目根据 MIT 许可证发布 - 请参阅 [LICENSE](LICENSE) 文件获取详细信息。

## 📝 致谢- **原始项目**: 基于 [Omar-V2/mcp-ical](https://github.com/Omar-V2/mcp-ical.git) 由 [Omar-V2](https://github.com/Omar-V2) 创建
- 使用 [Model Context Protocol](https://modelcontextprotocol.io) 构建
- 日历集成使用 [PyObjC](https://github.com/ronaldoussoren/pyobjc) 构建
- 代理功能由 [OpenAI Agent SDK](https://github.com/openai/openai-python) 提供支持