⚠️ 本项目仍处于实验阶段。功能可能会在没有通知的情况下更改。请谨慎使用！ ⚠️

cal2prompt

cal2prompt 是一个命令行工具，它可以获取您的日程安排（例如，来自 Google 日历），并通过模板引擎将其转换为自定义提示或文本片段。它可以直接输出到您的 stdout，或者作为实验性的 MCP（模型上下文协议）服务器运行。

cal2prompt 使用 Google Calendar API version 3。

CLI 示例

模型上下文协议 (MCP) 示例（实验性）

功能

• 🚀 Google 日历集成 使用 Google Calendar API v3 获取您的日程安排。

• 📄 使用模板引擎进行灵活的 LLM 提示自定义 使用 Jinja2 模板引擎自定义生成的提示。

• ⚡️ 极速 由 Rust 生态系统提供支持的高速处理。

• 🔧 实验性 MCP 模式 将 cal2prompt 作为 模型上下文协议 服务器运行。

安装

Brew (MacOS)

brew install shuntaka9576/tap/cal2prompt

Cargo (git)

git clone https://github.com/shuntaka9576/cal2prompt
cd cal2prompt
cargo install --path .

用法

$ cal2prompt --help
✨ 获取您的日程安排（例如，来自 Google 日历），并将其转换为单个 LLM 提示。它也可以作为 MCP（模型上下文协议）服务器运行。

Usage: cal2prompt [OPTIONS] [COMMAND]

Commands:
  mcp   将 cal2prompt 作为 MCP 服务器启动（实验性）。
  help  打印此消息或给定子命令的帮助

Options:
      --since <DATE>  开始日期 (YYYY-MM-DD)。需要 --until。
      --until <DATE>  结束日期 (YYYY-MM-DD)。需要 --since。
      --today         仅获取今天的事件。
      --this-week     获取本周的事件（周一至周日）。
      --this-month    获取本月的事件（1 号至月末）。
      --next-week     获取下周的事件（周一至周日）。
  -h, --help          打印帮助
  -V, --version       打印版本

初始设置

1. 设置 Google OAuth2.0 客户端

我们使用 OAuth2 进行 Google 帐户身份验证。身份验证后，生成的令牌存储在平台数据目录中的 oauth 文件中（例如，Linux 上的 ~/.local/share/cal2prompt/oauth）。首次启动 cal2prompt 时，身份验证过程将自动开始——只需按照屏幕上的说明进行操作即可。

目前，您必须使用自己的 Calendar API 令牌。Calendar API 令牌仅授予有限数量的用户，并且需要 Google 的批准。即使我作为项目所有者提供 Google 批准的客户端，也必然存在安全风险。因此，您需要创建和管理自己的令牌。

请按照 docs/setup-oauth 中的步骤创建您自己的 Google“项目”并获取 OAuth 令牌。

2. 设置配置

配置以 Lua 编写。以下是配置示例。如果愿意，您可以将公共信息和私有信息分隔到单独的文件中——只需自定义它以满足您的需求即可。

创建 ~/.config/cal2prompt/secrets.lua 并添加以下内容。文件名可以是任何名称，只要它与后面提到的 config.lua 中的 require 语句匹配即可。

请指定您之前创建的 clientID、clientSecret 和 Calendar ID。您可以在 Google 日历 Web UI 中找到 Calendar ID。

local M = {}

M.google = {
  clientID = "***.apps.googleusercontent.com",
  clientSecret = "***",
  calendarIDs = {
    "example@gmail.com"
  },
}

return M

创建 ~/.config/cal2prompt/config.lua 并添加以下内容：

local cal2prompt = require("cal2prompt") -- 内置模块
local os = require("os") -- stdlib
local secrets = require("secrets")

