cal2prompt

⚠️ 此项目仍处于实验阶段。功能可能会在未通知的情况下发生变化。请谨慎使用！⚠️

cal2prompt

cal2prompt 是一款命令行工具，可获取你的日程（例如 Google Calendar 中的日程），并通过模板引擎将其转换为自定义提示词或文本片段。它可以直接将结果输出到标准输出，也可以作为实验性的 MCP（Model Context Protocol）服务运行。

cal2prompt 使用 Google Calendar API version 3。

CLI 示例

Model Context Protocol（MCP）示例（实验性）

功能

• 🚀 Google Calendar 集成
  使用 Google Calendar API v3 获取你的日程。

• 📄 借助模板引擎灵活自定义大模型提示词
  使用 Jinja2 模板引擎自定义生成的提示词。

• ⚡️ 极速运行
  由 Rust 生态系统提供支持，实现高速处理。

• 🔧 实验性 MCP 模式
  将 cal2prompt 作为 Model Context Protocol 服务运行。

安装

Brew（MacOS）

brew install shuntaka9576/tap/cal2prompt

Cargo（git）

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

用法

$ cal2prompt --help
✨ Fetches your schedule (e.g., from Google Calendar) and converts it into a single LLM prompt. It can also run as an MCP (Model Context Protocol) server.

Usage: cal2prompt [OPTIONS] [COMMAND]

Commands:
  mcp   Launch cal2prompt as an MCP server (experimental).
  help  Print this message or the help of the given subcommand(s)

Options:
      --since <DATE>  Start date (YYYY-MM-DD). Requires --until.
      --until <DATE>  End date (YYYY-MM-DD). Requires --since.
      --today         Fetch events for today only.
      --this-week     Fetch events for the current week (Mon-Sun).
      --this-month    Fetch events for the current month (1st - end).
      --next-week     Fetch events for the upcoming week (Mon-Sun).
  -h, --help          Print help
  -V, --version       Print 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 Calendar 网页界面中找到 Calendar ID。

local M = {}

M.google = {
  clientID = "***.apps.googleusercontent.com",
  clientSecret = "***",
  calendarIDs = {
    "[email protected]"
  },
}

return M

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

local cal2prompt = require("cal2prompt") -- builtin module
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 = [[
Here is your schedule summary. Please find the details below:
{% for day in days %}
## Date: {{ day.date }}
--------------------------------------

### All-Day Events:
{% if day.all_day_events|length == 0 %}
  (No all-day events)
{% else %}
  {% for ev in day.all_day_events %}
  - {{ ev.summary }}
    - (All Day)
    - Location: {{ ev.location or "N/A" }}
    - Description: {{ ev.description or "No description." }}
    - Attendees:
      {% if ev.attendees|length > 0 %}
        {% for a in ev.attendees %}
        - {{ a }}
        {% endfor %}
      {% else %}
      - (No attendees)
      {% endif %}
  {% endfor %}
{% endif %}

### Timed Events:
{% if day.timed_events|length == 0 %}
  (No timed events)
{% else %}
  {% for ev in day.timed_events %}
  - {{ ev.summary }}
    - Start: {{ ev.start }}
    - End:   {{ ev.end }}
    - Location: {{ ev.location or "N/A" }}
    - Description: {{ ev.description or "No description." }}
    - Attendees:
      {% if ev.attendees|length > 0 %}
        {% for a in ev.attendees %}
        - {{ a }}
        {% endfor %}
      {% else %}
      - (No attendees)
      {% 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	是	IANA 时区格式。（例如：America/Los_Angeles Asia/Tokyo）	UTC
settings.oauthFilePath	否	OAuth2.0 令牌的临时存储路径。通常，用户无需更改此项，除非采用了自定义配置。	~/.local/share/cal2prompt/oauth
source.google.oauth2.clientID	是	用于通过 Google Calendar API 进行身份验证的 Google OAuth2 客户端 ID。	（无默认值；必须指定）
source.google.oauth2.clientSecret	是	用于通过 Google Calendar API 进行身份验证的 Google OAuth2 客户端密钥。	（无默认值；必须指定）
source.google.oauth2.scopes	否	授予 Google OAuth 2.0 客户端的权限范围。请参阅此处了解权限范围类型。	[https://www.googleapis.com/auth/calendar.events]
source.google.oauth2.redirectURL	否	Google 将响应发送到的 OAuth2 回调 URL。	"http://127.0.0.1:9004"
source.google.calendar.getEvents.calendarIDs	是	cal2prompt 将从中获取事件的一个或多个 Google Calendar ID 列表。通常可以在 Google Calendar 设置中找到每个 ID。如果提供多个 ID，将获取各日历中的事件并按时间顺序合并。	（无默认值；必须指定）
output.template	是	定义如何格式化／输出获取到的日历数据的字符串。	（无默认值；必须指定）
experimental.mcp.insertCalendarEvent.calendarID	否	使用实验性 MCP 功能时，将新事件插入的 Google Calendar ID。	无

环境变量

变量名	描述	默认值
CAL2_PROMPT_CONFIG_FILE_PATH	自定义 Lua 配置文件的路径；如果不想使用默认文件，请设置此项。	~/.config/cal2prompt/config.lua