RubyGems - flycal-cli - Versions diffs - 0.7.3 → 0.7.4 - Mend

flycal-cli 0.7.3 → 0.7.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9b15a5f08efcc922a2088d9a4c47fb852794932b4261406312f262905664c09
-  data.tar.gz: 114f71e6f2ca779315908015cf0b772f374b0e9de04e5775b220f8c3278aa5e5
+  metadata.gz: 1bfdf39ef3561cb1c12829bd2d28dfaf9c2062df7f4c4a163ee99e057af9d413
+  data.tar.gz: 8f0ee70cc004bfd8e29a1fd4c5d7b5d852c22a3958f2de596cc2c77f9ed044f8
 SHA512:
-  metadata.gz: 1545a6259e5a710d4db52267909e7bbbff350aba2e75d617c9e6e2cbb722bb77f9663b5ca8e08483a5606f8030642952c7b1f5c170c4550de706503d15db3fd8
-  data.tar.gz: 6a63614ed3c9cd16ad5d1cf01b358e49edd5fc46ef285b986e181973ef0c660e9353f40e38ae130265bc470073730314d31fce48639ba3942338989a371042c5
+  metadata.gz: 8069638ac5162722bc332a577833da48fb92161ee0b2ca39d6c7c31d1c4aeedecaebcc6bf696f0f9945306bbc4e99b8921718867356b5be87a9d1c22b10ff53e
+  data.tar.gz: 0bdca914927e92b873e91d42b7a061502a9558a858e392d1df1c93509c7ec85a281c5f47e309e011fd1ef734259c991a6d3fa761ecd520b5e6913a4d6f83590f

data/README.md CHANGED Viewed

@@ -1,188 +1,48 @@
 # flycal-cli