return {
  settings = {
    -- see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
    -- TZ = "Etc/UTC",
    TZ = "Asia/Tokyo",
    -- TZ = "America/Los_Angeles"
    -- TZ - "Asia/Shanghai"
  },
  source = {
    google = {
      oauth2 = {
        clientID = secrets.google.clientID,
        clientSecret = secrets.google.clientSecret,
      },
      calendar = {
        getEvents = {
          calendarIDs = secrets.google.calendarIDs,
        },
      },
    },
  },
  output = {
    -- template = cal2prompt.template.google.standard
    template = [[
这是您的日程安排摘要。请在下面找到详细信息：
{% for day in days %}
## 日期：{{ day.date }}
--------------------------------------

### 全天事件：
{% if day.all_day_events|length == 0 %}
  （没有全天事件）
{% else %}
  {% for ev in day.all_day_events %}
  - {{ ev.summary }}
    - （全天）
    - 地点：{{ ev.location or "N/A" }}
    - 描述：{{ ev.description or "没有描述。" }}
    - 参加者：
      {% if ev.attendees|length > 0 %}
        {% for a in ev.attendees %}
        - {{ a }}
        {% endfor %}
      {% else %}
      - （没有参加者）
      {% endif %}
  {% endfor %}
{% endif %}

### 定时事件：
{% if day.timed_events|length == 0 %}
  （没有定时事件）
{% else %}
  {% for ev in day.timed_events %}
  - {{ ev.summary }}
    - 开始时间：{{ ev.start }}
    - 结束时间：{{ ev.end }}
    - 地点：{{ ev.location or "N/A" }}
    - 描述：{{ ev.description or "没有描述。" }}
    - 参加者：
      {% if ev.attendees|length > 0 %}
        {% for a in ev.attendees %}
        - {{ a }}
        {% endfor %}
      {% else %}
      - （没有参加者）
      {% endif %}
  {% endfor %}
{% endif %}
{% endfor %}
]],
  },
}

3. CLI 身份验证

cal2prompt 执行 OAuth 2.0 流程以获取身份验证凭据。有关详细的分步流程说明，请参阅 docs/setup-cli-auth

cal2prompt

将 Claude Desktop 与 MCP 集成

请将以下配置添加到 ~/Library/Application\ Support/Claude/claude_desktop_config.json：

• 对于 mcpServers.cal2prompt.command：您必须指定运行 which cal2prompt 获得的完整路径。
• 对于 mcpServers.cal2prompt.env.HOME：由于 Claude Desktop 可能不会继承 HOME 环境变量，因此需要显式设置它。

{
  "mcpServers": {
    "cal2prompt": {
      "command": "/Users/username/.cargo/bin/cal2prompt",
      "args": ["mcp"],
      "env": {
        "HOME": "/Users/username"
      }
    }
  }
}

配置

配置选项

变量名	必需	描述	默认值
settings.TZ	true	IANA 时区格式。（例如 America/Los_Angeles Asia/Tokyo）	UTC
settings.oauthFilePath	false	临时存储 OAuth2.0 令牌的路径。通常，用户无需更改此设置，除非他们有自定义设置。	~/.local/share/cal2prompt/oauth
source.google.oauth2.clientID	true	您的 Google OAuth2 客户端 ID，用于通过 Google Calendar API 进行身份验证。	（没有默认值；必须指定）
source.google.oauth2.clientSecret	true	您的 Google OAuth2 客户端密钥，用于通过 Google Calendar API 进行身份验证。	（没有默认值；必须指定）
source.google.oauth2.scopes	false	授予 Google OAuth 2.0 客户端的范围。有关范围类型，请参阅此处。	[https://www.googleapis.com/auth/calendar.events]
source.google.oauth2.redirectURL	false	Google 将向其发送响应的 OAuth2 回调 URL。	"http://127.0.0.1:9004"
source.google.calendar.getEvents.calendarIDs	true	cal2prompt 将从中获取事件的一个或多个 Google 日历 ID 的列表。每个 ID 通常可以在您的 Google 日历设置中找到。如果提供了多个 ID，则将获取每个日历中的事件并按时间顺序组合。	（没有默认值；必须指定）
output.template	true	一个字符串，用于定义应如何格式化/输出获取的日历数据。	（没有默认值；必须指定）
experimental.mcp.insertCalendarEvent.calendarID	false	在使用实验性 MCP 功能时，将向其插入新事件的 Google 日历的 ID。	None

环境变量

变量名	描述	默认值
CAL2_PROMPT_CONFIG_FILE_PATH	如果您不想使用默认配置，则可以使用自定义 Lua 配置文件的路径。	~/.config/cal2prompt/config.lua