cal2prompt

⚠️ Este proyecto aún es experimental. Las funciones pueden cambiar sin previo aviso. ¡Úsalo con precaución! ⚠️

cal2prompt

cal2prompt es una herramienta de línea de comandos que obtiene tu horario (por ejemplo, de Google Calendar) y lo convierte en un prompt personalizado o fragmento de texto mediante un motor de plantillas. Puede generar la salida directamente en tu stdout, o ejecutarse como un servidor MCP (Model Context Protocol) experimental.

cal2prompt utiliza la versión 3 de la API de Google Calendar.

Ejemplo de CLI

Ejemplo de Model Context Protocol (MCP) (experimental)

Características

• 🚀 Integración con Google Calendar
  Utiliza la API de Google Calendar v3 para obtener tu horario.

• 📄 Personalización flexible de prompts de LLM con un motor de plantillas
  Personaliza los prompts generados usando el motor de plantillas Jinja2.

• ⚡️ Rápidísimo
  Procesamiento de alta velocidad impulsado por el ecosistema de Rust.

• 🔧 Modo MCP experimental
  Ejecuta cal2prompt como un servidor Model Context Protocol.

Instalación

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

Configuración inicial

1. Configurar el cliente de Google OAuth2.0

Usamos OAuth2 para autenticarte con tu cuenta de Google. Después de la autenticación, el token generado se almacena en el archivo oauth ubicado en el directorio de datos de tu plataforma (por ejemplo, ~/.local/share/cal2prompt/oauth en Linux). Cuando inicies cal2prompt por primera vez, el proceso de autenticación comenzará automáticamente: simplemente sigue las instrucciones en pantalla.

Actualmente, debes usar tu propio token de la API de Calendar. El token de la API de Calendar solo se otorga a un número limitado de usuarios y requiere la aprobación de Google. Incluso si yo, como propietario del proyecto, proporcionara un cliente aprobado por Google, inevitablemente habría riesgos de seguridad. Por lo tanto, necesitas crear y gestionar tu propio token.

Sigue los pasos en docs/setup-oauth para crear tu propio “proyecto” de Google y obtener un token de OAuth.

2. Configurar la configuración

La configuración se escribe en Lua. A continuación se muestra un ejemplo de la configuración. Puedes separar la información pública y privada en archivos separados si lo prefieres; simplemente personalízala según tus necesidades.

Crea ~/.config/cal2prompt/secrets.lua y agrega el siguiente contenido. El nombre del archivo puede ser cualquiera siempre que coincida con la declaración require en el config.lua mencionado más adelante.

Especifica el clientID, clientSecret y el ID de Calendar que creaste anteriormente. Puedes encontrar el ID de Calendar en la interfaz web de Google Calendar.

local M = {}

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

return M

Crea ~/.config/cal2prompt/config.lua y agrega el siguiente contenido:

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. Autenticación CLI

cal2prompt ejecuta el flujo de OAuth 2.0 para obtener credenciales de autenticación. Para obtener instrucciones detalladas paso a paso, consulta docs/setup-cli-auth.

cal2prompt

Integrando Claude Desktop con MCP

Agrega la siguiente configuración a ~/Library/Application\ Support/Claude/claude_desktop_config.json:

• Para mcpServers.cal2prompt.command: Debes especificar la ruta completa obtenida al ejecutar which cal2prompt.
• Para mcpServers.cal2prompt.env.HOME: Dado que Claude Desktop puede no heredar la variable de entorno HOME, debe establecerse explícitamente.

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

Configuración

Opciones de configuración

Nombre de variable	Requerido	Descripción	Valor predeterminado
settings.TZ	true	Formato de zona horaria IANA. (p. ej., America/Los_Angeles Asia/Tokyo)	UTC
settings.oauthFilePath	false	Ruta donde se almacenan temporalmente los tokens de OAuth2.0. Normalmente, los usuarios no necesitan cambiar esto a menos que tengan una configuración personalizada.	~/.local/share/cal2prompt/oauth
source.google.oauth2.clientID	true	Tu ID de cliente de Google OAuth2 utilizado para autenticarte con la API de Google Calendar.	(Sin valor predeterminado; debe especificarse)
source.google.oauth2.clientSecret	true	Tu secreto de cliente de Google OAuth2 utilizado para autenticarte con la API de Google Calendar.	(Sin valor predeterminado; debe especificarse)
source.google.oauth2.scopes	false	Ámbitos (scopes) para otorgar al cliente de Google OAuth 2.0. Consulta aquí para conocer los tipos de ámbitos.	[https://www.googleapis.com/auth/calendar.events]
source.google.oauth2.redirectURL	false	La URL de devolución de llamada de OAuth2 a la que Google enviará las respuestas.	"http://127.0.0.1:9004"
source.google.calendar.getEvents.calendarIDs	true	Una lista de uno o más IDs de Google Calendar de los cuales cal2prompt obtendrá eventos. Cada ID generalmente se puede encontrar en la configuración de tu Google Calendar. Si se proporcionan varios IDs, los eventos de cada calendario se obtendrán y combinarán en orden cronológico.	(Sin valor predeterminado; debe especificarse)
output.template	true	Una cadena que define cómo se debe formatear/salir los datos del calendario obtenidos.	(Sin valor predeterminado; debe especificarse)
experimental.mcp.insertCalendarEvent.calendarID	false	El ID del Google Calendar en el que se insertarán nuevos eventos al usar la función MCP experimental.	None

Entorno

Nombre de variable	Descripción	Valor predeterminado
CAL2_PROMPT_CONFIG_FILE_PATH	Ruta a un archivo de configuración Lua personalizado si no deseas usar el predeterminado.	~/.config/cal2prompt/config.lua