iit-mcp-autotask 0.13.1 → 0.15.0

package/README.md

@@ -40,11 +40,18 @@ its contract, `autotask_read` runs it.
   `include_api_users: true`; `by: "email"` narrows to the email field; a numeric identifier is looked up
   as a Resource id); compact rows carry `apiUser` and the licence label when the tenant's labels tell it, never an email. Every match carries `ref`, its human reference. A sweep returns compact matches (`resource`, `ref`, `id`, the human fields) unless `expand: true` (the full record under `record`); `limit` caps the TOTAL matches across resources (resource order, then the SDK's order) and a contains sweep reports `truncated` and per-resource `counts {returned, found}`.
 - `autotask_query` is the bounded filtered list over `resource`: `tickets`, `time_entries`,
-  `service_calls`, `contracts`, `time_off_requests` (limit default 50, max 2500).
+  `service_calls`, `contracts`, `time_off_requests` (limit default 50, max 2500). The served filter
+  schema declares each condition as `{field, op, value}` strings, so a client that builds one type
+  per array column writes `"29"`, `"true"`, `"2026-10-22"`; numbers, `in` arrays and and/or groups are
+  still accepted and passed through unchanged.
 - `autotask_read` runs any read by exact key, or up to 10 at once (`items`). Unbilled work
   (`companies.unbilledWork`), contract profitability (`contracts.profitability`), aggregates
   (`operations.aggregate`) and SLA health (`tickets.slaHealthCheck`) run here; `autotask_guide`
