flycal-cli 0.4.1 → 0.6.0
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.
- checksums.yaml +4 -4
- data/README.md +76 -17
- data/config/defaults.yml +8 -2
- data/lib/flycal_cli/cli.rb +270 -102
- data/lib/flycal_cli/config.rb +46 -1
- data/lib/flycal_cli/date_time_parser.rb +129 -0
- data/lib/flycal_cli/duration_parser.rb +15 -6
- data/lib/flycal_cli/locale.rb +6 -0
- data/lib/flycal_cli/slot_finder.rb +30 -12
- data/lib/flycal_cli/slot_formatter.rb +25 -0
- data/lib/flycal_cli/version.rb +1 -1
- data/lib/flycal_cli.rb +1 -0
- data/locales/en.json +26 -2
- data/locales/it.json +26 -2
- data/mcp/README.md +29 -0
- data/mcp/tools.json +318 -0
- metadata +4 -1
data/mcp/tools.json
ADDED
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"name": "flycal-cli",
|
|
4
|
+
"title": "flycal CLI MCP tools catalog",
|
|
5
|
+
"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.",
|
|
6
|
+
"version": "0.5.0",
|
|
7
|
+
"binary": "flycal",
|
|
8
|
+
"homepage": "https://github.com/magnum/flycal-cli",
|
|
9
|
+
"locale": {
|
|
10
|
+
"global_option": "--locale",
|
|
11
|
+
"supported": ["en", "it"],
|
|
12
|
+
"default": "en",
|
|
13
|
+
"config_key": "locale"
|
|
14
|
+
},
|
|
15
|
+
"config": {
|
|
16
|
+
"path": "~/.flycal/config.yml",
|
|
17
|
+
"credentials_path": "~/.flycal/credentials.json",
|
|
18
|
+
"keys": {
|
|
19
|
+
"calendar_default": {
|
|
20
|
+
"type": "string",
|
|
21
|
+
"description": "Default Google Calendar ID used by search and as slots fallback"
|
|
22
|
+
},
|
|
23
|
+
"locale": {
|
|
24
|
+
"type": "string",
|
|
25
|
+
"enum": ["en", "it"],
|
|
26
|
+
"description": "Default CLI locale"
|
|
27
|
+
},
|
|
28
|
+
"slots.hours": {
|
|
29
|
+
"type": "array",
|
|
30
|
+
"items": { "type": "string" },
|
|
31
|
+
"description": "Slot search hour ranges, e.g. [\"9:30-13:00\", \"14:00-18:30\"]"
|
|
32
|
+
},
|
|
33
|
+
"slots.defaults.from": {
|
|
34
|
+
"type": "string",
|
|
35
|
+
"description": "Default --from for slots (e.g. now or a date string)"
|
|
36
|
+
},
|
|
37
|
+
"slots.defaults.default_duration": {
|
|
38
|
+
"type": "string",
|
|
39
|
+
"description": "Default slot duration when --duration is omitted (e.g. 45min)"
|
|
40
|
+
},
|
|
41
|
+
"slots.free_before": {
|
|
42
|
+
"type": "string",
|
|
43
|
+
"description": "Buffer before each slot; events block this window before slot start"
|
|
44
|
+
},
|
|
45
|
+
"slots.free_after": {
|
|
46
|
+
"type": "string",
|
|
47
|
+
"description": "Buffer after each slot; gaps must fit duration + free_after"
|
|
48
|
+
},
|
|
49
|
+
"slots.weekdays_only": {
|
|
50
|
+
"type": "boolean",
|
|
51
|
+
"description": "When true, slots are searched Mon–Fri only"
|
|
52
|
+
},
|
|
53
|
+
"slots.exclude_calendars": {
|
|
54
|
+
"type": "array",
|
|
55
|
+
"items": { "type": "string" },
|
|
56
|
+
"description": "Calendar IDs whose events block free slots. If empty, calendar_default is used."
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
},
|
|
60
|
+
"notes": [
|
|
61
|
+
"flycal is read-only against Google Calendar (no create/update/delete of events).",
|
|
62
|
+
"Auth uses OAuth desktop flow; tokens live under ~/.flycal/.",
|
|
63
|
+
"Prefer quoting duration values that contain spaces (e.g. --in \"3 days\").",
|
|
64
|
+
"Duration formats without spaces also work (e.g. 30days, 48hours, 1h, 30min)."
|
|
65
|
+
],
|
|
66
|
+
"tools": [
|
|
67
|
+
{
|
|
68
|
+
"name": "flycal_version",
|
|
69
|
+
"title": "Show flycal version",
|
|
70
|
+
"description": "Print the installed flycal-cli version.",
|
|
71
|
+
"interactive": false,
|
|
72
|
+
"requires_auth": false,
|
|
73
|
+
"command": {
|
|
74
|
+
"argv": ["flycal", "version"],
|
|
75
|
+
"alternatives": [["flycal", "--version"], ["flycal", "-v"]]
|
|
76
|
+
},
|
|
77
|
+
"inputSchema": {
|
|
78
|
+
"type": "object",
|
|
79
|
+
"additionalProperties": false,
|
|
80
|
+
"properties": {
|
|
81
|
+
"locale": {
|
|
82
|
+
"type": "string",
|
|
83
|
+
"enum": ["en", "it"],
|
|
84
|
+
"description": "Optional locale override for this invocation"
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
},
|
|
89
|
+
{
|
|
90
|
+
"name": "flycal_update",
|
|
91
|
+
"title": "Update flycal gem",
|
|
92
|
+
"description": "Run gem update flycal-cli to install the latest published version.",
|
|
93
|
+
"interactive": false,
|
|
94
|
+
"requires_auth": false,
|
|
95
|
+
"side_effects": ["updates_local_gem"],
|
|
96
|
+
"command": {
|
|
97
|
+
"argv": ["flycal", "update"]
|
|
98
|
+
},
|
|
99
|
+
"inputSchema": {
|
|
100
|
+
"type": "object",
|
|
101
|
+
"additionalProperties": false,
|
|
102
|
+
"properties": {
|
|
103
|
+
"locale": {
|
|
104
|
+
"type": "string",
|
|
105
|
+
"enum": ["en", "it"]
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
},
|
|
110
|
+
{
|
|
111
|
+
"name": "flycal_login",
|
|
112
|
+
"title": "Connect Google account",
|
|
113
|
+
"description": "Start OAuth browser login for Google Calendar. Requires ~/.flycal/credentials.json and a browser. Interactive.",
|
|
114
|
+
"interactive": true,
|
|
115
|
+
"requires_auth": false,
|
|
116
|
+
"side_effects": ["writes_tokens"],
|
|
117
|
+
"command": {
|
|
118
|
+
"argv": ["flycal", "login"]
|
|
119
|
+
},
|
|
120
|
+
"inputSchema": {
|
|
121
|
+
"type": "object",
|
|
122
|
+
"additionalProperties": false,
|
|
123
|
+
"properties": {
|
|
124
|
+
"locale": {
|
|
125
|
+
"type": "string",
|
|
126
|
+
"enum": ["en", "it"]
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
},
|
|
131
|
+
{
|
|
132
|
+
"name": "flycal_logout",
|
|
133
|
+
"title": "Disconnect Google account",
|
|
134
|
+
"description": "Remove stored Google OAuth tokens and disconnect the account.",
|
|
135
|
+
"interactive": false,
|
|
136
|
+
"requires_auth": false,
|
|
137
|
+
"side_effects": ["deletes_tokens"],
|
|
138
|
+
"command": {
|
|
139
|
+
"argv": ["flycal", "logout"]
|
|
140
|
+
},
|
|
141
|
+
"inputSchema": {
|
|
142
|
+
"type": "object",
|
|
143
|
+
"additionalProperties": false,
|
|
144
|
+
"properties": {
|
|
145
|
+
"locale": {
|
|
146
|
+
"type": "string",
|
|
147
|
+
"enum": ["en", "it"]
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
},
|
|
152
|
+
{
|
|
153
|
+
"name": "flycal_calendars",
|
|
154
|
+
"title": "List calendars",
|
|
155
|
+
"description": "List available Google calendars as lines of \"name id\". Does not change configuration.",
|
|
156
|
+
"interactive": false,
|
|
157
|
+
"requires_auth": true,
|
|
158
|
+
"command": {
|
|
159
|
+
"argv": ["flycal", "calendars"]
|
|
160
|
+
},
|
|
161
|
+
"output": {
|
|
162
|
+
"format": "text/lines",
|
|
163
|
+
"example": "Work molinari@incode.it\nPersonal user@gmail.com"
|
|
164
|
+
},
|
|
165
|
+
"inputSchema": {
|
|
166
|
+
"type": "object",
|
|
167
|
+
"additionalProperties": false,
|
|
168
|
+
"properties": {
|
|
169
|
+
"locale": {
|
|
170
|
+
"type": "string",
|
|
171
|
+
"enum": ["en", "it"]
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
},
|
|
176
|
+
{
|
|
177
|
+
"name": "flycal_config",
|
|
178
|
+
"title": "Configure flycal (interactive)",
|
|
179
|
+
"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.",
|
|
180
|
+
"interactive": true,
|
|
181
|
+
"requires_auth": true,
|
|
182
|
+
"side_effects": ["writes_config"],
|
|
183
|
+
"command": {
|
|
184
|
+
"argv": ["flycal", "config"]
|
|
185
|
+
},
|
|
186
|
+
"menu_options": [
|
|
187
|
+
"calendar_default",
|
|
188
|
+
"exclude_calendars",
|
|
189
|
+
"edit config"
|
|
190
|
+
],
|
|
191
|
+
"inputSchema": {
|
|
192
|
+
"type": "object",
|
|
193
|
+
"additionalProperties": false,
|
|
194
|
+
"properties": {
|
|
195
|
+
"locale": {
|
|
196
|
+
"type": "string",
|
|
197
|
+
"enum": ["en", "it"]
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
},
|
|
202
|
+
{
|
|
203
|
+
"name": "flycal_search",
|
|
204
|
+
"title": "Search calendar events",
|
|
205
|
+
"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.",
|
|
206
|
+
"interactive": false,
|
|
207
|
+
"requires_auth": true,
|
|
208
|
+
"command": {
|
|
209
|
+
"argv_template": ["flycal", "search"],
|
|
210
|
+
"option_map": {
|
|
211
|
+
"calendar": ["--calendar", "{value}"],
|
|
212
|
+
"from": ["--from", "{value}"],
|
|
213
|
+
"to": ["--to", "{value}"],
|
|
214
|
+
"in": ["--in", "{value}"],
|
|
215
|
+
"description": ["--description", "{value}"],
|
|
216
|
+
"locale": ["--locale", "{value}"]
|
|
217
|
+
},
|
|
218
|
+
"examples": [
|
|
219
|
+
["flycal", "search"],
|
|
220
|
+
["flycal", "search", "--in", "30days", "--description", "placeholder"],
|
|
221
|
+
["flycal", "search", "-f", "2025-03-01", "-t", "2025-03-31", "-c", "Work"],
|
|
222
|
+
["flycal", "search", "--in", "2months", "-d", "placeholder", "--locale", "it"]
|
|
223
|
+
]
|
|
224
|
+
},
|
|
225
|
+
"inputSchema": {
|
|
226
|
+
"type": "object",
|
|
227
|
+
"additionalProperties": false,
|
|
228
|
+
"properties": {
|
|
229
|
+
"calendar": {
|
|
230
|
+
"type": "string",
|
|
231
|
+
"description": "Calendar name or ID. Default: calendar_default from config."
|
|
232
|
+
},
|
|
233
|
+
"from": {
|
|
234
|
+
"type": "string",
|
|
235
|
+
"description": "Start datetime. Default: today midnight. Formats: YYYY-MM-DD or YYYY-MM-DDTHH:MM"
|
|
236
|
+
},
|
|
237
|
+
"to": {
|
|
238
|
+
"type": "string",
|
|
239
|
+
"description": "End datetime. Default: 23:59 of day 30 from today. Ignored when `in` is set."
|
|
240
|
+
},
|
|
241
|
+
"in": {
|
|
242
|
+
"type": "string",
|
|
243
|
+
"description": "Duration from `from` (or now/from default), overrides `to`. Prefer no spaces or quote values: 30days, 48hours, 2months, 1year, or \"30 days\"."
|
|
244
|
+
},
|
|
245
|
+
"description": {
|
|
246
|
+
"type": "string",
|
|
247
|
+
"description": "Case-insensitive contains filter on event summary or description."
|
|
248
|
+
},
|
|
249
|
+
"locale": {
|
|
250
|
+
"type": "string",
|
|
251
|
+
"enum": ["en", "it"]
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
},
|
|
256
|
+
{
|
|
257
|
+
"name": "flycal_slots",
|
|
258
|
+
"title": "Find free time slots",
|
|
259
|
+
"description": "Find free slots within configured hours, subtracting busy events from slots.exclude_calendars (or calendar_default if that list is empty). Starts from --from (default: config slots.defaults.from or now) for a window of --in (default: 1 week). Duration defaults to slots.defaults.default_duration (45min). Respects free_before and free_after buffers from config. Output begins with a multi-line header, calendar names, a Google Calendar day link, then fixed-duration slots. Read-only.",
|
|
260
|
+
"interactive": false,
|
|
261
|
+
"requires_auth": true,
|
|
262
|
+
"command": {
|
|
263
|
+
"argv_template": ["flycal", "slots"],
|
|
264
|
+
"required_options": [],
|
|
265
|
+
"option_map": {
|
|
266
|
+
"duration": ["--duration", "{value}"],
|
|
267
|
+
"from": ["--from", "{value}"],
|
|
268
|
+
"in": ["--in", "{value}"],
|
|
269
|
+
"calendar": ["--calendar", "{value}"],
|
|
270
|
+
"locale": ["--locale", "{value}"]
|
|
271
|
+
},
|
|
272
|
+
"examples": [
|
|
273
|
+
["flycal", "slots"],
|
|
274
|
+
["flycal", "slots", "--duration", "1h"],
|
|
275
|
+
["flycal", "slots", "--from", "2026-08-01", "--in", "2 weeks", "--duration", "1h"]
|
|
276
|
+
]
|
|
277
|
+
},
|
|
278
|
+
"output": {
|
|
279
|
+
"format": "text/plain",
|
|
280
|
+
"example": "found 3 slots\nfrom wed 29 July 2026 to wed 5 August 2026\nwith duration 45min\nfor calendars\nWork\nhttps://calendar.google.com/calendar/r/day/2026/7/29\n\nfriday 15/7\n10-12\n13-15.30"
|
|
281
|
+
},
|
|
282
|
+
"inputSchema": {
|
|
283
|
+
"type": "object",
|
|
284
|
+
"additionalProperties": false,
|
|
285
|
+
"required": [],
|
|
286
|
+
"properties": {
|
|
287
|
+
"duration": {
|
|
288
|
+
"type": "string",
|
|
289
|
+
"description": "Slot length. Default from config slots.defaults.default_duration (45min)."
|
|
290
|
+
},
|
|
291
|
+
"from": {
|
|
292
|
+
"type": "string",
|
|
293
|
+
"description": "Start date/time. Default: now. YYYY-MM-DD always; with locale it also DD-MM-YYYY; with locale en also MM-DD-YYYY. Separators - or /. Optional time."
|
|
294
|
+
},
|
|
295
|
+
"in": {
|
|
296
|
+
"type": "string",
|
|
297
|
+
"description": "Search window from --from. Default: 1 week. Examples: 3 days, 1 week, 48 hours (quote if spaces)."
|
|
298
|
+
},
|
|
299
|
+
"calendar": {
|
|
300
|
+
"type": "string",
|
|
301
|
+
"description": "Fallback calendar name/ID when exclude_calendars is not configured."
|
|
302
|
+
},
|
|
303
|
+
"locale": {
|
|
304
|
+
"type": "string",
|
|
305
|
+
"enum": ["en", "it"]
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
],
|
|
311
|
+
"mcp_implementation_hints": {
|
|
312
|
+
"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.",
|
|
313
|
+
"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.",
|
|
314
|
+
"auth_errors": "If stdout/stderr indicates the user is not connected, suggest flycal login.",
|
|
315
|
+
"locale_arg": "If input.locale is set, append --locale <value> to argv for any tool.",
|
|
316
|
+
"tool_filter": "Expose at least flycal_search, flycal_slots, flycal_calendars, and flycal_version for agent use."
|
|
317
|
+
}
|
|
318
|
+
}
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: flycal-cli
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.6.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- flycal-cli
|
|
@@ -139,6 +139,7 @@ files:
|
|
|
139
139
|
- lib/flycal_cli/calendar_service.rb
|
|
140
140
|
- lib/flycal_cli/cli.rb
|
|
141
141
|
- lib/flycal_cli/config.rb
|
|
142
|
+
- lib/flycal_cli/date_time_parser.rb
|
|
142
143
|
- lib/flycal_cli/duration_parser.rb
|
|
143
144
|
- lib/flycal_cli/locale.rb
|
|
144
145
|
- lib/flycal_cli/slot_finder.rb
|
|
@@ -146,6 +147,8 @@ files:
|
|
|
146
147
|
- lib/flycal_cli/version.rb
|
|
147
148
|
- locales/en.json
|
|
148
149
|
- locales/it.json
|
|
150
|
+
- mcp/README.md
|
|
151
|
+
- mcp/tools.json
|
|
149
152
|
homepage: https://github.com/magnum/flycal-cli
|
|
150
153
|
licenses:
|
|
151
154
|
- MIT
|