node-autotask 0.8.3 → 0.10.0

package/N8N_MCP_MANIFEST.md

@@ -1,6 +1,6 @@
 # N8N MCP Manifest — node-autotask (consumer projection)
 
-<!-- GENERATED by scripts/project-n8n-mcp.mjs at 2026-10-08T18:52:16.007Z — do not hand-edit. -->
+<!-- GENERATED by scripts/project-n8n-mcp.mjs at 2026-10-11T12:48:07.196Z — do not hand-edit. -->
 
 The n8n CONSUMER projection of the capability registry: the canonical source for what the
 n8n-side MCP tools must expose. The SDK is canonical — this is a projection of it, never a
@@ -27,7 +27,7 @@ user's n8n instances; PROD is read-only for any verification).
 | `autotask_ticket_write` | write | ticket | false | false | false | true | 4 |
 | `autotask_contact` | read | contact | true | false | true | true | 10 |
 | `autotask_contact_write` | write | contact | false | false | false | true | 4 |
-| `autotask_company` | read | company | true | false | true | true | 12 |
+| `autotask_company` | read | company | true | false | true | true | 13 |
 | `autotask_company_write` | write | company | false | false | false | true | 3 |
 | `autotask_companyLocation` | read | companyLocation | true | false | true | true | 8 |
 | `autotask_companyLocation_write` | write | companyLocation | false | false | false | true | 2 |
@@ -35,12 +35,12 @@ user's n8n instances; PROD is read-only for any verification).
 | `autotask_ticketNote_write` | write | ticketNote | false | false | false | true | 2 |
 | `autotask_resource` | read | resource | true | false | true | true | 9 |
 | `autotask_resource_write` | write | resource | false | false | false | true | 2 |
-| `autotask_timeEntry` | read | timeEntry | true | false | true | true | 22 |
+| `autotask_timeEntry` | read | timeEntry | true | false | true | true | 23 |
 | `autotask_timeEntry_write` | write | timeEntry | false | false | false | true | 4 |
 
 ### `autotask_ticket` (read — ticket)
 
-> Read ticket records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for tickets: count: Count ticket records matching a JSON filter. | findByTicketNumber: Find a ticket by its ticketNumber. | fullContext: Get the full context of one ticket in a single call: the ticket, its company, contact, assigned resource and project, plus its notes, time entries, attachment metadata and (opt-in) histories — every part separately reported. | get: Get one Ticket by id. | getContext: Get a ticket with its primary context records in one call. | getEntityInfo: Get the Ticket capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the Ticket field catalog (types, picklists, required, maxLength). | getUdfInfo: Get the Ticket user-defined-field catalog. | query: Query Ticket records with a JSON filter. | resolve: Resolve a Ticket from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (title — exact match only). Returns the Ticket record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search ticket records by text (contains on the searchable fields). | slaHealthCheck: Run the SLA health check for a ticket (numeric ticket id). | summary: Get a one-call summary of a ticket (numeric ticket id). | timeline: Get the event timeline of a ticket (numeric ticket id).. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Bounded: limit default 25, max 500. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
+> Read ticket records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for tickets: count: Count ticket records matching a JSON filter. | findByTicketNumber: Find a ticket by its ticketNumber. | fullContext: Get the full context of one ticket in a single call: the ticket, its company, contact, assigned resource and project, plus its notes, time entries, attachment metadata and (opt-in) histories — every part separately reported. | get: Get one Ticket by id. | getContext: Get a ticket with its primary context records in one call. | getEntityInfo: Get the Ticket capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the Ticket field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). | getUdfInfo: Get the Ticket user-defined-field catalog. | query: Query Ticket records with a JSON filter. | resolve: Resolve a Ticket from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (title — exact match only). Returns the Ticket record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search ticket records by text (contains on the searchable fields). | slaHealthCheck: Run the SLA health check for a ticket (numeric ticket id). | summary: Get a one-call summary of a ticket (numeric ticket id). | timeline: Get the event timeline of a ticket (numeric ticket id).. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Bounded: limit default 25, max 500. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
 
 | backingOperation | verb | effect | flags | requiredArgs | purpose |
 |------------------|------|--------|-------|--------------|---------|
@@ -50,7 +50,7 @@ user's n8n instances; PROD is read-only for any verification).
 | `tickets.get` | get | read | — | id | Get one Ticket by id. |
 | `tickets.getContext` | getContext | read | — | id | Get a ticket with its primary context records in one call. |
 | `tickets.getEntityInfo` | getEntityInfo | read | — | none | Get the Ticket capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). |
