iit-mcp-autotask 0.13.1 → 0.14.0

package/README.md

@@ -44,7 +44,13 @@ its contract, `autotask_read` runs it.
 - `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. The two time-entry window keys (`time_entries.dateWorkedWindow`,
+  `time_entries.postedWithin`) also take flat named inputs instead of `args`, for clients that cannot
+  send a mixed-type array (Copilot Studio): `{operation, from, to, posted?, limit?, ticketID?,
+  resourceID?}`, `from`/`to` as inclusive `YYYY-MM-DD` dateWorked days (never UTC-converted),
+  `ticketID`/`resourceID` as numbers, no `tz` (it does not shift dateWorked). The SDK's
+  `foldFlattenedOpts` maps them onto its named invoke form, so the result and `truncated` flag are
+  the positional call's. `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/context/types.d.ts

@@ -33,7 +33,8 @@ export interface QueryWalkResult {
 /** The SDK operations the handler layer drives, bound in ONE place (the mock seam). */
 export interface ToolOps {
     /** The MCP request's AbortSignal, when the transport provides one: an abandoned request stops consuming vendor budget. */
-    invokeRead(client: ToolClient, operation: string, args?: readonly unknown[], opts?: InvokeOptions, signal?: AbortSignal): Promise<unknown>;
+    /** `args` is positional, or (#173, the window keys) the SDK's named form keyed by the record's inputSchema names. */
+    invokeRead(client: ToolClient, operation: string, args?: readonly unknown[] | Record<string, unknown>, opts?: InvokeOptions, signal?: AbortSignal): Promise<unknown>;
     invokeWrite(client: ToolClient, operation: string, args?: readonly unknown[], opts?: InvokeOptions, signal?: AbortSignal): Promise<unknown>;
     invokeDelete(client: ToolClient, operation: string, args?: readonly unknown[], opts?: InvokeOptions, signal?: AbortSignal): Promise<unknown>;
     resolveAny(client: ToolClient, identifier: number | string, opts?: {

package/dist/tools/dispatch.d.ts

@@ -78,4 +78,4 @@ export interface ReadOutcome {
  * governed invoke (the SDK's single read governor) and the untrusted projection of the result.
  * Errors are THROWN — the frame wraps them once, the `items` form maps them per slot.
  */
-export declare function readOneItem(ctx: ToolContext, operation: string, args: unknown[], signal: AbortSignal | undefined): Promise<ReadOutcome>;
+export declare function readOneItem(ctx: ToolContext, operation: string, args: unknown[] | Record<string, unknown>, signal: AbortSignal | undefined): Promise<ReadOutcome>;

package/dist/tools/dispatch.js

@@ -191,7 +191,9 @@ export async function readOneItem(ctx, operation, args, signal) {
     }
     assertOperationPermitted(operation, rec, ctx.config, ctx.log);
     // Issue #1: strip ONE exact outer <untrusted_content> wrapper from the string inputs.
-    const cleanArgs = stripUntrustedDeep(args);
+    const stripped = stripUntrustedDeep(args);
+    // A named-form object (#173) only arrives for the window keys, which no positional branch below touches.
+    const cleanArgs = Array.isArray(stripped) ? stripped : [];
     // #18: the *.query / *.count ops take a params bag whose `filter` top-level shape is refused
     // pre-request (zero wire on a refused shape).
     if (operation.endsWith('.query') || operation.endsWith('.count')) {
@@ -249,7 +251,7 @@ export async function readOneItem(ctx, operation, args, signal) {
                 cleanArgs[0] = { ...bag, labels: true };
         }
     }
-    const result = await ctx.ops.invokeRead(ctx.client, operation, cleanArgs, undefined, signal);
+    const result = await ctx.ops.invokeRead(ctx.client, operation, Array.isArray(stripped) ? cleanArgs : stripped, undefined, signal);
     if (result === undefined)
         return { aborted: true, result: undefined };
     const post = READ_POSTPROCESS[operation];

package/dist/tools/meta.js

@@ -16,15 +16,16 @@
  * fail-closed refusal, then the work, with the SDK error contract mapped on failure.
  */
 import { AutotaskConfigError } from 'node-autotask';
+import { foldFlattenedOpts } from 'node-autotask/operations';
 import { CATALOG, SDK_VERSION, TOOL_NAME_BY_OP, opsForTool, recordById, servedToolName, untrustedFieldsOf } from './catalog-data.js';
 import { releaseClientOnError } from './context.js';
-import { abortedAnswer, InputInvalidError, readOneItem, requestSecrets } from './dispatch.js';
+import { abortedAnswer, InputInvalidError, NeedsInputError, readOneItem, requestSecrets } from './dispatch.js';
 import { zoneClock } from './clock.js';
 import { crossResourceUntrusted, honestReadError, markResult, ok, typedErrorPayload } from './results.js';
 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, WINDOW_KEYS, WINDOW_OPS, 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 +251,13 @@ async function guidanceFor(ctx, rec, reachable) {
             example: `autotask_read {operation:"${rec.id}", args:[{filter:[{field:"id",op:"gt",value:0}],limit:10}]}`,
         };
     }
+    if (WINDOW_OPS.includes(rec.id)) {
+        // #173: the flat named form, for clients that cannot send the mixed positional [from, to, opts]
+        return {
+            namedInputs: 'from, to (YYYY-MM-DD dateWorked days, inclusive; never UTC-converted), posted, limit, ticketID, resourceID (numbers) as top-level autotask_read fields instead of args; same result and truncated flag. tz is not offered: it does not shift dateWorked.',
+            example: `autotask_read {operation:"${rec.id}", from:"2026-10-20", to:"2026-10-22", resourceID:123}`,
+        };
+    }
     if (op === 'moveToTicket') {
         // the move ops (#107): zero wire, a pointer to the governed path
         return {
@@ -307,6 +315,28 @@ async function describeRecord(ctx, operation, viaTool) {
         ...(names !== undefined ? { paramNames: names } : {}),
     });
 }
+/**
+ * #173: the window keys' flat named inputs, folded by the SDK (`foldFlattenedOpts`) into its named
+ * invoke form `{ from, to, opts }`; undefined when none is given (the positional call, unchanged).
+ * Refused before any request: a named input on any other key or in the items form, together with
+ * positional args, or without from and to.
+ */
+function windowNamedArgs(ctx, args) {
+    const named = Object.fromEntries(WINDOW_KEYS.filter((k) => args[k] !== undefined).map((k) => [k, args[k]]));
+    const first = Object.keys(named)[0];
+    if (first === undefined)
+        return undefined;
+    const op = args.operation;
+    if (op === undefined || !WINDOW_OPS.includes(op)) {
+        throw new InputInvalidError(`read: ${first} is a named input of ${WINDOW_OPS.join(' and ')} only (with operation); other reads take args`, first);
+    }
+    if (args.args.length > 0)
+        throw new InputInvalidError(`read: ${op} takes named inputs or args, not both`, 'args');
+    const missing = ['from', 'to'].filter((k) => named[k] === undefined);
+    if (missing.length > 0)
+        throw new NeedsInputError(`read: ${op} needs both from and to (YYYY-MM-DD) with its named inputs`, missing[0], missing.map((k) => `/${k}`));
+    return foldFlattenedOpts(ctx.record(op), named);
+}
 /** `autotask_read`: one read by exact key, or up to 10 (`items`) with per-item results. */
 export function buildRead(ctx) {
     return {
@@ -317,8 +347,9 @@ export function buildRead(ctx) {
             if ((args.operation === undefined) === (args.items === undefined)) {
                 throw new InputInvalidError('read: pass exactly one of operation (with args) or items', 'operation');
             }
+            const named = windowNamedArgs(ctx, args); // before the branch: a named input beside items is refused, never ignored
             if (args.operation !== undefined) {
-                const out = await readOneItem(ctx, args.operation, args.args, signal);
+                const out = await readOneItem(ctx, args.operation, named ?? args.args, signal);
                 if (out.aborted)
                     return abortedAnswer(ctx.correlationId);
                 // The server-side note (issue #56: the profitability window default applied) rides the

package/dist/tools/schemas.d.ts

@@ -210,13 +210,26 @@ export declare const DESCRIBE_INPUT: z.ZodObject<{
     resource: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const READ_MAX_ITEMS = 10;
+/**
+ * #173: the two time-entry window keys also take flat, typed named inputs (the SDK's own names,
+ * as its MCP projection serves them), because a client that cannot send a mixed-type array cannot
+ * send their positional `[from, to, opts]`. `tz` is left out: it does not shift a dateWorked day.
+ */
+export declare const WINDOW_OPS: readonly string[];
+export declare const WINDOW_KEYS: readonly ["from", "to", "posted", "limit", "ticketID", "resourceID"];
 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>;
+    from: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    to: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    posted: z.ZodPreprocess<z.ZodOptional<z.ZodBoolean>, unknown>;
+    limit: z.ZodPreprocess<z.ZodOptional<z.ZodNumber>, unknown>;
+    ticketID: z.ZodPreprocess<z.ZodOptional<z.ZodNumber>, unknown>;
+    resourceID: z.ZodPreprocess<z.ZodOptional<z.ZodNumber>, unknown>;
 }, z.core.$strip>;
 export declare const RESOLVE_INPUT: z.ZodObject<{
     identifier: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;

package/dist/tools/schemas.js

@@ -203,10 +203,30 @@ 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;
+/**
+ * #173: the two time-entry window keys also take flat, typed named inputs (the SDK's own names,
+ * as its MCP projection serves them), because a client that cannot send a mixed-type array cannot
+ * send their positional `[from, to, opts]`. `tz` is left out: it does not shift a dateWorked day.
+ */
+export const WINDOW_OPS = ['time_entries.dateWorkedWindow', 'time_entries.postedWithin'];
+export const WINDOW_KEYS = ['from', 'to', 'posted', 'limit', 'ticketID', 'resourceID'];
+/**
+ * An autotask_read input sent as null or '' is absent: form-filling clients (Copilot Studio) can
+ * send every unset optional that way, e.g. args: null beside the named window inputs. The advertised schema stays the plain scalar (no null union).
+ */
+const unset = (schema) => z.preprocess((v) => (v === null || v === '' ? undefined : v), schema);
 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.'),
+    // One description for the set: every served byte counts against the readonly-core budget. The SDK
+    // refuses a from/to that is not a real YYYY-MM-DD day, naming it, before any request.
+    from: unset(z.string().optional()).describe('time_entries.dateWorkedWindow/postedWithin only, instead of args: from, to are YYYY-MM-DD dateWorked days (inclusive); also posted, limit, ticketID, resourceID.'),
+    to: unset(z.string().optional()),
+    posted: unset(z.boolean().optional()),
+    limit: unset(z.number().int().min(1).optional()),
+    ticketID: unset(z.number().int().nonnegative().optional()),
+    resourceID: unset(z.number().int().nonnegative().optional()),
 });
 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.14.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.14.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.14.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.14.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.14.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

@@ -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_read:time_entries.dateWorkedWindow", "autotask_read:time_entries.postedWithin"]
 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)"]
@@ -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 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"). For a time entry window use the named form instead of args, all flat scalars: `autotask_read {operation:"time_entries.dateWorkedWindow", from:"2026-10-20", to:"2026-10-22", resourceID:<resource id>}` (also posted, limit, ticketID; resourceID and ticketID are numbers; the same for time_entries.postedWithin). It returns the same rows, counts and truncated flag as the positional call; from and to are inclusive YYYY-MM-DD dateWorked days, never UTC-converted, and there is no tz input (tz does not shift dateWorked). The server and SDK pass filter values through unchanged; string dates and ids are confirmed to work, other types are not verified on every field.
 
 ## Guardrails
 
@@ -68,4 +68,6 @@ 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_read | time_entries.dateWorkedWindow | read | from, to |
+| autotask_read | time_entries.postedWithin | read | from, to |
 <!-- generated:end -->