# Huly SDK / Dev-Lib Feature Gap Matrix

Scope: features that are represented in the local Huly SDK/dev reference tree or installed `@hcengineering/*` packages, but are not exposed by this MCP server as first-class LLM-facing tools.

Audit guard: `plans/sdk-parity-ledger.json` classifies every installed `@hcengineering/*` plugin class or model-like export and every `.reference/platform/models/*` area discovered by `scripts/audit-sdk-parity.mjs` as `covered`, `gap`, `ignored`, or `not-mcp-facing`. `pnpm verify-sdk-parity` fails when a newly installed SDK model export or reference model area is not classified here.

Local evidence sources:

- Installed SDK packages: `node_modules/@hcengineering/*`
- Huly platform reference: `.reference/platform/plugins/*`, `.reference/platform/models/*`, `.reference/platform/server-plugins/*`
- Current MCP surface: `src/mcp/tools/*`, registered from `src/mcp/tools/index.ts`

Current high-level MCP categories:

`projects`, `issues`, `comments`, `milestones`, `documents`, `storage`, `attachments`, `contacts`, `channels`, `calendar`, `time tracking`, `search`, `associations`, `activity`, `notifications`, `workspace`, `spaces`, `cards`, `custom-fields`, `labels`, `leads`, `processes`, `sdk-discovery`, `tags`, `tag-categories`, `task-management`, `test-management`, `user-statuses`, `virtual-office`.

## Missing Or Partially Missing SDK Surfaces

