iit-mcp-autotask 0.38.2 → 0.38.3

package/README.md

@@ -47,7 +47,9 @@ examples; `full: true` serves the complete record, `summary: true` about 2 KB),
   `time_off_requests`, `companies`, `billing_items`, ...; limit default 50, max 2500). With
   `group_by`, `sum` or `count: true` it answers totals instead of rows (the SDK's
   `operations.aggregate`; `top` 1-100 groups, `limit` up to 2,500 scanned rows; `hasMore` /
-  `groupsTruncated` mean partial). Records by id: `filter: [{field: "id", op: "in", value: "1,2,3"}]`
+  `groupsTruncated` mean partial). `filter` is not schema-required (a form-filler dead-ends on a
+  required Table, #241) but a missing or empty one is refused (`INPUT_INVALID`, rows and totals);
+  `{field: "id", op: "exist"}` targets the whole entity. Records by id: `filter: [{field: "id", op: "in", value: "1,2,3"}]`
   (`in` / `notIn` take an array or a comma string). Time entries have no `companyID`: the relation
   filter `{field: "ticket.companyID", op: "eq", value: "<id>"}` (also `task.<field>`; `project.<field>`
   where the entity has the FK) scopes them through one parent read of at most 300 ids (more is a typed

package/dist/tools/lists.js

@@ -51,6 +51,12 @@ export function buildQuery(ctx) {
             if (rec === undefined || rec.effect !== 'read') {
                 throw new InputInvalidError(`query: "${args.resource}" has no ${operation} read in the registry (find the resource with autotask_catalog)`, 'resource');
             }
+            // #241: filter is optional in the advertised schema (a form-filler dead-ends on a required Table), so a missing or
+            // empty one is refused here, rows and totals alike (unscoped totals answer the wrong scope), before any wire. An
+            // INPUT_INVALID error, as when the schema required it: a model retries it; needs_input reads as "stop" (rule 3).
+            if (args.filter === undefined || (Array.isArray(args.filter) && args.filter.length === 0)) {
+                throw new InputInvalidError('query: filter is missing or empty; call again with a scope condition such as {field: "companyID", op: "eq", value: "<id>"} (time_entries: ticket.companyID), or {field: "id", op: "exist"} for the whole entity', 'filter');
+            }
             // #228: totals mode (group_by / sum / count) is the SDK's operations.aggregate over the same filter
             if (args.group_by !== undefined || args.sum !== undefined || args.count === true) {
                 const clash = ['latest', 'include_fields', 'note_chars', 'via', 'format', 'output_path', 'acknowledge_unscoped', 'untrusted_wrapper'].find((k) => args[k] !== undefined);

package/dist/tools/schemas.d.ts

@@ -40,16 +40,17 @@ export declare const COMPANY_PROFILE_PART_LIMIT_DEFAULT = 10;
  * and/or groups are accepted unchanged). 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.
  * #231: the advertised condition is explicit for strict form-fillers (one prepared a required Table
- * with no rows and sent nothing): all three keys required, `op` the 13-operator enum, and an
- * `examples` entry (a relation filter plus a UTC date bound). exist/notExist take value "", which
- * {@link normalizeFilter} drops before dispatch.
+ * with no rows and sent nothing): `op` the 13-operator enum and an `examples` entry (a relation
+ * filter plus a UTC date bound). exist/notExist take value "", which {@link normalizeFilter} drops
+ * before dispatch. #241: `filter` and a condition's `value` are not required (Copilot Studio left the
+ * required Table unfilled and asked the user); the query handler refuses a missing or empty filter.
  */
 export declare const FILTER_OPS: readonly ["eq", "noteq", "gt", "gte", "lt", "lte", "beginsWith", "endsWith", "contains", "exist", "notExist", "in", "notIn"];
 /** #234: a `<self>.<field>` name on its own resource without the prefix; any other name unchanged. */
 export declare function ownField(resource: string, name: string): string;
 /**
  * #231: drop the empty `value` a strict form-filler sends on exist/notExist (the advertised schema
- * requires one on every condition). #234: a `<self>.<field>` condition on `resource` names the own
+ * required one on every condition until #241). #234: a `<self>.<field>` condition on `resource` names the own
  * field ({@link ownField}). Everything else passes through unchanged, groups and the bag form included.
  */
 export declare function normalizeFilter(filter: unknown, resource?: string): unknown;
