Chronos MCP - 高级CalDAV管理服务器

一个全面的模型上下文协议（MCP）服务器，用于CalDAV日历管理，基于FastMCP 2.0构建。Chronos提供了高级的日历和事件管理功能，并支持多账户。

🚀 功能

• 多账户支持：同时管理多个CalDAV服务器
• 完整的CRUD操作：创建、读取、更新和删除日历及事件 ✅
• 高级事件管理：
  • 支持重复事件的RRULE ✅
  • 支持部分字段修改的事件更新 ✅
  • 参与者管理和邀请（JSON格式） ✅
  • 提醒和警报（VALARM） ✅
  • 支持时区的操作
• 高级搜索：
  • 跨事件全文搜索 ✅
  • 字段特定搜索（标题、描述、地点） ✅
  • 多种匹配类型（包含、以...开头、精确、正则表达式） ✅
  • 日期范围过滤 ✅
  • 相关性排名算法 ✅
• 批量操作：
  • 并行创建多个事件 ✅
  • 高效删除多个事件 ✅
  • 原子操作并回滚 ✅
  • 可配置的错误处理模式 ✅
• 安全加固：
  • 全面的输入验证 ✅
  • 防止XSS和注入攻击 ✅
  • 防止路径遍历攻击 ✅
  • 符合RFC规范的验证 ✅
• 任务管理：完全支持VTODO ✅
• 日记条目：完全支持VJOURNAL ✅
• 导入/导出：支持iCalendar格式（即将推出）
• 同步能力：账户之间的日历同步（即将推出）

📋 任务管理（VTODO）

Chronos MCP提供全面的CalDAV任务支持：

• 创建任务，包括截止日期、优先级和描述
• 跟踪进度，使用百分比完成度（0-100%）
• 管理状态：NEEDS-ACTION、IN-PROCESS、COMPLETED、CANCELLED
• 创建子任务，使用related_to关系
• 批量操作，高效的任务管理

# 示例：创建任务
mcp call create_task '{
  "calendar_uid": "my-calendar",
  "summary": "完成项目文档",
  "due": "2_2025-02-01T15:00:00Z",
  "priority": 2
}'

📓 日记条目（VJOURNAL）

使用CalDAV日记条目保持详细的记录：

• 创建日记条目，带有时间戳和丰富的描述
• 关联相关条目，使用related_to关系
• 通过类别组织，提高可搜索性
• 更新和管理现有的日记条目

# 示例：创建日记条目
mcp call create_journal '{
  "calendar_uid": "my-calendar",
  "summary": "团队会议笔记",
  "description": "讨论了Q1目标..."
}'

更多详细用法，请参阅VTODO/VJOURNAL指南。

🔐 安全

安全密码存储（新！）

Chronos MCP现在支持使用系统密钥环（通过python-keyring）进行安全密码存储。当可用时，密码会自动存储在：

• macOS：Keychain Access
• Windows：Windows Credential Locker
• Linux：Secret Service（如GNOME Keyring、KWallet等）

迁移到安全存储

如果你有现有账户的密码以明文形式存储，可以迁移到安全存储：

# 检查将要迁移的内容（干运行）
python scripts/migrate_to_keyring.py --dry-run

# 执行实际迁移
python scripts/migrate_to_keyring.py

迁移脚本将：

1. 从~/.chronos/accounts.json读取现有密码
2. 将它们安全地存储在你的系统密钥环中
3. 创建原始配置的备份
4. 从JSON文件中移除密码

回退行为

如果密钥环不可用（例如SSH会话、容器），Chronos MCP将：

• 警告安全影响
• 回退到在配置文件中存储密码
• 当密钥环变得可用时，自动尝试将密码迁移到密钥环

遗留安全警告

注意：如果未安装或不可用密钥环，密码将以明文形式存储在~/.chronos/accounts.json。安装密钥环支持：

pip install "chronos-mcp[secure]"  # 或者：pip install keyring

安装

标准安装

pip install -e .

安全安装（推荐）

包括密钥环支持，用于安全密码存储：

pip install -e ".[secure]"

或者如果你已经安装了Chronos：

pip install keyring>=24.0.0

配置

环境变量（默认账户）

CALDAV_BASE_URL=http://<YOUR_CALDAV_SERVER>:5232
CALDAV_USERNAME=<YOUR_USERNAME>
CALDAV_PASSWORD=<YOUR_PASSWORD>

多账户配置

创建~/.chronos/accounts.json：

{
  "accounts": {
    "personal": {
      "url": "http://<YOUR_CALDAV_SERVER>:5232",
      "username": "<YOUR_USERNAME>",
      "display_name": "个人日历"
    },
    "work": {
      "url": "https://caldav.company.com",
      "username": "user",
      "display_name": "工作日历"
    }
  },
  "default_account": "personal"
}

注意：使用密钥环时，JSON中不包含密码。它们将：

• 在首次使用时被提示并安全存储
• 使用scripts/migrate_to_keyring.py从现有配置迁移
• 如果密钥环不可用，则仅存储在JSON中（附带警告）

使用

运行服务器

./run_chronos.sh

基本操作

列出所有已配置的账户：

list_accounts()

示例工具使用

创建带有提醒的事件：

chronos:create_event(
    calendar_uid="assistant",
    summary="团队会议",
    start="2025-07-08T14:00:00",
    end="2025-07-08T15:00:00",
    location="会议室",
    alarm_minutes="15"  # 注意：传递字符串！
)

创建带有参与者的重复事件：

chronos:create_event(
    calendar_uid="work",
    summary="每周站会",
    start="2025-07-07T09:00:00", 
    end="2025-07-07T09:30:00",
    recurrence_rule="FREQ=WEEKLY;BYDAY=MO,WE,FR",
    attendees_json='[{"email": "team@example.com", "name": "团队"}]'
)

删除事件：

chronos:delete_event(
    calendar_uid="assistant",
    event_uid="abc-123-def-456"
)

更新事件（部分更新）：

chronos:update_event(
    calendar_uid="assistant",
    event_uid="abc-123-def-456",
    location="202室",  # 更新位置
    alarm_minutes="30"    # 更改为30分钟提醒
    # 其他字段保持不变
)

文档

• API参考 - 完整的API文档
• 架构指南 - 系统设计和组件
• RRULE指南 - 重复事件文档
• 数据流 - 请求/响应模式
• 设计决策 - 技术选择解释

已知问题

查看KNOWN_ISSUES.md了解当前限制和解决方法。

更新日志

查看CHANGELOG.md了解版本历史。

贡献

查看CONTRIBUTING.md了解开发指南。