-| `tickets.getFieldInfo` | getFieldInfo | read | — | none | Get the Ticket field catalog (types, picklists, required, maxLength). |
+| `tickets.getFieldInfo` | getFieldInfo | read | — | none | Get the Ticket field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). |
 | `tickets.getUdfInfo` | getUdfInfo | read | — | none | Get the Ticket user-defined-field catalog. |
 | `tickets.query` | query | read | — | none | Query Ticket records with a JSON filter. Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. |
 | `tickets.resolve` | resolve | read | — | identifier | Resolve a Ticket from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (title — exact match only). Returns the Ticket record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). |
@@ -63,18 +63,18 @@ user's n8n instances; PROD is read-only for any verification).
 
 > Write ticket records (mode: write — the registry operations with effect=write for tickets: changeStatus, create, openWithNoteAndAssign, update). Writes are dry-run first: dry_run defaults to true — the request is validated against the registry inputSchema and a DryRunResult envelope is returned; the mutating request is never issued unless the caller passes confirm (the n8n-side handler must force dry-run unless confirm is present, mirroring the SDK governor). Destructive operations are refused without the confirm flag — confirm must equal the operation key exactly (the deliberate act is the call). The n8n consumer surface excludes destructive operations by curation default (excludeDestructive); they remain available on the canonical SDK server (autotask_delete / per-op tools). By curation default (excludeDestructive) no destructive operation is included; destructive capability remains on the canonical SDK server surface. Per-operation required arguments: changeStatus [id, targetStatus]; create [data]; openWithNoteAndAssign [params]; update [id, data]. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
 
-Tool input: {"operation":{"type":"string","enum":["changeStatus","create","openWithNoteAndAssign","update"]},"id":{"type":"number | string (the ticket id — a safe integer, or a canonical integer string for ids above 2^53)"},"targetStatus":{"type":"number (must be in the ww29 status picklist — the 31 live-pinned values, max id 43; unknown → STATUS_UNKNOWN, zero wire)"},"fields":{"type":"object (optional) — extra ticket fields merged into the same PUT (the caller value wins over the node map defaults; the merge keeps every other current field)"},"data":{"type":"object","ref":"tickets body (see types)"},"params":{"type":"object — { companyID: number | string (the parent company id), title: string, priority?: number (default 3 Low), status?: number (default 1 New), queueID?: number (the node NEVER guesses a queue: omitted + vendor-500 → the typed QUEUE_REQUIRED error with the vendor message + discovery suggestedAction) }"},"note":{"type":"object (optional) — { description: string, title?: string, noteType?: number (default 1), publish?: number (default 1; integer picklist 1/2/4 — a JSON boolean 500s) }"},"assign":{"type":"object (optional) — { resourceID: number | string, roleID: number (required with resourceID) } (prechecked via resources.get BEFORE the create — RESOURCE_INVALID on missing/inactive; the resources table is blind to the API user, get is the authority)"},"dry_run":{"type":"boolean","default":true,"note":"true (the default) = the pinned DryRunResult envelope; the mutating request is never issued. The handler must force dry-run unless confirm is present."},"confirm":{"type":"string","note":"The operation key (e.g. \"tickets.create\") — its presence lifts the dry run. For destructive/approval-gated operations confirm must equal the operation key exactly; the call is refused pre-request without it."}} (required: operation)
+Tool input: {"operation":{"type":"string","enum":["changeStatus","create","openWithNoteAndAssign","update"]},"id":{"type":"number | string (the ticket id — a safe integer, or a canonical integer string for ids above 2^53)"},"targetStatus":{"type":"number (validated pre-request against the tenant's LIVE status picklist from the entity metadata when it is resolvable — a value the live picklist lacks → typed STATUS_UNKNOWN; when the metadata is unavailable the vendor's own validation decides)"},"fields":{"type":"object (optional) — extra ticket fields merged into the same PUT (the caller value wins over the node map defaults; the merge keeps every other current field)"},"data":{"type":"object","ref":"tickets body (see types)"},"params":{"type":"object — { companyID: number | string (the parent company id), title: string, priority?: number (default 3 Low), status?: number (default 1 New), queueID?: number (the node NEVER guesses a queue: omitted + vendor-500 → the typed QUEUE_REQUIRED error with the vendor message + discovery suggestedAction) }"},"note":{"type":"object (optional) — { description: string, title?: string, noteType?: number (default 1), publish?: number (default 1; integer picklist 1/2/4 — a JSON boolean 500s) }"},"assign":{"type":"object (optional) — { resourceID: number | string, roleID: number (required with resourceID) } (prechecked via resources.get BEFORE the create — RESOURCE_INVALID on missing/inactive; the resources table is blind to the API user, get is the authority)"},"dry_run":{"type":"boolean","default":true,"note":"true (the default) = the pinned DryRunResult envelope; the mutating request is never issued. The handler must force dry-run unless confirm is present."},"confirm":{"type":"string","note":"The operation key (e.g. \"tickets.create\") — its presence lifts the dry run. For destructive/approval-gated operations confirm must equal the operation key exactly; the call is refused pre-request without it."}} (required: operation)
 
 | backingOperation | verb | effect | flags | requiredArgs | purpose |
 |------------------|------|--------|-------|--------------|---------|