-  holds their recipes. `autotask_read` and `autotask_fetch_many` answer ONE envelope (the next minor,
+  holds their recipes. Its inputs are generic (`operation`, `args`, `items`): no operation-specific
+  fields, because form-filling clients (Copilot Studio) fill every optional input they are shown. A
+  client that cannot send a mixed-type array asks for a time entry window over a resource with
+  `autotask_query` `time_entries` (`resourceID` eq, `dateWorked` gte/lte, every value a string: the
+  served filter schema types `value` as a string). `autotask_read` and `autotask_fetch_many` answer ONE envelope (the next minor,
   breaking): `data = { results: Slot[], ok, failed, budget?, budgetWarning? }`, an array in input
   order even for a single read (`data.results[0].result`). A slot is `{ ok: true, operation, result,
   windowNote? }` or `{ ok: false, operation, error }`; fetch_many slots also echo `resource` and `id`

package/dist/tools/dispatch.js

@@ -65,11 +65,19 @@ export class NeedsInputError extends Error {
 export async function runTool(ctx, input, rawArgs, extra, work) {
     return stamp(ctx.correlationId, await frame(ctx, input, rawArgs, extra, work));
 }
+/** `raw` without the keys `ignored` names (a copy; `raw` itself unchanged), or `raw` as is when there are none. */
+function dropKeys(raw, ignored) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return raw;
+    const keys = ignored(raw);
+    return keys.length === 0 ? raw : Object.fromEntries(Object.entries(raw).filter(([k]) => !keys.includes(k)));
+}
 async function frame(ctx, input, rawArgs, extra, work) {
-    const closed = closedArgsError(rawArgs ?? {}, input.validKeys, ctx.correlationId);
+    const raw = dropKeys(rawArgs ?? {}, input.ignored);
+    const closed = closedArgsError(raw, input.validKeys, ctx.correlationId);
     if (closed !== null)
         return closed;
-    const parsed = input.schema.safeParse(rawArgs ?? {});
+    const parsed = input.schema.safeParse(raw);
     if (!parsed.success) {
         const issue = parsed.error.issues[0];
         const field = issue === undefined ? undefined : issue.path.map(String).join('.');
@@ -198,6 +206,12 @@ export async function readOneItem(ctx, operation, args, signal) {
         // No params bag at all (args omitted / []): the same bounded default (#83); the SDK's own bag-less form is unbounded.
         if (operation.endsWith('.query') && cleanArgs[0] === undefined)
             cleanArgs[0] = { limit: QUERY_LIMIT.parse(undefined) };
+        const given = cleanArgs[0];
+        // #173: a digit-string limit (a client that writes every value as text, e.g. Copilot Studio's
+        // limit: "5") is that number; the SDK still range-checks it.
+        if (given !== null && typeof given === 'object' && !Array.isArray(given) && typeof given.limit === 'string' && /^\d{1,9}$/.test(given.limit)) {
+            cleanArgs[0] = { ...given, limit: Number(given.limit) };
+        }
         const bag = cleanArgs[0];
         if (bag !== null && typeof bag === 'object' && !Array.isArray(bag)) {
             assertFilterShape(bag.filter, operation);

package/dist/tools/meta.js

@@ -24,7 +24,7 @@ import { crossResourceUntrusted, honestReadError, markResult, ok, typedErrorPayl
 import { bm25Rank } from './rank.js';
 import { playbooksFor } from './guide.js';
 import { SERVER_NAME, SERVER_VERSION } from './server-version.js';
-import { CATALOG_INPUT, DESCRIBE_INPUT, COMPANY_FULL_PROFILE_INPUT, CONFIGURATION_ITEM_PROFILE_INPUT, CONTACT_FULL_PROFILE_INPUT, CONTRACT_FULL_PROFILE_INPUT, FETCH_MANY_INPUT, INVOICE_GET_INPUT, PROJECT_GET_CONTEXT_INPUT, QUERY_INPUT, QUOTE_GET_INPUT, RESOLVE_INPUT, RESOURCE_WORKLOAD_INPUT, SERVICE_CALL_FULL_PROFILE_INPUT, TICKET_FULL_CONTEXT_INPUT, QUERY_LIMIT, READ_INPUT, TENANT_STATUS_INPUT, TENANT_STATUS_PARTS, closedInput, } from './schemas.js';
+import { CATALOG_INPUT, DESCRIBE_INPUT, COMPANY_FULL_PROFILE_INPUT, CONFIGURATION_ITEM_PROFILE_INPUT, CONTACT_FULL_PROFILE_INPUT, CONTRACT_FULL_PROFILE_INPUT, FETCH_MANY_INPUT, INVOICE_GET_INPUT, PROJECT_GET_CONTEXT_INPUT, QUERY_INPUT, QUOTE_GET_INPUT, RESOLVE_INPUT, RESOURCE_WORKLOAD_INPUT, SERVICE_CALL_FULL_PROFILE_INPUT, TICKET_FULL_CONTEXT_INPUT, QUERY_LIMIT, READ_INPUT, TENANT_STATUS_INPUT, TENANT_STATUS_PARTS, readIgnoredKeys, closedInput, } from './schemas.js';
 import { refusalReason } from '../policy.js';
 /** Search text per catalog row (key words + purpose), built once. */
 const ROW_TEXT = CATALOG.catalog.map((r) => `${r.operation} ${r.operation.replace(/[._]/g, ' ')} ${r.purpose ?? ''}`);
@@ -250,6 +250,13 @@ async function guidanceFor(ctx, rec, reachable) {
             example: `autotask_read {operation:"${rec.id}", args:[{filter:[{field:"id",op:"gt",value:0}],limit:10}]}`,
         };
     }
+    if (rec.id === 'time_entries.dateWorkedWindow' || rec.id === 'time_entries.postedWithin') {
+        // #173: the positional [from, to, opts] mixes types; the same window as one uniform-string filter
+        return {
+            exampleArgs: ['2026-10-20', '2026-10-22', { resourceID: 123 }],
+            sameWindowAsQuery: 'autotask_query {resource:"time_entries", filter:[{field:"resourceID",op:"eq",value:"123"},{field:"dateWorked",op:"gte",value:"2026-10-20"},{field:"dateWorked",op:"lte",value:"2026-10-22"}], limit:500}: the same rows up to limit (the window caps at 500; dateWorked is a date, both days inclusive), without the posted counts, for a client that cannot send a mixed-type array.',
+        };
+    }
     if (op === 'moveToTicket') {
         // the move ops (#107): zero wire, a pointer to the governed path
         return {
@@ -311,7 +318,7 @@ async function describeRecord(ctx, operation, viaTool) {
 export function buildRead(ctx) {
     return {
         title: 'Run Autotask read operations by exact key',
-        input: closedInput(READ_INPUT),
+        input: closedInput(READ_INPUT, readIgnoredKeys),
         run: async (raw, signal) => {
             const args = raw;
             if ((args.operation === undefined) === (args.items === undefined)) {

package/dist/tools/schemas.d.ts

@@ -48,14 +48,18 @@ export interface ClosedInput {
     input: StandardSchemaWithJSON<Record<string, unknown>, Record<string, unknown>>;
     schema: z.ZodType;
     validKeys: readonly string[];
+    /** The raw top-level keys to drop before the closed-key check (none for most tools). */
+    ignored: (raw: Record<string, unknown>) => readonly string[];
 }
 /**
  * Wrap a zod object schema so its top level is CLOSED and the SDK never rejects it:
  * - the ADVERTISED wire schema is the object's JSON Schema with `additionalProperties: false`;
  * - `validate` returns the raw arguments unchanged — the call frame runs the closed-key check and
  *   the zod parse, so every refusal is an envelope (M1), never the SDK's plain-text error.
+ * `ignored(raw)` names raw keys dropped before the closed-key check (never advertised, never named
+ * as valid keys).
  */
-export declare function closedInput(schema: z.ZodType): ClosedInput;
+export declare function closedInput(schema: z.ZodType, ignored?: ClosedInput['ignored']): ClosedInput;
 /**
  * The envelope as served: every field typed only. The `status` / `next` values are listed once,
  * in the server instructions (that is the byte budget: the zod form with enums and bounds costs
@@ -210,13 +214,24 @@ export declare const DESCRIBE_INPUT: z.ZodObject<{
     resource: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const READ_MAX_ITEMS = 10;
+/**
+ * 0.15.0: autotask_read carries no operation-specific inputs. The six flat window inputs of 0.14.x
+ * are gone from the served schema (a form-filling client fills every optional it is shown, e.g. a
+ * stray limit: 5 on a resources.query), but a client still holding the 0.14.x tool list may send
+ * them. On any other read they are dropped (they never meant anything there). Beside a window key
+ * (top level or in items) a set one is NOT dropped, so the closed-key check refuses it naming the
+ * key: dropping a resourceID or ticketID there would silently widen the window. null or '' is unset.
+ * ponytail: drop this list once no 0.14.x tool list can be cached (a later minor).
+ */
+export declare const READ_RETIRED_KEYS: readonly ["from", "to", "posted", "limit", "ticketID", "resourceID"];
+export declare function readIgnoredKeys(raw: Record<string, unknown>): readonly string[];
 export declare const READ_INPUT: z.ZodObject<{
-    operation: z.ZodOptional<z.ZodString>;
-    args: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
-    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    operation: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    args: z.ZodPreprocess<z.ZodDefault<z.ZodArray<z.ZodUnknown>>, unknown>;
+    items: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
         operation: z.ZodString;
         args: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
-    }, z.core.$strict>>>;
+    }, z.core.$strict>>>, unknown>;
 }, z.core.$strip>;
 export declare const RESOLVE_INPUT: z.ZodObject<{
     identifier: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;

package/dist/tools/schemas.js

@@ -65,8 +65,18 @@ const COMPANY_PROFILE_PART_LIMIT_LOCATIONS = z
  * The JSON filter (pass-through for WELL-FORMED shapes: the condition grammar — 13 operators +
  * and/or — is validated by the SDK pre-request; unsupported TOP-LEVEL shapes are refused by this
  * server pre-request, see {@link assertFilterShape}).
+ *
+ * #173: the ADVERTISED schema types a condition's `value` as a string, so a client that builds one
+ * column type per array (Copilot Studio's Table) gets a uniform string column instead of inferring
+ * one from mixed values; the runtime stays pass-through (numbers, booleans, in/notIn arrays and
+ * and/or groups are accepted unchanged, nothing is converted). Only field/op/value are advertised:
+ * a form-filling client fills every property it is shown, and a filled `udf` or `items` would change
+ * the query.
  */
-const FILTER = z.unknown().describe('Array of {field, op, value} conditions (grammar: server instructions). Field names are pre-validated against the field catalog (0.20.0): an unknown name is a CONFIG_ERROR with the field-catalog pointer — zero QUERY wire (a cold field cache makes one vendor metadata GET first); one udf:true condition per query is exempt. When a client cannot send mixed-type arrays (Copilot Studio), write every value as a string: string dates and ids work; other types are not verified on every field.');
+const FILTER = z
+    .unknown()
+    .meta({ type: 'array', items: { type: 'object', properties: { field: { type: 'string' }, op: { type: 'string' }, value: { type: 'string' } } } })
+    .describe('Conditions {field, op, value} (grammar: server instructions); write every value as a string: "29", "true", "2026-10-22" (numbers also work; in/notIn take an array, and/or groups take items). Field names are pre-validated against the field catalog: an unknown name is a CONFIG_ERROR with the field-catalog pointer, zero QUERY wire (a cold field cache makes one vendor metadata GET first); one udf:true condition per query is exempt.');
 /**
  * The pre-dispatch filter-shape gate (#18): accepts the two top-level shapes the pinned SDK
  * understands — a conditions array, or a params bag whose `filter` field is a conditions array
@@ -100,8 +110,10 @@ export function assertEnrichApplicable(resource, keys, operation) {
  * - the ADVERTISED wire schema is the object's JSON Schema with `additionalProperties: false`;
  * - `validate` returns the raw arguments unchanged — the call frame runs the closed-key check and
  *   the zod parse, so every refusal is an envelope (M1), never the SDK's plain-text error.
+ * `ignored(raw)` names raw keys dropped before the closed-key check (never advertised, never named
+ * as valid keys).
  */
-export function closedInput(schema) {
+export function closedInput(schema, ignored = () => []) {
     const advertised = z.toJSONSchema(schema, { target: 'draft-2020-12', io: 'input' });
     const validKeys = Object.keys(advertised.properties ?? {});
     const input = {
@@ -119,7 +131,7 @@ export function closedInput(schema) {
             },
         },
     };
-    return { input, schema, validKeys };
+    return { input, schema, validKeys, ignored };
 }
 // ---------------------------------------------------------------------------
 // The served output schema: the compact result envelope (one per tool)
@@ -203,10 +215,31 @@ export const DESCRIBE_INPUT = z.object({
 });
 const READ_ITEM = z.strictObject({ operation: OP_KEY.describe('Exact read key.'), args: ARGS });
 export const READ_MAX_ITEMS = 10;
+/**
+ * An autotask_read input sent as null or '' is absent: form-filling clients (Copilot Studio) can
+ * send every unset optional that way. The advertised schema stays the plain type (no null union).
+ */
+const unset = (schema) => z.preprocess((v) => (v === null || v === '' ? undefined : v), schema);
+/**
+ * 0.15.0: autotask_read carries no operation-specific inputs. The six flat window inputs of 0.14.x
+ * are gone from the served schema (a form-filling client fills every optional it is shown, e.g. a
+ * stray limit: 5 on a resources.query), but a client still holding the 0.14.x tool list may send
+ * them. On any other read they are dropped (they never meant anything there). Beside a window key
+ * (top level or in items) a set one is NOT dropped, so the closed-key check refuses it naming the
+ * key: dropping a resourceID or ticketID there would silently widen the window. null or '' is unset.
+ * ponytail: drop this list once no 0.14.x tool list can be cached (a later minor).
+ */
+export const READ_RETIRED_KEYS = ['from', 'to', 'posted', 'limit', 'ticketID', 'resourceID'];
+const WINDOW_OPS = ['time_entries.dateWorkedWindow', 'time_entries.postedWithin'];
+export function readIgnoredKeys(raw) {
+    const items = Array.isArray(raw.items) ? raw.items : [];
+    const window = WINDOW_OPS.includes(raw.operation) || items.some((i) => typeof i === 'object' && i !== null && WINDOW_OPS.includes(i.operation));
+    return READ_RETIRED_KEYS.filter((k) => k in raw && (!window || raw[k] === null || raw[k] === ''));
+}
 export const READ_INPUT = z.object({
-    operation: OP_KEY.optional().describe('Exact read key, e.g. tickets.get (autotask_catalog finds it).'),
-    args: ARGS,
-    items: z.array(READ_ITEM).min(1).max(READ_MAX_ITEMS).optional().describe('Up to 10 reads in one call, each { operation, args }; use instead of operation.'),
+    operation: unset(OP_KEY.optional()).describe('Exact read key, e.g. tickets.get (autotask_catalog finds it).'),
+    args: unset(ARGS),
+    items: unset(z.array(READ_ITEM).min(1).max(READ_MAX_ITEMS).optional()).describe('Up to 10 reads in one call, each { operation, args }; use instead of operation.'),
 });
 export const RESOLVE_INPUT = z.object({
     identifier: z.union([z.number().int().nonnegative(), z.string().min(1).max(200)]).describe('Numeric id, name, ticket number, serial or email. resources: numeric identifiers are looked up as Resource ids.'),

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.13.1";
+export declare const SERVER_VERSION = "0.15.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.13.1';
+export const SERVER_VERSION = '0.15.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.13.1";
+    readonly version: "0.15.0";
     readonly mcpProtocolBaseline: "2026-07-28";
     readonly legacyProtocolFallback: "2025-11-25";
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.13.1",
+  "version": "0.15.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.13.1",
+  "version": "0.15.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/filter-semantics.md

@@ -28,7 +28,7 @@ No inputs: this is a reference page about the filter behaviour of autotask_query
 3. tickets.search is a vendor contains on the TITLE only: no free-text search, no matched-field reporting, and vendor contains is looser than a literal substring (case/token matching can return MORE hits than a local title-substring check). The per-field contains of tickets.query is the precise tool.
 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 an array mixes value types: a number and a string in one filter, or dateWorkedWindow args (strings plus an object). For such a client, write every filter value as a string ("<resource id>", "2026-10-22", "true") and use autotask_query time_entries with a dateWorked gte/lte pair in place of dateWorkedWindow. The server and SDK pass values through unchanged; string dates and ids are confirmed to work, other types are not verified on every field.
+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.
 
 ## Guardrails