| SDK / dev-lib area | Evidence in Huly libs | Current MCP coverage | Missing MCP feature surface |
|---|---|---|---|
| Controlled Documents / TraceX documents | `.reference/platform/models/controlled-documents/src/types.ts`: `DocumentSpace`, `DocumentSpaceType`, `OrgSpace`, `ExternalSpace`, `Project`, `Document`, `HierarchyDocument`, `DocumentTemplate`, `DocumentTraining`, `DocumentCategory`, `ControlledDocument`, `ChangeControl`, `DocumentSnapshot`, `ControlledDocumentSnapshot`, `DocumentComment`, `DocumentReviewRequest`, `DocumentApprovalRequest` | Basic non-controlled teamspaces/documents only via `documents` tools | Controlled document spaces/projects, controlled document CRUD, quality/technical docs, document templates, categories, review/approval requests, co-authors/reviewers/approvers, e-signature workflow, release/effective-date metadata, change control, snapshots/history, document training linkage, controlled-document comments/resolve |
| Products / product versions | `.reference/platform/models/products/src/index.ts`: `Product`, `ProductVersion`, `ProductTypeData`, `TypeProductVersionState` | No product tools; generic documents may not model product spaces | Product spaces, product members, product descriptions/attachments, product version CRUD, version state transitions, version change-control link |
| Trainings | `.reference/platform/models/training/src/types.ts`: `Training`, `TrainingRequest`, `TrainingAttempt`, state/attempt-state types | No training tools | Training CRUD, revisions, description/attachments, passing score, release, questions collection, assign requests to trainees/roles, due date/max attempts, cancel requests, attempts, submit/score attempts, results/reporting |
| Questions / assessments | `.reference/platform/models/questions/src/doc-types/*`: `Question`, `Assessment`, `Answer`, single-choice, multiple-choice, ordering types and answer data | No question-bank or assessment tools | Question CRUD, assessment CRUD, answer options, correct-answer/assessment data, ordering questions, answer submission/readback, reusable question model for trainings/surveys |
| Drive | `.reference/platform/models/drive/src/index.ts`: `Drive`, `Resource`, `Folder`, `File`, `FileVersion`, `TypeFileVersion` | Partial first-class `drive` tools: list/get drives, path traversal/list/get items, idempotent folder creation, upload file with parent creation, list versions, restore existing version. Low-level `upload_file` remains available for raw blob uploads. | Drive create/update/delete, item move/rename/delete, adding new versions to existing files, Drive comments/activity, Drive permissions/members |
| Human Resources | `.reference/platform/models/hr/src/index.ts`: `Department`, `Staff`, `RequestType`, `Request`, `PublicHoliday`, `TzDate` | No HR tools | Departments and nested departments, department members/managers/subscribers/team lead, employee-to-department staff mixin, HR request types, PTO/sick/overtime/remote schedule requests, public holidays, HR schedule/table reports |
| Recruiting | `.reference/platform/models/recruit/src/types.ts`: `Vacancy`, `Candidate`, `VacancyList`, `Applicant`, `ApplicantMatch`, `Review`, `Opinion`; statuses in `.reference/platform/models/recruit/src/spaceType.ts` | No recruiting tools | Vacancies, talents/candidates, applications, application statuses, recruiter assignment, candidate skills, reviews, review verdicts/opinions, applicant matches, vacancy-company lists, recruiting-specific comments/attachments/activity/relations/custom fields |
| Surveys / polls | `.reference/platform/models/survey/src/types.ts`: `Survey`, `Poll` | No survey tools | Survey CRUD, poll creation/attachment, survey question data, poll completion/status, survey results |
| Generic approval requests | `.reference/platform/models/request/src/index.ts`: `Request`, `RequestDecisionComment`, request presenters | No generic request tools; controlled docs consume it internally | Create/list/approve/reject/cancel approval requests, decision comments, required approval counts, request status and requested/approved/rejected people |
| Boards | `.reference/platform/models/board/src/index.ts`: `Board`, board `Card`, card cover, board preferences, menu pages | No board-specific tools; unrelated `cards` category covers Huly Card module, not board plugin | Board CRUD, board cards, board status workflow, board card members/assignee/location/cover/archive, board labels/menu/archive views |
| Inventory | `.reference/platform/models/inventory/src/index.ts`: inventory `Category`, `Product`, `Variant` | No inventory tools | Inventory categories, products, variants/SKUs, product photos, attachments, activity/comments, category-product hierarchy |
| Leads write surface | `.reference/platform/models/lead/src/types.ts`: `Funnel`, `Lead`, `Customer`, `DefaultFunnelTypeData`, `LeadTypeData` | Read-only: list funnels, list leads, get lead; contacts has `make_organization_customer` | Create/update/delete funnels, create/update/delete leads, change lead status, assign lead, start date, customer description, person customer support, lead comments/attachments/labels/relations |
| Contact channels and identities | `.reference/platform/models/contact/src/index.ts`: `Channel`, `SocialIdentity`, `ChannelProvider`, `SocialIdentityProvider`, `Status`, `PersonSpace`, `WorkspaceMemberStatus`, `Employee` mixin | Persons/orgs/employees read, basic person/org CRUD, org channels/members | Add/update/remove person channels, social identities, channel provider discovery, contact statuses, contact notes/comments as first-class target, person attachments, person merge, employee invite/create, kick/reinvite employee, inactive employee management |
| Calendar schedules and integrations | Installed `@hcengineering/calendar`; `.reference/platform/models/calendar/src/index.ts`: `Calendar`, `ExternalCalendar`, `Event`, recurring events/instances, `Schedule`, `PrimaryCalendar` | Event CRUD, recurring event create/list, instances, stable event fields (`participants`, `externalParticipants`, `reminders`, `access`, `timeZone`, `blockTime`), writable calendars, calendar target moves by ID/name, schedule CRUD | Calendar CRUD/config, external calendar sync metadata, primary calendar management, invite/RSVP response state if a stable model appears |
| Planner / ToDos | Installed `@hcengineering/time`; `.reference/platform/models/time/src/index.ts`: `ToDo`, `ProjectToDo`, `WorkSlot`, `TodoAutomationHelper`, todo priority | Work slots plus issue time reporting; no ToDo CRUD | Personal action item CRUD, project-linked ToDos, schedule/unschedule ToDos, complete/reopen ToDos, ToDo priority, visibility/privacy, automation helper visibility, document action-item assignment |
| Team planner / schedule reporting | `.reference/platform/models/time`, `.reference/platform/models/calendar`, HR docs/models | Work slots can be listed/created; calendar events can be listed | Team agenda/calendar reports across members/projects, workload/capacity summaries, visibility-aware free/busy views |
| Virtual office / meetings | Installed `@hcengineering/love@0.7.0`; `.reference/platform/models/love/src/index.ts`: `Room`, `Office`, `Floor`, `ParticipantInfo`, `RoomInfo`, `Meeting` mixin, `MeetingMinutes`, `MeetingSchedule`; settings in `setting.class.OfficeSettings` | Read-only office discovery: floors, rooms, offices, active room info, active participant info, meeting minutes, device preferences, room recording/transcription/language defaults. Meeting event/schedule mixin data is surfaced as room-aware calendar/schedule summaries rather than raw mixin internals. | Office floors/rooms CRUD, meeting schedule room writes, live meeting join/leave/start/stop, transcripts/recordings as first-class artifacts, deeper `setting.class.OfficeSettings` write/read coverage where backend support is proven |
| Chat channel membership/options | Installed `@hcengineering/chunter`; `.reference/platform/models/chunter/src/types.ts`: `Channel`, `DirectMessage`, `ChatMessage`, `ThreadMessage` | Channel CRUD, channel message writes, direct-message listing, thread replies | Direct-message send/update/delete, channel member add/remove/list as mutations, join/leave/request access, archive/unarchive vs delete, star/favorite channels, group direct messages, close/reopen conversations, pin messages, message attachments, translate message |
| Communication applets and chat polls | `.reference/platform/models/communication/src/types.ts`: `MessageAction`, `Applet`, `PollAnswer`, `GuestCommunicationSettings` | No communication applet/poll tools | Chat applets, in-message poll creation/answers, custom activity presenters, guest communication settings |
| Inbox / notification gaps | Installed `@hcengineering/notification`; `.reference/platform/models/notification/src/index.ts`: `InboxNotification`, `DocNotifyContext`, provider/type settings, hidden context, collaborator mixin | Notifications list/get/read/unread/archive/unarchive/delete, contexts list/get/pin/hide/unhide/archive/unarchive, provider/type discovery, provider/type setting writes, current-account object subscribe/unsubscribe, and generic object collaborator list/add/remove | Browser/push subscription internals, provider default documents, and UI presenter/group metadata remain non-MCP-facing; rating-backed stars remain blocked by the unpublished rating package |
| Activity gaps | Installed `@hcengineering/activity`; `.reference/platform/models/activity/src/index.ts`: pinned messages, replies, references, filters, saved messages, reactions, mentions | List/get/pin activity, generic activity replies, activity filters, activity references, reactions, save/unsave, mentions, and update/reference/info message summaries | Presenter/viewlet/extension/control metadata remains non-MCP-facing |
| Attachments gaps | Installed `@hcengineering/attachment`; `.reference/platform/models/attachment/src/index.ts`: `Attachment`, `Embedding`, `Photo`, `SavedAttachments`, `Drawing` | Generic attachment CRUD/download/pin with attachment/embedding/photo class selection, saved attachments, drawing CRUD, metadata return, and issue/document convenience add | Attachment previews/preview UI metadata and object-specific friendly wrappers beyond issue/document |
| Tags/labels beyond tracker issues | Installed `@hcengineering/tags`; `.reference/platform/models/tags/src/index.ts`: `TagElement`, `TagReference`, `TagCategory` with arbitrary `targetClass` | SDK-level generic tags are covered: target-class TagElement CRUD, raw TagReference list/attach/detach, tracker `labels` wrappers, and arbitrary-target tag categories | Module-specific friendly wrappers remain for recruiting skills, board labels, controlled-doc labels, and contact tags so callers do not need raw object IDs/classes/collection names |
| Core classes, attributes, enums | Installed `@hcengineering/core`; `.reference/platform/models/core/src/core.ts`: `Class`, `Mixin`, `Enum`, `Attribute`, type classes, sequence/custom sequence | Custom-field read/set; read-only `list_huly_classes`, `get_huly_class`, `list_huly_attributes`, `list_huly_enums` expose class/interface/mixin IDs, attributes, inherited fields, enum values, and purpose-built MCP tool hints | Attribute/property create/update/delete/hide, enum CRUD/options, sequence management |
| Core spaces, permissions, roles | Installed `@hcengineering/core`; `.reference/platform/models/core/src/security.ts`: `Space`, `TypedSpace`, `SpaceType`, `Role`, `Permission`, permission groups | Generic `spaces` tools list/get spaces, list/get space types, list permissions, update safe existing-space metadata, add/remove members, and replace owners; workspace member role update; project/teamspace create/update partial | Role assignment mutations, role/permission definition writes, generic space creation, global spaces admins, module-specific wrappers above the generic foundation |
| Settings / integrations registry | `.reference/platform/models/setting/src/index.ts`: `Integration`, `IntegrationType`, settings categories, invite settings, role capability settings, office settings, workspace settings | Guest settings and access links, workspace info/profile | List integrations/integration types, connect/disconnect/configure integration records where backend supports it, invite settings, role capability settings, office settings, workspace setting icon/metadata |
| GitHub integration | Huly docs plus integration architecture in settings; PR task type appears through tracker/task type model when GitHub is enabled | No GitHub integration tools; issue tools may operate on synced issues after setup | Connect/list mapped repositories, map/unmap repo to project, list pull requests, issue GitHub sync controls, GitHub link metadata |
| Google Calendar integration | Settings integration architecture; external calendar model in calendar | No integration management | Connect/configure/disconnect Google Calendar, list synced calendars, enable/disable synced calendars, sync status/errors |
| Bitrix integration | `.reference/platform/models/bitrix/src/index.ts`: `BitrixSyncDoc`, `EntityMapping`, `FieldMapping` | No Bitrix tools | Integration connect/configure, entity mappings, field mappings, import/sync status, mapped docs |
| Gmail / email channel | `.reference/platform/models/gmail/src/index.ts`: `Message`, `NewMessage`, `SharedMessages` | No email tools; contacts can store email values | Email channel messages, compose/send queued email, reply-to, CC, attachments, shared email messages on contacts/channels, send status/error |
| Telegram channel | `.reference/platform/models/telegram/src/index.ts`: `Message`, `NewMessage`, `SharedMessages` | No Telegram tools; contacts can store Telegram channel values | Telegram messages, compose/send queued Telegram message, shared messages, attachments, send status |
| Huly Mail / Mail plugin | `.reference/platform/plugins/huly-mail`, `.reference/platform/plugins/mail`, `.reference/platform/models/huly-mail`, `.reference/platform/models/mail` | No mail-specific tools | Mail integration surface, mail app/channel behavior. Needs deeper model review before tool design because much of this appears plugin/resource driven |
| Message templates | `.reference/platform/models/templates/src/index.ts`: `MessageTemplate`, `TemplateCategory`, `TemplateFieldCategory`, `TemplateField` | No template tools except issue templates and controlled-doc gap above | Global message templates, template categories, template fields, render/copy template output |
| AI assistant integration | `.reference/platform/models/ai-assistant/src/index.ts` registers `IntegrationType` | No AI-assistant integration tools | Connect/configure/disconnect AI assistant integration, inspect connection state. Actual assistant runtime needs deeper server-plugin review |
| AI bot | `.reference/platform/plugins/ai-bot`, `.reference/platform/server-plugins/ai-bot`; model has no first-class docs | No AI bot tools | Bot configuration/actions if server plugin exposes callable behavior. Needs deeper server-plugin review |
| Rating / reputation | `.reference/platform/models/rating/src/index.ts`: `DocReaction`, `PersonRating`; `npm view @hcengineering/rating version` returns 404 as of 2026-06-10 | Emoji reactions only through activity, not rating model | Star/rating reactions on docs, person rating/statistics, rating widget data blocked by #90 until a typed published SDK package is available |
| Support widget | `.reference/platform/models/support/src/index.ts`: `SupportConversation`, `SupportSystem` | No support tools | Support conversation state, unread support messages, support system discovery |
| Billing / tiers | `.reference/platform/models/billing/src/index.ts`: `Tier`; billing plugin/resources | No billing tools | Billing tier/status discovery if relevant to workspace administration |
| Analytics collector / onboarding channel | `.reference/platform/models/analytics-collector/src/index.ts`: `OnboardingChannel` | No analytics/onboarding tools | Onboarding channels and analytics collector configuration; likely low priority for MCP |
| View / saved filtered views | `.reference/platform/models/view/src/index.ts`: `FilteredView`, `Viewlet`, actions, view preferences | No saved-view tools; list tools accept ad hoc filters | Saved filtered views, user view preferences, viewlet descriptors, reusable filters/sorts/groups |
| Workbench tabs/widgets/apps | `.reference/platform/models/workbench/src/index.ts`: `Application`, `ApplicationNavModel`, `HiddenApplication`, `Widget`, `WidgetPreference`, `WorkbenchTab` | No workbench UI state tools | List/hide apps, tabs, widgets, widget prefs. Mostly UI state, lower MCP priority |
| Preference model | `.reference/platform/models/preference`; many modules store preferences | No generic preference tools | User preferences discovery/update for modules with preference-backed settings |
| Document preferences and history | Installed `@hcengineering/document`; `node_modules/@hcengineering/document/types/types.d.ts` still exposes stale `SavedDocument extends Preference` plus `DocumentSnapshot`. Current platform source removed the `SavedDocument` model in hcengineering/platform#10124 and replaced document stars with rating-backed `DocReaction` / `ReactionKind.Star` | Document tools cover teamspaces, document CRUD, content edit, inline comments, relations, deletion, and read-only snapshot/history list/get. | Snapshot restore remains deferred until restore semantics are proven. Do not implement `SavedDocument` as SDK parity unless the platform model is restored; current document stars belong to the Rating / reputation row |