-| `tickets.changeStatus` | changeStatus | write | — | id, targetStatus | Move a ticket to a target status in ONE op — the node carries the ww29 status picklist + the live-discovered per-status required-field map and fills the proven-safe defaults itself (the vendor 500s when a target status has unsatisfied field requirements; the MCP LLM has no way to know the map). Dry-run first (dry_run). |
+| `tickets.changeStatus` | changeStatus | write | — | id, targetStatus | Move a ticket to a target status in ONE op — the node validates targetStatus against the tenant's LIVE status picklist (entity metadata; vendor rejection is the fallback when the metadata is unavailable) + the live-discovered per-status required-field map and fills the proven-safe defaults itself (the vendor 500s when a target status has unsatisfied field requirements; the MCP LLM has no way to know the map). Dry-run first (dry_run). |
 | `tickets.create` | create | write | — | data | Create a ticket. Dry-run first (dry_run). |
 | `tickets.openWithNoteAndAssign` | openWithNoteAndAssign | write | — | params | Open a ticket with an optional first scoped note and an optional assignment in ONE op — the node absorbs the ww29-proven create contract and the note/assignment wire choreography (6 calls today → 1). Dry-run first (dry_run). |
 | `tickets.update` | update | write | idempotent | id, data | Update a ticket. Dry-run first (dry_run). Idempotent. |
 
 ### `autotask_contact` (read — contact)
 
-> Read contact records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for contacts: count: Count contact records matching a JSON filter. (under a company) | findByEmail: Find a contact by email address. | get: Get one Contact by id. | getContext: Get a contact with its primary context records in one call. (under a company) | getEntityInfo: Get the Contact capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the Contact field catalog (types, picklists, required, maxLength). | getUdfInfo: Get the Contact user-defined-field catalog. | query: Query Contact records with a JSON filter. | resolve: Resolve a Contact from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (firstName + lastName — exact match only). Returns the Contact record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search contact records by text (contains on the searchable fields). (under a company). Bounds: Sensitive. Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Sensitive. Bounded: limit default 25, max 500. Sensitive. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
+> Read contact records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for contacts: count: Count contact records matching a JSON filter. (under a company) | findByEmail: Find a contact by email address. | get: Get one Contact by id. | getContext: Get a contact with its primary context records in one call. (under a company) | getEntityInfo: Get the Contact capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the Contact field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). | getUdfInfo: Get the Contact user-defined-field catalog. | query: Query Contact records with a JSON filter. | resolve: Resolve a Contact from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (firstName + lastName — exact match only). Returns the Contact record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search contact records by text (contains on the searchable fields). (under a company). Bounds: Sensitive. Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Sensitive. Bounded: limit default 25, max 500. Sensitive. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
 
 | backingOperation | verb | effect | flags | requiredArgs | purpose |
 |------------------|------|--------|-------|--------------|---------|
@@ -83,7 +83,7 @@ Tool input: {"operation":{"type":"string","enum":["changeStatus","create","openW
 | `contacts.get` | get | read | sensitive | parentId, id | Get one Contact by id. Sensitive. |
 | `contacts.getContext` | getContext | read | sensitive | id | Get a contact with its primary context records in one call. (under a company) Sensitive. |
 | `contacts.getEntityInfo` | getEntityInfo | read | sensitive | none | Get the Contact capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). Sensitive. |
-| `contacts.getFieldInfo` | getFieldInfo | read | sensitive | none | Get the Contact field catalog (types, picklists, required, maxLength). Sensitive. |
+| `contacts.getFieldInfo` | getFieldInfo | read | sensitive | none | Get the Contact field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). Sensitive. |
 | `contacts.getUdfInfo` | getUdfInfo | read | sensitive | none | Get the Contact user-defined-field catalog. Sensitive. |
 | `contacts.query` | query | read | sensitive | none | Query Contact records with a JSON filter. Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Sensitive. |
 | `contacts.resolve` | resolve | read | sensitive | identifier | Resolve a Contact from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (firstName + lastName — exact match only). Returns the Contact record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). Sensitive. |
