@assetlab/mcp-server 1.27.0 → 1.28.0

package/dist/tools-write.js

@@ -20,7 +20,17 @@ function buildBody(params) {
     return body;
 }
 const PM_RESOURCE_TYPES = ['TOOL', 'PART', 'MATERIAL', 'EQUIPMENT'];
-const FORM_TEMPLATE_CATEGORIES = ['task_checklist', 'inspection', 'compliance', 'survey'];
+// 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',
@@ -109,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'),
@@ -161,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'),
@@ -897,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)'),
@@ -908,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));
@@ -971,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'),
@@ -982,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));
@@ -1066,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)));
@@ -1129,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)));
@@ -1153,10 +1181,11 @@ export function registerWriteTools(server, client) {
     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'),
-        category: z
-            .enum(FORM_TEMPLATE_CATEGORIES)
+        work_category_id: z
+            .string()
+            .uuid()
             .optional()
-            .describe('Form category: inspection (default), task_checklist, compliance, or survey. Manufacturer-recommended equipment checks → inspection.'),
+            .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()
@@ -1174,10 +1203,11 @@ export function registerWriteTools(server, client) {
         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'),
-        category: z
-            .enum(FORM_TEMPLATE_CATEGORIES)
+        work_category_id: z
+            .string()
+            .uuid()
             .optional()
-            .describe('Form category (task_checklist, inspection, compliance, or survey)'),
+            .describe('Work category ID (look up with list_work_categories)'),
         status: z
             .enum(FORM_TEMPLATE_STATUSES)
             .optional()
@@ -1286,6 +1316,44 @@ export function registerWriteTools(server, client) {
         }
     });
     // ============================================================
+    // 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.', {
@@ -4280,6 +4348,7 @@ export function registerWriteTools(server, client) {
         'pm-templates',
         'form-templates',
         'form-template-items',
+        'form-responses',
         'projects',
         'contracts',
         'invoices',