## Installed SDK Packages With Partial MCP Coverage

| Installed package | Current status | Notable missing first-class tools |
|---|---|---|
| `@hcengineering/activity` | Partial | Pin/unpin activity messages, generic replies, activity filters/references |
| `@hcengineering/attachment` | Partial | Saved attachments, photos, drawings, embeddings, more friendly object targets |
| `@hcengineering/calendar` | Partial | Calendar/external-calendar config, primary-calendar preferences, RSVP/invite response state if added upstream |
| `@hcengineering/love` | Partial read-only | Room/floor/office CRUD, meeting schedule room writes, live meeting session mutations, transcripts/recordings as first-class artifacts, deeper office settings |
| `@hcengineering/card` | Mostly basic CRUD | Card roles/permissions, favorites, export extensions, advanced master tag schema management |
| `@hcengineering/chunter` | Partial | Group DMs, channel membership, join/leave, pin/star/archive semantics, message attachments/translation |
| `@hcengineering/contact` | Partial | Person channels/social identities, employee invite/kick/reinvite, merge contacts, contact statuses |
| `@hcengineering/core` | Partial | Attribute/enum writes, role assignment mutations, role/permission definition writes, generic space creation, collaborators, sequences |
| `@hcengineering/document` | Partial | Snapshot restore, backlinks, notes, structured action items/tables, PDF/export, advanced document relationships |
| `@hcengineering/notification` | Partial | Mute contexts, notification type settings, collaborators |
| `@hcengineering/tags` | SDK-level covered; module wrappers partial | Module-specific wrappers for tag-backed concepts such as recruiting skills, board labels, controlled-doc labels, and contact tags |
| `@hcengineering/task` | Partial | Generic task/project abstractions beyond tracker, reusable task workflows |
| `@hcengineering/time` | Partial | ToDo/action item lifecycle, personal planner, visibility, schedule reports |
| `@hcengineering/tracker` | Strong but partial | GitHub pull-request task type/sync details, PDF export, saved views beyond ProjectTargetPreference, tracker-local Document support type, and broader workflow automation behavior |