@@ -104,7 +104,7 @@ Tool input: {"operation":{"type":"string","enum":["create","moveToCompany","upda
 
 ### `autotask_company` (read — company)
 
-> Read company records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for companies: count: Count company records matching a JSON filter. | fullProfile: Get everything the node knows about one company in a single call: the company record, its locations, contacts and notes, its open tickets, and its projects — every part separately reported with caps. | get: Get one Company by id. | getContext: Get a company with its primary context records in one call. | getEntityInfo: Get the Company capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the Company field catalog (types, picklists, required, maxLength). | getUdfInfo: Get the Company user-defined-field catalog. | query: Query Company records with a JSON filter. | resolve: Resolve a Company from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (companyName — exact match only). Returns the Company record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search company records by text (contains on the searchable fields). | searchByDomain: Find companies whose web address matches a domain (when no web address matches, the op falls back to matching contact emails). | searchByIdentity: Find companies by any combination of companyName / email / website identity values.. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Bounded: limit default 25, max 500. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
+> Read company records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for companies: count: Count company records matching a JSON filter. | fullProfile: Get everything the node knows about one company in a single call: the company record, its locations, contacts and notes, its open tickets, and its projects — every part separately reported with caps. | get: Get one Company by id. | getContext: Get a company with its primary context records in one call. | getEntityInfo: Get the Company capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the Company field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). | getUdfInfo: Get the Company user-defined-field catalog. | query: Query Company records with a JSON filter. | resolve: Resolve a Company from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (companyName — exact match only). Returns the Company record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search company records by text (contains on the searchable fields). | searchByDomain: Find companies whose web address matches a domain (when no web address matches, the op falls back to matching contact emails). | searchByIdentity: Find companies by any combination of companyName / email / website identity values. | unbilledWork: One call for a company's unbilled work: its posted billing items (per source), the time behind them (joined through the company's tickets and tasks — time entries carry no companyID), the per-ticket rollup, the unposted anti-join section, ex-tax totals + hours, and the billing-vs-time warnings. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Bounded: limit default 25, max 500. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
 
 | backingOperation | verb | effect | flags | requiredArgs | purpose |
 |------------------|------|--------|-------|--------------|---------|
@@ -113,13 +113,14 @@ Tool input: {"operation":{"type":"string","enum":["create","moveToCompany","upda
 | `companies.get` | get | read | — | id | Get one Company by id. |
 | `companies.getContext` | getContext | read | — | id | Get a company with its primary context records in one call. |
 | `companies.getEntityInfo` | getEntityInfo | read | — | none | Get the Company capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). |
-| `companies.getFieldInfo` | getFieldInfo | read | — | none | Get the Company field catalog (types, picklists, required, maxLength). |
+| `companies.getFieldInfo` | getFieldInfo | read | — | none | Get the Company field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). |
 | `companies.getUdfInfo` | getUdfInfo | read | — | none | Get the Company user-defined-field catalog. |
 | `companies.query` | query | read | — | none | Query Company records with a JSON filter. Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. |
 | `companies.resolve` | resolve | read | — | identifier | Resolve a Company from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (companyName — exact match only). Returns the Company record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). |
 | `companies.search` | search | read | — | query | Search company records by text (contains on the searchable fields). Bounded: limit default 25, max 500. |
 | `companies.searchByDomain` | searchByDomain | read | — | domain | Find companies whose web address matches a domain (when no web address matches, the op falls back to matching contact emails). |
 | `companies.searchByIdentity` | searchByIdentity | read | — | identity | Find companies by any combination of companyName / email / website identity values. |
+| `companies.unbilledWork` | unbilledWork | read | — | id | One call for a company's unbilled work: its posted billing items (per source), the time behind them (joined through the company's tickets and tasks — time entries carry no companyID), the per-ticket rollup, the unposted anti-join section, ex-tax totals + hours, and the billing-vs-time warnings |
 
 ### `autotask_company_write` (write — company)
 
