@assetlab/mcp-server 1.26.0 → 1.28.0

package/dist/tools-write.js

@@ -20,6 +20,27 @@ function buildBody(params) {
     return body;
 }
 const PM_RESOURCE_TYPES = ['TOOL', 'PART', 'MATERIAL', 'EQUIPMENT'];
+// Shared by the four PM tools: linking a form here makes every work order the schedule
+// generates carry a copy of that form for the technician to fill in.
+const FORM_TEMPLATE_LINK_SCHEMA = z
+    .string()
+    .uuid()
+    .optional()
+    .describe('Form template ID to attach to every work order this generates — resolve via list_form_templates. Use a PUBLISHED template: generation resolves the current published version of the form, so a draft attaches nothing until it is published.');
+// Work orders and PM schedules store each association twice — a singular id and a plural array.
+// The API mirrors whichever side is sent, but callers still need the arrays to associate several
+// records at once (and systems, which have no singular field at all).
+const ASSOCIATION_ARRAY_SCHEMA = (description) => z.array(z.string().uuid()).optional().describe(description);
+const FORM_TEMPLATE_STATUSES = ['draft', 'published', 'archived'];
+const FORM_ITEM_TYPES = [
+    'section',
+    'checkbox',
+    'single_select',
+    'multi_select',
+    'number',
+    'text',
+    'photo',
+];
 function randomTaskId() {
     const g = globalThis;
     return g.crypto?.randomUUID?.() ?? `task_${Math.random().toString(36).slice(2, 12)}`;
@@ -98,8 +119,15 @@ export function registerWriteTools(server, client) {
             .string()
             .uuid()
             .optional()
-            .describe('Location ID — resolve last via list_locations filtered by building_id'),
-        asset_id: z.string().uuid().optional().describe('Asset ID'),
+            .describe('Location this work order is for — resolve last via list_locations filtered by building_id. The server mirrors it into location_ids, so send this OR location_ids, not a conflicting pair.'),
+        asset_id: z
+            .string()
+            .uuid()
+            .optional()
+            .describe('Asset this work order is for — resolve via list_assets. The server mirrors it into asset_ids.'),
+        location_ids: ASSOCIATION_ARRAY_SCHEMA('Locations this work order covers — use instead of location_id when there is more than one. Sending location_id alone replaces this with that single id.'),
+        asset_ids: ASSOCIATION_ARRAY_SCHEMA('Assets this work order covers — use instead of asset_id when there is more than one.'),
+        system_ids: ASSOCIATION_ARRAY_SCHEMA('Systems this work order covers — resolve via list_systems. Systems have no singular field; this array is the only way to associate them.'),
         start_date: z.string().optional().describe('Start date (ISO 8601)'),
         due_date: z.string().optional().describe('Due date (ISO 8601)'),
         estimated_time: z.number().min(0).optional().describe('Estimated time in hours'),
@@ -150,8 +178,15 @@ export function registerWriteTools(server, client) {
             .string()
             .uuid()
             .optional()
-            .describe('Location ID — resolve last via list_locations filtered by building_id'),
-        asset_id: z.string().uuid().optional().describe('Asset ID'),
+            .describe('Location this work order is for — resolve last via list_locations filtered by building_id. The server mirrors it into location_ids, so send this OR location_ids, not a conflicting pair.'),
+        asset_id: z
+            .string()
+            .uuid()
+            .optional()
+            .describe('Asset this work order is for — resolve via list_assets. The server mirrors it into asset_ids.'),
+        location_ids: ASSOCIATION_ARRAY_SCHEMA('Locations this work order covers — use instead of location_id when there is more than one. Sending location_id alone replaces this with that single id.'),
+        asset_ids: ASSOCIATION_ARRAY_SCHEMA('Assets this work order covers — use instead of asset_id when there is more than one.'),
+        system_ids: ASSOCIATION_ARRAY_SCHEMA('Systems this work order covers — resolve via list_systems. Systems have no singular field; this array is the only way to associate them.'),
         start_date: z.string().optional().describe('Start date (ISO 8601)'),
         due_date: z.string().optional().describe('Due date (ISO 8601)'),
         estimated_time: z.number().min(0).optional().describe('Estimated time in hours'),
@@ -886,9 +921,9 @@ export function registerWriteTools(server, client) {
             .describe('Meter interval — trigger every N units'),
         meter_unit: z.string().max(50).optional().describe('Meter unit (km, miles, hours, cycles)'),
         start_date: z.string().optional().describe('Start date (ISO 8601)'),
-        asset_ids: z.array(z.string().uuid()).optional().describe('Array of asset IDs'),
-        system_ids: z.array(z.string().uuid()).optional().describe('Array of system IDs'),
-        location_ids: z.array(z.string().uuid()).optional().describe('Array of location IDs'),
+        asset_ids: ASSOCIATION_ARRAY_SCHEMA('Assets this schedule covers — use instead of asset_id when there is more than one.'),
+        system_ids: ASSOCIATION_ARRAY_SCHEMA('Systems this schedule covers. Systems have no singular field; this array is the only way to associate them.'),
+        location_ids: ASSOCIATION_ARRAY_SCHEMA('Locations this schedule covers — use instead of location_id when there is more than one. Sending location_id alone replaces this with that single id.'),
         tasks: z
             .array(z.object({
             id: z.string().describe('Unique task ID (use a random string)'),
@@ -897,6 +932,7 @@ export function registerWriteTools(server, client) {
         }))
             .optional()
             .describe('Checklist of tasks for this PM schedule'),
+        form_template_id: FORM_TEMPLATE_LINK_SCHEMA,
     }, async (params) => {
         try {
             const result = await client.create('pm-schedules', buildBody(params));
@@ -960,9 +996,9 @@ export function registerWriteTools(server, client) {
             .describe('Meter interval — trigger every N units'),
         meter_unit: z.string().max(50).optional().describe('Meter unit (km, miles, hours, cycles)'),
         start_date: z.string().optional().describe('Start date (ISO 8601)'),
-        asset_ids: z.array(z.string().uuid()).optional().describe('Array of asset IDs'),
-        system_ids: z.array(z.string().uuid()).optional().describe('Array of system IDs'),
-        location_ids: z.array(z.string().uuid()).optional().describe('Array of location IDs'),
+        asset_ids: ASSOCIATION_ARRAY_SCHEMA('Assets this schedule covers — use instead of asset_id when there is more than one.'),
+        system_ids: ASSOCIATION_ARRAY_SCHEMA('Systems this schedule covers. Systems have no singular field; this array is the only way to associate them.'),
+        location_ids: ASSOCIATION_ARRAY_SCHEMA('Locations this schedule covers — use instead of location_id when there is more than one. Sending location_id alone replaces this with that single id.'),
         tasks: z
             .array(z.object({
             id: z.string().describe('Unique task ID'),
@@ -971,6 +1007,7 @@ export function registerWriteTools(server, client) {
         }))
             .optional()
             .describe('Checklist of tasks for this PM schedule'),
+        form_template_id: FORM_TEMPLATE_LINK_SCHEMA,
     }, async ({ id, ...rest }) => {
         try {
             const result = await client.update('pm-schedules', id, buildBody(rest));
@@ -1055,6 +1092,7 @@ export function registerWriteTools(server, client) {
             .array(z.string().uuid())
             .optional()
             .describe('Default location IDs to seed on derived schedules'),
+        form_template_id: FORM_TEMPLATE_LINK_SCHEMA,
     }, async (params) => {
         try {
             const result = await client.create('pm-templates', buildBody(normalizePmTemplateBody(params)));
@@ -1118,6 +1156,7 @@ export function registerWriteTools(server, client) {
         documents: z.array(z.record(z.unknown())).optional().describe('Document references'),
         asset_ids: z.array(z.string().uuid()).optional().describe('Default asset IDs'),
         location_ids: z.array(z.string().uuid()).optional().describe('Default location IDs'),
+        form_template_id: FORM_TEMPLATE_LINK_SCHEMA,
     }, async ({ id, ...rest }) => {
         try {
             const result = await client.update('pm-templates', id, buildBody(normalizePmTemplateBody(rest)));
@@ -1137,6 +1176,184 @@ export function registerWriteTools(server, client) {
         }
     });
     // ============================================================
+    // 8c. Forms & Inspections (scope: form_templates, form_template_items)
+    // ============================================================
+    server.tool('create_form_template', 'Create a form template — a reusable inspection, checklist, compliance, or survey definition. Step 1 of building a form: create it as a draft, then add questions with create_form_template_item (or bulk_create on form-template-items), then publish with update_form_template status=published (publishing is rejected if any question is malformed). Requires form_templates:write scope.', {
+        name: z.string().min(1).max(500).describe('Form template name (required)'),
+        description: z.string().max(5000).optional().describe('Description'),
+        work_category_id: z
+            .string()
+            .uuid()
+            .optional()
+            .describe('Work category ID — the same tenant-configured categories used by work orders (e.g. Electrical, Plumbing, HVAC). Look them up with list_work_categories and pick the closest match; omit if none fits.'),
+        status: z
+            .enum(FORM_TEMPLATE_STATUSES)
+            .optional()
+            .describe('Publication status — leave as draft (default) until all questions are added.'),
+    }, async (params) => {
+        try {
+            const result = await client.create('form-templates', buildBody(params));
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    server.tool('update_form_template', 'Update an existing form template by ID. Requires form_templates:write scope.', {
+        id: z.string().uuid().describe('Form template ID'),
+        name: z.string().min(1).max(500).optional().describe('Form template name'),
+        description: z.string().max(5000).optional().describe('Description'),
+        work_category_id: z
+            .string()
+            .uuid()
+            .optional()
+            .describe('Work category ID (look up with list_work_categories)'),
+        status: z
+            .enum(FORM_TEMPLATE_STATUSES)
+            .optional()
+            .describe('Publication status (draft, published, or archived)'),
+    }, async ({ id, ...rest }) => {
+        try {
+            const result = await client.update('form-templates', id, buildBody(rest));
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    server.tool('delete_form_template', 'Delete a form template by ID. Requires form_templates:write scope.', { id: z.string().uuid().describe('Form template ID') }, async ({ id }) => {
+        try {
+            const result = await client.remove('form-templates', id);
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    server.tool('create_form_template_item', 'Add one question (item) to a form template. Build a form by calling this once per question in order, or use bulk_create on form-template-items. Requires form_template_items:write scope.', {
+        template_id: z.string().uuid().describe('Form template ID — resolve via list_form_templates'),
+        item_key: z
+            .string()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe('Optional stable key, unique within the template. OMIT IT and the server derives one from the label (recommended). Only set it when a later item’s visible_when must reference this one — then use a short slug like "compressor_status".'),
+        sort_order: z
+            .number()
+            .int()
+            .min(0)
+            .describe('Display order within the template (0-based; questions render in this order)'),
+        item_type: z
+            .enum(FORM_ITEM_TYPES)
+            .describe('Pick by the answer you want: single_select = exactly one choice (Pass/Fail, Yes/No, Yes/No/N-A, or custom — supply options); multi_select = pick several (supply options); number = a numeric reading/count (use config.min/max/unit/integer); checkbox = a single done/not-done tick; text = free comment (config.multiline for long text); photo = photo evidence (config.maxPhotos); section = a non-answerable heading that groups the questions under it.'),
+        label: z.string().min(1).max(2000).describe('Question text / prompt shown to the user'),
+        help_text: z.string().max(5000).optional().describe('Optional hint shown under the label'),
+        required: z
+            .boolean()
+            .optional()
+            .describe('Whether an answer is required to complete the form (default false)'),
+        options: z
+            .array(z.object({ value: z.string(), label: z.string() }))
+            .optional()
+            .describe('REQUIRED for single_select/multi_select: at least 2 choices as { value, label } with unique values. value is a machine slug (e.g. "fail"), label is shown to the user (e.g. "Fail"). Omit for other types.'),
+        config: z
+            .record(z.unknown())
+            .optional()
+            .describe('Per-type settings. number: { min, max, unit, integer, decimals }. text: { multiline, maxLength, placeholder }. multi_select: { minSelections, maxSelections }. photo: { minPhotos, maxPhotos }.'),
+        visible_when: z
+            .object({ itemKey: z.string(), op: z.string(), value: z.unknown().optional() })
+            .nullable()
+            .optional()
+            .describe('Optional conditional visibility { itemKey, op, value }. itemKey must reference an EARLIER item’s key (set that item’s item_key explicitly). Operators by referenced type — single_select/checkbox: equals, not_equals, in, not_in, is_answered, is_blank; number: gt, lt, gte, lte, equals, not_equals, is_answered, is_blank; text: is_answered, is_blank, equals, not_equals; multi_select: in, not_in, is_answered, is_blank. e.g. show a "Details" text item only when item "compressor_status" equals "fail".'),
+    }, async (params) => {
+        try {
+            const result = await client.create('form-template-items', buildBody(params));
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    server.tool('update_form_template_item', 'Update an existing form template item by ID. template_id and item_key are immutable and cannot be changed. Requires form_template_items:write scope.', {
+        id: z.string().uuid().describe('Form template item ID'),
+        sort_order: z.number().int().min(0).optional().describe('Display order within the template'),
+        item_type: z
+            .enum(FORM_ITEM_TYPES)
+            .optional()
+            .describe('Item type (section, checkbox, single_select, multi_select, number, text, photo)'),
+        label: z.string().min(1).max(2000).optional().describe('Question label / prompt'),
+        help_text: z.string().max(5000).optional().describe('Help text shown under the label'),
+        required: z.boolean().optional().describe('Whether an answer is required'),
+        options: z
+            .array(z.object({ value: z.string(), label: z.string() }))
+            .optional()
+            .describe('Choices for single_select / multi_select items'),
+        config: z
+            .record(z.unknown())
+            .optional()
+            .describe('Per-type configuration (e.g. { min, max, unit, multiline })'),
+        visible_when: z
+            .object({ itemKey: z.string(), op: z.string(), value: z.unknown().optional() })
+            .nullable()
+            .optional()
+            .describe('Conditional-visibility rule referencing another item'),
+    }, async ({ id, ...rest }) => {
+        try {
+            const result = await client.update('form-template-items', id, buildBody(rest));
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    server.tool('delete_form_template_item', 'Delete a form template item by ID. Requires form_template_items:write scope.', { id: z.string().uuid().describe('Form template item ID') }, async ({ id }) => {
+        try {
+            const result = await client.remove('form-template-items', id);
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ============================================================
+    // 8d. Form responses — attach / detach (scope: form_responses)
+    // ============================================================
+    server.tool('create_form_response', "Attach a published form to one record so it can be filled in — the direct way to put an inspection or checklist on an existing work order. The form's questions are snapshotted at attach time, so later edits to the template never change a form already in progress. To put a form on every work order a PM schedule generates, set form_template_id on the schedule instead of calling this per work order. Answering and completing the form happen in the AssetLab app, not through this API. Requires form_responses:write scope.", {
+        template_id: z
+            .string()
+            .uuid()
+            .describe('Published form template ID — resolve via list_form_templates. A draft or archived template is rejected; publish it first with update_form_template status="published".'),
+        subject_type: z
+            .enum(['work_order', 'pm_schedule', 'infrastructure_asset', 'compliance_record', 'site'])
+            .describe('What kind of record the form is being attached to'),
+        subject_id: z
+            .string()
+            .uuid()
+            .describe('ID of the record — resolve via the matching list tool (list_work_orders, list_pm_schedules, list_infrastructure_assets, list_compliance_records, list_sites)'),
+    }, async (params) => {
+        try {
+            const result = await client.create('form-responses', buildBody(params));
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    server.tool('delete_form_response', 'Remove a form from the record it is attached to, along with any answers already given. Use this before attaching a different form, since a record holds at most one form. Requires form_responses:write scope.', {
+        id: z
+            .string()
+            .uuid()
+            .describe('Form response ID — resolve via list_form_responses filtered by subject_id'),
+    }, async ({ id }) => {
+        try {
+            const result = await client.remove('form-responses', id);
+            return formatResult(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    // ============================================================
     // 9. Projects (scope: projects)
     // ============================================================
     server.tool('create_project', 'Create a new project. Requires projects:write scope.', {
@@ -4129,6 +4346,9 @@ export function registerWriteTools(server, client) {
         'system-classes',
         'pm-schedules',
         'pm-templates',
+        'form-templates',
+        'form-template-items',
+        'form-responses',
         'projects',
         'contracts',
         'invoices',