kaiten-cli 0.3.3__py3-none-any.whl

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 (99) hide show
  1. kaiten_cli/__init__.py +5 -0
  2. kaiten_cli/__main__.py +9 -0
  3. kaiten_cli/agent_gateway.py +577 -0
  4. kaiten_cli/app.py +1636 -0
  5. kaiten_cli/completion.py +570 -0
  6. kaiten_cli/discovery.py +39 -0
  7. kaiten_cli/errors.py +79 -0
  8. kaiten_cli/i18n.py +92 -0
  9. kaiten_cli/locales/ru.json +2967 -0
  10. kaiten_cli/localized_click.py +160 -0
  11. kaiten_cli/models.py +202 -0
  12. kaiten_cli/profiles.py +316 -0
  13. kaiten_cli/registry/__init__.py +260 -0
  14. kaiten_cli/registry/addons.py +392 -0
  15. kaiten_cli/registry/audit_and_analytics.py +451 -0
  16. kaiten_cli/registry/automation_schema.py +44 -0
  17. kaiten_cli/registry/automation_schemas.json +7417 -0
  18. kaiten_cli/registry/automations.py +342 -0
  19. kaiten_cli/registry/base.py +62 -0
  20. kaiten_cli/registry/blockers.py +320 -0
  21. kaiten_cli/registry/boards.py +520 -0
  22. kaiten_cli/registry/card_relations.py +376 -0
  23. kaiten_cli/registry/card_types.py +363 -0
  24. kaiten_cli/registry/cards.py +1329 -0
  25. kaiten_cli/registry/charts.py +539 -0
  26. kaiten_cli/registry/checklists.py +600 -0
  27. kaiten_cli/registry/columns.py +558 -0
  28. kaiten_cli/registry/comments.py +224 -0
  29. kaiten_cli/registry/custom_directories.py +980 -0
  30. kaiten_cli/registry/custom_properties.py +1460 -0
  31. kaiten_cli/registry/dashboards.py +564 -0
  32. kaiten_cli/registry/documents.py +761 -0
  33. kaiten_cli/registry/external_links.py +128 -0
  34. kaiten_cli/registry/files.py +738 -0
  35. kaiten_cli/registry/github_addon.py +613 -0
  36. kaiten_cli/registry/iterations.py +397 -0
  37. kaiten_cli/registry/lanes.py +205 -0
  38. kaiten_cli/registry/live_contracts.py +361 -0
  39. kaiten_cli/registry/members.py +336 -0
  40. kaiten_cli/registry/module_docs.py +108 -0
  41. kaiten_cli/registry/projects.py +369 -0
  42. kaiten_cli/registry/query.py +129 -0
  43. kaiten_cli/registry/restrictions.py +249 -0
  44. kaiten_cli/registry/roles_and_groups.py +1102 -0
  45. kaiten_cli/registry/scim.py +263 -0
  46. kaiten_cli/registry/service_desk.py +1270 -0
  47. kaiten_cli/registry/snapshot.py +187 -0
  48. kaiten_cli/registry/spaces.py +272 -0
  49. kaiten_cli/registry/subscribers.py +168 -0
  50. kaiten_cli/registry/tags.py +193 -0
  51. kaiten_cli/registry/time_logs.py +353 -0
  52. kaiten_cli/registry/tree.py +352 -0
  53. kaiten_cli/registry/utilities.py +287 -0
  54. kaiten_cli/registry/webhooks.py +265 -0
  55. kaiten_cli/runtime/__init__.py +1 -0
  56. kaiten_cli/runtime/automation_validation.py +115 -0
  57. kaiten_cli/runtime/behaviors.py +787 -0
  58. kaiten_cli/runtime/cache.py +733 -0
  59. kaiten_cli/runtime/client.py +387 -0
  60. kaiten_cli/runtime/endpoints.py +59 -0
  61. kaiten_cli/runtime/executor.py +269 -0
  62. kaiten_cli/runtime/fs_security.py +168 -0
  63. kaiten_cli/runtime/input.py +310 -0
  64. kaiten_cli/runtime/output.py +59 -0
  65. kaiten_cli/runtime/public_validation.py +35 -0
  66. kaiten_cli/runtime/snapshot_build.py +527 -0
  67. kaiten_cli/runtime/snapshot_common.py +363 -0
  68. kaiten_cli/runtime/snapshot_query.py +306 -0
  69. kaiten_cli/runtime/snapshot_store.py +1192 -0
  70. kaiten_cli/runtime/snapshots.py +62 -0
  71. kaiten_cli/runtime/sqlite_errors.py +23 -0
  72. kaiten_cli/runtime/support/__init__.py +1 -0
  73. kaiten_cli/runtime/support/addons.py +953 -0
  74. kaiten_cli/runtime/support/audit.py +70 -0
  75. kaiten_cli/runtime/support/batch.py +234 -0
  76. kaiten_cli/runtime/support/card_move_url.py +213 -0
  77. kaiten_cli/runtime/support/cards.py +174 -0
  78. kaiten_cli/runtime/support/checklists.py +21 -0
  79. kaiten_cli/runtime/support/company_users.py +117 -0
  80. kaiten_cli/runtime/support/dashboards.py +35 -0
  81. kaiten_cli/runtime/support/documents.py +175 -0
  82. kaiten_cli/runtime/support/files.py +561 -0
  83. kaiten_cli/runtime/support/markdown_export.py +525 -0
  84. kaiten_cli/runtime/support/pagination.py +167 -0
  85. kaiten_cli/runtime/support/projects.py +66 -0
  86. kaiten_cli/runtime/support/relations.py +86 -0
  87. kaiten_cli/runtime/support/restrictions.py +62 -0
  88. kaiten_cli/runtime/support/spaces.py +20 -0
  89. kaiten_cli/runtime/support/time_logs.py +61 -0
  90. kaiten_cli/runtime/support/tree.py +140 -0
  91. kaiten_cli/runtime/support/tree_sharing.py +447 -0
  92. kaiten_cli/runtime/trace.py +500 -0
  93. kaiten_cli/runtime/transforms.py +128 -0
  94. kaiten_cli/schema_docs.py +22 -0
  95. kaiten_cli/update_check.py +519 -0
  96. kaiten_cli-0.3.3.dist-info/METADATA +1110 -0
  97. kaiten_cli-0.3.3.dist-info/RECORD +99 -0
  98. kaiten_cli-0.3.3.dist-info/WHEEL +4 -0
  99. kaiten_cli-0.3.3.dist-info/entry_points.txt +3 -0