@@ -135,14 +136,14 @@ Tool input: {"operation":{"type":"string","enum":["create","update","upsertByNam
 
 ### `autotask_companyLocation` (read — companyLocation)
 
-> Read companyLocation records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for company_locations: count: Count company location records matching a JSON filter. | get: Get one CompanyLocation by id. | getEntityInfo: Get the CompanyLocation capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the CompanyLocation field catalog (types, picklists, required, maxLength). | getUdfInfo: Get the CompanyLocation user-defined-field catalog. | query: Query CompanyLocation records with a JSON filter. | resolve: Resolve a company location from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (name — exact match only). Returns the Company location record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search company location records by text (contains on the searchable fields).. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Bounded: limit default 25, max 500. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
+> Read companyLocation records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for company_locations: count: Count company location records matching a JSON filter. | get: Get one CompanyLocation by id. | getEntityInfo: Get the CompanyLocation capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the CompanyLocation field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). | getUdfInfo: Get the CompanyLocation user-defined-field catalog. | query: Query CompanyLocation records with a JSON filter. | resolve: Resolve a company location from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (name — exact match only). Returns the Company location record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search company location records by text (contains on the searchable fields).. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Bounded: limit default 25, max 500. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
 
 | backingOperation | verb | effect | flags | requiredArgs | purpose |
 |------------------|------|--------|-------|--------------|---------|
 | `company_locations.count` | count | read | — | none | Count company location records matching a JSON filter. |
 | `company_locations.get` | get | read | — | parentId, id | Get one CompanyLocation by id. |
 | `company_locations.getEntityInfo` | getEntityInfo | read | — | none | Get the CompanyLocation capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). |
-| `company_locations.getFieldInfo` | getFieldInfo | read | — | none | Get the CompanyLocation field catalog (types, picklists, required, maxLength). |
+| `company_locations.getFieldInfo` | getFieldInfo | read | — | none | Get the CompanyLocation field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). |
 | `company_locations.getUdfInfo` | getUdfInfo | read | — | none | Get the CompanyLocation user-defined-field catalog. |
 | `company_locations.query` | query | read | — | none | Query CompanyLocation records with a JSON filter. Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. |
 | `company_locations.resolve` | resolve | read | — | identifier | Resolve a company location from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (name — exact match only). Returns the Company location record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). |
@@ -161,14 +162,14 @@ Tool input: {"operation":{"type":"string","enum":["create","update"]},"parentId"
 
 ### `autotask_ticketNote` (read — ticketNote)
 
-> Read ticketNote records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for ticket_notes: count: Count ticket note records matching a JSON filter. | get: Get one TicketNote by id. | getEntityInfo: Get the TicketNote capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the TicketNote field catalog (types, picklists, required, maxLength). | getUdfInfo: Get the TicketNote user-defined-field catalog. | query: Query TicketNote records with a JSON filter. | resolve: Resolve a ticket note from a numeric id (the direct fetch) only — this resource has no searchable text field, so a non-numeric identifier throws a config error.. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
+> Read ticketNote records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for ticket_notes: count: Count ticket note records matching a JSON filter. | get: Get one TicketNote by id. | getEntityInfo: Get the TicketNote capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the TicketNote field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). | getUdfInfo: Get the TicketNote user-defined-field catalog. | query: Query TicketNote records with a JSON filter. | resolve: Resolve a ticket note from a numeric id (the direct fetch) only — this resource has no searchable text field, so a non-numeric identifier throws a config error.. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
 
 | backingOperation | verb | effect | flags | requiredArgs | purpose |
 |------------------|------|--------|-------|--------------|---------|
 | `ticket_notes.count` | count | read | — | none | Count ticket note records matching a JSON filter. |
 | `ticket_notes.get` | get | read | — | parentId, id | Get one TicketNote by id. |
 | `ticket_notes.getEntityInfo` | getEntityInfo | read | — | none | Get the TicketNote capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). |
-| `ticket_notes.getFieldInfo` | getFieldInfo | read | — | none | Get the TicketNote field catalog (types, picklists, required, maxLength). |
+| `ticket_notes.getFieldInfo` | getFieldInfo | read | — | none | Get the TicketNote field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). |
 | `ticket_notes.getUdfInfo` | getUdfInfo | read | — | none | Get the TicketNote user-defined-field catalog. |
 | `ticket_notes.query` | query | read | — | none | Query TicketNote records with a JSON filter. Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. |
 | `ticket_notes.resolve` | resolve | read | — | identifier | Resolve a ticket note from a numeric id (the direct fetch) only — this resource has no searchable text field, so a non-numeric identifier throws a config error. |