@@ -60,9 +61,9 @@ export declare function normalizeFilter(filter: unknown, resource?: string): unk
  * the typed CONFIG_ERROR BEFORE any request is built (zero wire). node-autotask before 0.9.0
  * silently DROPPED a bare object's conditions, so an unrefused bare object queried UNFILTERED;
  * 0.9.0 refuses it too (#83), and this server's refusal stays the zero-wire pre-request
- * guarantee. The `filter` key itself is required by `QUERY_INPUT` — a no-filter call is refused at the
- * dispatch frame before this validator runs (the served `latest` description states this); the
- * `undefined` early return remains for direct callers of the validator.
+ * guarantee. The `filter` key is optional in `QUERY_INPUT` (#241): the query handler refuses a
+ * missing or empty one (INPUT_INVALID) before this validator runs; the `undefined` early return
+ * serves autotask_read, whose `<resource>.query` params bag may omit it.
  */
 export declare function assertFilterShape(filter: unknown, operation: string): void;
 /** A registered input: the StandardSchema the SDK sees, the zod object the frame parses, the key set. */
@@ -289,7 +290,7 @@ export declare const RESOLVE_INPUT: z.ZodObject<{
 }, z.core.$strip>;
 export declare const QUERY_INPUT: z.ZodObject<{
     resource: z.ZodString;
-    filter: z.ZodUnknown;
+    filter: z.ZodOptional<z.ZodUnknown>;
     limit: z.ZodOptional<z.ZodNumber>;
     group_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sum: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/tools/schemas.js

@@ -72,21 +72,23 @@ const COMPANY_PROFILE_PART_LIMIT_LOCATIONS = z
  * and/or groups are accepted unchanged). 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.
  * #231: the advertised condition is explicit for strict form-fillers (one prepared a required Table
- * with no rows and sent nothing): all three keys required, `op` the 13-operator enum, and an
- * `examples` entry (a relation filter plus a UTC date bound). exist/notExist take value "", which
- * {@link normalizeFilter} drops before dispatch.
+ * with no rows and sent nothing): `op` the 13-operator enum and an `examples` entry (a relation
+ * filter plus a UTC date bound). exist/notExist take value "", which {@link normalizeFilter} drops
+ * before dispatch. #241: `filter` and a condition's `value` are not required (Copilot Studio left the
+ * required Table unfilled and asked the user); the query handler refuses a missing or empty filter.
  */
 export const FILTER_OPS = ['eq', 'noteq', 'gt', 'gte', 'lt', 'lte', 'beginsWith', 'endsWith', 'contains', 'exist', 'notExist', 'in', 'notIn'];
 const FILTER = z
     .unknown()
+    .optional()
     .meta({
     type: 'array',
     // op keeps type string beside the enum: a Table client types each column from `type` (#173)
-    items: { type: 'object', properties: { field: { type: 'string' }, op: { type: 'string', enum: FILTER_OPS }, value: { type: 'string' } }, required: ['field', 'op', 'value'] },
+    items: { type: 'object', properties: { field: { type: 'string' }, op: { type: 'string', enum: FILTER_OPS }, value: { type: 'string' } }, required: ['field', 'op'] },
     // one filter copied verbatim by form-fillers: the ticket relation on time_entries, the own fields on tickets (#234)
     examples: [[{ field: 'ticket.companyID', op: 'eq', value: '123' }, { field: 'ticket.createDate', op: 'gte', value: '2026-10-01T00:00:00Z' }]],
 })
