iit-mcp-autotask 0.33.0 → 0.34.0

package/.env.example

@@ -68,7 +68,7 @@ AUTOTASK_PROFILE=readonly
 # The kill file: while it exists every preview and apply is denied (default <state dir>/KILL).
 # AUTOTASK_KILL_FILE=/var/lib/autotask-mcp/KILL
 # Optional toolsets on top of core (core is always on): a comma list of service, records, finance,
-# or all. An unknown name fails boot. Unset = core only (10 tools).
+# or all. An unknown name fails boot. Unset = core only (11 tools).
 # AUTOTASK_TOOLSETS=service,records,finance
 # IANA time zone of the people asking (their local "today"), default UTC; not the tenant's or
 # the server's zone. Autotask stores UTC; the zone is reported by

package/README.md

@@ -19,7 +19,7 @@ client + SDK-owned TTL caches).
 
 ## Tool surface
 
-The **core** toolset (10 tools) is always served; `AUTOTASK_TOOLSETS` adds `service`, `records` and
+The **core** toolset (11 tools) is always served; `AUTOTASK_TOOLSETS` adds `service`, `records` and
 `finance` (or `all`, 18 tools); the operator profile adds two. The whole tool surface (20 tools) is
 listed below. Every other operation in the SDK's 1,216-operation registry stays
 reachable through the generic layer: `autotask_catalog` finds the key, `autotask_describe` serves
@@ -27,8 +27,8 @@ its contract, `autotask_read` runs it.
 
 | Toolset | Tools |
 |---------|-------|
-| core (always) | `autotask_guide` · `autotask_catalog` · `autotask_describe` · `autotask_read` · `autotask_resolve` · `autotask_query` · `autotask_fetch_many` · `autotask_tenant_status` · `autotask_ticket_full_context` · `autotask_company_full_profile` |
-| `service` | `autotask_project_get_context` · `autotask_service_call_full_profile` · `autotask_resource_workload` |
+| core (always) | `autotask_guide` · `autotask_catalog` · `autotask_describe` · `autotask_read` · `autotask_resolve` · `autotask_query` · `autotask_fetch_many` · `autotask_tenant_status` · `autotask_ticket_full_context` · `autotask_company_full_profile` · `autotask_resource_workload` |
+| `service` | `autotask_project_get_context` · `autotask_service_call_full_profile` |
 | `records` | `autotask_contact_full_profile` · `autotask_configuration_item_profile` · `autotask_contract_full_profile` |
 | `finance` | `autotask_quote_get` · `autotask_invoice_get` (`format`: `record`, `html`, `xml`, `pdf`) |
 | `operator` (operator profile) | `autotask_write` (preview, changes nothing) · `autotask_apply` (execute the previewed plan) |
@@ -70,7 +70,7 @@ vendor, so loading a playbook costs no wire and adds no injection surface.
 - `{skill, section}`: one of its `## ` sections.
 
 Skills: `ticket-triage`, `company-360`, `unbilled-work-review`, `contract-profitability`,
-`invoice-export`, `filter-semantics`, `slim-reads`, and on the operator profile `log-time-entry` and `crm-onboarding`.
+`invoice-export`, `filter-semantics`, `slim-reads`, and on the operator profile `log-time-entry` and `crm-management`.
 
 The playbooks are discoverable in both directions:
 

package/capabilities.json