@@ -186,14 +187,14 @@ Tool input: {"operation":{"type":"string","enum":["create","update"]},"parentId"
 
 ### `autotask_resource` (read — resource)
 
-> Read resource records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for resources: count: Count resource records matching a JSON filter. | get: Get one Resource by id. | getEntityInfo: Get the Resource capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the Resource field catalog (types, picklists, required, maxLength). | getUdfInfo: Get the Resource user-defined-field catalog. | query: Query Resource records with a JSON filter. | resolve: Resolve a resource from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (firstName + lastName — exact match only). Returns the Resource record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search resource records by text (contains on the searchable fields). | whoAmI: Identify the resource the current credentials act as.. Bounds: Sensitive. Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Sensitive. Bounded: limit default 25, max 500. Sensitive. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
+> Read resource records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for resources: count: Count resource records matching a JSON filter. | get: Get one Resource by id. | getEntityInfo: Get the Resource capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the Resource field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). | getUdfInfo: Get the Resource user-defined-field catalog. | query: Query Resource records with a JSON filter. | resolve: Resolve a resource from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (firstName + lastName — exact match only). Returns the Resource record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). | search: Search resource records by text (contains on the searchable fields). | whoAmI: Identify the resource the current credentials act as.. Bounds: Sensitive. Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Sensitive. Bounded: limit default 25, max 500. Sensitive. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
 
 | backingOperation | verb | effect | flags | requiredArgs | purpose |
 |------------------|------|--------|-------|--------------|---------|
 | `resources.count` | count | read | sensitive | none | Count resource records matching a JSON filter. Sensitive. |
 | `resources.get` | get | read | sensitive | id | Get one Resource by id. Sensitive. |
 | `resources.getEntityInfo` | getEntityInfo | read | sensitive | none | Get the Resource capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). Sensitive. |
-| `resources.getFieldInfo` | getFieldInfo | read | sensitive | none | Get the Resource field catalog (types, picklists, required, maxLength). Sensitive. |
+| `resources.getFieldInfo` | getFieldInfo | read | sensitive | none | Get the Resource field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). Sensitive. |
 | `resources.getUdfInfo` | getUdfInfo | read | sensitive | none | Get the Resource user-defined-field catalog. Sensitive. |
 | `resources.query` | query | read | sensitive | none | Query Resource records with a JSON filter. Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Sensitive. |
 | `resources.resolve` | resolve | read | sensitive | identifier | Resolve a resource from a numeric id (the direct fetch, tried first) or an exact value of its primary text field(s) (firstName + lastName — exact match only). Returns the Resource record with the numeric id for get/update/delete. Other identifier forms (e.g. an email address) are NOT tried by resolve — use the resource's dedicated lookup op where one exists (see autotask_catalog). Sensitive. |
