flycal-cli 0.7.3 → 0.7.7

data/mcp/tools.json

@@ -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": {
@@ -208,42 +358,102 @@
           "to": ["--to", "{value}"],
           "in": ["--in", "{value}"],
           "description": ["--description", "{value}"],
-          "locale": ["--locale", "{value}"]
+          "locale": ["--locale", "{value}"],
+          "format": ["--format", "{value}"]
         },
         "examples": [
           ["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."
+        },
+        "format": {
+          "cli": ["--format"],
+          "type": "string",
+          "enum": ["text", "json"],
+          "required": false,
+          "default": "text",
+          "description": "Output format: text (shell) or json (pretty-printed)."
+        }
+      },
       "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)."
+          },
+          "format": {
+            "type": "string",
+            "enum": ["text", "json"],
+            "description": "--format. Output format (default: text). json returns params/info/items/groups."
           }
         }
       }
@@ -251,7 +461,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 +478,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 +551,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."
   }
 }

data/mockTemplates/mock1.json

@@ -0,0 +1,11 @@
+{
+  "mockCalendar": "mock1",
+  "mockEventDescriptionPatterns": "work,personal,event",
+  "mockEventCount": 100,
+  "mockEventFrom": "2026-01-01",
+  "mockEventTo": "2026-01-31",
+  "mockEventDurationMin": "4h",
+  "mockEventDurationMax": "4h",
+  "mockEventHoursFrom": "09:00",
+  "mockEventHoursTo": "17:00"
+}

data/mocks/mock1.json

@@ -0,0 +1,11 @@
+{
+  "mockCalendar": "mock1",
+  "mockEventDescriptionPatterns": "work,personal,event",
+  "mockEventCount": 100,
+  "mockEventFrom": "2026-01-01",
+  "mockEventTo": "2026-01-31",
+  "mockEventDurationMin": "4h",
+  "mockEventDurationMax": "4h",
+  "mockEventHoursFrom": "09:00",
+  "mockEventHoursTo": "17:00"
+}