STARWARCLOUD STARWAR.AI
返回市场
日历应用服务器

日历应用服务器

作者：rygwdn2 星标更新：2025-04-22
安装使用来源：spider==github.com

项目介绍

Calendar App MCP

这是一个提供对macOS Calendar.app事件和提醒访问的MCP（模型上下文协议）服务器，用于与Claude和其他AI助手集成。

MCP集成

此包可以作为MCP服务器运行，以与支持MCP协议的Claude和其他AI助手集成，使它们能够访问并与其macOS日历数据进行交互。

# 作为MCP服务器运行以集成AI助手
uvx calendar-app-mcp   # 自动作为MCP服务器运行，无需参数
uvx calendar-app-mcp mcp   # 显式运行MCP服务器

一旦运行，Claude可以通过MCP协议与您的日历数据进行交互，允许它：

  • 检查即将举行的事件
  • 查找空闲时间
  • 查看事件详情
  • 访问提醒
  • 根据日历、日期范围等过滤事件

MCP工具和资源

此包提供了几个MCP工具和资源：

工具

  • get_events: 获取特定日期范围内的事件
  • get_reminders: 获取特定日期范围内的提醒
  • list_calendars: 列出所有可用的日历
  • get_today_summary: 获取当天事件和提醒的摘要
  • search: 搜索包含特定术语的事件和提醒
  • get_current_time: 获取任何时区的当前日期和时间
  • convert_time: 将时间从一个时区转换到另一个时区
  • list_timezones: 列出可用的时区，可选地按地区筛选

资源

  • calendar://events/{date}: 访问特定日期的事件
  • calendar://calendars: 访问可用日历列表
  • datetime://current/{timezone}: 获取特定时区的当前时间

提示

  • daily_agenda: 生成查看您日常安排的提示

功能

  • 访问macOS Calendar.app事件和提醒
  • 根据日期范围、日历名称以及全天/忙碌状态进行筛选
  • 将输出格式化为JSON或Markdown
  • 安全、本地访问日历数据

安装

# 从PyPI安装
pip install calendar-app-mcp

# 使用uv
uv pip install calendar-app-mcp

# 使用uvx（直接执行而不安装）
uvx calendar-app-mcp calendars
uvx calendar-app-mcp mcp

可用命令名

安装后，该包提供了两个命令行可执行文件：

# 通用日历应用工具 - 在没有参数的情况下运行时显示帮助信息
calendar-app

# 集中于MCP的变体 - 在没有参数的情况下默认运行MCP服务器
calendar-app-mcp

两个命令都支持相同的子命令，但calendar-app-mcp针对作为MCP服务器使用进行了优化。

开发安装

# 克隆仓库
git clone https://github.com/rygwdn/calendar-app-mcp.git
cd calendar-app-mcp

# 如果尚未安装，请安装uv包管理器
# https://github.com/astral-sh/uv

# 以开发模式安装包
uv install -e .

# 安装开发依赖项（用于测试）
uv install -e '.[dev]'

CLI使用

除了作为MCP服务器运行外，此包还可以作为命令行工具直接访问日历数据：

# 列出可用日历
uvx calendar-app-mcp calendars

# 获取今天的事件和提醒
uvx calendar-app-mcp today

# 获取仅事件
uvx calendar-app-mcp events

# 获取仅提醒
uvx calendar-app-mcp reminders

# 获取事件和提醒
uvx calendar-app-mcp all

# 显示JSON模式
uvx calendar-app-mcp schema

# 检查版本
uvx calendar-app-mcp --version
# 或
uvx calendar-app-mcp version

命令选项

大多数子命令接受以下选项：

# 输出为JSON格式（默认为markdown）
uvx calendar-app-mcp events --json

# 根据日期范围筛选
uvx calendar-app-mcp events --from 2024-12-01 --to 2024-12-31

# 根据特定日历筛选
uvx calendar-app-mcp events --calendars "Work" "Personal"

# 仅显示全天事件
uvx calendar-app-mcp events --all-day-only

# 仅显示忙碌事件
uvx calendar-app-mcp events --busy-only

# 包括已完成的提醒
uvx calendar-app-mcp reminders --include-completed

开发

使用UV与公共PyPI注册表

确保UV使用公共PyPI注册表而不是任何本地配置的存储库：

# 使用仅PyPI生成锁文件
UV_NO_CONFIG=1 uv lock

# 使用仅PyPI安装依赖项
UV_NO_CONFIG=1 uv install

UV_NO_CONFIG=1环境变量告诉UV忽略任何系统级配置，并仅使用公共PyPI注册表。

发布到PyPI

要发布新版本到PyPI：

  1. 更新pyproject.toml中的版本号
  2. 运行测试以验证一切正常：uv run pytest --black --ruff
  3. 构建包：UV_NO_CONFIG=1 uv run python -m build
  4. 上传到PyPI： 
    UV_NO_CONFIG=1 uv run twine upload dist/calendar_app_mcp-X.Y.Z*
    将X.Y.Z替换为实际版本号。
  5. 验证包可以被安装：uvx calendar-app-mcp@latest --version
  6. 创建并推送版本标签：git tag vX.Y.Z && git push origin vX.Y.Z

请参阅CLAUDE.md文件获取更多详细说明。

运行测试

运行所有测试：

python -m pytest

带有覆盖率报告的测试运行：

python -m pytest --cov=calendar_app

运行特定测试文件：

python -m pytest tests/unit/utils/test_date_utils.py

运行特定测试：

python -m pytest tests/unit/utils/test_date_utils.py::TestParseDate::test_valid_date