-[![Gem Version](https://badge.fury.io/rb/flycal-cli.svg)](https://badge.fury.io/rb/flycal-cli)
+[![Gem Version](https://badge.fury.io/rb/flycal-cli.svg)](https://badge.fury.io/rb/flycal-cli)
-A command-line tool to access and search Google Calendar events. Connect your Google account, choose a default calendar, and search events with flexible date ranges and text filters.
+Read your Google Calendar from the terminal: search events, find free slots, copy them into an email. **Read-only** — nothing is modified on the calendar.
-## Requirements
-- Ruby 3.1 or later
-- A Google Cloud project with Calendar API enabled
-## Installation
+## Quick start
 ```bash
 gem install flycal-cli
-```
-Or add to your Gemfile:
-```ruby
-gem "flycal-cli"
-```
-Then run `bundle install`.
-## Setup
-Before using flycal, you need OAuth credentials from Google Cloud Console:
-1. Go to [Google Cloud Console - Credentials](https://console.cloud.google.com/apis/credentials)
-2. Create a project or select an existing one
-3. Enable the **Google Calendar API** (APIs & Services → Library → search for "Google Calendar API")
-4. Create **Desktop app** credentials (OAuth 2.0 Client IDs)
-5. Add this URI as an authorized redirect:
-   ```
-   http://127.0.0.1:9292/oauth2callback
-   ```
-6. Download the JSON file and save it as `~/.flycal/credentials.json`
-## Commands
-All commands support a per-invocation locale override:
-```bash
-flycal search --locale it --in 7days
-flycal slots --locale en --in "3 days" --duration 1h
-```
-### login
-Connect to your Google account. Opens a browser for OAuth authentication when not yet connected.
-```bash
 flycal login
 ```
-If already connected, the command reports the current status and suggests running `flycal config` to set the default calendar.
-### logout
-Disconnect from your Google account and remove stored tokens.
-```bash
-flycal logout
-```
-### update
-Update `flycal-cli` to the latest published gem version.
-```bash
-flycal update
-```
-### version
-Show the current installed `flycal-cli` version.
-```bash
-flycal version
-flycal --version
-flycal -v
-```
-### calendars
+During the test phase the project already provides the Google API credentials.
+Open the browser, approve access, done.
-List available calendars with name and ID.
+Optional but useful once:
 ```bash
-flycal calendars
-```
-Example output:
-```
-Work user@example.com
-Personal user@gmail.com
+flycal config          # set default calendar + calendars that block free slots
+flycal calendars       # list calendars (name + id)
 ```
-### config
+## Common examples
-Interactive configuration menu.
-```bash
-flycal config
-```
-Options:
-- `calendar_default` — choose the default calendar and save it to `~/.flycal/config.yml`
-- `exclude_calendars` — multi-select one or more calendars whose events block free slots (default selection includes the current default calendar)
-- `edit config` — open `~/.flycal/config.yml` with `$EDITOR` (or `vi`)
-Press Ctrl+C during configuration to cancel without error (`config cancelled...`).
-The default calendar is used by the search command when no calendar is specified.
-### search
-Search for events in your calendar(s). Supports flexible date ranges and text filtering.
-```bash
-flycal search
-flycal search --in 30days --description placeholder
-flycal search -f 2025-03-01 -t 2025-03-31 -c "Work"
-flycal search -i 2months -d placeholder
-```
-**Options:**
-- `--from` / `-f` — Start date/time. Default: midnight of current day. Formats: `YYYY-MM-DD`, locale forms (`DD-MM-YYYY` for `it`, `MM-DD-YYYY` for `en`, `/` or `-`), or with time `YYYY-MM-DDTHH:MM`
-- `--to` / `-t` — End date/time. Default: 23:59 of the 30th day from today. Same formats as `--from`
-- `--in` / `-i` — Duration from `--from`, overrides `--to`. Format: `30days`, `48hours`, `2months`, `1year` (no space). With space use quotes: `--in "30 days"`
-- `--calendar` / `-c` — Calendar name or ID. Default: calendar set via `flycal config`
-- `--description` / `-d` — Filter events by text. Matches events where the string appears in title or description (case-insensitive, contains)
-**Time range behavior:**
-- If neither `--from` nor `--to` is given: searches from today at midnight to 23:59 of the 30th day from today
-- If `--in` is given: `--to` is ignored; the end time is computed from `--from` plus the duration
-- Examples: `--in 30days`, `--in 48hours`, `--in 1months`, `--in 1year`
-**Output:**
-Each event is printed as: `Calendar | Start | End | Title`
-The summary shows:
-- From and To dates used
-- Number of events found
-- Total time occupied (hours, minutes, and working days based on 8-hour days)
-For time frames longer than 7 days, a weekly breakdown is added (week number, start/end dates, hours, working days per week). For time frames longer than 30 days, a monthly breakdown is shown instead (month number, month name, hours, working days per month).
-### slots
-Find free time slots in your calendar. Output is a simple list for copy/paste into email or other tools.
+**Find free slots (most useful day-to-day)**
 ```bash
 flycal slots
+flycal slots --in "5 days"
 flycal slots --from monday --in "5 days"
-flycal slots --from "next monday" --in "5 days" --locale it
-flycal slots --from lunedi --in "5 days" --locale it
+flycal slots --from "next monday" --in "2 weeks" --duration 1h
 flycal slots --in "12 days" --template dinner
+flycal slots --locale it --from lunedi --in "5 days"
 ```
-**Options:**
-- `--duration` — Slot length. Default: `slots.defaults.default_duration` in config (`45min`). Examples: `1h`, `30 minutes`
-- `--from` / `-f` — Start date/time. Default: `slots.defaults.from` in config (`now`). Accepts:
-  - absolute: `YYYY-MM-DD`, locale dates (`DD-MM-YYYY` / `MM-DD-YYYY`), optional time
-  - relative: `now`, `today`/`oggi`, `tomorrow`/`domani`, `monday`/`lunedi`, `next monday`/`prossimo lunedi`, `last friday`/`scorso venerdi`
-- `--in` / `-i` — Search window from `--from`. Default: `1 week`.
-- `--template` / `-T` — Template from `slots.templates` in config. Default: first template (`work`)
-- `--calendar` / `-c` — Calendar name or ID used as fallback when `exclude_calendars` is not configured
-**Output:**
+Output is a short header plus a clean list ready to paste (and copied to the clipboard when `pbcopy` / `clip` / `wl-copy` / `xclip` is available):
 ```
 found 6 slots
 from sat 1 August 2026 to sat 8 August 2026
 with duration 45min, template dinner
 considering calendars
-- incode - antonio
-- Polimi 10110009
-- antoniomolinari1977@gmail.com
+- Work
+- Personal
 link: https://calendar.google.com/calendar/r/day/2026/8/1
 saturday 1/8
@@ -192,9 +52,31 @@ monday 3/8
 19 - 23
 ```
-If a clipboard tool is available (`pbcopy` on macOS, `wl-copy`/`xclip` on Linux, `clip` on Windows), the slot list without the header is also copied to the clipboard.
+**Search events**
+```bash
+flycal search
+flycal search --in 30days
+flycal search --in 30days --description meeting
+flycal search --from 2026-08-01 --to 2026-08-31 -c Work
+flycal search --from monday --in "2 weeks" --locale it
+```
-Slot search windows are configured in `~/.flycal/config.yml`:
+**Other commands**
+```bash
+flycal version
+flycal update
+flycal logout
+```
+All commands accept `--locale en|it`.
+---
+## Configuration (`~/.flycal/config.yml`)
+Defaults are created automatically on first run. Edit with `flycal config` → `edit config`, or by hand.
 ```yaml
 calendar_default: ~
@@ -202,27 +84,15 @@ locale: en
 slots:
   templates:
     work:
-      days:
-        - 1
-        - 2
-        - 3
-        - 4
-        - 5
+      days: [1, 2, 3, 4, 5]          # 1=Mon … 7=Sun
       hours:
         - 9:30-13:00
         - 14:00-18:30
     dinner:
-      days:
-        - 1
-        - 2
-        - 3
-        - 4
-        - 5
-        - 6
-        - 7
+      days: [1, 2, 3, 4, 5, 6, 7]
       hours:
         - 19-23
-  exclude_calendars: []
+  exclude_calendars: []              # calendars whose events block free slots
   defaults:
     from: now
     default_duration: 45min
@@ -230,80 +100,81 @@ slots:
   free_after: 15m
 ```
-Missing keys are filled from `config/defaults.yml` in the gem and saved to your `config.yml` on first read.
-- `calendar_default: ~` means no default calendar is set (`~` is YAML null)
-- `templates` — named schedules; default used is the first one (`work`)
-- `templates.*.days` — weekdays as numbers: `1` Monday … `7` Sunday
-- `templates.*.hours` — one or more ranges (`H-H`, `HH:MM-HH:MM`, mixed)
-- `defaults.from` — default `--from` for slots (`now` or a date string)
-- `defaults.default_duration` — default slot length when `--duration` is omitted
-- `free_before` — buffer before each slot
-- `free_after` — buffer after each slot; gaps must fit `duration + free_after`, output shows continuous free ranges
-- `exclude_calendars` — calendars whose events block free slots; if empty, `calendar_default` is used
-- `locale` supports `en` and `it` (default is `en`)
+| Key | Meaning |
+|---|---|
+| `calendar_default` | Default calendar (`~` = unset) |
+| `locale` | `en` or `it` |
+| `slots.templates` | Named schedules; `flycal slots` uses the first one unless `--template` is set |
+| `slots.exclude_calendars` | Events here block free slots (fallback: `calendar_default`) |
+| `slots.defaults.*` | Defaults for `--from` / `--duration` |
+| `slots.free_before` / `free_after` | Buffers around busy events |
-**Output example:**
+Interactive helpers:
+```bash
+flycal config
 ```
-friday 15/7
-10 - 12
-13 - 15.30
-monday 21/7
-12 - 13
-14 - 15
-```
+- `calendar_default` — pick the default calendar
+- `exclude_calendars` — multi-select calendars that block slots
+- `edit config` — open the YAML in `$EDITOR`
-## Configuration
+---
-Data is stored in `~/.flycal/`:
+## Parameters (reference)
-| File | Purpose |
-|:-----|---------|
-| `config.yml` | Default calendar ID and other settings |
-| `credentials.json` | OAuth credentials (created manually from Google Cloud Console) |
-| `tokens.yml` | Access tokens (managed automatically) |
+### `flycal slots`
-## Publishing to RubyGems
+| Option | Default | Notes |
+|---|---|---|
+| `--duration` | `45min` | Min free range length (`1h`, `90min`, …) |
+| `--from` / `-f` | `now` | Absolute date or relative: `monday`, `next monday`, `tomorrow`, `lunedi`, … |
+| `--in` / `-i` | `1 week` | Window from `--from` (`"5 days"`, `2weeks`, …) |
+| `--template` / `-T` | first template (`work`) | e.g. `dinner` |
+| `--calendar` / `-c` | — | Fallback if `exclude_calendars` is empty |
+| `--locale` | config / `en` | `en` or `it` |
-### First release
+### `flycal search`
-1. Create an account at [rubygems.org](https://rubygems.org) if needed
-2. Update `flycal-cli.gemspec` with your author, email, and homepage
-3. Build and push:
+| Option | Default | Notes |
+|---|---|---|
+| `--from` / `-f` | today midnight | Absolute or relative date |
+| `--to` / `-t` | +30 days | Ignored if `--in` is set |
+| `--in` / `-i` | — | Duration from `--from` |
+| `--description` / `-d` | — | Contains filter on title/description |
+| `--calendar` / `-c` | `calendar_default` | Name or ID |
+| `--locale` | config / `en` | `en` or `it` |
-```bash
-gem build flycal-cli.gemspec
-gem push flycal-cli-0.1.0.gem
-```
+Relative dates work in English and Italian: `today`/`oggi`, `tomorrow`/`domani`, `monday`/`lunedi`, `next monday`/`prossimo lunedi`, `last friday`/`scorso venerdi`.
-### Subsequent releases
+---
-1. Update the version in `lib/flycal_cli/version.rb`
-2. Build and push:
+## Optional: your own Google Cloud credentials
-```bash
-gem build flycal-cli.gemspec
-gem push flycal-cli-X.Y.Z.gem
-```
+**Not needed** for the default test API — `flycal login` is enough.
-3. Optionally tag and push:
+Use this only if you want flycal to talk to **your own** Google Cloud OAuth client instead of the project-provided test credentials.
-```bash
-git tag vX.Y.Z
-git push origin vX.Y.Z
-```
+1. [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials)
+2. Enable **Google Calendar API**
+3. Create **Desktop app** OAuth credentials
+4. Authorized redirect URI: `http://127.0.0.1:9292/oauth2callback`
+5. Save the JSON as `~/.flycal/credentials.json`
+6. Run `flycal login`
-### Using rake release
+You can also ask a teammate who manages the Cloud project to share that JSON with you.
-With `bundler/gem_tasks` in your Rakefile:
+---
-```bash
-bundle exec rake release
-```
+## Files
+| Path | Purpose |
+|---|---|
+| `~/.flycal/config.yml` | Settings (calendars, templates, locale, …) |
+| `~/.flycal/credentials.json` | Own OAuth client (optional) |
+| `~/.flycal/tokens.yml` | Login tokens (managed automatically) |
-This builds the gem, pushes to RubyGems, and can handle git tagging and pushing.
+MCP catalog for agents: [`mcp/tools.json`](mcp/tools.json)
 ## License

data/lib/flycal_cli/version.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module FlycalCli
-  VERSION = '0.7.3'
+  VERSION = '0.7.4'
 end

data/mcp/README.md CHANGED Viewed

@@ -1,29 +1,68 @@
 # flycal MCP catalog
-This directory contains a machine-readable description of **flycal-cli** commands for MCP (Model Context Protocol) servers.
+Machine-readable description of **flycal-cli** for MCP servers.
 ## File
-- [`tools.json`](./tools.json) — tools catalog with MCP-style `inputSchema`, CLI argv templates, auth/interactivity flags, and config keys.
+- [`tools.json`](./tools.json) — full catalog:
+  - `global_options` / `shared_formats` — shared `--locale`, date and duration formats
+  - `config.keys` — `~/.flycal/config.yml` keys used by the CLI
+  - `tools[].parameters` — human-readable parameter docs (cli flags, defaults, examples)
+  - `tools[].inputSchema` — JSON Schema for MCP tool registration
+  - `command.option_map` — how to build argv from tool arguments
 ## How an MCP server can use it
 1. Load `tools.json` at startup.
-2. Register each entry in `tools` with your MCP SDK (`server.tool(...)`), using `name`, `description`, and `inputSchema`.
-3. On tool call, build the argv:
+2. Register each entry in `tools` with your MCP SDK using `name`, `description`, and `inputSchema`.
+3. On tool call, build argv:
    - static tools → `command.argv`
-   - parameterized tools → start from `command.argv_template`, then append pairs from `command.option_map` for each provided argument
+   - parameterized tools → start from `command.argv_template`, then for each provided arg append `command.option_map[arg]`
    - if `locale` is set → append `--locale <value>`
-4. Run `flycal` as a subprocess and return stdout as text content.
-5. Skip or gate tools with `"interactive": true` (`flycal_login`, `flycal_config`) unless a TTY is available.
+4. Run `flycal` as a subprocess and return stdout as text.
+5. Skip tools with `"interactive": true` (`flycal_login`, `flycal_config`) unless a TTY is available.
+## Parameters cheat sheet
+### Global
+| Param | CLI | Values |
+|---|---|---|
+| `locale` | `--locale` | `en`, `it` |
+### `flycal_search`
+| Param | CLI | Default | Notes |
+|---|---|---|---|
+| `calendar` | `--calendar` / `-c` | `calendar_default` | name or ID |
+| `from` | `--from` / `-f` | today midnight | absolute or relative date |
+| `to` | `--to` / `-t` | +30 days 23:59 | ignored if `in` set |
+| `in` | `--in` / `-i` | — | duration from `from`, overrides `to` |
+| `description` | `--description` / `-d` | — | contains filter |
+| `locale` | `--locale` | config/`en` | |
+### `flycal_slots`
+| Param | CLI | Default | Notes |
+|---|---|---|---|
+| `duration` | `--duration` | `45min` (config) | min free-range length |
+| `from` | `--from` / `-f` | `now` (config) | absolute or relative (`monday`, `next monday`, …) |
+| `in` | `--in` / `-i` | `1 week` | window from `--from` |
+| `template` | `--template` / `-T` | first template (`work`) | from `slots.templates` |
+| `calendar` | `--calendar` / `-c` | — | fallback if `exclude_calendars` empty |
+| `locale` | `--locale` | config/`en` | |
+### Relative `--from` examples
+`now`, `today`/`oggi`, `tomorrow`/`domani`, `monday`/`lunedi`, `next monday`/`prossimo lunedi`, `last friday`/`scorso venerdi`
 ## Suggested tools to expose
 | MCP tool | CLI | Notes |
 |---|---|---|
 | `flycal_search` | `flycal search ...` | Primary read tool |
-| `flycal_slots` | `flycal slots --in ... --duration ...` | Free slots |
+| `flycal_slots` | `flycal slots ...` | Free slots |
 | `flycal_calendars` | `flycal calendars` | List name + id |
 | `flycal_version` | `flycal version` | Health / version check |
-Interactive / side-effect tools (`login`, `logout`, `config`, `update`) are documented in the catalog but are usually better left to the user terminal.
+Interactive / side-effect tools (`login`, `logout`, `config`, `update`) are documented but usually better left to a user terminal.

data/mcp/tools.json CHANGED Viewed

@@ -2,52 +2,140 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "flycal-cli",
   "title": "flycal CLI MCP tools catalog",
-  "description": "Machine-readable catalog of flycal-cli commands for MCP servers. Each tool maps to a CLI invocation via the `command` template. Non-interactive tools are safe to run from an MCP host; interactive tools require a TTY and should be surfaced as guidance only or refused unless the client can attach a terminal.",
-  "version": "0.5.0",
+  "description": "Machine-readable catalog of flycal-cli commands for MCP servers. Each tool maps to a CLI invocation. Non-interactive tools are safe to run from an MCP host; interactive tools require a TTY.",
+  "version": "0.7.3",
   "binary": "flycal",
   "homepage": "https://github.com/magnum/flycal-cli",
-  "locale": {
-    "global_option": "--locale",
-    "supported": ["en", "it"],
-    "default": "en",
-    "config_key": "locale"
+  "read_only": true,
+  "global_options": {
+    "locale": {
+      "cli": ["--locale"],
+      "type": "string",
+      "enum": ["en", "it"],
+      "default": "en",
+      "config_key": "locale",
+      "description": "Override UI locale for this invocation only. Falls back to config locale, then en."
+    }
+  },
+  "shared_formats": {
+    "absolute_date": {
+      "description": "Absolute calendar date/time",
+      "examples": [
+        "2026-08-01",
+        "2026/08/01",
+        "2026-08-01T14:30",
+        "01-08-2026 (locale it)",
+        "08-01-2026 (locale en)",
+        "01/08/2026 09:00"
+      ],
+      "notes": [
+        "YYYY-MM-DD and YYYY/MM/DD always accepted",
+        "locale it also accepts DD-MM-YYYY / DD/MM/YYYY",
+        "locale en also accepts MM-DD-YYYY / MM/DD/YYYY",
+        "optional time: THH:MM or space + HH:MM(:SS)"
+      ]
+    },
+    "relative_date": {
+      "description": "Relative start expressions (en + it)",
+      "examples": [
+        "now",
+        "today",
+        "oggi",
+        "tomorrow",
+        "domani",
+        "yesterday",
+        "ieri",
+        "monday",
+        "lunedi",
+        "next monday",
+        "prossimo lunedi",
+        "last friday",
+        "scorso venerdi"
+      ],
+      "notes": [
+        "bare weekday = next occurrence including today if it matches",
+        "next/prossimo = next occurrence excluding today",
+        "last/scorso = previous occurrence excluding today"
+      ]
+    },
+    "duration": {
+      "description": "Duration / window length",
+      "examples": [
+        "45min",
+        "1h",
+        "90min",
+        "3 days",
+        "5days",
+        "1 week",
+        "1week",
+        "48 hours",
+        "2 months",
+        "1 year"
+      ],
+      "notes": [
+        "quote values that contain spaces",
+        "no-space forms also work (30days, 48hours)"
+      ]
+    }
   },
   "config": {
     "path": "~/.flycal/config.yml",
     "credentials_path": "~/.flycal/credentials.json",
+    "tokens_path": "~/.flycal/tokens.yml",
+    "credentials_note": "Default/test phase: project-provided API credentials — just run flycal login. Creating your own Google Cloud Console OAuth client is optional and only needed if you want to use your own API project; save that JSON as ~/.flycal/credentials.json then run flycal login.",
     "keys": {
       "calendar_default": {
         "type": ["string", "null"],
-        "description": "Default Google Calendar ID used by search and as slots fallback. YAML null (~) means unset."
+        "cli_related": ["flycal_config", "flycal_search.calendar", "flycal_slots.calendar"],
+        "description": "Default Google Calendar ID. YAML null (~) means unset."
       },
       "locale": {
         "type": "string",
         "enum": ["en", "it"],
+        "default": "en",
         "description": "Default CLI locale"
       },
       "slots.templates": {
         "type": "object",
-        "description": "Named templates with days (1=Mon..7=Sun) and hours ranges. Default template is the first key (work)."
+        "description": "Named day/hour schedules for flycal slots. Default used = first key (usually work).",
+        "item_shape": {
+          "days": {
+            "type": "array",
+            "items": { "type": "integer", "minimum": 1, "maximum": 7 },
+            "description": "1=Monday ... 7=Sunday"
+          },
+          "hours": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Ranges like 9:30-13:00 or 19-23"
+          }
+        },
+        "default_templates": ["work", "dinner"]
       },
       "slots.defaults.from": {
         "type": "string",
-        "description": "Default --from for slots (e.g. now or a date string)"
+        "default": "now",
+        "description": "Default value for slots --from when omitted"
       },
       "slots.defaults.default_duration": {
         "type": "string",
-        "description": "Default slot duration when --duration is omitted (e.g. 45min)"
+        "default": "45min",
+        "description": "Default value for slots --duration when omitted"
       },
       "slots.free_before": {
         "type": "string",
-        "description": "Buffer before each slot; events block this window before slot start"
+        "default": "0m",
+        "description": "Busy buffer before each slot start"
       },
       "slots.free_after": {
         "type": "string",
-        "description": "Buffer after each slot; gaps must fit duration + free_after"
+        "default": "15m",
+        "description": "Busy buffer after each slot; free gaps must fit duration + free_after"
       },
       "slots.exclude_calendars": {
         "type": "array",
         "items": { "type": "string" },
+        "default": [],
         "description": "Calendar IDs whose events block free slots. If empty, calendar_default is used."
       }
     }
@@ -55,20 +143,23 @@
   "notes": [
     "flycal is read-only against Google Calendar (no create/update/delete of events).",
     "Auth uses OAuth desktop flow; tokens live under ~/.flycal/.",
-    "Prefer quoting duration values that contain spaces (e.g. --in \"3 days\").",
-    "Duration formats without spaces also work (e.g. 30days, 48hours, 1h, 30min)."
+    "Prefer quoting values with spaces (e.g. --in \"3 days\", --from \"next monday\").",
+    "slots copies the availability list (without header) to clipboard when pbcopy, wl-copy, xclip, or clip is available."
   ],
   "tools": [
     {
       "name": "flycal_version",
       "title": "Show flycal version",
-      "description": "Print the installed flycal-cli version.",
+      "description": "Print the installed flycal-cli version string (e.g. flycal 0.7.3).",
       "interactive": false,
       "requires_auth": false,
       "command": {
         "argv": ["flycal", "version"],
         "alternatives": [["flycal", "--version"], ["flycal", "-v"]]
       },
+      "parameters": {
+        "locale": { "$ref": "#/global_options/locale" }
+      },
       "inputSchema": {
         "type": "object",
         "additionalProperties": false,
@@ -76,7 +167,7 @@
           "locale": {
             "type": "string",
             "enum": ["en", "it"],
-            "description": "Optional locale override for this invocation"
+            "description": "Optional locale override (--locale)."
           }
         }
       }
@@ -84,20 +175,30 @@
     {
       "name": "flycal_update",
       "title": "Update flycal gem",
-      "description": "Run gem update flycal-cli to install the latest published version.",
+      "description": "Run `gem update flycal-cli` to install the latest published version.",
       "interactive": false,
       "requires_auth": false,
       "side_effects": ["updates_local_gem"],
       "command": {
         "argv": ["flycal", "update"]
       },
+      "parameters": {
+        "locale": {
+          "cli": ["--locale"],
+          "type": "string",
+          "enum": ["en", "it"],
+          "required": false,
+          "description": "Optional locale override."
+        }
+      },
       "inputSchema": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
           "locale": {
             "type": "string",
-            "enum": ["en", "it"]
+            "enum": ["en", "it"],
+            "description": "Optional locale override (--locale)."
           }
         }
       }
@@ -105,20 +206,30 @@
     {
       "name": "flycal_login",
       "title": "Connect Google account",
-      "description": "Start OAuth browser login for Google Calendar. Requires ~/.flycal/credentials.json and a browser. Interactive.",
+      "description": "Start OAuth browser login. Requires ~/.flycal/credentials.json and a browser/TTY. Interactive.",
       "interactive": true,
       "requires_auth": false,
       "side_effects": ["writes_tokens"],
       "command": {
         "argv": ["flycal", "login"]
       },
+      "parameters": {
+        "locale": {
+          "cli": ["--locale"],
+          "type": "string",
+          "enum": ["en", "it"],
+          "required": false,
+          "description": "Optional locale override."
+        }
+      },
       "inputSchema": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
           "locale": {
             "type": "string",
-            "enum": ["en", "it"]
+            "enum": ["en", "it"],
+            "description": "Optional locale override (--locale)."
           }
         }
       }
@@ -133,13 +244,23 @@
       "command": {
         "argv": ["flycal", "logout"]
       },
+      "parameters": {
+        "locale": {
+          "cli": ["--locale"],
+          "type": "string",
+          "enum": ["en", "it"],
+          "required": false,
+          "description": "Optional locale override."
+        }
+      },
       "inputSchema": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
           "locale": {
             "type": "string",
-            "enum": ["en", "it"]
+            "enum": ["en", "it"],
+            "description": "Optional locale override (--locale)."
           }
         }
       }
@@ -147,15 +268,24 @@
     {
       "name": "flycal_calendars",
       "title": "List calendars",
-      "description": "List available Google calendars as lines of \"name id\". Does not change configuration.",
+      "description": "List available Google calendars as lines of \"name id\". Read-only; does not change config.",
       "interactive": false,
       "requires_auth": true,
       "command": {
         "argv": ["flycal", "calendars"]
       },
+      "parameters": {
+        "locale": {
+          "cli": ["--locale"],
+          "type": "string",
+          "enum": ["en", "it"],
+          "required": false,
+          "description": "Optional locale override."
+        }
+      },
       "output": {
         "format": "text/lines",
-        "example": "Work molinari@incode.it\nPersonal user@gmail.com"
+        "example": "Work work@example.com\nPersonal personal@example.com"
       },
       "inputSchema": {
         "type": "object",
@@ -163,7 +293,8 @@
         "properties": {
           "locale": {
             "type": "string",
-            "enum": ["en", "it"]
+            "enum": ["en", "it"],
+            "description": "Optional locale override (--locale)."
           }
         }
       }
@@ -171,7 +302,7 @@
     {
       "name": "flycal_config",
       "title": "Configure flycal (interactive)",
-      "description": "Interactive configuration menu. Options: calendar_default (single select), exclude_calendars (multi-select, min 1), edit config (opens ~/.flycal/config.yml in $EDITOR or vi). Ctrl+C prints \"config cancelled...\". Prefer editing config.yml or using dedicated non-interactive flows from MCP hosts.",
+      "description": "Interactive configuration menu. Prefer editing ~/.flycal/config.yml from MCP hosts unless a TTY is available.",
       "interactive": true,
       "requires_auth": true,
       "side_effects": ["writes_config"],
@@ -179,17 +310,36 @@
         "argv": ["flycal", "config"]
       },
       "menu_options": [
-        "calendar_default",
-        "exclude_calendars",
-        "edit config"
+        {
+          "id": "calendar_default",
+          "description": "Single-select default calendar; saved as calendar_default"
+        },
+        {
+          "id": "exclude_calendars",
+          "description": "Multi-select calendars whose events block slots; saved as slots.exclude_calendars (min 1)"
+        },
+        {
+          "id": "edit config",
+          "description": "Open ~/.flycal/config.yml with $EDITOR or vi"
+        }
       ],
+      "parameters": {
+        "locale": {
+          "cli": ["--locale"],
+          "type": "string",
+          "enum": ["en", "it"],
+          "required": false,
+          "description": "Optional locale override."
+        }
+      },
       "inputSchema": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
           "locale": {
             "type": "string",
-            "enum": ["en", "it"]
+            "enum": ["en", "it"],
+            "description": "Optional locale override (--locale)."
           }
         }
       }
@@ -197,7 +347,7 @@
     {
       "name": "flycal_search",
       "title": "Search calendar events",
-      "description": "Search Google Calendar events. Prints one line per event (Calendar | Start | End | Title) plus a summary with total occupied time in hours/minutes and 8-hour working days. For ranges >7 days adds a weekly breakdown; for >30 days a monthly breakdown. Contains-filter on title/description when description is set. Read-only.",
+      "description": "Search Google Calendar events. Prints one line per event (Calendar | Start | End | Title) plus a summary with total occupied time (hours/minutes and 8-hour working days). Ranges >7 days add weekly breakdown; >30 days monthly. Read-only.",
       "interactive": false,
       "requires_auth": true,
       "command": {
@@ -214,36 +364,82 @@
           ["flycal", "search"],
           ["flycal", "search", "--in", "30days", "--description", "placeholder"],
           ["flycal", "search", "-f", "2025-03-01", "-t", "2025-03-31", "-c", "Work"],
-          ["flycal", "search", "--in", "2months", "-d", "placeholder", "--locale", "it"]
+          ["flycal", "search", "--from", "monday", "--in", "2 weeks", "--locale", "it"]
         ]
       },
+      "parameters": {
+        "calendar": {
+          "cli": ["--calendar", "-c"],
+          "type": "string",
+          "required": false,
+          "default": "config.calendar_default (or primary)",
+          "description": "Calendar name or ID to search."
+        },
+        "from": {
+          "cli": ["--from", "-f"],
+          "type": "string",
+          "required": false,
+          "default": "today midnight",
+          "description": "Range start. Absolute or relative date/time.",
+          "formats": ["absolute_date", "relative_date"]
+        },
+        "to": {
+          "cli": ["--to", "-t"],
+          "type": "string",
+          "required": false,
+          "default": "23:59 of day 30 from today",
+          "description": "Range end. Ignored when `in` is set.",
+          "formats": ["absolute_date", "relative_date"]
+        },
+        "in": {
+          "cli": ["--in", "-i"],
+          "type": "string",
+          "required": false,
+          "description": "Duration from `from`; overrides `to`.",
+          "formats": ["duration"]
+        },
+        "description": {
+          "cli": ["--description", "-d"],
+          "type": "string",
+          "required": false,
+          "description": "Case-insensitive contains filter on event summary or description."
+        },
+        "locale": {
+          "cli": ["--locale"],
+          "type": "string",
+          "enum": ["en", "it"],
+          "required": false,
+          "description": "Optional locale override."
+        }
+      },
       "inputSchema": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
           "calendar": {
             "type": "string",
-            "description": "Calendar name or ID. Default: calendar_default from config."
+            "description": "--calendar / -c. Calendar name or ID. Default: calendar_default from config."
           },
           "from": {
             "type": "string",
-            "description": "Start datetime. Default: today midnight. Formats: YYYY-MM-DD or YYYY-MM-DDTHH:MM"
+            "description": "--from / -f. Start datetime. Default: today midnight. Absolute (YYYY-MM-DD, locale dates) or relative (monday, tomorrow, next monday, lunedi, …)."
           },
           "to": {
             "type": "string",
-            "description": "End datetime. Default: 23:59 of day 30 from today. Ignored when `in` is set."
+            "description": "--to / -t. End datetime. Default: 23:59 of day 30 from today. Ignored when `in` is set. Same formats as from."
           },
           "in": {
             "type": "string",
-            "description": "Duration from `from` (or now/from default), overrides `to`. Prefer no spaces or quote values: 30days, 48hours, 2months, 1year, or \"30 days\"."
+            "description": "--in / -i. Duration from `from`, overrides `to`. Examples: 30days, \"3 days\", 2months, 1week, 48hours."
           },
           "description": {
             "type": "string",
-            "description": "Case-insensitive contains filter on event summary or description."
+            "description": "--description / -d. Case-insensitive contains filter on event summary or description."
           },
           "locale": {
             "type": "string",
-            "enum": ["en", "it"]
+            "enum": ["en", "it"],
+            "description": "--locale. Optional locale override (en, it)."
           }
         }
       }