@@ -0,0 +1,761 @@
1
+ """Document and document-group tool specs."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from kaiten_cli.models import (
6
+ CACHE_POLICY_NONE,
7
+ CACHE_POLICY_PERSISTENT_OPT_IN,
8
+ ExampleSpec,
9
+ OperationSpec,
10
+ ResponsePolicy,
11
+ RuntimeBehavior,
12
+ )
13
+ from kaiten_cli.registry.base import make_tool
14
+ from kaiten_cli.runtime.behaviors import (
15
+ document_list_search_request,
16
+ prepare_document_request,
17
+ prevent_redirect_request,
18
+ )
19
+ from kaiten_cli.runtime.support.files import execute_file_upload
20
+ from kaiten_cli.runtime.support.markdown_export import execute_document_get
21
+
22
+
23
+ DOCUMENT_PARENT_USAGE_NOTES = (
24
+ "`parent_entity_uid` places the document under a document group/container in the sidebar tree.",
25
+ "Do not use document parent fields for UI catalog tables (`custom-directories`) or `custom-properties catalog-values`.",
26
+ )
27
+
28
+ DOCUMENT_GROUP_USAGE_NOTES = (
29
+ "Document groups are document folders/containers in the sidebar tree.",
30
+ "Use `document-groups.*` when a request says document catalog, folder, or container.",
31
+ "They do not manage UI catalog tables (`custom-directories`) or `custom-properties catalog-values`.",
32
+ "Documents can be placed into a group with `parent_entity_uid`; tree commands read groups together with documents and spaces.",
33
+ )
34
+
35
+
36
+ TOOLS = (
37
+ make_tool(
38
+ canonical_name="documents.list",
39
+ mcp_alias="kaiten_list_documents",
40
+ description="List Kaiten documents.",
41
+ input_schema={
42
+ "type": "object",
43
+ "properties": {
44
+ "query": {"type": "string", "description": "Search filter"},
45
+ "limit": {
46
+ "type": "integer",
47
+ "minimum": 1,
48
+ "maximum": 100,
49
+ "description": "Max results (default: 50, max: 100)",
50
+ },
51
+ "offset": {"type": "integer", "minimum": 0, "description": "Pagination offset"},
52
+ "version": {
53
+ "type": "integer",
54
+ "description": "Search version. Use 2 for OpenSearch result/position response.",
55
+ },
56
+ "condition": {"type": "integer", "description": "Filter condition for version=2"},
57
+ "search_fields": {
58
+ "type": "string",
59
+ "description": "Comma-separated API search fields for version=2. Sent as Kaiten query parameter 'fields'.",
60
+ },
61
+ "start_position": {
62
+ "type": "string",
63
+ "description": "Search cursor for version=2 pagination.",
64
+ },
65
+ "include_search_preview": {
66
+ "type": "boolean",
67
+ "description": "Include search preview objects for version=2.",
68
+ },
69
+ "fields": {
70
+ "type": "string",
71
+ "description": "Comma-separated field names to keep in the response. Example: 'uid,title'",
72
+ },
73
+ "compact": {
74
+ "type": "boolean",
75
+ "description": "Return compact response without heavy fields (avatars, nested user objects)",
76
+ "default": False,
77
+ },
78
+ },
79
+ },
80
+ operation=OperationSpec(
81
+ method="GET",
82
+ path_template="/documents",
83
+ query_fields=(
84
+ "query",
85
+ "limit",
86
+ "offset",
87
+ "version",
88
+ "condition",
89
+ "start_position",
90
+ "include_search_preview",
91
+ ),
92
+ ),
93
+ runtime_behavior=RuntimeBehavior(
94
+ request_shaper=document_list_search_request,
95
+ ),
96
+ response_policy=ResponsePolicy(
97
+ compact_supported=True, fields_supported=True, default_limit=50, result_kind="list"
98
+ ),
99
+ examples=(
100
+ ExampleSpec(
101
+ command='kaiten --json documents list --query "Design"',
102
+ description="List documents.",
103
+ ),
104
+ ExampleSpec(
105
+ command="kaiten --json documents list --compact --fields uid,title",
106
+ description="List documents with a narrow response surface.",
107
+ ),
108
+ ),
109
+ ),
110
+ make_tool(
111
+ canonical_name="documents.create",
112
+ mcp_alias="kaiten_create_document",
113
+ description="Create a new Kaiten document.",
114
+ input_schema={
115
+ "type": "object",
116
+ "properties": {
117
+ "title": {"type": "string", "description": "Document title"},
118
+ "text": {
119
+ "type": "string",
120
+ "description": "Markdown content converted to ProseMirror.",
121
+ },
122
+ "data": {"type": "object", "description": "Raw ProseMirror JSON."},
123
+ "parent_entity_uid": {
124
+ "type": ["string", "null"],
125
+ "description": "Parent document group UID",
126
+ "x-documentation-alternatives": [
127
+ {"type": "string", "description": "Parent tree entity uid"},
128
+ {"type": "null"},
129
+ ],
130
+ },
131
+ "sort_order": {
132
+ "type": ["integer", "number"],
133
+ "description": "Sort order (auto-generated if not provided)",
134
+ },
135
+ "key": {
136
+ "type": ["string", "null"],
137
+ "description": "Unique key identifier",
138
+ "pattern": "^[A-Z][A-Z0-9_]{1,9}$",
139
+ "x-documentation-alternatives": [
140
+ {
141
+ "type": "string",
142
+ "minLength": 2,
143
+ "maxLength": 10,
144
+ "pattern": "^[A-Z][A-Z0-9_]{1,9}$",
145
+ "description": "Unique key for document, used in API and web interface. Must be unique across entire company",
146
+ },
147
+ {"type": "null"},
148
+ ],
149
+ },
150
+ "for_everyone_access_role_id": {"type": "string"},
151
+ "clone_uid": {"type": "string", "description": "Document uid to copy"},
152
+ "clone_version": {"type": "number", "description": "Document version to copy"},
153
+ },
154
+ "required": [],
155
+ },
156
+ operation=OperationSpec(
157
+ method="POST",
158
+ path_template="/documents",
159
+ body_fields=(
160
+ "title",
161
+ "text",
162
+ "data",
163
+ "parent_entity_uid",
164
+ "sort_order",
165
+ "key",
166
+ "for_everyone_access_role_id",
167
+ "clone_uid",
168
+ "clone_version",
169
+ ),
170
+ ),
171
+ runtime_behavior=RuntimeBehavior(request_shaper=prepare_document_request),
172
+ examples=(
173
+ ExampleSpec(
174
+ command='kaiten --json documents create --title "Spec" --text "# Header"',
175
+ description="Create a document from markdown.",
176
+ ),
177
+ ),
178
+ usage_notes=DOCUMENT_PARENT_USAGE_NOTES,
179
+ ),
180
+ make_tool(
181
+ canonical_name="documents.get",
182
+ mcp_alias="kaiten_get_document",
183
+ description="Get a Kaiten document by UID.",
184
+ input_schema={
185
+ "type": "object",
186
+ "properties": {
187
+ "document_uid": {"type": "string", "description": "Document UID"},
188
+ "markdown": {
189
+ "type": "boolean",
190
+ "description": "Save the document body as Markdown instead of returning JSON.",
191
+ },
192
+ "output": {
193
+ "type": "string",
194
+ "description": "Markdown output file or directory. Defaults to the current working directory.",
195
+ },
196
+ "overwrite": {
197
+ "type": "boolean",
198
+ "description": "Replace an existing Markdown output file.",
199
+ },
200
+ },
201
+ "required": ["document_uid"],
202
+ },
203
+ operation=OperationSpec(
204
+ method="GET", path_template="/documents/{document_uid}", path_fields=("document_uid",)
205
+ ),
206
+ runtime_behavior=RuntimeBehavior(
207
+ execution_mode="custom",
208
+ custom_executor=execute_document_get,
209
+ cache_policy=CACHE_POLICY_PERSISTENT_OPT_IN,
210
+ ),
211
+ examples=(
212
+ ExampleSpec(
213
+ command="kaiten --json documents get --document-uid doc-1",
214
+ description="Get a document.",
215
+ ),
216
+ ExampleSpec(
217
+ command="kaiten --json documents get --document-uid doc-1 --markdown --output ./doc.md",
218
+ description="Save a document as Markdown.",
219
+ ),
220
+ ),
221
+ usage_notes=(
222
+ "`--markdown` does the same document GET, renders the result locally, and saves a Markdown file instead of returning the document JSON.",
223
+ "`--markdown` keeps document file links as Kaiten `/api/documents/<uid>/files/<file_id>` URLs.",
224
+ "Use `--output` for the target file/directory and `--overwrite` to replace an existing Markdown file.",
225
+ "Separate CLI processes do not share in-memory results, so default `--cache-mode auto` persists repeated safe document reads.",
226
+ ),
227
+ ),
228
+ make_tool(
229
+ canonical_name="documents.update",
230
+ mcp_alias="kaiten_update_document",
231
+ description="Update a Kaiten document.",
232
+ input_schema={
233
+ "type": "object",
234
+ "properties": {
235
+ "document_uid": {"type": "string", "description": "Document UID"},
236
+ "title": {"type": "string", "description": "New document title"},
237
+ "text": {
238
+ "type": "string",
239
+ "description": "Markdown content converted to ProseMirror.",
240
+ },
241
+ "data": {"type": "object", "description": "Raw ProseMirror JSON."},
242
+ "parent_entity_uid": {
243
+ "type": ["string", "null"],
244
+ "description": "New parent group UID",
245
+ },
246
+ "sort_order": {"type": ["integer", "number"], "description": "Sort order"},
247
+ "key": {
248
+ "type": ["string", "null"],
249
+ "description": "Unique key identifier",
250
+ "pattern": "^[A-Z][A-Z0-9_]{1,9}$",
251
+ "x-documentation-alternatives": [
252
+ {
253
+ "type": "string",
254
+ "minLength": 2,
255
+ "maxLength": 10,
256
+ "pattern": "^[A-Z][A-Z0-9_]{1,9}$",
257
+ "description": "Unique key for document, used in API and web interface. Must be unique across entire company",
258
+ },
259
+ {"type": "null", "description": "Reset existing key"},
260
+ ],
261
+ },
262
+ "publish_date": {
263
+ "description": "Deadline. ISO 8601 format",
264
+ "type": ["string", "null"],
265
+ "x-documentation-alternatives": [
266
+ {"type": "string", "description": "Deadline. ISO 8601 format"},
267
+ {"type": "null", "description": "Empty card description"},
268
+ ],
269
+ },
270
+ "access": {"enum": ["for_everyone", "by_invite"], "type": "string"},
271
+ "for_everyone_access_role_id": {"type": "string"},
272
+ "public": {"type": "boolean"},
273
+ "redirect_url": {"type": ["string", "null"]},
274
+ "hidden_on_public_site": {"type": "boolean"},
275
+ "settings": {
276
+ "type": "object",
277
+ "description": "Server-side shallow merge: only the key(s) sent are changed, other existing settings are preserved. Sending a key with value null removes it (for keys whose schema allows null).",
278
+ "properties": {
279
+ "content_width": {
280
+ "type": "string",
281
+ "enum": ["default", "wide"],
282
+ "description": 'Setting this to "wide" is only available for companies in the documents-ui-settings rollout; other companies get a 403 (code doc_2) if they try. Setting it to "default" is always allowed.',
283
+ }
284
+ },
285
+ "x-documentation-additionalProperties": False,
286
+ },
287
+ "backup_version": {"type": "number"},
288
+ "published_version": {
289
+ "description": "Version to publish on public site: a number, null, or current.",
290
+ "type": ["number", "null", "string"],
291
+ "oneOf": [
292
+ {"type": "number", "description": "Version to publish on public site"},
293
+ {
294
+ "type": "null",
295
+ "description": "No spicific version to publish on public site, current version will be published",
296
+ },
297
+ {"type": "string", "enum": ["current"]},
298
+ ],
299
+ },
300
+ "icon_type": {
301
+ "enum": ["emoji", "material_icon"],
302
+ "description": "Type of icon",
303
+ "type": ["string", "null"],
304
+ "x-documentation-alternatives": [
305
+ {"enum": ["emoji", "material_icon"], "description": "Type of icon"},
306
+ {"type": "null", "description": "No icon"},
307
+ ],
308
+ },
309
+ "icon_value": {
310
+ "maxLength": 100,
311
+ "description": "Icon value (emoji character or material icon name)",
312
+ "type": ["string", "null"],
313
+ "x-documentation-alternatives": [
314
+ {
315
+ "type": "string",
316
+ "maxLength": 100,
317
+ "description": "Icon value (emoji character or material icon name)",
318
+ },
319
+ {"type": "null", "description": "No icon value"},
320
+ ],
321
+ },
322
+ "icon_color": {
323
+ "minimum": 1,
324
+ "maximum": 17,
325
+ "description": "Icon color index (1-17)",
326
+ "type": ["integer", "null"],
327
+ "x-documentation-alternatives": [
328
+ {
329
+ "type": "integer",
330
+ "minimum": 1,
331
+ "maximum": 17,
332
+ "description": "Icon color index (1-17)",
333
+ },
334
+ {"type": "null", "description": "No icon color"},
335
+ ],
336
+ },
337
+ "notification_period_start": {
338
+ "description": "Notification period start date",
339
+ "type": ["string", "null"],
340
+ "x-documentation-alternatives": [
341
+ {"type": "string", "description": "Notification period start date"},
342
+ {"type": "null", "description": "Reset notification period start date"},
343
+ ],
344
+ },
345
+ "notification_period_end": {
346
+ "description": "Notification period end date",
347
+ "type": ["string", "null"],
348
+ "x-documentation-alternatives": [
349
+ {"type": "string", "description": "Notification period end date"},
350
+ {"type": "null", "description": "Reset notification period end date"},
351
+ ],
352
+ },
353
+ "slug": {
354
+ "minLength": 3,
355
+ "maxLength": 128,
356
+ "pattern": "^[a-z0-9-]+$",
357
+ "description": "Human-readable URL slug. Lowercase latin letters, digits and hyphens only. Must be unique within the public site subtree",
358
+ "type": ["string", "null"],
359
+ "x-documentation-alternatives": [
360
+ {
361
+ "type": "string",
362
+ "minLength": 3,
363
+ "maxLength": 128,
364
+ "pattern": "^[a-z0-9-]+$",
365
+ "description": "Human-readable URL slug. Lowercase latin letters, digits and hyphens only. Must be unique within the public site subtree",
366
+ },
367
+ {
368
+ "type": "null",
369
+ "description": "Reset slug (fall back to auto-slug generated from title)",
370
+ },
371
+ ],
372
+ },
373
+ },
374
+ "required": ["document_uid"],
375
+ },
376
+ operation=OperationSpec(
377
+ method="PATCH",
378
+ path_template="/documents/{document_uid}",
379
+ path_fields=("document_uid",),
380
+ body_fields=(
381
+ "title",
382
+ "text",
383
+ "data",
384
+ "parent_entity_uid",
385
+ "sort_order",
386
+ "key",
387
+ "publish_date",
388
+ "access",
389
+ "for_everyone_access_role_id",
390
+ "public",
391
+ "redirect_url",
392
+ "hidden_on_public_site",
393
+ "settings",
394
+ "backup_version",
395
+ "published_version",
396
+ "icon_type",
397
+ "icon_value",
398
+ "icon_color",
399
+ "notification_period_start",
400
+ "notification_period_end",
401
+ "slug",
402
+ ),
403
+ ),
404
+ runtime_behavior=RuntimeBehavior(request_shaper=prepare_document_request),
405
+ examples=(
406
+ ExampleSpec(
407
+ command='kaiten --json documents update --document-uid doc-1 --text "**bold**"',
408
+ description="Update a document body.",
409
+ ),
410
+ ),
411
+ usage_notes=DOCUMENT_PARENT_USAGE_NOTES,
412
+ ),
413
+ make_tool(
414
+ canonical_name="documents.delete",
415
+ mcp_alias="kaiten_delete_document",
416
+ description="Delete a Kaiten document.",
417
+ input_schema={
418
+ "type": "object",
419
+ "properties": {"document_uid": {"type": "string", "description": "Document UID"}},
420
+ "required": ["document_uid"],
421
+ },
422
+ operation=OperationSpec(
423
+ method="DELETE",
424
+ path_template="/documents/{document_uid}",
425
+ path_fields=("document_uid",),
426
+ ),
427
+ examples=(
428
+ ExampleSpec(
429
+ command="kaiten --json documents delete --document-uid doc-1",
430
+ description="Delete a document.",
431
+ ),
432
+ ),
433
+ ),
434
+ make_tool(
435
+ canonical_name="document-files.get-url",
436
+ mcp_alias="kaiten_get_document_file_url",
437
+ description="Resolve a document file to a short-lived signed download URL.",
438
+ input_schema={
439
+ "type": "object",
440
+ "properties": {
441
+ "document_uid": {"type": "string", "description": "Document UID"},
442
+ "file_id": {"type": "string", "description": "Document file UID without extension"},
443
+ },
444
+ "required": ["document_uid", "file_id"],
445
+ },
446
+ operation=OperationSpec(
447
+ method="GET",
448
+ path_template="/documents/{document_uid}/files/{file_id}",
449
+ path_fields=("document_uid", "file_id"),
450
+ ),
451
+ runtime_behavior=RuntimeBehavior(request_shaper=prevent_redirect_request),
452
+ examples=(
453
+ ExampleSpec(
454
+ command="kaiten --json document-files get-url --document-uid doc-1 --file-id file-1",
455
+ description="Resolve a private document file URL for download.",
456
+ ),
457
+ ),
458
+ usage_notes=(
459
+ "Uses `prevent_redirect=true`, so the response is JSON with a short-lived signed storage URL instead of an HTTP redirect.",
460
+ ),
461
+ ),
462
+ make_tool(
463
+ canonical_name="document-files.upload",
464
+ mcp_alias="kaiten_upload_document_file",
465
+ description="Upload a local binary file to a Kaiten document using multipart/form-data.",
466
+ input_schema={
467
+ "type": "object",
468
+ "properties": {
469
+ "document_uid": {"type": "string", "description": "Document UID."},
470
+ "file": {"type": "string", "description": "Local file path to upload."},
471
+ },
472
+ "required": ["document_uid", "file"],
473
+ },
474
+ operation=OperationSpec(
475
+ method="PUT",
476
+ path_template="/documents/{document_uid}/files",
477
+ path_fields=("document_uid",),
478
+ ),
479
+ runtime_behavior=RuntimeBehavior(
480
+ execution_mode="custom",
481
+ custom_executor=execute_file_upload,
482
+ cache_policy=CACHE_POLICY_NONE,
483
+ ),
484
+ examples=(
485
+ ExampleSpec(
486
+ command="kaiten --json document-files upload --document-uid doc-1 --file ./screenshot.png",
487
+ description="Upload a local file to a document.",
488
+ ),
489
+ ),
490
+ usage_notes=(
491
+ "Uploads the local file as multipart/form-data field `file`.",
492
+ "The returned `id` can be used as a ProseMirror image node `attrs.fileId`.",
493
+ ),
494
+ ),
495
+ make_tool(
496
+ canonical_name="document-schemas.get",
497
+ mcp_alias="kaiten_get_document_schema",
498
+ description="Get a document data schema.",
499
+ input_schema={
500
+ "type": "object",
501
+ "properties": {
502
+ "schema_id": {"type": "integer", "description": "Document schema ID."},
503
+ "format": {"description": "Response format. Default: draft-06.", "type": "string"},
504
+ },
505
+ "required": ["schema_id"],
506
+ },
507
+ operation=OperationSpec(
508
+ method="GET",
509
+ path_template="/document-schemas/{schema_id}",
510
+ path_fields=("schema_id",),
511
+ query_fields=("format",),
512
+ ),
513
+ examples=(
514
+ ExampleSpec(
515
+ command="kaiten --json document-schemas get --schema-id 1",
516
+ description="Get a document data schema.",
517
+ ),
518
+ ),
519
+ ),
520
+ make_tool(
521
+ canonical_name="document-groups.list",
522
+ mcp_alias="kaiten_list_document_groups",
523
+ description="List Kaiten document groups.",
524
+ input_schema={
525
+ "type": "object",
526
+ "properties": {
527
+ "query": {"type": "string", "description": "Search filter"},
528
+ "limit": {
529
+ "type": "integer",
530
+ "minimum": 1,
531
+ "maximum": 100,
532
+ "description": "Max results (default: 50, max: 100)",
533
+ },
534
+ "offset": {"type": "integer", "minimum": 0, "description": "Pagination offset"},
535
+ "version": {
536
+ "type": "integer",
537
+ "description": "Search version. Default: 1. Use version=2 to search via OpenSearch and enable the new response format with result and position fields",
538
+ },
539
+ "condition": {
540
+ "type": "integer",
541
+ "description": "Filter condition. Used with version=2",
542
+ },
543
+ "start_position": {
544
+ "type": "string",
545
+ "description": "Search cursor for version=2 pagination. Pass the position value from the previous version=2 response",
546
+ },
547
+ "role": {
548
+ "type": "integer",
549
+ "description": "Filter by minimum user role. 1 — reader, 2 — writer, 3 — admin",
550
+ },
551
+ },
552
+ },
553
+ operation=OperationSpec(
554
+ method="GET",
555
+ path_template="/document-groups",
556
+ query_fields=(
557
+ "query",
558
+ "limit",
559
+ "offset",
560
+ "version",
561
+ "condition",
562
+ "start_position",
563
+ "role",
564
+ ),
565
+ ),
566
+ response_policy=ResponsePolicy(default_limit=50, result_kind="list"),
567
+ examples=(
568
+ ExampleSpec(
569
+ command='kaiten --json document-groups list --query "Engineering"',
570
+ description="List document groups.",
571
+ ),
572
+ ),
573
+ usage_notes=DOCUMENT_GROUP_USAGE_NOTES,
574
+ ),
575
+ make_tool(
576
+ canonical_name="document-groups.create",
577
+ mcp_alias="kaiten_create_document_group",
578
+ description="Create a new Kaiten document group.",
579
+ input_schema={
580
+ "type": "object",
581
+ "properties": {
582
+ "title": {"type": "string", "description": "Group title"},
583
+ "parent_entity_uid": {
584
+ "type": ["string", "null"],
585
+ "description": "Parent group UID for nesting",
586
+ },
587
+ "sort_order": {
588
+ "type": ["integer", "number"],
589
+ "description": "Sort order (auto-generated if not provided)",
590
+ },
591
+ "for_everyone_access_role_id": {
592
+ "type": ["string", "null"],
593
+ "format": "uuid",
594
+ "description": "Role id for everyone access",
595
+ },
596
+ "key": {
597
+ "type": ["string", "null"],
598
+ "maxLength": 256,
599
+ "description": "Unique document group key within company",
600
+ },
601
+ },
602
+ "required": ["title"],
603
+ },
604
+ operation=OperationSpec(
605
+ method="POST",
606
+ path_template="/document-groups",
607
+ body_fields=(
608
+ "title",
609
+ "parent_entity_uid",
610
+ "sort_order",
611
+ "for_everyone_access_role_id",
612
+ "key",
613
+ ),
614
+ ),
615
+ runtime_behavior=RuntimeBehavior(request_shaper=prepare_document_request),
616
+ examples=(
617
+ ExampleSpec(
618
+ command='kaiten --json document-groups create --title "Engineering"',
619
+ description="Create a document group.",
620
+ ),
621
+ ),
622
+ usage_notes=DOCUMENT_GROUP_USAGE_NOTES,
623
+ ),
624
+ make_tool(
625
+ canonical_name="document-groups.get",
626
+ mcp_alias="kaiten_get_document_group",
627
+ description="Get a Kaiten document group by UID.",
628
+ input_schema={
629
+ "type": "object",
630
+ "properties": {"group_uid": {"type": "string", "description": "Document group UID"}},
631
+ "required": ["group_uid"],
632
+ },
633
+ operation=OperationSpec(
634
+ method="GET", path_template="/document-groups/{group_uid}", path_fields=("group_uid",)
635
+ ),
636
+ examples=(
637
+ ExampleSpec(
638
+ command="kaiten --json document-groups get --group-uid grp-1",
639
+ description="Get a document group.",
640
+ ),
641
+ ),
642
+ usage_notes=DOCUMENT_GROUP_USAGE_NOTES,
643
+ ),
644
+ make_tool(
645
+ canonical_name="document-groups.update",
646
+ mcp_alias="kaiten_update_document_group",
647
+ description="Update a Kaiten document group.",
648
+ input_schema={
649
+ "type": "object",
650
+ "properties": {
651
+ "group_uid": {"type": "string", "description": "Document group UID"},
652
+ "title": {"type": "string", "description": "New group title"},
653
+ "parent_entity_uid": {
654
+ "type": ["string", "null"],
655
+ "description": "Parent tree entity uid. Used to move document group in the tree",
656
+ },
657
+ "sort_order": {
658
+ "type": "number",
659
+ "minimum": 0,
660
+ "exclusiveMinimum": 0,
661
+ "description": "Sort order",
662
+ },
663
+ "access": {
664
+ "enum": ["for_everyone", "by_invite"],
665
+ "description": "Document group access type",
666
+ "type": "string",
667
+ },
668
+ "for_everyone_access_role_id": {
669
+ "type": ["string", "null"],
670
+ "format": "uuid",
671
+ "description": "Role id for everyone access",
672
+ },
673
+ "hostname": {
674
+ "type": ["string", "null"],
675
+ "maxLength": 30,
676
+ "description": "Custom hostname for public site. Can contain only letters, numbers and «-», length 2–30 symbols, cannot end with «-»",
677
+ },
678
+ "redirect_url": {"type": ["string", "null"], "description": "Redirect URL"},
679
+ "key": {
680
+ "type": ["string", "null"],
681
+ "maxLength": 256,
682
+ "description": "Unique document group key within company. Cannot be changed once set",
683
+ },
684
+ "icon_type": {
685
+ "type": ["string", "null"],
686
+ "enum": ["material_icon", None],
687
+ "description": "Icon type",
688
+ },
689
+ "icon_value": {
690
+ "type": ["string", "null"],
691
+ "description": "Icon value (icon name for material_icon type)",
692
+ },
693
+ "icon_color": {"type": ["integer", "null"], "description": "Icon color"},
694
+ "hidden_on_public_site": {
695
+ "type": "boolean",
696
+ "description": "Hide document group on public site",
697
+ },
698
+ "news_feed": {
699
+ "type": "boolean",
700
+ "description": "Mark document group as news feed. Requires hostname to be set on this folder or one of its parent folders",
701
+ },
702
+ "index_document_uid": {
703
+ "type": ["string", "null"],
704
+ "format": "uuid",
705
+ "description": "UID of the document to use as the home page for this folder. Requires hostname to be set on this folder. Document must be within the document group tree, not archived and not hidden on public site",
706
+ },
707
+ },
708
+ "required": ["group_uid"],
709
+ },
710
+ operation=OperationSpec(
711
+ method="PATCH",
712
+ path_template="/document-groups/{group_uid}",
713
+ path_fields=("group_uid",),
714
+ body_fields=(
715
+ "title",
716
+ "parent_entity_uid",
717
+ "sort_order",
718
+ "access",
719
+ "for_everyone_access_role_id",
720
+ "hostname",
721
+ "redirect_url",
722
+ "key",
723
+ "icon_type",
724
+ "icon_value",
725
+ "icon_color",
726
+ "hidden_on_public_site",
727
+ "news_feed",
728
+ "index_document_uid",
729
+ ),
730
+ ),
731
+ examples=(
732
+ ExampleSpec(
733
+ command='kaiten --json document-groups update --group-uid grp-1 --title "Docs"',
734
+ description="Update a document group.",
735
+ ),
736
+ ),
737
+ usage_notes=DOCUMENT_GROUP_USAGE_NOTES,
738
+ ),
739
+ make_tool(
740
+ canonical_name="document-groups.delete",
741
+ mcp_alias="kaiten_delete_document_group",
742
+ description="Delete a Kaiten document group.",
743
+ input_schema={
744
+ "type": "object",
745
+ "properties": {"group_uid": {"type": "string", "description": "Document group UID"}},
746
+ "required": ["group_uid"],
747
+ },
748
+ operation=OperationSpec(
749
+ method="DELETE",
750
+ path_template="/document-groups/{group_uid}",
751
+ path_fields=("group_uid",),
752
+ ),
753
+ examples=(
754
+ ExampleSpec(
755
+ command="kaiten --json document-groups delete --group-uid grp-1",
756
+ description="Delete a document group.",
757
+ ),
758
+ ),
759
+ usage_notes=DOCUMENT_GROUP_USAGE_NOTES,
760
+ ),
761
+ )