cal2prompt

⚠️ Este projeto ainda é experimental. Os recursos podem mudar sem aviso prévio. Use com cautela! ⚠️

cal2prompt

cal2prompt é uma ferramenta de linha de comando que busca sua agenda (por exemplo, do Google Calendar) e a converte em um prompt personalizado ou trecho de texto por meio de um mecanismo de template. Ela pode gerar a saída diretamente no seu stdout ou ser executada como um servidor MCP (Model Context Protocol) experimental.

cal2prompt utiliza a Google Calendar API versão 3.

Exemplo de CLI

Exemplo de Model Context Protocol (MCP) (experimental)

Recursos

• 🚀 Integração com Google Calendar
  Utiliza a Google Calendar API v3 para buscar sua agenda.

• 📄 Personalização flexível de prompts para LLM com mecanismo de template
  Personalize os prompts gerados usando o mecanismo de template Jinja2.

• ⚡️ Extremamente rápido
  Processamento de alta velocidade impulsionado pelo ecossistema Rust.

• 🔧 Modo MCP experimental
  Execute cal2prompt como um servidor Model Context Protocol.

Instalação

Brew (MacOS)

brew install shuntaka9576/tap/cal2prompt

Cargo (git)

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

Uso

$ 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

Configuração inicial

1. Configurar o cliente Google OAuth2.0

Usamos OAuth2 para autenticação com sua conta Google. Após a autenticação, o token gerado é armazenado no arquivo oauth localizado no diretório de dados da sua plataforma (por exemplo, ~/.local/share/cal2prompt/oauth no Linux). Ao iniciar cal2prompt pela primeira vez, o processo de autenticação começará automaticamente—basta seguir as instruções na tela.

Atualmente, você deve usar seu próprio token da Calendar API. O token da Calendar API é concedido apenas a um número limitado de usuários e requer aprovação do Google. Mesmo que eu, como proprietário do projeto, fornecesse um cliente aprovado pelo Google, haveria inevitavelmente riscos de segurança. Portanto, você precisa criar e gerenciar seu próprio token.

Siga os passos em docs/setup-oauth para criar seu próprio "projeto" no Google e obter um token OAuth.

2. Configuração

A configuração é escrita em Lua. Abaixo está um exemplo da configuração. Você pode separar informações públicas e privadas em arquivos distintos, se preferir—basta personalizá-la conforme suas necessidades.

Crie ~/.config/cal2prompt/secrets.lua e adicione o seguinte conteúdo. O nome do arquivo pode ser qualquer um, desde que corresponda à instrução require no config.lua mencionado posteriormente.

Especifique o clientID, clientSecret e o ID do Calendário que você criou anteriormente. Você pode encontrar o ID do Calendário na interface web do Google Calendar.

local M = {}

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

return M

Crie ~/.config/cal2prompt/config.lua e adicione o seguinte conteúdo:

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. Autenticação via CLI

cal2prompt executa o fluxo OAuth 2.0 para obter credenciais de autenticação. Para instruções detalhadas passo a passo, consulte docs/setup-cli-auth

cal2prompt

Integrando o Claude Desktop com MCP

Adicione a seguinte configuração ao ~/Library/Application\ Support/Claude/claude_desktop_config.json:

• Para mcpServers.cal2prompt.command: Você deve especificar o caminho completo obtido ao executar which cal2prompt.
• Para mcpServers.cal2prompt.env.HOME: Como o Claude Desktop pode não herdar a variável de ambiente HOME, ela precisa ser definida explicitamente.

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

Configuração

Opções de Configuração

Nome da Variável	Obrigatório	Descrição	Valor Padrão
settings.TZ	true	Formato de fuso horário IANA. (ex.: America/Los_Angeles Asia/Tokyo)	UTC
settings.oauthFilePath	false	Caminho onde os tokens OAuth2.0 são armazenados temporariamente. Normalmente, os usuários não precisam alterar isso, a menos que tenham uma configuração personalizada.	~/.local/share/cal2prompt/oauth
source.google.oauth2.clientID	true	Seu Google OAuth2 Client ID usado para autenticação com a Google Calendar API.	(Sem padrão; deve ser especificado)
source.google.oauth2.clientSecret	true	Seu Google OAuth2 Client Secret usado para autenticação com a Google Calendar API.	(Sem padrão; deve ser especificado)
source.google.oauth2.scopes	false	Escopos a serem concedidos ao cliente Google OAuth 2.0. Consulte aqui para os tipos de escopos.	[https://www.googleapis.com/auth/calendar.events]
source.google.oauth2.redirectURL	false	A URL de retorno de chamada OAuth2 para a qual o Google enviará as respostas.	"http://127.0.0.1:9004"
source.google.calendar.getEvents.calendarIDs	true	Uma lista de um ou mais IDs de Google Calendar dos quais cal2prompt buscará eventos. Cada ID geralmente pode ser encontrado nas configurações do seu Google Calendar. Se vários IDs forem fornecidos, os eventos de cada calendário serão buscados e combinados em ordem cronológica.	(Sem padrão; deve ser especificado)
output.template	true	Uma string que define como os dados do calendário buscados devem ser formatados/saída.	(Sem padrão; deve ser especificado)
experimental.mcp.insertCalendarEvent.calendarID	false	O ID do Google Calendar no qual novos eventos serão inseridos ao usar o recurso MCP experimental.	Nenhum

Ambiente

Nome da Variável	Descrição	Valor Padrão
CAL2_PROMPT_CONFIG_FILE_PATH	Caminho para um arquivo de configuração Lua personalizado, caso você não queira usar o padrão.	~/.config/cal2prompt/config.lua