iit-mcp-autotask 0.4.2 → 0.4.3

package/README.md

@@ -32,7 +32,7 @@ miss never fails the call (typed `absent`); only a missing root record fails the
 | C — dedicated workflow (23) | `autotask_ticket_query` · `autotask_ticket_full_context` · `autotask_ticket_sla_health_check` · `autotask_ticket_find_by_ticket_number` · `autotask_company_full_profile` · `autotask_timeEntry_query` · `autotask_timeEntry_create` · `autotask_quote_get` · `autotask_invoice_get` · `autotask_invoice_markup` · `autotask_configurationItem_profile` · `autotask_configurationItems_find_by_serial` · `autotask_contact_full_profile` · `autotask_contact_find_by_email` · `autotask_project_get_context` · `autotask_serviceCall_query` · `autotask_serviceCall_full_profile` · `autotask_contract_full_profile` · `autotask_contract_query` · `autotask_resource_workload` · `autotask_timeOffRequest_query` · `autotask_company_unbilled_work` · `autotask_aggregate` (names verbatim from the SDK manifest where they exist — case inconsistency included) | Bounded filtered lists, one-call composites, natural-key lookups, the single dedicated write |
 
 Machine-readable catalogue: [`capabilities.json`](capabilities.json) · server metadata: [`server.json`](server.json) ·
-per-workflow mapping: [`docs/capability-matrix.md`](docs/capability-matrix.md) · full design: [`docs/architecture.md`](docs/architecture.md).
+per-workflow mapping: [`docs/capability-matrix.md`](docs/capability-matrix.md) · full design: [`docs/architecture.md`](docs/architecture.md) · contract P&L manual recipe (the `autotask_contract_profitability` gap until it ships): [`docs/contract-economics.md`](docs/contract-economics.md).
 
 ### The 5-META generic layer
 

package/capabilities.json