## Highest-Value Additions For LLM Agents

1. **Common clear-field contract for update tools (implemented)**: Huly `DocumentUpdate<T>` supports `$unset`, but existing domain tools used a mix of field-specific clearing semantics: `null` for some optional relationships/dates/text, empty string for some descriptions/topics, and markup-specific empty references for rich descriptions. Update tools now use a shared LLM-facing contract where `null` means "clear/unset this field" for clearable fields, while backend operations map that intent to field-specific Huly-safe representations such as `""`, `null` markup refs, `$unset`, or `0`. Custom-field clearing remains separate because its safe backend representation depends on dynamic field metadata and storage owner.

   Required fields such as `update_milestone.targetDate` and required category refs such as `update_tag.category` are intentionally not clearable without a separate SDK-backed design.
2. **Generic space/member/role foundation follow-ups**: role assignment mutations, role/permission definition writes, generic space creation, and module-specific wrappers are still separate work. Generic space discovery, space type/permission reads, safe metadata updates, member mutations, and owner replacement are implemented under `spaces`.
3. **SDK discovery phase 2**: add plugin configuration and sequence metadata discovery on top of the class/attribute/enum/space-type/permission tools.
4. **Drive**: high-value and strongly modeled (`Drive`, `Folder`, `File`, `FileVersion`) but absent.