@@ -3,9 +3,9 @@
   "domain": "autotask",
   "description": "Machine-readable capability catalogue for iit-mcp-autotask: the tools the server can serve, with the toolset and the lowest profile that serves each. Everything else in the registry is reachable through the generic layer (autotask_catalog / autotask_describe / autotask_read) and documented in docs/capability-matrix.md. Generated from src/tools/surface.ts by scripts/build-capabilities.mjs.",
   "exposedToolCount": {
-    "readonlyCore": 10,
+    "readonlyCore": 11,
     "readonlyAll": 18,
-    "operatorCore": 12,
+    "operatorCore": 13,
     "operatorAll": 20
   },
   "profiles": {
@@ -27,12 +27,12 @@
       "autotask_fetch_many",
       "autotask_tenant_status",
       "autotask_ticket_full_context",
-      "autotask_company_full_profile"
+      "autotask_company_full_profile",
+      "autotask_resource_workload"
     ],
     "service": [
       "autotask_project_get_context",
-      "autotask_service_call_full_profile",
-      "autotask_resource_workload"
+      "autotask_service_call_full_profile"
     ],
     "records": [
       "autotask_contact_full_profile",
@@ -211,14 +211,14 @@
       }
     },
     {
-      "id": "autotask.project.get_context",
-      "description": "One project with its company, opportunity and lead resource. Project phases and task lists do not exist on this API; charges and notes go through autotask_read.",
+      "id": "autotask.resource.workload",
+      "description": "One resource's availability: open tickets as primary or secondary resource (de-duplicated, with counts), service-call assignments, time-off balances and time-off awaiting approval. Missing parts degrade to typed absent.",
       "mcpPrimitive": "tool",
-      "toolName": "autotask_project_get_context",
+      "toolName": "autotask_resource_workload",
       "type": "read",
-      "toolset": "service",
+      "toolset": "core",
       "profile": "readonly",
-      "backingOperation": "projects.getContext",
+      "backingOperation": "resources.get",
       "annotations": {
         "readOnly": true,
         "idempotent": true,
@@ -227,14 +227,14 @@
       }
     },
     {
-      "id": "autotask.service_call.full_profile",
-      "description": "One service call with its linked tickets, tasks and resource assignments, for on-site visit work. Missing parts degrade to typed absent.",
+      "id": "autotask.project.get_context",
+      "description": "One project with its company, opportunity and lead resource. Project phases and task lists do not exist on this API; charges and notes go through autotask_read.",
       "mcpPrimitive": "tool",
-      "toolName": "autotask_service_call_full_profile",
+      "toolName": "autotask_project_get_context",
       "type": "read",
       "toolset": "service",
       "profile": "readonly",
-      "backingOperation": "service_calls.get",
+      "backingOperation": "projects.getContext",
       "annotations": {
         "readOnly": true,
         "idempotent": true,
@@ -243,14 +243,14 @@
       }
     },
     {
-      "id": "autotask.resource.workload",
-      "description": "One resource's availability: open tickets as primary or secondary resource (de-duplicated, with counts), service-call assignments, time-off balances and time-off awaiting approval. Missing parts degrade to typed absent.",
+      "id": "autotask.service_call.full_profile",
+      "description": "One service call with its linked tickets, tasks and resource assignments, for on-site visit work. Missing parts degrade to typed absent.",
       "mcpPrimitive": "tool",
-      "toolName": "autotask_resource_workload",
+      "toolName": "autotask_service_call_full_profile",
       "type": "read",
       "toolset": "service",
       "profile": "readonly",
-      "backingOperation": "resources.get",
+      "backingOperation": "service_calls.get",
       "annotations": {
         "readOnly": true,
         "idempotent": true,
@@ -260,7 +260,7 @@
     },
     {
       "id": "autotask.contact.full_profile",
-      "description": "One contact with their company and open tickets (closed set from the tenant status picklist, 2-4 reads). Contains personal data. Missing parts degrade to typed absent.",
+      "description": "One contact with their company and open tickets (closed set from the tenant status picklist, 2-5 reads). Contains personal data. Missing parts degrade to typed absent.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_contact_full_profile",
       "type": "read",

package/dist/tools/catalog-data.js

@@ -121,7 +121,7 @@ export const TOOL_DESCRIPTIONS = {
     autotask_project_get_context: 'One project with its company, opportunity and lead resource. Project phases and task lists do not exist on this API; charges and notes go through autotask_read.',
     autotask_service_call_full_profile: 'One service call with its linked tickets, tasks and resource assignments, for on-site visit work. Missing parts degrade to typed absent.',
     autotask_resource_workload: 'One resource\'s availability: open tickets as primary or secondary resource (de-duplicated, with counts), service-call assignments, time-off balances and time-off awaiting approval. Missing parts degrade to typed absent.',
-    autotask_contact_full_profile: 'One contact with their company and open tickets (closed set from the tenant status picklist, 2-4 reads). Contains personal data. Missing parts degrade to typed absent.',
+    autotask_contact_full_profile: 'One contact with their company and open tickets (closed set from the tenant status picklist, 2-5 reads). Contains personal data. Missing parts degrade to typed absent.',
     autotask_configuration_item_profile: 'One configuration item with type, category, notes, related items and billing products. Zone ww29 has no configuration items: expect not found there.',
     autotask_contract_full_profile: 'One contract with services, billing rules, the 50 newest charges and service units. Monthly P&L: autotask_read (guide: contract-profitability).',
     autotask_quote_get: 'One quote with its line items in one call. A list of quotes: autotask_read quotes.query.',

package/dist/tools/server-version.d.ts

@@ -1,3 +1,3 @@
 /** The wire identity of this server: a leaf module (no imports) so any tool can read it without an import cycle. */
 export declare const SERVER_NAME = "iit-mcp-autotask";
-export declare const SERVER_VERSION = "0.33.0";
+export declare const SERVER_VERSION = "0.34.0";

package/dist/tools/server-version.js

@@ -1,4 +1,4 @@
 /** The wire identity of this server: a leaf module (no imports) so any tool can read it without an import cycle. */
 export const SERVER_NAME = 'iit-mcp-autotask';
-export const SERVER_VERSION = '0.33.0';
+export const SERVER_VERSION = '0.34.0';
 //# sourceMappingURL=server-version.js.map

package/dist/tools/server.d.ts

@@ -60,7 +60,7 @@ export declare function serverInstructions(config: Pick<Config, 'AUTOTASK_PROFIL
 /** The full identity stamp (the `/metadata` build block — the era pair, FR-2). */
 export declare const SERVER_IDENTITY: {
     readonly name: "iit-mcp-autotask";
-    readonly version: "0.33.0";
+    readonly version: "0.34.0";
     readonly mcpProtocolBaseline: "2026-07-28";
     readonly legacyProtocolFallback: "2025-11-25";
 };

package/dist/tools/surface.js

@@ -25,9 +25,9 @@ export const SURFACE = [
     { name: 'autotask_tenant_status', toolset: 'core', profile: 'readonly', vendor: true, build: buildTenantStatus },
     { name: 'autotask_ticket_full_context', toolset: 'core', profile: 'readonly', vendor: true, build: buildTicketFullContext },
     { name: 'autotask_company_full_profile', toolset: 'core', profile: 'readonly', vendor: true, build: buildCompanyFullProfile },
+    { name: 'autotask_resource_workload', toolset: 'core', profile: 'readonly', vendor: true, build: buildResourceWorkload },
     { name: 'autotask_project_get_context', toolset: 'service', profile: 'readonly', vendor: true, build: buildProjectGetContext },
     { name: 'autotask_service_call_full_profile', toolset: 'service', profile: 'readonly', vendor: true, build: buildServiceCallFullProfile },
-    { name: 'autotask_resource_workload', toolset: 'service', profile: 'readonly', vendor: true, build: buildResourceWorkload },
     { name: 'autotask_contact_full_profile', toolset: 'records', profile: 'readonly', vendor: true, build: buildContactFullProfile },
     { name: 'autotask_configuration_item_profile', toolset: 'records', profile: 'readonly', vendor: true, build: buildConfigurationItemProfile },
     { name: 'autotask_contract_full_profile', toolset: 'records', profile: 'readonly', vendor: true, build: buildContractFullProfile },

package/dist/tools/write/preview.js

@@ -1,6 +1,7 @@
 /** `autotask_write`: the preview tool (issue #89). */
 import { MoveRefusedError } from 'node-autotask';
 import { abortedResult, cleanUntrustedText } from '../results.js';
+import { assertOperationPermitted } from '../../policy.js';
 import { WRITE_INPUT, closedInput } from '../schemas.js';
 import { hashOf } from '../../write/canonical.js';
 import { evaluate } from '../../write/evaluate.js';
@@ -141,9 +142,13 @@ async function entryResource(r, a) {
         return { id, roleID, name: null, absent: true };
     }
 }
+/** The response sanitiser's per-string cap (UNTRUSTED_TEXT_CAP): a longer warning would lose its tail. */
+const LOCATION_WARNING_CAP = 500;
 /**
  * #183: a contact written with no `companyLocationID` while its company has active locations. One bounded
- * read (limit 50), only when the field is unset; a failed read adds nothing.
+ * read (limit 50), only when the field is unset; a failed or refused read adds nothing. The read goes through
+ * the same deployment gate as `autotask_read`. The sanitiser caps each warning at 500 characters, so the instruction
+ * comes first and only as many location ids as fit are listed. No vendor text enters the sentence: ids are numbers.
  */
 async function locationWarning(r, a, current) {
     if (r.op !== 'contacts.create' && r.op !== 'contacts.update')
@@ -154,12 +159,25 @@ async function locationWarning(r, a, current) {
     if (current?.companyLocationID != null)
         return undefined; // update on a contact that already has a location
     try {
+        assertOperationPermitted('company_locations.query', r.ctx.record('company_locations.query'), r.ctx.config, r.ctx.log);
         const rows = (await r.ctx.ops.invokeRead(r.ctx.client, 'company_locations.query', [{ filter: [{ field: 'companyID', op: 'eq', value: companyID }, { field: 'isActive', op: 'eq', value: true }], limit: 50 }], undefined, r.signal));
-        const list = (Array.isArray(rows) ? rows : rows?.items) ?? [];
+        const raw = (Array.isArray(rows) ? rows : rows?.items) ?? [];
+        const list = raw.filter((l) => Number.isSafeInteger(l.id) && l.id > 0); // ids are the only thing served: no row without one is listed or counted
         if (list.length === 0)
             return undefined;
-        const names = list.map((l) => `${String(l.id)} - ${cleanUntrustedText(String(l.name ?? ''), false).slice(0, 60)}${l.isPrimary === true ? ' (primary)' : ''}`).join(', ');
-        return `companyLocationID is not set on this contact and the parent company ${companyID} has ${list.length} active location(s): ${names}. Set companyLocationID before applying; if the contact's address is unknown${list.length > 1 ? ', ask the user which location applies' : ' and there is one location, set it'}.`;
+        const total = list.length >= 50 ? 'at least 50' : String(list.length);
+        const head = `companyLocationID is not set on this contact and the parent company ${companyID} has ${total} active location(s). Set companyLocationID before applying; if the contact's address is unknown${list.length > 1 ? ', ask the user which location applies' : ' and there is one location, set it'}. Location ids (names: company_locations.query): `;
+        // ids and the primary flag only: no vendor text in server prose; the model reads names through company_locations.query
+        const items = list.map((l) => `${l.id}${l.isPrimary === true ? ' (primary)' : ''}`);
+        let text = head;
+        let shown = 0;
+        for (const it of items) {
+            if (text.length + it.length + 2 > LOCATION_WARNING_CAP - 40)
+                break; // 40 = room for the ' (first N of at least M listed)' tail
+            text += (shown > 0 ? ', ' : '') + it;
+            shown++;
+        }
+        return shown < items.length ? `${text} (first ${shown} of ${total} listed)` : text;
     }
     catch {
         return undefined;
@@ -255,7 +273,7 @@ export function buildWrite(ctx) {
             if ('stop' in dry)
                 return dry.stop;
             const loc = await locationWarning(r, admitted.ok, snap.ok.current);
-            const dried = loc === undefined ? dry.ok : { ...dry.ok, warnings: [...(dry.ok.warnings ?? []), loc] };
+            const dried = loc === undefined ? dry.ok : { ...dry.ok, warnings: [loc, ...(dry.ok.warnings ?? [])] };
             return persist(r, admitted.ok, snap.ok, evaluatePhase(r, admitted.ok, snap.ok, dried, await entryResource(r, admitted.ok)));
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "MCP server for the Autotask (Datto) PSA domain, built on the node-autotask SDK",
   "license": "MIT",
   "author": "Max Soukhomlinov",

package/server.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "MCP server for the Autotask (Datto) PSA API, powered by the node-autotask SDK",
   "mcpProtocolBaseline": "2026-07-28",
   "legacyProtocolFallback": "2025-11-25",

package/skills/{crm-onboarding.md → crm-management.md}

@@ -1,5 +1,5 @@
 ---
-name: crm-onboarding
+name: crm-management
 kind: write
 version: 1
 profile: operator
@@ -10,7 +10,7 @@ inputs: {"type": "object", "required": ["intent", "run_id"], "properties": {"int
 outcomes: ["ok", "needs_input", "ambiguous", "denied", "error"]
 hazards: ["writes company, location and contact records to the PSA", "every new company gets an auto-created \"Primary Address\" location that cannot be deleted through the API: rename it", "companies, resources and countries are blind surfaces on some tenants: no match is not proof of absence; owners and countries are lookups, not lists"]
 related: ["company-360"]
-eval: evals/crm-onboarding.json
+eval: evals/crm-management.json
 ---
 
 # Create or update a company, location or contact

package/skills/filter-semantics.md

@@ -5,7 +5,7 @@ version: 1
 profile: readonly
 description: Filter footguns for autotask_query: strict date lt, case-insensitive contains, FK 0 vs NULL, field-name checks, all-strings values.
 when_not_to_use: the filter grammar itself (the 13 operators + and/or grouping, server instructions); the per-operation notes (autotask_describe)
-ops: ["autotask_query:tickets.query", "autotask_query:time_entries.query", "autotask_query:service_calls.query", "autotask_query:contracts.query", "autotask_query:time_off_requests.query", "autotask_read:operations.fieldCatalog"]
+ops: ["autotask_query:tickets.query", "autotask_query:time_entries.query", "autotask_query:service_calls.query", "autotask_query:contracts.query", "autotask_query:time_off_requests.query", "autotask_read:operations.fieldCatalog", "autotask_resource_workload"]
 inputs: {"type": "object", "required": [], "properties": {}}
 outcomes: ["ok", "error"]
 hazards: ["gt/lt around a day boundary silently drops an edge day", "ticketID eq 0 finds nothing (time_entries store NULL)", "an unknown field name is a zero-query-wire CONFIG_ERROR (0.20.0 pre-validation; a cold field cache makes one vendor metadata GET first)"]
@@ -29,10 +29,11 @@ No inputs: this is a reference page about the filter behaviour of autotask_query
 4. Unassigned FKs are not uniform. tickets store 0; time_entries store NULL. Unallocated time needs notExist (ticketID eq 0 finds nothing); assignedResourceID eq 0 and notExist differ.
 5. Field names are vendor casing, and an unknown field name now fails pre-dispatch as a typed CONFIG_ERROR with the field-catalog pointer, with zero query wire (0.20.0 pre-validation), on all five autotask_query operations (tickets.query, time_entries.query, service_calls.query, contracts.query, time_off_requests.query). One udf: true condition per query is exempt from the name check. List names for the queried resource with the scoped call `autotask_read {operation:"operations.fieldCatalog", args:[{resources:["<resource>"]}]}` (add `fields: [names]` to project; a scoped call also returns picklist labels by default on this server). Never the bare `operations.fieldCatalog`: it serves the whole five-resource catalog (~85 KB) and has no row for time_entries, service_calls, contracts or time_off_requests. Do not guess names. The answer is `data.results[0].result`.
 6. Some clients (Copilot Studio) fail locally, before any request, when one array mixes value types (a number beside a string in one filter, or dateWorkedWindow args: strings plus an object). The autotask_query filter declares value as a string, so write every value as a string ("<resource id>", "2026-10-22", "true"); numbers still work for clients that send them. For a time entry window over a resource or ticket, query time entries instead of dateWorkedWindow: `autotask_query {resource:"time_entries", filter:[{field:"resourceID",op:"eq",value:"<resource id>"},{field:"dateWorked",op:"gte",value:"2026-10-20"},{field:"dateWorked",op:"lte",value:"2026-10-22"}], limit:500}`: the window's rows up to limit (dateWorkedWindow caps at 500; the query defaults to 50), both days inclusive because dateWorked is a date, without the posted counts (derive them from postedDate where the zone serves it). A bare window with no narrowing is `autotask_read {operation:"time_entries.dateWorkedWindow", args:["2026-10-20","2026-10-22"]}` (all strings). The server and SDK pass filter values through unchanged; string dates, ids and booleans are confirmed on resources and time_entries, other fields are not verified.
+7. tickets.assignedResourceID is the PRIMARY owner only. Secondary assignments live in the separate ticket_secondary_resources table, which carries no status, so "how many open tickets does <resource> have" cannot be answered from tickets.query alone or from that table alone. Use `autotask_resource_workload {id}`: its open_tickets part is the de-duplicated union of primary and secondary open tickets with counts {primary, secondary, both, open}. The counts describe the returned set; when value.capped is true the answer is partial: call again with a larger ticket_limit (up to 500) before quoting counts, and say so if it is still capped. If the part is absent with CLOSED_STATUS_UNRESOLVED the tenant's closed statuses could not be read: say the count is unavailable rather than guessing.
 
 ## Guardrails
 
-- Apply the five rules above when composing or debugging any autotask_query filter.
+- Apply the seven rules above when composing or debugging any autotask_query filter.
 - Do not "fix" a filter that already returns the right rows into a stricter spelling (a case-sensitive contains, an exclusive range, a zero-FK predicate).
 - Never guess field names: since 0.20.0 an unknown name is a typed CONFIG_ERROR with zero query wire (a cold field cache makes one vendor metadata GET first) — list names with the scoped fieldCatalog call from step 5 first.
 
@@ -68,4 +69,5 @@ No inputs: this is a reference page about the filter behaviour of autotask_query
 | autotask_query | contracts.query | read | - |
 | autotask_query | time_off_requests.query | read | - |
 | autotask_read | operations.fieldCatalog | read | - |
+| autotask_resource_workload | - | - | - |
 <!-- generated:end -->