@firfi/huly-mcp 0.48.0 → 0.49.1

package/README.md

@@ -13,6 +13,12 @@
 > [!IMPORTANT]
 > **Hosted Huly is shutting down.** Huly's upstream README says shutdown is expected July 20. If you use `https://huly.app`, [export and migrate your data](https://github.com/hcengineering/platform/blob/develop/README.md) as soon as possible. See the [backup and restore guide](https://github.com/hcengineering/platform/blob/develop/docs/guides/backup-restore.en.md) and [self-hosting repository](https://github.com/hcengineering/huly-selfhost). Self-hosted deployments are not affected.
 
+## Huly CLI Alternative
+
+Looking for a Huly CLI, terminal-native Huly integration, or a scripting and automation alternative to running an MCP server? [`@firfi/huly-cli`](https://www.npmjs.com/package/@firfi/huly-cli) is a feature-complete command-line interface for Huly with full Huly operation parity with Huly MCP. It exposes the same Huly operations as native, schema-aware commands with human-readable or JSON output, file-backed inputs, uploads, and downloads.
+
+Huly MCP and Huly CLI are maintained together in this monorepo and derive from the same shared operation registry, keeping operation inputs, outputs, warnings, and typed failures aligned. See the [Huly CLI documentation](packages/huly-cli/README.md) for installation, examples, and the complete generated command reference.
+
 ## Installation
 
 The standard configuration works with most MCP clients:
@@ -290,7 +296,7 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 | `get_tool_schema` | Returns the exact input and output schema for one proxy-visible Huly tool. Use this before invoke_tool when you are not certain about required argument names or result shape. |
 | `invoke_tool` | Invokes one proxy-visible Huly tool by exact name with its arguments. This tool can call read or write Huly operations; check get_tool_schema and the target tool annotations when safety matters. |
 
-**`TOOLSETS` categories:** `projects`, `issues`, `comments`, `milestones`, `documents`, `storage`, `attachments`, `contacts`, `channels`, `calendar`, `time tracking`, `search`, `associations`, `activity`, `notifications`, `workspace`, `approvals`, `boards`, `cards`, `collaborators`, `custom-fields`, `drive`, `inventory`, `labels`, `leads`, `templates`, `model-administration`, `planner`, `preferences`, `processes`, `recruiting`, `sdk-discovery`, `security-administration`, `sequence-administration`, `spaces`, `tag-categories`, `tags`, `task-management`, `test-management`, `user-statuses`, `views`, `virtual-office`, `workflow-statuses`
+**`TOOLSETS` categories:** `projects`, `issues`, `comments`, `milestones`, `documents`, `storage`, `attachments`, `contacts`, `channels`, `calendar`, `time tracking`, `search`, `associations`, `activity`, `notifications`, `workspace`, `approvals`, `boards`, `cards`, `collaborators`, `custom-fields`, `drive`, `inventory`, `labels`, `leads`, `mail`, `templates`, `model-administration`, `planner`, `preferences`, `processes`, `recruiting`, `sdk-discovery`, `security-administration`, `sequence-administration`, `spaces`, `support`, `tag-categories`, `tags`, `task-management`, `test-management`, `user-statuses`, `views`, `virtual-office`, `workbench`, `workflow-statuses`
 
 ### Projects
 
@@ -378,6 +384,10 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 | `edit_document` | Edit an existing Huly document. You may rename with title and/or edit the body. Body editing has two mutually exclusive modes: (1) content replaces the entire markdown body, (2) old_text + new_text performs exact targeted search-and-replace. Use markdown links to current-workspace Huly browse URLs for native references; Huly browse links returned in get_document content round-trip as native references. The URL identifies the object; link text is display text; plain issue keys stay text. External URLs stay normal markdown links. For targeted replace, multiple matches error unless replace_all is true; empty new_text deletes matched text. Content supports native Mermaid diagrams. Returns a 'url' field pointing to the document in the Huly web app. |
 | `list_inline_comments` | List inline comment threads from a Huly document. Extracts comments embedded in document content as ProseMirror marks. Each comment includes the highlighted text and thread ID. Set includeReplies=true to also fetch thread reply messages with sender names. |
 | `delete_document` | Permanently delete a Huly document. This action cannot be undone. |
+| `list_document_label_definitions` | List label definitions available for ordinary Huly documents by optional title substring. Does not expose raw target-class or category mechanics. |
+| `list_document_labels` | List labels attached to one ordinary Huly document. Resolves the teamspace by name or ID and the document by title or ID; no raw class, space, or collection values are needed. |
+| `add_document_label` | Idempotently attach a label to an ordinary Huly document resolved by teamspace and title or ID. label accepts a definition ID or exact title; a missing title creates the document label definition first, while duplicate exact titles return candidate IDs. |
+| `remove_document_label` | Detach a label from one ordinary Huly document without deleting the reusable label definition. Returns detached=false when the label exists but is not attached; duplicate exact titles return candidate IDs. |
 
 ### Storage
 
@@ -467,7 +477,7 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 | `update_channel` | Update fields on an existing Huly channel. Only provided fields are modified. |
 | `delete_channel` | Permanently delete a Huly channel. This action cannot be undone. For reversible channel lifecycle changes, use archive_channel and unarchive_channel instead. |
 | `list_channel_messages` | List messages in a Huly channel. Returns messages sorted by date (newest first). |
-| `list_external_channel_messages` | Assess whether external messages can be listed safely for a provider channel. Gmail returns supported=false because Huly does not expose the live deployment-wide v1/v2 writer version needed to distinguish current legacy records from stale data; Telegram returns supported=false because no compatible published message package is installed. Returns an unsupportedReason and an empty messages array. The limit defaults to 50 and is capped at 200. This tool never sends, replies, deletes, mutates, or returns fake messages. |
+| `list_external_channel_messages` | Read persisted Telegram contact-channel messages or assess why an external provider cannot be read safely. For provider=telegram, resolve channel by exact stored value or stable contact-channel ID and return newest contentMarkdown, direction, stored Huly sendOn timestamp, and attachment count; returns supported=false when the workspace model or channel is unavailable. Inbound attachment creation is asynchronous, so attachmentCount can temporarily lag the message; attachment bytes are not returned. This proves only Huly-stored records, not provider freshness, an active Telegram connection, or provider delivery/read status. Gmail returns supported=false because Huly does not expose the live deployment-wide v1/v2 writer version needed to distinguish current legacy records from stale data. The limit defaults to 50 and is capped at 200. This tool never sends, replies, deletes, or mutates. |
 | `send_channel_message` | Send a message to a Huly channel. Message body supports markdown formatting. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. |
 | `update_channel_message` | Update a channel message. Only the body can be modified; body supports markdown formatting. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. |
 | `delete_channel_message` | Permanently delete a channel message. This action cannot be undone. |
@@ -751,6 +761,12 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 | `get_lead` | Retrieve full details for a Huly lead including markdown description, customer name, funnel ID and funnel name, and status. Lead identifiers follow the upstream Huly format like 'LEAD-1'. |
 | `create_lead` | Create one native Huly lead in an active funnel for an existing person or organization. Resolve the funnel by ID or exact name; identify the customer explicitly as person or organization; optionally choose an employee assignee, Lead-compatible task type, exact workflow status, and Markdown description. Automatically applies the Customer mixin when needed, preserves native Huly references, and returns both leadId and LEAD-<number>. This tool never creates a person or organization inline. |
 
+### Mail
+
+| Tool | Description |
+|------|-------------|
+| `list_mail_threads` | Discover read-only Huly Mail thread metadata in one call: outer channel titles, human-resolved spaces, timestamps, and up to 10 newest child subject summaries per channel. This does not return message bodies or attachments and never sends, replies, mutates, or reports mailbox/delivery capability. A channelTitle may resemble a replication-recipient email but does not prove a correspondent or configured mailbox. Omit filters to list recent channels; filter by exact space name/ID or case-insensitive channel-title substring. Empty threads is a supported result. |
+
 ### Templates
 
 | Tool | Description |
@@ -776,6 +792,10 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 
 | Tool | Description |
 |------|-------------|
+| `list_todo_label_definitions` | List label definitions available for Huly Planner ToDos by optional title substring. Does not expose raw target-class or category mechanics. |
+| `list_todo_labels` | List labels attached to one Planner ToDo. Resolves the ToDo by raw ID or the same human-oriented issue, title, owner, and completion locators used by get_todo. |
+| `add_todo_label` | Idempotently attach a label to a Planner ToDo resolved by raw ID or human locator. label accepts a definition ID or exact title; a missing title creates the ToDo label definition first, while duplicate exact titles return candidate IDs. |
+| `remove_todo_label` | Detach a label from one Planner ToDo without deleting the reusable label definition. Returns detached=false when the label exists but is not attached; duplicate exact titles return candidate IDs. |
 | `list_todos` | List Huly Planner ToDos. Empty input returns up to 50 ToDos in planner order with all completion states. Use owner, issue, title, due date, priority, visibility, or completion filters to narrow results. |
 | `get_todo` | Get one Planner ToDo by raw todoId or by human locator such as issue + title + owner. Returns stable ToDo fields, owner, attachment context, description, labels count, and work slot count. |
 | `create_todo` | Create a Planner ToDo. Omit attachedTo for a personal ToDo, or pass attachedTo.type=issue with project and identifier for an issue action item. Omit owner to use the authenticated user. Description supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. |
@@ -907,6 +927,12 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 | `add_space_role_members` | Idempotently add members to one role on a typed Huly space while preserving all other role assignments. Role accepts a raw role _id or exact role name from the space's SpaceType. Members accept account UUID, exact email, or exact person display name. |
 | `remove_space_role_members` | Idempotently remove members from one role on a typed Huly space while preserving all other role assignments. Role accepts a raw role _id or exact role name from the space's SpaceType. Members accept account UUID, exact email, or exact person display name. |
 
+### Support
+
+| Tool | Description |
+|------|-------------|
+| `get_support_status` | Discover Huly support-widget model/setup and the authenticated account's private stored status rows in one read-only call. Returns supported=false when either required workspace classifier is unavailable; otherwise setup is missing when no SupportSystem exists, configured for exactly one, or ambiguous with every candidate instead of choosing nondeterministically. providerConversationId is opaque and storedHasUnreadMessages is only a persisted fallback with no provider-freshness guarantee. Malformed private rows are skipped with an agent warning that never includes provider IDs. Huly exposes no support message bodies, participants, attachments, transcripts, live unread count, delivery/read status, or safe send/reply/widget-control API; this tool never loads the executable widget factory or mutates data. |
+
 ### Tag-Categories
 
 | Tool | Description |
@@ -920,13 +946,13 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 
 | Tool | Description |
 |------|-------------|
-| `list_tags` | List generic Huly tag definitions for one SDK target class. Use this for SDK-level tags such as recruiting skills or document labels. For Tracker issue labels, prefer list_labels. |
-| `create_tag` | Create a generic Huly tag definition for one targetClass. Idempotent by targetClass + title. This exposes the SDK tags model; for Tracker issue labels, prefer create_label. |
+| `list_tags` | List generic Huly tag definitions for one SDK target class. Prefer module tools for issue labels, document labels, Planner ToDo labels, board labels, and recruiting skills; use this as the raw SDK fallback for other tag-backed domains or category administration. |
+| `create_tag` | Create a generic Huly tag definition for one targetClass. Idempotent by targetClass + title. Prefer module label or skill tools when attaching to a supported object; use this raw fallback for definition administration and unsupported tag-backed domains. |
 | `update_tag` | Update a generic Huly tag definition. The tag argument accepts a tag ID or exact title, resolved within targetClass. |
 | `delete_tag` | Delete a generic Huly tag definition by ID or exact title, resolved within targetClass. This deletes the tag definition, not only one object's tag reference. |
-| `list_attached_tags` | List generic Huly TagReference rows attached to one raw object collection. Requires objectId, objectClass, space, and collection because this is an SDK-level tool. |
-| `attach_tag` | Attach a generic Huly tag to one raw object collection. Requires targetClass for the tag definition and objectId/objectClass/space/collection for the TagReference. Idempotent for the same object, collection, and tag. |
-| `detach_tag` | Detach a generic Huly tag from one raw object collection. Requires targetClass and objectId/objectClass/space/collection. Returns detached=false when the tag is not attached. |
+| `list_attached_tags` | List generic Huly TagReference rows attached to one raw object collection. Prefer module tools for issues, documents, Planner ToDos, board cards, and recruiting candidates; this SDK fallback requires objectId, objectClass, space, and collection. |
+| `attach_tag` | Attach a generic Huly tag to one raw object collection. Prefer module tools for supported issue, document, Planner, board, and recruiting objects; this SDK fallback requires targetClass plus objectId/objectClass/space/collection and is idempotent for the same object, collection, and tag. |
+| `detach_tag` | Detach a generic Huly tag from one raw object collection. Prefer module tools for supported issue, document, Planner, board, and recruiting objects; this SDK fallback requires targetClass and objectId/objectClass/space/collection. |
 
 ### Task-Management
 
@@ -1003,6 +1029,12 @@ When resolved tool exposure is `proxy`, clients see the built-in tools plus thes
 | `list_device_preferences` | List readable virtual-office media device preferences. |
 | `list_office_defaults` | List room-level language, default recording, and default transcription settings. |
 
+### Workbench
+
+| Tool | Description |
+|------|-------------|
+| `list_workbench_applications` | List read-only Huly Workbench application model declarations by exact URL alias or case-insensitive alias substring. Returns untranslated labelId values, static model flags, the authenticated account's caller-scoped hiddenByPreference state, and summarized declarative space/special/group navigation without executing components, resource callbacks, or query builders. Legacy space-navigation entries without a stable id are omitted with an agent-visible warning. Application presence is not proof that a plugin, integration provider, worker, API, role, permission, or effective browser visibility is enabled. Personal tabs, active browser state, widgets, widget tabs/preferences, and all Workbench mutations are intentionally unsupported because they are private or browser-local and lack a reliable human-readable agent workflow. |
+
 ### Workflow-Statuses
 
 | Tool | Description |