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を使用してスケジュールを取得します。

• 📄 テンプレートエンジンによる柔軟なLLMプロンプトのカスタマイズ
  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クライアントを設定する

Googleアカウントの認証にはOAuth2を使用します。認証後、生成されたトークンはプラットフォームのデータディレクトリにある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を指定してください。Calendar IDはGoogle CalendarのウェブUIで確認できます。

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を実行して取得したフルパスを指定する必要があります。
• Claude DesktopはHOME環境変数を継承しない場合があるため、mcpServers.cal2prompt.env.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 のリストです。ID は通常、Google カレンダーの設定で確認できます。複数の ID を指定すると、各カレンダーの予定を取得し、時系列順にまとめます。	(デフォルト値なし。指定が必要です)
output.template	はい	取得したカレンダーデータのフォーマットと出力方法を定義する文字列です。	(デフォルト値なし。指定が必要です)
experimental.mcp.insertCalendarEvent.calendarID	いいえ	実験的な MCP 機能を使用して新しい予定を追加する Google Calendar の ID です。	なし

環境変数

変数名	説明	デフォルト値
CAL2_PROMPT_CONFIG_FILE_PATH	デフォルトの Lua 設定ファイルを使用しない場合に指定する、カスタム Lua 設定ファイルのパスです。	~/.config/cal2prompt/config.lua