@@ -213,15 +214,16 @@ Tool input: {"operation":{"type":"string","enum":["transferOwnership","update"]}
 
 ### `autotask_timeEntry` (read — timeEntry)
 
-> Read timeEntry records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for time_entries: count: Count time entry records matching a JSON filter. | customRange: Get time entries for an explicit dateWorked range. | get: Get one TimeEntry by id. | getEntityInfo: Get the TimeEntry capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the TimeEntry field catalog (types, picklists, required, maxLength). | getPosted: Get posted time entries (optionally for one ticket). | getUdfInfo: Get the TimeEntry user-defined-field catalog. | getUnposted: Get unposted time entries (optionally for one ticket). | last14: Get time entries for the last 14 days (rolling, dateWorked). | last24h: Get time entries for the last 24 hours (rolling, dateWorked). | last30: Get time entries for the last 30 days (rolling, dateWorked). | last7: Get time entries for the last 7 days (rolling, dateWorked). | last90: Get time entries for the last 90 days (rolling, dateWorked). | lastFullFortnight: Get time entries for the last complete fortnight. | lastFullMonth: Get time entries for the last complete calendar month. | lastFullQuarter: Get time entries for the last complete calendar quarter. | lastFullWeek: Get time entries for the last complete calendar week. | postedWithin: Get time entries worked within a UTC date window (inclusive) with the posted/unposted split, counted in one pass. | query: Query TimeEntry records with a JSON filter. | resolve: Resolve a time entry from a numeric id (the direct fetch) only — this resource has no searchable text field, so a non-numeric identifier throws a config error. | today: Get time entries for today (dateWorked = now, server date). | yesterday: Get time entries for yesterday (dateWorked = yesterday, server date).. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
+> Read timeEntry records (mode: read — effect=read operations only; zero mutating requests, ungated by design). Registry operations for time_entries: count: Count time entry records matching a JSON filter. | customRange: Get time entries for an explicit dateWorked range. | dateWorkedWindow: The clearer-named alias for time_entries.postedWithin (issue #66): the dateWorked window read with the posted/unposted split, counted in one pass — same wire, same result (incl. truncated). | get: Get one TimeEntry by id. | getEntityInfo: Get the TimeEntry capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). | getFieldInfo: Get the TimeEntry field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). | getPosted: Get posted time entries (optionally for one ticket). | getUdfInfo: Get the TimeEntry user-defined-field catalog. | getUnposted: Get unposted time entries (optionally for one ticket). | last14: Get time entries for the last 14 days (rolling, dateWorked). | last24h: Get time entries for the last 24 hours (rolling, dateWorked). | last30: Get time entries for the last 30 days (rolling, dateWorked). | last7: Get time entries for the last 7 days (rolling, dateWorked). | last90: Get time entries for the last 90 days (rolling, dateWorked). | lastFullFortnight: Get time entries for the last complete fortnight. | lastFullMonth: Get time entries for the last complete calendar month. | lastFullQuarter: Get time entries for the last complete calendar quarter. | lastFullWeek: Get time entries for the last complete calendar week. | postedWithin: Get time entries worked within an inclusive dateWorked window with the posted/unposted split, counted in one pass (the window is ON the dateWorked field — the posted narrowing is a server-side postedDate exist|notExist predicate; the counts cover the returned rows only, truncated flags the capped window). | query: Query TimeEntry records with a JSON filter. | resolve: Resolve a time entry from a numeric id (the direct fetch) only — this resource has no searchable text field, so a non-numeric identifier throws a config error. | today: Get time entries for today (dateWorked = now, server date). | yesterday: Get time entries for yesterday (dateWorked = yesterday, server date).. Bounds: Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. Errors carry the SDK error contract: code, category, retryable, operation, httpStatus, suggestedAction (the nextAction directive — follow the directive), correlationId, vendorError (when the vendor returned a response body — the deep-redacted body, host-sourced text wrapped as untrusted content when untrusted-wrapping is on); credentials never appear in an error message.
 
 | backingOperation | verb | effect | flags | requiredArgs | purpose |
 |------------------|------|--------|-------|--------------|---------|
 | `time_entries.count` | count | read | — | none | Count time entry records matching a JSON filter. |
 | `time_entries.customRange` | customRange | read | — | from, to | Get time entries for an explicit dateWorked range. |
+| `time_entries.dateWorkedWindow` | dateWorkedWindow | read | — | from, to | The clearer-named alias for time_entries.postedWithin (issue #66): the dateWorked window read with the posted/unposted split, counted in one pass — same wire, same result (incl. truncated). |
 | `time_entries.get` | get | read | — | id | Get one TimeEntry by id. |
 | `time_entries.getEntityInfo` | getEntityInfo | read | — | none | Get the TimeEntry capability metadata (canCreate/canUpdate/hasUserDefinedFields/...). |
-| `time_entries.getFieldInfo` | getFieldInfo | read | — | none | Get the TimeEntry field catalog (types, picklists, required, maxLength). |
+| `time_entries.getFieldInfo` | getFieldInfo | read | — | none | Get the TimeEntry field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog). |
 | `time_entries.getPosted` | getPosted | read | — | none | Get posted time entries (optionally for one ticket). |
 | `time_entries.getUdfInfo` | getUdfInfo | read | — | none | Get the TimeEntry user-defined-field catalog. |
 | `time_entries.getUnposted` | getUnposted | read | — | none | Get unposted time entries (optionally for one ticket). |
@@ -234,7 +236,7 @@ Tool input: {"operation":{"type":"string","enum":["transferOwnership","update"]}
 | `time_entries.lastFullMonth` | lastFullMonth | read | — | none | Get time entries for the last complete calendar month. |
 | `time_entries.lastFullQuarter` | lastFullQuarter | read | — | none | Get time entries for the last complete calendar quarter. |
 | `time_entries.lastFullWeek` | lastFullWeek | read | — | none | Get time entries for the last complete calendar week. |
-| `time_entries.postedWithin` | postedWithin | read | — | from, to | Get time entries worked within a UTC date window (inclusive) with the posted/unposted split, counted in one pass. |
+| `time_entries.postedWithin` | postedWithin | read | — | from, to | Get time entries worked within an inclusive dateWorked window with the posted/unposted split, counted in one pass (the window is ON the dateWorked field — the posted narrowing is a server-side postedDate exist|notExist predicate; the counts cover the returned rows only, truncated flags the capped window). |
 | `time_entries.query` | query | read | — | none | Query TimeEntry records with a JSON filter. Bounded: server-side pagination — up to limit records (default 500, max 2500) in one call; 1000-page guard; hasMore flags a truncation. |
 | `time_entries.resolve` | resolve | read | — | identifier | Resolve a time entry from a numeric id (the direct fetch) only — this resource has no searchable text field, so a non-numeric identifier throws a config error. |
 | `time_entries.today` | today | read | — | none | Get time entries for today (dateWorked = now, server date). |
@@ -267,19 +269,19 @@ only via a recorded change to `n8n-mcp.curation.json`.
 
 ## Stats
 
-- registryRecords: 1183
+- registryRecords: 1212
 - curatedEntities: 7
 - includedEntities: 7
 - readTools: 7
 - writeTools: 7
 - totalTools: 14
-- readOperations: 82
+- readOperations: 84
 - writeOperations: 21
 - approvalGatedWrites: 2
 - destructiveExcluded: 3
 
 ## Meta
 
-- generatedAt: 2026-10-08T18:52:16.007Z
-- capabilitiesHash: 153785c8af9ef250fbe8854f9de36e2d54eeeb46b24955177c243a5a4afc417a
+- generatedAt: 2026-10-11T12:48:07.196Z
+- capabilitiesHash: 2f15d1ed249cebb21175ed8ef078d89a13fbe04aa7fe6b2d3c5d00d468a80b00
 - curationHash: e19117ce73e38d9aded3be7e7f077a4e185d2e10294622b76c17d67f63cf9e3b

package/README.md

@@ -54,11 +54,16 @@ const companies = await autotask.companies.queryBounded({
   filter: [{ field: 'companyName', op: 'contains', value: 'acme' }],
   limit: 10,
   // includeFields: ['id', 'companyName'],
+  // fieldsPreset: 'billing_join',  // a closed includeFields preset (not with includeFields)
+  // latest: 5,                     // the 5 highest-id rows (count-anchored)
+  // noteChars: 500,                // cap long free-text fields (marked when cut)
+  // A filter that is not a conditions array or { filter: [...] } is refused
+  // pre-request (typed AutotaskConfigError, zero wire) — never silently dropped.
 });
 
 // 3. Resolve — bare value: numeric id, then exact match on the primary text field.
 //    Miss: numeric id throws NotFoundError; non-match returns null; ambiguity throws
-//    ResolutionError (candidates in resourceIds); cap-tripped scan throws
+//    ResolutionError (candidates in resourceIds); cap-tripped scan (only with `resolution.scanOnMiss`) throws
 //    ResolutionError (RESOLUTION_TRUNCATED) — never a silent null.
 const company = await autotask.companies.resolve(companies.items[0]!.id);
 
@@ -280,8 +285,11 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
      dropped); the process env credentials are IGNORED (no env fallback);
      one pooled `AutotaskClient` per credential tuple (`node-autotask/pool`),
      with a bounded (2 s) warm-up per tenant before serving; the pooled
-     gateway clients force the read-through cache on (`ttlMs: 5 min`) so a
-     tenant's repeated single-record reads stay cheap across requests.
+     gateway clients run with the read-through cache on (`ttlMs: 5 min` —
+     the SDK default since issue #80; the examples keep sending it
+     explicitly until the server 0.2.0 preset work, after which they can
+     send nothing) so a tenant's repeated single-record reads stay cheap
+     across requests.
    Both MCP servers share `examples/mcp-register.ts` (one registration code
    path: manifest descriptions, zod v4 schemas, annotations derived from
    `effect` + `flags`, the mode-enforced `autotask_read` / `autotask_write` /
@@ -303,7 +311,7 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
    whose MCP annotation is `readOnlyHint !== true` — today exactly **254
    tools**: the 252 dedicated write/delete tools (198 `effect=write` + 54
    `effect=destructive`, every one of them has a dedicated tool) +
-   `autotask_write` + `autotask_delete`. The remaining **571 tools** (the 558
+   `autotask_write` + `autotask_delete`. The remaining **600 tools** (the 587
    dedicated read tools + the 10 core read tools + `autotask_read` +
    `autotask_catalog` + `autotask_describe`) all carry `readOnlyHint: true`
    and are safe ungated: every op they can route is `effect=read` (zero