-    .describe('Conditions; write every value as a string ("29", "true"; exist/notExist: ""; in/notIn: "1,2,3"). Dates: UTC ISO-8601. An unknown field name (also group_by, sum) is a pre-query CONFIG_ERROR. ticket.<field> scopes time entries by their ticket; on tickets use the plain field.');
+    .describe('Needed (missing or [] is refused). Conditions; write every value as a string ("29", "true"; exist/notExist: ""; in/notIn: "1,2,3"). Dates: UTC ISO-8601. An unknown field name (also group_by, sum) is a pre-query CONFIG_ERROR. ticket.<field> scopes time entries by their ticket; on tickets use the plain field.');
 /**
  * #234: the SDK's relation targets. On the target resource itself `<self>.` can only mean an own
  * field (none of them carries a `<self>ID`), so `ticket.companyID` on tickets is `companyID`; the SDK
@@ -100,7 +102,7 @@ export function ownField(resource, name) {
 }
 /**
  * #231: drop the empty `value` a strict form-filler sends on exist/notExist (the advertised schema
- * requires one on every condition). #234: a `<self>.<field>` condition on `resource` names the own
+ * required one on every condition until #241). #234: a `<self>.<field>` condition on `resource` names the own
  * field ({@link ownField}). Everything else passes through unchanged, groups and the bag form included.
  */
 export function normalizeFilter(filter, resource = '') {
@@ -131,9 +133,9 @@ export function normalizeFilter(filter, resource = '') {
  * the typed CONFIG_ERROR BEFORE any request is built (zero wire). node-autotask before 0.9.0
  * silently DROPPED a bare object's conditions, so an unrefused bare object queried UNFILTERED;
  * 0.9.0 refuses it too (#83), and this server's refusal stays the zero-wire pre-request
- * guarantee. The `filter` key itself is required by `QUERY_INPUT` — a no-filter call is refused at the
- * dispatch frame before this validator runs (the served `latest` description states this); the
- * `undefined` early return remains for direct callers of the validator.
+ * guarantee. The `filter` key is optional in `QUERY_INPUT` (#241): the query handler refuses a
+ * missing or empty one (INPUT_INVALID) before this validator runs; the `undefined` early return
+ * serves autotask_read, whose `<resource>.query` params bag may omit it.
  */
 export function assertFilterShape(filter, operation) {
     if (filter === undefined)
@@ -307,7 +309,7 @@ export const QUERY_INPUT = z.object({
     count: z.boolean().optional().describe('true: count the matching rows, no rows returned.'),
     top: z.number().int().min(1).max(100).optional().describe('Groups kept, 1-100 (default 25).'),
     include_fields: z.array(z.string().min(1)).optional().describe('Exact vendor field names to return (id always included); an unknown name is a pre-query CONFIG_ERROR. Absent: tickets and time_entries return default columns, others the full row.'),
-    latest: z.number().int().min(1).max(2500).optional().describe('N newest records (highest id). filter is required on this tool (a no-filter call is refused); to target the whole entity pass the tautology {field: id, op: exist}. Needs limit >= N (limit defaults to 50).'),
+    latest: z.number().int().min(1).max(2500).optional().describe('N newest records (highest id). A filter is needed on this tool (a no-filter call is refused); to target the whole entity pass the tautology {field: id, op: exist}. Needs limit >= N (limit defaults to 50).'),
     note_chars: z.number().int().min(1).optional().describe('Cap each free-text field at N characters.'),
     via: z.enum(['post', 'get']).optional().describe('Vendor transport (get caps the URL at 2048 chars).'),
     format: z.enum(['json', 'tsv']).optional().describe('tsv: the table as data.tsv, items omitted.'),

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.38.2";
+export declare const SERVER_VERSION = "0.38.3";

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.38.2';
+export const SERVER_VERSION = '0.38.3';
 //# 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.38.2";
+    readonly version: "0.38.3";
     readonly mcpProtocolBaseline: "2026-07-28";
     readonly legacyProtocolFallback: "2025-11-25";
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.38.2",
+  "version": "0.38.3",
   "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.38.2",
+  "version": "0.38.3",
   "description": "MCP server for the Autotask (Datto) PSA API, powered by the node-autotask SDK",
   "mcpProtocolBaseline": "2026-07-28",
   "legacyProtocolFallback": "2025-11-25",