@@ -539,12 +539,12 @@
     },
     {
       "id": "autotask.contract.full_profile",
-      "description": "One contract + its services (+ units) + its billing rules in a single call: parts degrade to typed absent, never a failure; the contract itself missing → NOT_FOUND. Deeper machinery (bundles, adjustments, exclusions, charges): autotask_read; a contract list: autotask_contract_query.",
+      "description": "One contract + its services + billing rules + recent charges (50 newest) + service units in one call: parts degrade to typed absent, never a failure; the contract itself missing → NOT_FOUND. Deeper machinery (bundles, adjustments, exclusions): autotask_read; contract list: autotask_contract_query.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_contract_full_profile",
       "type": "read",
       "layer": "C",
-      "backingOperation": "contracts.get + contract_services.query + contract_billing_rules.query",
+      "backingOperation": "contracts.get + contract_services.query + contract_billing_rules.query + contract_charges.query + contract_service_units.query",
       "annotations": {
         "readOnly": true,
         "idempotent": true,

package/dist/tools/catalog-data.d.ts

@@ -144,7 +144,7 @@ export declare function cacheOptionsForPreset(preset: 'on' | 'off', fieldCacheTt
  * fails the boot (or the CI test) instead of quietly shipping a tool surface that no longer
  * describes the SDK behind it.
  */
-export declare const BUILT_AGAINST_PLAN_HASH = "4c8d9f800e97c350acc681ade183f67474c044b674494eb78cd0f14a933dc1fc";
+export declare const BUILT_AGAINST_PLAN_HASH = "6547153895b65c577ef59ced6c06361d0763d1299d6048531b8ffa94f77821d3";
 /**
  * Fail fast when the installed SDK's plan has moved out from under this surface.
  * Called at boot (main.ts) and safe to call repeatedly (pure comparison).

package/dist/tools/catalog-data.js

@@ -273,7 +273,7 @@ export const TOOL_DESCRIPTIONS = {
     autotask_project_get_context: `One project with its primary context: project + company + opportunity + lead resource. Project phase/task lists do NOT exist on this surface (no such vendor operations) — do not attempt them; charges/notes ride the generic layer (autotask_read). The project record alone: autotask_project_resolve.`,
     autotask_serviceCall_query: `Query ServiceCall records with a JSON filter — the on-site visit queue. Full profile (linked tickets, tasks, assignments): autotask_serviceCall_full_profile. Assignment writes ride autotask_write. Bounded: limit default 50, max 2500. per-call options: see the server instructions.`,
     autotask_serviceCall_full_profile: `One service call + its linked tickets + its tasks (incl. resource assignments). Parts degrade to typed absent (no tasks → NO_TASKS on the assignments part); the service call itself missing → NOT_FOUND. Prefer this before on-site-visit work (assignment writes ride autotask_write).`,
-    autotask_contract_full_profile: `One contract + its services (+ units) + its billing rules in a single call: parts degrade to typed absent, never a failure; the contract itself missing → NOT_FOUND. Deeper machinery (bundles, adjustments, exclusions, charges): autotask_read; a contract list: autotask_contract_query.`,
+    autotask_contract_full_profile: `One contract + its services + billing rules + recent charges (50 newest) + service units in one call: parts degrade to typed absent, never a failure; the contract itself missing → NOT_FOUND. Deeper machinery (bundles, adjustments, exclusions): autotask_read; contract list: autotask_contract_query.`,
     autotask_contract_query: `Query Contract records with a JSON filter — e.g. active contracts for a company (the SLA & recurring-service view). One contract with its services/units/billing rules: autotask_contract_full_profile. Bounded: limit default 50, max 2500. per-call options: see the server instructions.`,
     autotask_resource_workload: `One resource's availability picture: open assigned tickets + service-call assignments + time-off balances + pending time-off requests. Parts degrade to typed absent; resource missing → NOT_FOUND. Approve/reject: autotask_write. The request list: autotask_timeOffRequest_query. Sensitive.`,
     autotask_timeOffRequest_query: `Query TimeOffRequest records with a JSON filter. Approve/reject ride autotask_write (time_off_requests.approve / .reject — dry-run-first; reject takes a reason). Availability: autotask_resource_workload. Bounded: limit default 50, max 2500. per-call options: see the server instructions.`,
@@ -339,7 +339,7 @@ export function cacheOptionsForPreset(preset, fieldCacheTtlMs) {
  * fails the boot (or the CI test) instead of quietly shipping a tool surface that no longer
  * describes the SDK behind it.
  */
-export const BUILT_AGAINST_PLAN_HASH = '4c8d9f800e97c350acc681ade183f67474c044b674494eb78cd0f14a933dc1fc';
+export const BUILT_AGAINST_PLAN_HASH = '6547153895b65c577ef59ced6c06361d0763d1299d6048531b8ffa94f77821d3';
 /**
  * Fail fast when the installed SDK's plan has moved out from under this surface.
  * Called at boot (main.ts) and safe to call repeatedly (pure comparison).

package/dist/tools/composites.js

@@ -13,7 +13,14 @@
  *
  * Parts run as bounded fan-outs over ONE pooled tenant client: the client's own concurrency
  * guard (the agent profile) bounds the in-flight vendor requests; the part list is small and
- * static per tool.
+ * static per tool. Wire budget per call: the contract profile is the widest — 1 root read + 4
+ * parts in one parallel fan-out (contract_services.query / contract_billing_rules.query /
+ * contract_charges.query / contract_service_units.query, each limit 50 → one page), EXCEPT the
+ * charges part, which rides the SDK's count-anchored `latest` 50 (the vendor has no sort
+ * parameter; newest-first = id-newest, tracking the vendor's createDate/datePurchased) — 1 count
+ * + at most 6 page POSTs while the matching set is <= 2500 rows (the SDK's full-set mode); above
+ * that the SDK spends its own id-threshold count-probe budget before a <= 6-page walk, and a
+ * blind surface takes the plain bounded walk. Common case: at most 11 vendor requests per call.
  */
 import { NotFoundError } from 'node-autotask';
 import { TICKET_FULL_CONTEXT_INPUT, COMPANY_FULL_PROFILE_INPUT, CONFIGURATION_ITEM_PROFILE_INPUT, PROJECT_GET_CONTEXT_INPUT, QUOTE_GET_INPUT, INVOICE_GET_INPUT, INVOICE_MARKUP_INPUT, CONTACT_FULL_PROFILE_INPUT, SERVICE_CALL_FULL_PROFILE_INPUT, CONTRACT_FULL_PROFILE_INPUT, RESOURCE_WORKLOAD_INPUT, UNBILLED_WORK_INPUT, AGGREGATE_INPUT, COMPOSITE_OUTPUT, resultOutput, aggregateOutput, unbilledWorkOutput, closedInput, } from './schemas.js';
@@ -25,6 +32,11 @@ import { assertSecretReadPermitted, assertWritePermitted } from '../policy.js';
 const TICKET_STATUS_CLOSED = 5;
 /** The cap on a fan-out `in` filter (the task-id join between two parts). */
 const IN_FILTER_CAP = 100;
+/** The charges part's recent-N cap (issue #49): the N newest contract charges, newest first —
+ *  served through the SDK's count-anchored `latest` (the vendor has no sort parameter). */
+const CHARGES_RECENT_CAP = 50;
+/** The units part's row cap (issue #49). */
+const SERVICE_UNITS_CAP = 50;
 /** Run one part read: a miss/fault degrades to `{ value: null, absent: code }`, never a throw. */
 async function part(ctx, op, args, signal) {
     try {
@@ -370,12 +382,13 @@ function registerServiceCallFullProfile(server, ctx) {
         },
     });
 }
-// ---- autotask_contract_full_profile: the contract, its services, its billing rules ----
+// ---- autotask_contract_full_profile: the contract, its services, its billing rules,
+// ---- its recent charges (issue #49) and its service units (issue #49) ----
 function registerContractFullProfile(server, ctx) {
     const contractInput = closedInput(CONTRACT_FULL_PROFILE_INPUT);
     registerServerComposite(ctx, server, {
         tool: 'autotask_contract_full_profile',
-        title: 'Get a contract with its services and billing rules',
+        title: 'Get a contract with its services, billing rules, recent charges and service units',
         description: ctx.description('autotask_contract_full_profile', 'contracts.get'),
         input: contractInput,
         rootOp: 'contracts.get',
@@ -383,16 +396,34 @@ function registerContractFullProfile(server, ctx) {
             const id = args.id;
             // The declared per-part limits (QUERY_LIMIT: 1-2500, default 50 — schema-validated at the
             // protocol layer); each part reads its own declared argument, not one shared phantom key.
+            // The two issue #49 parts carry NO input knobs (the closed bag is unchanged): the charges
+            // part is the FIXED recent-N and the units part the fixed row cap.
             const serviceLimit = args.service_limit ?? 50;
             const billingRuleLimit = args.billing_rule_limit ?? 50;
             const root = await c.ops.invokeRead(c.client, 'contracts.get', [id], undefined, signal);
             if (root === undefined)
                 return { root: null, rootOp: 'contracts.get', parts: {} };
-            const [services, billingRules] = await Promise.all([
+            const [services, billingRules, charges, units] = await Promise.all([
                 part(c, 'contract_services.query', [{ filter: [{ field: 'contractID', op: 'eq', value: id }], limit: serviceLimit }], signal),
                 part(c, 'contract_billing_rules.query', [{ filter: [{ field: 'contractID', op: 'eq', value: id }], limit: billingRuleLimit }], signal),
+                // The recent charges (issue #49): the vendor has NO sort parameter — the SDK's
+                // count-anchored `latest` (the N highest-id rows, id-descending) is the only ordering
+                // channel; the id order tracks the vendor's createDate/datePurchased, so newest-first
+                // is id-newest-first. limit === latest is the legal coexistence (limit >= latest) and
+                // keeps the walk window explicit (1 count + at most 6 page POSTs).
+                part(c, 'contract_charges.query', [{ filter: [{ field: 'contractID', op: 'eq', value: id }], limit: CHARGES_RECENT_CAP, latest: CHARGES_RECENT_CAP }], signal),
+                part(c, 'contract_service_units.query', [{ filter: [{ field: 'contractID', op: 'eq', value: id }], limit: SERVICE_UNITS_CAP }], signal),
             ]);
-            return { root, rootOp: 'contracts.get', parts: { services: ['contract_services.query', services], billing_rules: ['contract_billing_rules.query', billingRules] } };
+            return {
+                root,
+                rootOp: 'contracts.get',
+                parts: {
+                    services: ['contract_services.query', services],
+                    billing_rules: ['contract_billing_rules.query', billingRules],
+                    charges: ['contract_charges.query', charges],
+                    units: ['contract_service_units.query', units],
+                },
+            };
         },
     });
 }

package/dist/tools/schemas.d.ts

@@ -385,7 +385,11 @@ export declare function queryEnvelope(fields?: readonly string[]): z.ZodType;
 /** The five bounded query tools' output: the typed envelope under `result` (mirrors `resultOutput`). */
 export declare function queryEnvelopeOutput(fields?: readonly string[]): z.ZodType;
 /** A composite answer (SDK or server-built): the root record + one entry per part; a part miss
- *  is `null + absent`, never a tool failure — only a missing ROOT fails the composite. */
+ *  is `null + absent`, never a tool failure — only a missing ROOT fails the composite.
+ *  The part names are tool-specific (this shared envelope stays a record): the contract
+ *  profile serves `services` / `billing_rules` / `charges` (the recent-50 via the SDK's
+ *  count-anchored `latest`, newest first — issue #49) / `units` (issue #49), every one riding
+ *  the same value/absent envelope. */
 export declare const COMPOSITE_OUTPUT: z.ZodObject<{
     root: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
     parts: z.ZodRecord<z.ZodString, z.ZodObject<{

package/dist/tools/schemas.js

@@ -408,6 +408,8 @@ export const CONTRACT_FULL_PROFILE_INPUT = z.object({
     id: ID.describe('The numeric contract id.'),
     service_limit: QUERY_LIMIT,
     billing_rule_limit: QUERY_LIMIT,
+    // issue #49: the two new parts (charges — the FIXED recent-50 via the SDK's `latest`; units —
+    // the fixed 50-row cap) carry NO input keys: the closed bag above is unchanged.
 });
 export const RESOURCE_WORKLOAD_INPUT = z.object({
     id: ID.describe('The numeric resource id.'),
@@ -588,7 +590,11 @@ export function queryEnvelopeOutput(fields = []) {
     return z.object({ result: queryEnvelope(fields) });
 }
 /** A composite answer (SDK or server-built): the root record + one entry per part; a part miss
- *  is `null + absent`, never a tool failure — only a missing ROOT fails the composite. */
+ *  is `null + absent`, never a tool failure — only a missing ROOT fails the composite.
+ *  The part names are tool-specific (this shared envelope stays a record): the contract
+ *  profile serves `services` / `billing_rules` / `charges` (the recent-50 via the SDK's
+ *  count-anchored `latest`, newest first — issue #49) / `units` (issue #49), every one riding
+ *  the same value/absent envelope. */
 export const COMPOSITE_OUTPUT = z.object({
     root: dataField('The root record (a missing root fails the call with the typed vendor error).'),
     parts: z

package/dist/tools/server.d.ts

@@ -24,7 +24,7 @@ import type { Config } from '../config.js';
 import type { Logger } from '../logger.js';
 /** The wire identity of this server (the initialize answer + the `/metadata` payload). */
 export declare const SERVER_NAME = "iit-mcp-autotask";
-export declare const SERVER_VERSION = "0.4.2";
+export declare const SERVER_VERSION = "0.4.3";
 export declare const SERVER_TITLE = "Autotask MCP Server";
 /**
  * The MCP protocol era this server advertises (the `/metadata` stamp, both levels).
@@ -62,7 +62,7 @@ export declare const SERVER_INSTRUCTIONS: string;
 /** 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.4.2";
+    readonly version: "0.4.3";
     readonly mcpProtocolBaseline: "2026-07-28";
     readonly legacyProtocolFallback: "2025-11-25";
 };

package/dist/tools/server.js

@@ -27,7 +27,7 @@ import { UNTRUSTED_NOTE } from './catalog-data.js';
 import { registerTools } from './register.js';
 /** The wire identity of this server (the initialize answer + the `/metadata` payload). */
 export const SERVER_NAME = 'iit-mcp-autotask';
-export const SERVER_VERSION = '0.4.2';
+export const SERVER_VERSION = '0.4.3';
 export const SERVER_TITLE = 'Autotask MCP Server';
 /**
  * The MCP protocol era this server advertises (the `/metadata` stamp, both levels).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "MCP server for the Autotask (Datto) PSA domain, built on the node-autotask SDK",
   "license": "MIT",
   "author": "Max Soukhomlinov",
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.2.0",
-    "node-autotask": "0.10.0",
+    "node-autotask": "0.11.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/server.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "MCP server for the Autotask (Datto) PSA API, powered by the node-autotask SDK",
   "mcpProtocolBaseline": "2026-07-28",
   "legacyProtocolFallback": "2025-11-25",
@@ -29,7 +29,7 @@
   "capabilitiesManifest": "capabilities.json",
   "sdk": {
     "package": "node-autotask",
-    "versionRange": "0.10.0"
+    "versionRange": "0.11.0"
   },
   "vendorExtensions": false
 }