@@ -251,7 +447,7 @@
     {
       "name": "flycal_slots",
       "title": "Find free time slots",
-      "description": "Find free slots using a config template (days + hours). Default template is the first one (work). Use --template dinner for evening hours. Subtracts busy events from slots.exclude_calendars. Starts from --from (default: now) for --in (default: 1 week). Duration defaults to 45min. Respects free_before/free_after. Output: header, template name, calendars, Google Calendar day link, continuous free ranges.",
+      "description": "Find continuous free ranges using a slots.templates schedule (days + hours). Default template = first key (usually work). Busy events come from slots.exclude_calendars (or calendar_default if empty). Respects free_before/free_after. Prints header + availability; copies availability list to clipboard when a clipboard tool exists.",
       "interactive": false,
       "requires_auth": true,
       "command": {
@@ -268,13 +464,71 @@
         "examples": [
           ["flycal", "slots"],
           ["flycal", "slots", "--in", "5 days"],
+          ["flycal", "slots", "--from", "monday", "--in", "5 days", "--locale", "it"],
           ["flycal", "slots", "--in", "12 days", "--template", "dinner"],
-          ["flycal", "slots", "--duration", "1h"]
+          ["flycal", "slots", "--from", "next monday", "--duration", "1h", "--template", "work"]
         ]
       },
+      "parameters": {
+        "duration": {
+          "cli": ["--duration"],
+          "type": "string",
+          "required": false,
+          "default": "config slots.defaults.default_duration (45min)",
+          "description": "Minimum free-range length to keep a slot.",
+          "formats": ["duration"],
+          "examples": ["45min", "1h", "90min"]
+        },
+        "from": {
+          "cli": ["--from", "-f"],
+          "type": "string",
+          "required": false,
+          "default": "config slots.defaults.from (now)",
+          "description": "Search window start. Absolute or relative date/time. If date-only is today, starts from now.",
+          "formats": ["absolute_date", "relative_date"],
+          "examples": ["now", "monday", "next monday", "lunedi", "2026-08-01"]
+        },
+        "in": {
+          "cli": ["--in", "-i"],
+          "type": "string",
+          "required": false,
+          "default": "1 week",
+          "description": "Search window length from --from.",
+          "formats": ["duration"],
+          "examples": ["5 days", "1 week", "12 days", "48 hours"]
+        },
+        "template": {
+          "cli": ["--template", "-T"],
+          "type": "string",
+          "required": false,
+          "default": "first key in slots.templates (usually work)",
+          "description": "Named schedule from config slots.templates (e.g. work, dinner).",
+          "examples": ["work", "dinner"]
+        },
+        "calendar": {
+          "cli": ["--calendar", "-c"],
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Fallback calendar name/ID only when slots.exclude_calendars is empty/unset."
+        },
+        "locale": {
+          "cli": ["--locale"],
+          "type": "string",
+          "enum": ["en", "it"],
+          "required": false,
+          "description": "Optional locale override."
+        }
+      },
       "output": {
         "format": "text/plain",
-        "example": "found 6 slots\nfrom sat 1 August 2026 to sat 8 August 2026\nwith duration 45min, template dinner\nconsidering calendars\n- Work\nlink: https://calendar.google.com/calendar/r/day/2026/8/1\n\nsaturday 1/8\n19 - 23"
+        "includes": [
+          "count + from/to + duration + template",
+          "bullet list of considered calendars",
+          "link: Google Calendar day URL at --from",
+          "availability ranges grouped by day (copied to clipboard without header)"
+        ],
+        "example": "found 6 slots\nfrom sat 1 August 2026 to sat 8 August 2026\nwith duration 45min, template dinner\nconsidering calendars\n- Work\n- Personal\nlink: https://calendar.google.com/calendar/r/day/2026/8/1\n\nsaturday 1/8\n19 - 23"
       },
       "inputSchema": {
         "type": "object",
@@ -283,37 +537,38 @@
         "properties": {
           "duration": {
             "type": "string",
-            "description": "Slot length. Default from config slots.defaults.default_duration (45min)."
+            "description": "--duration. Slot length. Optional. Default: slots.defaults.default_duration (45min). Examples: 45min, 1h, 90min."
           },
           "from": {
             "type": "string",
-            "description": "Start date/time. Default: now. Absolute dates, or relative: monday, next monday, tomorrow, lunedi, prossimo lunedi, etc."
+            "description": "--from / -f. Window start. Optional. Default: slots.defaults.from (now). Absolute dates (YYYY-MM-DD, locale dates) or relative (now, today/oggi, tomorrow/domani, monday/lunedi, next monday/prossimo lunedi, last friday/scorso venerdi)."
           },
           "in": {
             "type": "string",
-            "description": "Search window from --from. Default: 1 week. Examples: 3 days, 1 week, 48 hours (quote if spaces)."
+            "description": "--in / -i. Window length from --from. Optional. Default: 1 week. Examples: \"5 days\", 1week, \"12 days\", 48hours."
           },
           "template": {
             "type": "string",
-            "description": "Template name from slots.templates (default: first template, usually work)."
+            "description": "--template / -T. Template name from slots.templates. Optional. Default: first template (usually work). Built-ins: work (Mon-Fri office hours), dinner (evening hours)."
           },
           "calendar": {
             "type": "string",
-            "description": "Fallback calendar name/ID when exclude_calendars is not configured."
+            "description": "--calendar / -c. Fallback calendar name/ID when slots.exclude_calendars is empty."
           },
           "locale": {
             "type": "string",
-            "enum": ["en", "it"]
+            "enum": ["en", "it"],
+            "description": "--locale. Optional locale override (en, it)."
           }
         }
       }
     }
   ],
   "mcp_implementation_hints": {
-    "execution": "Spawn the flycal binary with argv from command.argv or build argv from option_map. Capture stdout/stderr and exit code. Return stdout as MCP text content.",
-    "interactive_tools": "Do not auto-run tools with interactive=true unless the host provides a TTY. Instead tell the user to run the command in a terminal.",
-    "auth_errors": "If stdout/stderr indicates the user is not connected, suggest flycal login.",
-    "locale_arg": "If input.locale is set, append --locale <value> to argv for any tool.",
-    "tool_filter": "Expose at least flycal_search, flycal_slots, flycal_calendars, and flycal_version for agent use."
+    "execution": "Spawn the flycal binary with argv from command.argv, or build argv from argv_template + option_map for each provided parameter. Capture stdout/stderr and exit code. Return stdout as MCP text content.",
+    "parameter_building": "For each non-null input property present in option_map, append the mapped flag and value. Quote values with spaces. Always append --locale when locale is set.",
+    "interactive_tools": "Do not auto-run tools with interactive=true unless the host provides a TTY. Tell the user to run them in a terminal.",
+    "auth_errors": "If output indicates the user is not connected, suggest flycal login (after credentials.json is in place).",
+    "tool_filter": "Prefer exposing flycal_search, flycal_slots, flycal_calendars, and flycal_version to agents."
   }
 }

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flycal-cli
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.7.4
 platform: ruby
 authors:
 - flycal-cli