使用说明

Chronos MCP-高级CalDAV管理服务器

使用FastMCP 2.0构建的用于CalDAV日历管理的综合模型上下文协议（MCP）服务器。Chronos提供高级日历和事件管理功能，支持多帐户。

🚀 特性

多账户支持：同时管理多个CalDAV服务器
完整的CRUD操作：创建、读取、更新和删除日历和事件✅
高级事件管理:
- RRULE支持下的重复事件✅
- 部分字段修改的事件更新✅
- 与会者管理和邀请（JSON格式）✅
- 提醒和警报（VALARM）✅
- 时区感知操作
高级搜索:
- 跨事件的全文搜索✅
- 特定字段搜索（标题、描述、位置）✅
- 多种匹配类型（包含、starts_with、精确、正则表达式）✅
- 日期范围过滤✅
- 相关性排名算法✅
批量操作:
- 并行创建多个事件✅
- 高效删除多个事件✅
- 具有回滚功能的原子操作✅
- 可配置的错误处理模式✅
安全加固:
- 全面的输入验证✅
- XSS和注射预防✅
- 路径遍历保护✅
- 符合RFC的验证✅
任务管理：完全支持VTODO✅
日记账分录：完整的VJOURNAL支持✅

📋 任务管理（VTODO）

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

创建任务 包括截止日期、优先级和描述
跟踪进度 完成百分比（0-100%）
管理状态：需要-行动，正在进行中，已完成，已取消
创建子任务 使用related_to关系
批量操作 高效的任务管理

可用工具：

create_task --创建一个包含摘要、截止日期、优先级和描述的任务
list_tasks --在日历中列出任务，可选择按状态筛选
update_task --任务字段的部分更新（状态、优先级、进度等）
delete_task --按UID删除任务
bulk_create_tasks --并行创建多个任务
bulk_delete_tasks --并行删除多个任务

# Example: Create a task
mcp call create_task '{
  "calendar_uid": "my-calendar",
  "summary": "Complete project documentation",
  "due": "2025-02-01T15:00:00Z",
  "priority": 2
}'

📓 日记条目（VJOURNAL）

保留CalDAV日记账分录的详细记录：

创建日记条目 带有时间戳和丰富的描述
链接相关条目 使用related_to关系
按类别组织 为了更好的可搜索性
更新和管理 现有日记账分录

可用工具：

create_journal --创建包含摘要和描述的日记条目
list_journals --列出日历中的日记条目
update_journal --日记字段的部分更新
delete_journal --按UID删除日记条目
bulk_create_journals --并行创建多个日记条目
bulk_delete_journals --并行删除多个日记账条目

# Example: Create a journal entry
mcp call create_journal '{
  "calendar_uid": "my-calendar",
  "summary": "Team Meeting Notes",
  "description": "Discussed Q1 objectives..."
}'

有关详细用法，请参阅 VTODO/VJOURNAL指南.

🔐 安全

安全密码存储（新！）

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

macOS：钥匙链访问
视窗：Windows凭据锁定器
Linux：特勤局（GNOME钥匙圈、KWallet等）

迁移到安全存储

如果您的现有帐户密码以纯文本存储，请将其迁移到安全存储：

# Check what will be migrated (dry run)
python scripts/migrate_to_keyring.py --dry-run

# Perform actual migration
python scripts/migrate_to_keyring.py

迁移脚本将：

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

回退行为

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

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

传统安全警告

备注：如果未安装或未提供密钥环，密码将以纯文本形式存储在 ~/.chronos/accounts.json.使用以下工具安装钥匙圈支架：

pip install "chronos-mcp[secure]"  # or just: 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": "Personal Calendar"
    },
    "work": {
      "url": "https://caldav.company.com",
      "username": "user",
      "display_name": "Work Calendar"
    }
  },
  "default_account": "personal"
}

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

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

用法

运行服务器

./run_chronos.sh

基本操作

列出所有已配置的帐户：

list_accounts()

工具使用示例

创建带有提醒的事件：

chronos:create_event(
    calendar_uid="assistant",
    summary="Team Meeting",
    start="2025-07-08T14:00:00",
    end="2025-07-08T15:00:00",
    location="Conference Room",
    alarm_minutes="15"  # Note: Pass as string!
)

与与会者一起创建定期活动：

chronos:create_event(
    calendar_uid="work",
    summary="Weekly Standup",
    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": "Team"}]'
)

删除事件：

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="Room 202",  # Update location
    alarm_minutes="30"    # Change reminder to 30 minutes
    # Other fields remain unchanged
)

文档

用法 -基本工具使用示例
架构指南 -系统设计和组件
RRULE指南 -重复事件文档
VTODO/VJOURNAL指南 -任务和日志管理
架构决策 -ADR记录
贡献 -开发指南
安全策略 -安全报告和做法

已知问题

看 GitHub问题了解当前的限制和解决方法。

更新日志

看更改日志.md 版本历史。

贡献

看贡献.md 发展指南。