## Calendar, Schedule, And Virtual Office Omissions

- RSVP/calendar invite response state: omitted because installed `@hcengineering/calendar@0.7.0` exposes `Event`, `ReccuringEvent`, `ReccuringInstance`, and `Schedule` but no stable RSVP/response-status model. Unlock condition: a published SDK declaration with attendee response state or invite response records.
- Live meeting join/leave/start/stop writes: omitted from the first slice because they depend on transient room session and LiveKit behavior, not just durable model documents. Unlock condition: integration tests that can exercise local Huly live-session behavior deterministically.
- Meeting schedule room writes and raw love mixins: omitted as direct MCP inputs because callers should not need Huly mixin mechanics. Unlock condition: a room-aware calendar schedule write contract with integration coverage proving the backend accepts the mixin mutation.
- Transcripts and recordings as first-class artifacts: omitted because `MeetingMinutes` only exposes collection counts for transcription/messages/attachments in the current model declarations. Unlock condition: a stable read path for transcript/recording records and storage URLs.
- Latest SDK package upgrade: still blocked. `@hcengineering/love@0.7.0` is pinned because it publishes declarations that match the current SDK line; newer `0.7.423` tarballs were not adopted in this slice due missing/unsuitable declaration publication evidence captured in `plans/hcengineering-types-publication-evidence.md`.
5. **Planner/ToDos**: strongly modeled and user-visible; current `WorkSlot` tools are not enough.
6. **Recruiting**: strongly modeled, currently absent, and requires first-class resolvers for vacancies/talents/applications.
7. **Controlled documents + trainings**: broad TraceX surface with many modeled objects; likely larger implementation but clearly represented in dev libs.
8. **Tag-backed module wrappers**: generic tags now exist, but recruiting skills and similar module concepts still need LLM-first object resolvers.

## Notes

- Some SDK/dev surfaces are UI/internal-heavy (`workbench`, `view`, `preference`, parts of `presentation`). They are included because models exist, but they are lower priority unless the MCP server aims to manage Huly UI state.
- Some integrations (`GitHub`, `Google Calendar`) are clearly product features, but their management APIs may live in account/server/plugin layers rather than simple document CRUD. They need implementation spikes before promising write tools.
- Existing generic tools (`list_activity`, `add_attachment`, `set_custom_field`, `create_relation`) can sometimes operate on raw Huly object IDs/classes. That is not counted as full coverage because it is not LLM-first: the caller must already know class IDs, collection names, and object resolution rules.
- Stale installed SDK declarations are not parity targets by themselves. `@hcengineering/document#SavedDocument` is deliberately ignored because current platform source removed its model registration and UI usage in hcengineering/platform#10124; current document stars are `@hcengineering/rating#DocReaction`.
