iit-mcp-autotask 0.4.2 → 0.5.0

package/README.md

@@ -3,21 +3,21 @@
 MCP server for the Autotask (Datto) PSA domain, built on the [`node-autotask`](https://www.npmjs.com/package/node-autotask) SDK.
 
 It is an **AI-facing capability layer over the SDK** — not a raw SDK passthrough: a minimal, task-oriented
-tool surface (41 tools) anchored to ten confirmed MSP workflows, composites that collapse multi-read
+tool surface (42 tools) anchored to ten confirmed MSP workflows, composites that collapse multi-read
 context into one call, a generic capability layer for the long tail, bounded responses, predictable
 schemas, strong security boundaries, and predictable per-tenant in-process state (pooled client +
 SDK-owned TTL caches).
 
-> **Package status (2026-10-12):** the runtime dependency `node-autotask` is published to public npm
-> at `0.10.0`; the committed `pnpm-lock.yaml` pins that
+> **Package status (2026-10-16):** the runtime dependency `node-autotask` is published to public npm
+> at `0.13.0`; the committed `pnpm-lock.yaml` pins that
 > release with its integrity hash, so installs resolve deterministically. The dependency is always npm
-> (node-autotask pinned exactly at `0.10.0`) — never a `file:`, `git:`, `link:` or workspace reference
+> (node-autotask pinned exactly at `0.13.0`) — never a `file:`, `git:`, `link:` or workspace reference
 > to a local checkout.
 
 ## Tool surface
 
-41 tools: **13 platform/discovery** (Layer A) + **5 workflow-resource resolves** (Layer B) +
-**23 dedicated workflow tools** (Layer C). Every other operation in the SDK's 1,212-operation
+42 tools: **13 platform/discovery** (Layer A) + **5 workflow-resource resolves** (Layer B) +
+**24 dedicated workflow tools** (Layer C). Every other operation in the SDK's 1,213-operation
 registry stays reachable through the **generic capability layer** — never pre-registered.
 
 Composites bound **each part independently**: every part reads its own declared limit argument
@@ -29,17 +29,17 @@ miss never fails the call (typed `absent`); only a missing root record fails the
 |-------|-------|------|
 | A — platform & discovery (13) | `autotask_catalog` · `autotask_describe` · `autotask_read` · `autotask_write` · `autotask_delete` · `autotask_resource_who_am_i` · `autotask_version` · `autotask_threshold_information` · `autotask_resolve_any` · `autotask_search_across_resources` · `autotask_fetch_many` · `autotask_read_batch` · `autotask_relationship_map` | The five **META** dispatchers + tenant identity + cross-resource helpers |
 | B — workflow resolves (5) | `autotask_company_resolve` · `autotask_configurationItems_resolve` · `autotask_contact_resolve` · `autotask_project_resolve` · `autotask_ticket_resolve` | Numeric-id-or-exact-name resolution for the five SDK workflow resources |
-| 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 |
+| C — dedicated workflow (24) | `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_contract_profitability` · `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 (`autotask_contract_profitability` first; the manual recipe behind it): [`docs/contract-economics.md`](docs/contract-economics.md).
 
 ### The 5-META generic layer
 
 The five META tools are the SDK's own live-verified governance layer, adopted verbatim (a recorded
 decision — see `docs/architecture.md` §2.5):
 
-- `autotask_catalog` — list registry operations (bounded: limit default 41 / max 500, tier + effect + `q` (key+purpose substring) + `resource` filters; `compact` reduced rows). Policy-refused writes are hidden by default (the output carries `hidden_refused: N`); `show_refused: true` lists them with their `policyReason`.
+- `autotask_catalog` — list registry operations (bounded: limit default 42 / max 500, tier + effect + `q` (key+purpose substring) + `resource` filters; `compact` reduced rows). Policy-refused writes are hidden by default (the output carries `hidden_refused: N`); `show_refused: true` lists them with their `policyReason`.
 - `autotask_describe` — exact input/output schema + examples + error codes for one operation by key.
 - `autotask_read` — route any `effect=read` operation by **exact registry key** (the 363 metadata-trio
   reads with no dedicated tool ride here). Read-only by construction; a write/delete routed here is
@@ -447,7 +447,7 @@ Full control set: `.squad/security.md` (S1–S13, blocking B1–B9, decisions D-
 
 ## SDK dependency
 
-`iit-mcp-autotask` depends on **`node-autotask` from npm at exactly `0.10.0`** (an exact pin —
+`iit-mcp-autotask` depends on **`node-autotask` from npm at exactly `0.13.0`** (an exact pin —
 no range operator; subpaths `.` / `/capabilities` / `/operations` / `/resources` / `/types` /
 `/pool`) — the only **vendor** dependency; the other two runtime dependencies are
 `@modelcontextprotocol/server` (the MCP framework) and `zod` (schema validation). It never
@@ -457,7 +457,7 @@ user — the published tarball ships no lockfile) must resolve to the release th
 reviewed against, or the plan-hash boot check refuses to start.
 
 **Publishing `node-autotask` is the maintainer's action, done manually.** It is published on the
-public registry at `0.10.0` (published 2026-10-11); the
+public registry at `0.13.0` (published 2026-10-16); the
 exact pin and the committed `pnpm-lock.yaml` (with `pnpm-workspace.yaml`) pin the real published
 tarball with its integrity hash, so installs resolve to exactly that release — the lockfile
 freezes the pnpm/git/Docker paths, the pin freezes the npm/npx paths. The docs are written against this
@@ -550,7 +550,7 @@ physical assets (Autotask models them as Configuration Items — covered).
 
 | # | Item | Status |
 |---|------|--------|
-| B1 | **Project phase & task lists** (W7 sub-capability): no `project_tasks`/`project_phases` operations in the SDK's 1,212-op registry. W7 ships with project status + context; phase/task lists excluded and documented. Classification (SDK gap vs vendor API-version limit) is decided by recon's spec-side check (A2). | blocked — documented |
+| B1 | **Project phase & task lists** (W7 sub-capability): no `project_tasks`/`project_phases` operations in the SDK's 1,213-op registry. W7 ships with project status + context; phase/task lists excluded and documented. Classification (SDK gap vs vendor API-version limit) is decided by recon's spec-side check (A2). | blocked — documented |
 | B2 | **Time-entry writes on ww29/australia-nz for API-only users**: vendor 500 (live-verified). `autotask_timeEntry_create` works where the API user is a real resource; the wall is documented in the tool description so agents don't loop. | zone limitation |
 | B3 | **`time_entries.getPosted`/`getUnposted` 500 on ww29** (no posted-state filter on the zone's entity). Reachable via the generic layer; `postedWithin` is the zone-robust alternative. | zone limitation |
 | B4 | **CI create on tenants without products** (ww29 product wall: `products.count = 0`): `configuration_items.create` requires an existing `productID`. No dedicated CI-create in v1; the wall is documented on the generic side. | zone limitation |

package/capabilities.json

@@ -1,18 +1,18 @@
 {
   "version": "0.3.0",
   "domain": "autotask",
-  "description": "Machine-readable capability catalogue for iit-mcp-autotask: the 41 exposed MCP tools only. Intentionally omitted SDK operations do NOT appear here; they remain reachable through the generic capability layer (autotask_catalog / autotask_describe / autotask_read / autotask_write / autotask_delete) and are documented in docs/capability-matrix.md.",
-  "exposedToolCount": 41,
+  "description": "Machine-readable capability catalogue for iit-mcp-autotask: the 42 exposed MCP tools only. Intentionally omitted SDK operations do NOT appear here; they remain reachable through the generic capability layer (autotask_catalog / autotask_describe / autotask_read / autotask_write / autotask_delete) and are documented in docs/capability-matrix.md.",
+  "exposedToolCount": 42,
   "layerLegend": {
     "A": "platform & discovery (13: 5 META dispatchers + 3 identity + 5 cross-resource helpers)",
     "B": "workflow-resource resolves (5: the SDK's R4 core tier)",
-    "C": "dedicated workflow tools (23: 1:1 registry reads, composites, one write)"
+    "C": "dedicated workflow tools (24: 1:1 registry reads, composites, one write)"
   },
   "naming": "Tool names for 1:1 registry operations are the SDK manifest names verbatim, case inconsistency included (a recorded decision; SDK finding F2). Server-built composites carry the approved architecture names (docs/architecture.md section 3.3); per the Lead-ratified rename (2026-10-06, Description phase) the service-call composite is `autotask_serviceCall_full_profile`, so the W8 pair (`autotask_serviceCall_query` + `autotask_serviceCall_full_profile`) now follows the manifest's camelCase entity convention.",
   "capabilities": [
     {
       "id": "autotask.platform.catalog",
-      "description": "List capability registry rows: key, tool, purpose, effect, policy verdict (reachable/policyReason). Filters: q (key+purpose substring), resource, tier, effect; compact: key/tool/effect/reachable. Refused writes hidden by default (hidden_refused; show_refused lists them). limit default 41, max 500.",
+      "description": "List capability registry rows: key, tool, purpose, effect, policy verdict (reachable/policyReason). Filters: q (key+purpose substring), resource, tier, effect; compact: key/tool/effect/reachable. Refused writes hidden by default (hidden_refused; show_refused lists them). limit default 42, max 500.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_catalog",
       "type": "read",
@@ -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 + services + billing rules + recent charges (50 newest) + service units in one call: parts degrade to typed absent; contract missing → NOT_FOUND. P&L / profitable?: autotask_contract_profitability. Deeper (bundles, adjustments, exclusions): autotask_read; 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,
@@ -613,6 +613,20 @@
         "destructive": false
       }
     },
+    {
+      "id": "autotask.contract.profitability",
+      "description": "Contract P&L by month: profit, margin, revenue (recurring/T&M/charges), break-even, unbilled/unposted time, Block Hours included hours, warnings. Args: id, date_from/date_to (default last 12 months), include_rows. Internal-currency billing-period (start-month) money; parts degrade to typed absent.",
+      "mcpPrimitive": "tool",
+      "toolName": "autotask_contract_profitability",
+      "type": "read",
+      "layer": "C",
+      "backingOperation": "contracts.profitability",
+      "annotations": {
+        "readOnly": true,
+        "idempotent": true,
+        "destructive": false
+      }
+    },
     {
       "id": "autotask.discovery.aggregate",
       "description": "Fold a query surface into groups/sums/totals or count it (the count endpoint). operation = an EXACT plan .query op (others refused); filter (grammar; empty array = unfiltered: a 0 on a blind surface is marked blind: true); group_by / sum / top / limit: server instructions. Read op; zero mutating.",
@@ -637,8 +651,8 @@
       "autotask_write",
       "autotask_delete"
     ],
-    "backingRegistryOperations": 1212,
-    "projectedSdkTools": 849,
+    "backingRegistryOperations": 1213,
+    "projectedSdkTools": 850,
     "note": "The five effect-split SDK META dispatchers are the v1 generic layer (decision, architecture section 2.5): registered exact registry operation keys only, effect-segregated dispatch, dry-run-first writes, confirm-governed deletes, pre-request cross-mode refusal. The ~1,145 non-exposed operations remain discoverable (catalog/describe) and reachable (read/write/delete) — nothing is a silent gap."
   },
   "schemas": {}

package/dist/mocks/fixture-ops.d.ts

@@ -4,7 +4,7 @@
  *
  * `defaultToolOps` binds the real `node-autotask/operations` in exactly one
  * place (`tools/context.ts`); this bundle implements the same `ToolOps`
- * interface against in-memory fixtures. The 41 tool handlers are driven
+ * interface against in-memory fixtures. The 42 tool handlers are driven
  * unchanged through the same MCP protocol path — no handler carries a mock
  * branch, so a test that passes here proves the handler layer, the shared
  * call frame, the policy gates and the error mapping; the vendor itself is

package/dist/mocks/harness.js

@@ -4,7 +4,7 @@
  * Mirrors the production per-request factory glue exactly (the header read,
  * the scope resolution, the deps bundle, the per-serving-unit `McpServer`)
  * with ONE substitution: the `ToolOps` bundle is injectable. `mockOps` mode
- * drives all 41 tools through the real MCP protocol path against a
+ * drives all 42 tools through the real MCP protocol path against a
  * fixture-backed ops bundle (zero vendor calls by construction); `wire` mode
  * runs the production `createMcpServerFactory` with the real SDK ops bundle
  * and the global-fetch wire mock (the real `AutotaskClient` + pool run

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

@@ -59,7 +59,7 @@ export declare function recordById(operation: string): CapabilityRecord | undefi
  * `autotask_read` / `autotask_write` / `autotask_delete` by exact key, never a dead name).
  */
 export declare const TOOL_NAME_BY_OP: Readonly<Record<string, string>>;
-/** Every tool name this server registers (Layer A 13 + Layer B 5 + Layer C 23 = 41). */
+/** Every tool name this server registers (Layer A 13 + Layer B 5 + Layer C 24 = 42). */
 export declare const REGISTERED_TOOL_NAMES: readonly string[];
 /** The META tools' names (the five platform dispatchers). */
 export declare const META_TOOL_NAMES: readonly string[];
@@ -81,7 +81,7 @@ export declare const UNTRUSTED_NOTE = "Externally-sourced free text in the resul
 export declare function untrustedFieldsOf(rec: CapabilityRecord): string[];
 /**
  * The per-tool description budget (issue #10 item (a): every served tool description
- * <= ~300 chars — the cap pin in test/unit/catalog-data.test.ts enforces it over all 41).
+ * <= ~300 chars — the cap pin in test/unit/catalog-data.test.ts enforces it over all 42).
  */
 export declare const MAX_DESCRIPTION_CHARS = 300;
 /**
@@ -99,11 +99,11 @@ export declare const MAX_DESCRIPTION_CHARS = 300;
  * thin-composite closed bags) rides the `instructions`' recipes and the tool input schemas
  * (autotask_describe's surface).
  *
- * 40 of the 41 tools are pinned here (the census at the pinned base showed 38 over the
+ * 41 of the 42 tools are pinned here (the census at the pinned base showed 38 over the
  * budget); the four formerly manifest-composed tools (who_am_i, company_resolve,
  * project_resolve, relationship_map) gained entries so the budget holds for them. Tools
  * ABSENT from this map serve the manifest-composed text (override ?? purpose + the
- * mechanical bounds sentence) unchanged — 1 of the 41 (version).
+ * mechanical bounds sentence) unchanged — 1 of the 42 (version).
  */
 export declare const TOOL_DESCRIPTIONS: Readonly<Record<string, string>>;
 /**
@@ -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 = "bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14";
 /**
  * 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

@@ -9,7 +9,7 @@
  * - `MCP_TOOL_OVERRIDES.json` — the curation deltas (ALL `field: description`): when-to-call
  *   hints and the zone-labelled wall pins. Applied exactly as the SDK's projector applies them,
  *   so the served descriptions equal the manifest's (the drift gate moves with the plan hash);
- * - the compiled capability registry (`node-autotask/capabilities`) — the 1,212-operation
+ * - the compiled capability registry (`node-autotask/capabilities`) — the 1,213-operation
  *   records the SDK's own invoke governor resolves against.
  *
  * The two JSON files are NOT behind the package's `exports` map (only `.` / `./capabilities` /
@@ -51,7 +51,7 @@ export function recordById(operation) {
     return RECORD_BY_ID.get(operation);
 }
 // ---------------------------------------------------------------------------
-// The 41-tool surface: server tool names per backing operation
+// The 42-tool surface: server tool names per backing operation
 // ---------------------------------------------------------------------------
 /**
  * The server tool that serves each backing operation.
@@ -103,9 +103,10 @@ export const TOOL_NAME_BY_OP = {
     'resources.get': 'autotask_resource_workload',
     'time_off_requests.query': 'autotask_timeOffRequest_query',
     'companies.unbilledWork': 'autotask_company_unbilled_work',
+    'contracts.profitability': 'autotask_contract_profitability',
     'operations.aggregate': 'autotask_aggregate',
 };
-/** Every tool name this server registers (Layer A 13 + Layer B 5 + Layer C 23 = 41). */
+/** Every tool name this server registers (Layer A 13 + Layer B 5 + Layer C 24 = 42). */
 export const REGISTERED_TOOL_NAMES = [
     // Layer A — platform & discovery (13)
     'autotask_catalog',
@@ -127,7 +128,7 @@ export const REGISTERED_TOOL_NAMES = [
     'autotask_contact_resolve',
     'autotask_project_resolve',
     'autotask_ticket_resolve',
-    // Layer C — dedicated workflow tools (23)
+    // Layer C — dedicated workflow tools (24)
     'autotask_ticket_query',
     'autotask_ticket_full_context',
     'autotask_ticket_sla_health_check',
@@ -150,6 +151,7 @@ export const REGISTERED_TOOL_NAMES = [
     'autotask_resource_workload',
     'autotask_timeOffRequest_query',
     'autotask_company_unbilled_work',
+    'autotask_contract_profitability',
     'autotask_aggregate',
 ];
 const REGISTERED = new Set(REGISTERED_TOOL_NAMES);
@@ -219,7 +221,7 @@ function boundsSentence(rec) {
 }
 /**
  * The per-tool description budget (issue #10 item (a): every served tool description
- * <= ~300 chars — the cap pin in test/unit/catalog-data.test.ts enforces it over all 41).
+ * <= ~300 chars — the cap pin in test/unit/catalog-data.test.ts enforces it over all 42).
  */
 export const MAX_DESCRIPTION_CHARS = 300;
 /**
@@ -237,14 +239,14 @@ export const MAX_DESCRIPTION_CHARS = 300;
  * thin-composite closed bags) rides the `instructions`' recipes and the tool input schemas
  * (autotask_describe's surface).
  *
- * 40 of the 41 tools are pinned here (the census at the pinned base showed 38 over the
+ * 41 of the 42 tools are pinned here (the census at the pinned base showed 38 over the
  * budget); the four formerly manifest-composed tools (who_am_i, company_resolve,
  * project_resolve, relationship_map) gained entries so the budget holds for them. Tools
  * ABSENT from this map serve the manifest-composed text (override ?? purpose + the
- * mechanical bounds sentence) unchanged — 1 of the 41 (version).
+ * mechanical bounds sentence) unchanged — 1 of the 42 (version).
  */
 export const TOOL_DESCRIPTIONS = {
-    autotask_catalog: `List capability registry rows: key, tool, purpose, effect, policy verdict (reachable/policyReason). Filters: q (key+purpose substring), resource, tier, effect; compact: key/tool/effect/reachable. Refused writes hidden by default (hidden_refused; show_refused lists them). limit default 41, max 500.`,
+    autotask_catalog: `List capability registry rows: key, tool, purpose, effect, policy verdict (reachable/policyReason). Filters: q (key+purpose substring), resource, tier, effect; compact: key/tool/effect/reachable. Refused writes hidden by default (hidden_refused; show_refused lists them). limit default 42, max 500.`,
     autotask_describe: `The exact input + output schema, examples, error codes and this deployment's policy verdict (reachable/why_not) for ONE operation. operation = the EXACT registry key (e.g. companies.query — never a tool name, never fuzzy). Call after autotask_catalog names the key, or before a mode-tool call.`,
     autotask_read: `Route any effect=read registry op by its EXACT key (never a tool name) — incl. the catalog-only field/entity/UDF-info reads. args positional; query/count ops: args[0] is the params object (autotask_describe first). Write/delete ops are refused pre-request. Prefer the dedicated tool when one exists.`,
     autotask_write: `Route any effect=write registry op by its EXACT key, dry-run-first (dry_run false applies — mutating request is never issued before then). The 3 approval-gated writes also need confirm === the op key (BOTH modes). Read/delete ops refused pre-request. Write-policy gated (POLICY_DENIED pre-request).`,
@@ -273,11 +275,12 @@ 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 + services + billing rules + recent charges (50 newest) + service units in one call: parts degrade to typed absent; contract missing → NOT_FOUND. P&L / profitable?: autotask_contract_profitability. Deeper (bundles, adjustments, exclusions): autotask_read; 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.`,
     autotask_company_unbilled_work: `A company's unbilled work: posted billing items, the time behind them, per-ticket rollup, the unposted section, totals + hours + warnings. Arguments: id + closed bag (see the server instructions). A filtered empty part is a TRUE zero; shape problems → typed CONFIG_ERROR; missing company → NOT_FOUND.`,
+    autotask_contract_profitability: `Contract P&L by month: profit, margin, revenue (recurring/T&M/charges), break-even, unbilled/unposted time, Block Hours included hours, warnings. Args: id, date_from/date_to (default last 12 months), include_rows. Internal-currency billing-period (start-month) money; parts degrade to typed absent.`,
     autotask_aggregate: `Fold a query surface into groups/sums/totals or count it (the count endpoint). operation = an EXACT plan .query op (others refused); filter (grammar; empty array = unfiltered: a 0 on a blind surface is marked blind: true); group_by / sum / top / limit: server instructions. Read op; zero mutating.`,
     autotask_resource_who_am_i: `Identify the authenticated integration by its Resource record (name, zone, tenant). Call first to verify credentials and scope before other work. No arguments; returns the compact ResourceSummary, or null when the configured user cannot be matched. Sensitive.`,
     autotask_company_resolve: `Resolve a Company from a numeric id (tried first) or a companyName — exact by default, or fuzzy candidates via match:'contains' (+ include_family). The record carries companyName — cite that, never the bare id. Other forms (e.g. email) NOT tried; a miss is a typed NOT_FOUND. Read-only. Sensitive.`,
@@ -339,7 +342,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 = 'bd88648453f58ede018062ce66acefacb672fecaa450af89f421057809971e14';
 /**
  * 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.d.ts

@@ -2,7 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/server';
 import type { ToolContext } from './context.js';
 /** Register the whole composite surface. */
 /**
- * The 13 composite tool names. The served `tools/list` order is the approved surface order
+ * The 14 composite tool names. The served `tools/list` order is the approved surface order
  * (architecture §2.3 — the `REGISTERED_TOOL_NAMES` constant); `register.ts` drives the
  * registration one tool at a time through {@link registerCompositeTool}.
  */
@@ -11,3 +11,12 @@ export declare const COMPOSITE_TOOL_NAMES: readonly string[];
 export declare function registerCompositeTools(server: McpServer, ctx: ToolContext): void;
 /** Register ONE composite tool by name (FT-2: per-tool order, driven by `register.ts`). */
 export declare function registerCompositeTool(server: McpServer, ctx: ToolContext, tool: string): void;
+/**
+ * The profitability window: the caller's days, else the default — 12 calendar months ending
+ * date_to (default today, UTC): from the 1st of the month 11 months before date_to's month. An
+ * inverted window is refused pre-request (the typed CONFIG_ERROR, zero wire).
+ */
+export declare function profitabilityWindow(dateFrom: string | undefined, dateTo: string | undefined, now?: Date): {
+    dateFrom: string;
+    dateTo: string;
+};

package/dist/tools/composites.js

@@ -13,10 +13,17 @@
  *
  * 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';
+import { AutotaskConfigError, 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, CONTRACT_PROFITABILITY_INPUT, AGGREGATE_INPUT, COMPOSITE_OUTPUT, resultOutput, aggregateOutput, unbilledWorkOutput, contractProfitabilityOutput, closedInput, } from './schemas.js';
 import { annotationsFor, untrustedFieldsOf } from './catalog-data.js';
 import { runTool, abortedAnswer } from './dispatch.js';
 import { markResult, ok } from './results.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 {
@@ -59,7 +71,7 @@ function registerSdkComposite(ctx, server, spec) {
     const rec = ctx.record(spec.operation);
     if (rec === undefined)
         throw new Error(`composites: no registry record for ${spec.operation}`);
-    const fields = untrustedFieldsOf(rec);
+    const fields = [...new Set([...untrustedFieldsOf(rec), ...(spec.extraUntrusted ?? [])])].sort();
     const output = (spec.outputSchema ?? ((f) => resultOutput('The composite (the SDK runs the bounded fan-out; a part miss is null + the typed absent reason).', f)))(fields);
     server.registerTool(spec.tool, {
         title: spec.title,
@@ -79,7 +91,9 @@ function registerSdkComposite(ctx, server, spec) {
         // default off) is the DEFAULT lever: it applies only when the caller left `names` ABSENT,
         // so a per-call names: false overrides the env opt-in OFF. Absent both keys and the env
         // unset leaves the bag byte-identical to the pre-names surface (issue #20 AC 4).
-        if (opts.names === undefined && ctx.config.AUTOTASK_COMPOSITE_NAMES === 'on')
+        // Only the tools that declare `names` take it: the closed SDK bags of the others (unbilled
+        // work, profitability) refuse an unknown key.
+        if (opts.names === undefined && ctx.config.AUTOTASK_COMPOSITE_NAMES === 'on' && spec.input.validKeys.includes('names'))
             opts.names = true;
         // A missing root fails the call (the typed vendor error); per-part misses degrade inside the SDK.
         // The positional list is built CONDITIONALLY: the operation's declared arity is the contract
@@ -122,7 +136,7 @@ function registerServerComposite(ctx, server, spec) {
 }
 /** Register the whole composite surface. */
 /**
- * The 13 composite tool names. The served `tools/list` order is the approved surface order
+ * The 14 composite tool names. The served `tools/list` order is the approved surface order
  * (architecture §2.3 — the `REGISTERED_TOOL_NAMES` constant); `register.ts` drives the
  * registration one tool at a time through {@link registerCompositeTool}.
  */
@@ -139,6 +153,7 @@ export const COMPOSITE_TOOL_NAMES = [
     'autotask_contract_full_profile',
     'autotask_resource_workload',
     'autotask_company_unbilled_work',
+    'autotask_contract_profitability',
     'autotask_aggregate',
 ];
 /** Register the whole composite surface (group form; the ORDERED form is per-tool). */
@@ -173,6 +188,8 @@ export function registerCompositeTool(server, ctx, tool) {
             return registerResourceWorkload(server, ctx);
         case 'autotask_company_unbilled_work':
             return registerUnbilledWork(server, ctx);
+        case 'autotask_contract_profitability':
+            return registerContractProfitability(server, ctx);
         case 'autotask_aggregate':
             return registerAggregateTool(server, ctx);
     }
@@ -370,12 +387,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 +401,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],
+                },
+            };
         },
     });
 }
@@ -465,6 +501,74 @@ function registerUnbilledWork(server, ctx) {
         ]),
     });
 }
+// ---- autotask_contract_profitability: the SDK's contract P&L composite (<=21 bounded reads) ----
+/** A Date's UTC calendar day (YYYY-MM-DD). */
+function utcDay(d) {
+    return d.toISOString().slice(0, 10);
+}
+/**
+ * The profitability window: the caller's days, else the default — 12 calendar months ending
+ * date_to (default today, UTC): from the 1st of the month 11 months before date_to's month. An
+ * inverted window is refused pre-request (the typed CONFIG_ERROR, zero wire).
+ */
+export function profitabilityWindow(dateFrom, dateTo, now = new Date()) {
+    const to = dateTo ?? utcDay(now);
+    const [y, m] = to.split('-').map(Number);
+    const from = dateFrom ?? utcDay(new Date(Date.UTC(y, m - 1 - 11, 1)));
+    if (to < from) {
+        throw new AutotaskConfigError(`profitability: date_to (${to}) must be >= date_from (${from})${dateTo === undefined ? ' — date_to defaulted to today (UTC)' : ''}`, {
+            operation: 'contracts.profitability',
+        });
+    }
+    return { dateFrom: from, dateTo: to };
+}
+/** The reads behind the profitability result's customer + part containers (their untrusted stamps). */
+const PROFITABILITY_PART_OPS = [
+    'companies.get',
+    'contract_services.query',
+    'contract_service_units.query',
+    'contract_charges.query',
+    'contract_role_costs.query',
+    'contract_rates.query',
+    'contract_blocks.query',
+    'billing_items.query',
+    'invoices.query',
+    'time_entries.query',
+    'tickets.query',
+    'resources.query',
+    'expense_items.query',
+    'configuration_items.query',
+    'subscriptions.query',
+];
+function registerContractProfitability(server, ctx) {
+    registerSdkComposite(ctx, server, {
+        tool: 'autotask_contract_profitability',
+        operation: 'contracts.profitability',
+        title: "Get a contract's profitability (monthly P&L) in one call",
+        input: closedInput(CONTRACT_PROFITABILITY_INPUT),
+        outputSchema: contractProfitabilityOutput,
+        // The registry stamp covers the contract record only; the result also carries the customer,
+        // the part rows (include_rows) and vendor text in the folds: highest_cost_tickets[].title,
+        // open_renewal_items[].label (ticket title / subscriptionName / contractName),
+        // contract_type.label (the tenant picklist label) and the part notes (an absent part's note
+        // quotes the vendor error message).
+        extraUntrusted: [...PROFITABILITY_PART_OPS.flatMap((op) => ctx.untrustedFields(op)), 'title', 'label', 'note'],
+        // opts is REQUIRED by the SDK (dateFrom + dateTo), so the bag always travels.
+        opts: (a) => ({
+            ...profitabilityWindow(a.date_from, a.date_to),
+            ...bagOf([
+                ['includeRows', a.include_rows],
+                ['labourCostMethod', a.labour_cost_method],
+                ['labourRatePerHour', a.labour_rate_per_hour],
+                ['includeRecurringCosts', a.include_recurring_costs],
+                ['includeUnbilledRevenue', a.include_unbilled_revenue],
+                ['externalMonthlyCosts', a.external_monthly_costs],
+                ['staleAfterDays', a.stale_after_days],
+                ['limit', a.limit],
+            ]),
+        }),
+    });
+}
 // ---- autotask_aggregate: count / group / sum over ONE query surface (the SDK folds client-side) ----
 function registerAggregateTool(server, ctx) {
     const aggregateInput = closedInput(AGGREGATE_INPUT);

package/dist/tools/context.d.ts

@@ -1,7 +1,7 @@
 /**
  * tools/context.ts — what the tool registrations share, and the ONLY place the SDK is reached.
  *
- * One thin client/ops factory stands between the 41 tool handlers and `node-autotask`:
+ * One thin client/ops factory stands between the 42 tool handlers and `node-autotask`:
  *
  * - `ToolClient` is the client token (a real `AutotaskClient` in production; a fixture-backed
  *   token in tests). Handlers never call SDK methods directly.

package/dist/tools/context.js

@@ -1,7 +1,7 @@
 /**
  * tools/context.ts — what the tool registrations share, and the ONLY place the SDK is reached.
  *
- * One thin client/ops factory stands between the 41 tool handlers and `node-autotask`:
+ * One thin client/ops factory stands between the 42 tool handlers and `node-autotask`:
  *
  * - `ToolClient` is the client token (a real `AutotaskClient` in production; a fixture-backed
  *   token in tests). Handlers never call SDK methods directly.

package/dist/tools/register.d.ts

@@ -1,15 +1,15 @@
 /**
  * tools/register.ts — `registerTools`: derives the per-server context from the deps bundle once,
- * then registers the whole 41-tool surface in layer order (the registration order is the
+ * then registers the whole 42-tool surface in layer order (the registration order is the
  * `tools/list` order the model sees):
  *
  * - Layer A (13): catalog, describe, read/write/delete (the mode tools), who_am_i, version,
  *   threshold_information, resolve_any, search_across_resources, fetch_many, read_batch,
  *   relationship_map;
  * - Layer B (5): the dedicated workflow-resource resolves;
- * - Layer C (23): the five bounded queries + the SLA check + the three find-by lookups, the five
- *   SDK-backed composites (the unbilled-work composite included), the aggregate helper, the seven
- *   server-built composites/reads, and the one dedicated write (`autotask_time_entry_create`).
+ * - Layer C (24): the five bounded queries + the SLA check + the three find-by lookups, the six
+ *   SDK-backed composites (the unbilled-work and profitability composites included), the
+ *   aggregate helper, the seven server-built composites/reads, and the one dedicated write (`autotask_time_entry_create`).
  *
  * Under a read-only deployment the write/delete mode tools are simply absent from the surface
  * (the deployment's policy IS the surface — see `registerModeTools`). The dedicated write

package/dist/tools/register.js

@@ -6,10 +6,10 @@ import { registerListTool } from './lists.js';
 import { COMPOSITE_TOOL_NAMES, registerCompositeTool } from './composites.js';
 import { registerTimeEntryCreate } from './dispatch.js';
 /**
- * Layer C in the approved order: the constant's last 23 entries (Layer A's 13 + Layer B's 5
+ * Layer C in the approved order: the constant's last 24 entries (Layer A's 13 + Layer B's 5
  * precede them in `REGISTERED_TOOL_NAMES`).
  */
-const LAYER_C_TOOLS = REGISTERED_TOOL_NAMES.slice(-23);
+const LAYER_C_TOOLS = REGISTERED_TOOL_NAMES.slice(-24);
 /**
  * Register the full tool surface on one serving unit's server.
  *

package/dist/tools/schemas.d.ts

@@ -306,6 +306,24 @@ export declare const UNBILLED_WORK_INPUT: z.ZodObject<{
     }>>;
     limit: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+export declare const CONTRACT_PROFITABILITY_INPUT: z.ZodObject<{
+    id: z.ZodNumber;
+    date_from: z.ZodOptional<z.ZodString>;
+    date_to: z.ZodOptional<z.ZodString>;
+    include_rows: z.ZodOptional<z.ZodBoolean>;
+    labour_cost_method: z.ZodOptional<z.ZodEnum<{
+        billing_item_our_cost: "billing_item_our_cost";
+        contract_role_cost: "contract_role_cost";
+        resource_internal_cost: "resource_internal_cost";
+        provided: "provided";
+    }>>;
+    labour_rate_per_hour: z.ZodOptional<z.ZodNumber>;
+    include_recurring_costs: z.ZodOptional<z.ZodBoolean>;
+    include_unbilled_revenue: z.ZodOptional<z.ZodBoolean>;
+    external_monthly_costs: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    stale_after_days: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 export declare const AGGREGATE_INPUT: z.ZodObject<{
     operation: z.ZodString;
     filter: z.ZodUnknown;
@@ -385,7 +403,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<{
@@ -450,6 +472,14 @@ export declare function aggregateOutput(): z.ZodType;
 export declare function unbilledWorkRoot(fields?: readonly string[]): z.ZodType;
 /** The unbilled-work tool's output: the typed root under `result` (the served `parts` object is the closed status vocabulary). */
 export declare function unbilledWorkOutput(fields?: readonly string[]): z.ZodType;
+/**
+ * The contract profitability root (d.ts-transcribed, pinned 0.13.0 `ContractsProfitabilityResult`):
+ * the folds are typed; the vendor records (contract, customer, part rows) stay `dataField` + the
+ * untrusted stamp by design (OQ-3).
+ */
+export declare function contractProfitabilityRoot(fields?: readonly string[]): z.ZodType;
+/** The contract profitability tool's output: the typed root under `result`. */
+export declare function contractProfitabilityOutput(fields?: readonly string[]): z.ZodType;
 /** A cross-resource result; `truncated` names resources whose scan hit its cap (undecided). */
 export declare const RESOLVE_ANY_OUTPUT: z.ZodObject<{
     identifier: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;

package/dist/tools/schemas.js

@@ -175,7 +175,7 @@ function untrustedField(schema, fields) {
 // Layer A — platform & discovery inputs (12)
 // ---------------------------------------------------------------------------
 export const CATALOG_INPUT = z.object({
-    limit: z.number().int().min(1).max(500).default(41).describe('Maximum rows per page (1-500, default 41 — the whole served surface on one default page).'),
+    limit: z.number().int().min(1).max(500).default(42).describe('Maximum rows per page (1-500, default 42 — the whole served surface on one default page).'),
     offset: z.number().int().min(0).default(0).describe('Row offset — how to page past the limit.'),
     tier: z.enum(['core', 'extended', 'advanced']).optional().describe('Filter rows by plan tier.'),
     effect: z.enum(['read', 'write', 'destructive']).optional().describe('Filter rows by effect.'),
@@ -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.'),
@@ -454,6 +456,41 @@ export const UNBILLED_WORK_INPUT = z.object({
         .optional()
         .describe('The per-part record cap (default 25, clamped 1..500).'),
 });
+/** A calendar day (YYYY-MM-DD). */
+const DAY = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'expected YYYY-MM-DD');
+export const CONTRACT_PROFITABILITY_INPUT = z.object({
+    id: ID.describe('The numeric contract id.'),
+    date_from: DAY.optional().describe('Window start (YYYY-MM-DD, UTC day). Default: the 1st of the month 11 months before date_to (12 calendar months).'),
+    date_to: DAY.optional().describe('Window end (YYYY-MM-DD, UTC day, >= date_from; window at most 36 months). Default: today (UTC).'),
+    include_rows: z
+        .boolean()
+        .optional()
+        .describe('Return the raw rows behind every part (default false — each part carries its stamps + rows_fetched instead of items; every computed figure is returned either way).'),
+    labour_cost_method: z
+        .enum(['billing_item_our_cost', 'contract_role_cost', 'resource_internal_cost', 'provided'])
+        .optional()
+        .describe('The labour-cost ladder rung rows start from (default "billing_item_our_cost"; a row without a rate falls down the ladder). "provided" requires labour_rate_per_hour.'),
+    labour_rate_per_hour: z
+        .number()
+        .min(0)
+        .optional()
+        .describe('A caller-supplied labour cost rate: REQUIRED with labour_cost_method "provided"; otherwise the final-rung fallback.'),
+    include_recurring_costs: z.boolean().optional().describe('Include contract charge + service-unit costs (default true).'),
+    include_unbilled_revenue: z.boolean().optional().describe('Include the expected-but-unbilled revenue section (default true).'),
+    external_monthly_costs: z
+        .array(z.number().min(0))
+        .max(36)
+        .optional()
+        .describe('Caller-supplied per-month tooling costs, indexed by month from date_from (not vendor data — reported as caller_supplied and counted in total_cost).'),
+    stale_after_days: z.number().int().min(1).optional().describe('The open-ticket staleness horizon in days (default 30).'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .optional()
+        .describe('The per-part record cap (default 50, clamped 1..500).'),
+});
 export const AGGREGATE_INPUT = z.object({
     operation: z
         .string()
@@ -588,7 +625,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
@@ -708,6 +749,179 @@ export function unbilledWorkRoot(fields = []) {
 export function unbilledWorkOutput(fields = []) {
     return z.object({ result: unbilledWorkRoot(fields) });
 }
+/** One labour-cost rate-ladder bucket (entries / hours / cost carried by that rung). */
+const RATE_BUCKET = z.object({ entries: z.number(), hours: z.number(), cost: z.number() });
+/**
+ * One profitability part container (d.ts-transcribed, pinned 0.13.0 `ProfitabilityPart` /
+ * `ProfitabilityPartDigest`): the digest (the default — the stamps + `rows_fetched`, no items)
+ * or, with include_rows, the full container (the stamps + the vendor rows). A faulted part is
+ * status 'absent' + the typed code — the part degraded, the call did not.
+ */
+function profitabilityPartSchema(fields) {
+    const stamps = {
+        capped: z.boolean().describe('True when the page came back full (the cap rows) — more may exist.'),
+        hasMore: z.boolean().describe("The part's hasMore."),
+        note: untrustedField(z.string(), fields).optional().describe('An honest note (skipped reason / join-set truncation / blind-list quirk / true zero / per-item misses); an absent part\'s note quotes the vendor error text.'),
+        blindSurface: BLIND_SURFACE_SCHEMA.optional(),
+        emptyReason: EMPTY_REASON_SCHEMA.optional(),
+        absent: z.string().optional().describe("status 'absent' only: the typed error code of the read that faulted."),
+        status: z.enum(['ok', 'blind', 'skipped', 'absent']).describe('The part status (the closed SDK vocabulary).'),
+    };
+    return z.union([
+        z.object({ ...stamps, rows_fetched: z.number().describe('The rows the part read (include_rows false — the default).') }),
+        z.object({ ...stamps, items: z.array(dataField("The part's vendor records (include_rows true; untrusted by construction).", fields)) }),
+    ]);
+}
+/** One month of the contract P&L (d.ts-transcribed, pinned 0.13.0 `ProfitabilityMonthlyRow`). */
+const PROFITABILITY_MONTH = z.object({
+    month: z.string().describe('YYYY-MM (the billing period; annual units are attributed to their start month).'),
+    revenue_invoiced: z.number(),
+    revenue_by_type: z.object({ recurring: z.number(), labour: z.number(), charges: z.number(), expenses: z.number(), other: z.number() }),
+    revenue_voided_excluded: z.number(),
+    revenue_posted_uninvoiced: z.number(),
+    revenue_unresolved_invoice: z.number(),
+    revenue_expected: z.number().nullable(),
+    revenue_expected_unbilled: z.number(),
+    unposted_time: z
+        .object({ entries: z.number(), hours: z.number(), value: z.number().nullable(), absent: z.string().optional() })
+        .describe('Billable time not yet posted; value is priced on Time & Materials contracts only (otherwise null + absent).'),
+    labour_hours: z.number(),
+    labour_cost: z.object({ total: z.number(), unresolvedHours: z.number(), rateSources: z.record(z.string(), RATE_BUCKET) }),
+    tooling_cost: z
+        .object({ vendor: z.number().nullable(), caller_supplied: z.number() })
+        .describe('vendor = CI subscription cost, REPORTED only (excluded from total_cost); caller_supplied = external_monthly_costs (included).'),
+    recurring_cost: z.number(),
+    expense_cost: z.number(),
+    total_cost: z.number(),
+    profit: z.number(),
+    margin: z.number().nullable(),
+    break_even_hours: z.number().nullable(),
+    coverage_gaps: z.array(z.string()).describe('Why the month may be incomplete (absent / truncated / capped parts). Empty = complete.'),
+});
+/**
+ * The contract profitability root (d.ts-transcribed, pinned 0.13.0 `ContractsProfitabilityResult`):
+ * the folds are typed; the vendor records (contract, customer, part rows) stay `dataField` + the
+ * untrusted stamp by design (OQ-3).
+ */
+export function contractProfitabilityRoot(fields = []) {
+    const part = profitabilityPartSchema(fields);
+    const partStatus = (...s) => z.enum(s);
+    return z.object({
+        contract: dataField('The contract record (the root — a missing contract fails the call).', fields),
+        customer: dataField('The customer company, or null when unread.', fields).nullable(),
+        customerAbsent: z.string().optional().describe('The typed code when the customer read faulted.'),
+        contract_type: z.object({ id: z.number().nullable(), label: untrustedField(z.string(), fields).nullable().describe('The tenant picklist label.'), absent: z.string().optional() }),
+        included_hours: z
+            .object({
+            value: z.object({ purchased: z.number(), approved: z.number(), remaining: z.number() }).nullable(),
+            absent: z.string().optional(),
+        })
+            .describe('Block Hours contracts only; otherwise null + the typed reason.'),
+        period: z.object({ dateFrom: z.string(), dateTo: z.string(), months: z.array(z.string()), asOf: z.string() }),
+        currency: z.object({ companyCurrencyID: z.number().nullable(), note: z.string() }).describe('Money figures are in the internal currency.'),
+        monthly: z.array(PROFITABILITY_MONTH),
+        activity_categories: z.array(z.object({
+            ticketCategory: z.number().nullable(),
+            ticketCount: z.number(),
+            entryCount: z.number(),
+            hours: z.number(),
+            cost: z.number(),
+            sample_ticketNumbers: z.array(z.number()),
+        })),
+        highest_cost_tickets: z.array(z.object({
+            ticketId: z.number(),
+            ticketNumber: z.number().nullable(),
+            title: untrustedField(z.string(), fields).describe('The vendor ticket title (untrusted by construction).'),
+            status: z.number().nullable(),
+            hours: z.number(),
+            cost: z.number(),
+            lastActivityDate: z.string().nullable(),
+        })),
+        possible_miscoding: z.array(z.object({
+            entryId: z.number(),
+            reason: z.enum(['no_contract_on_entry', 'ticket_of_other_contract', 'ticket_not_in_fetched_set']),
+            ticketId: z.number().nullable(),
+            contractId: z.number().nullable(),
+            hours: z.number(),
+        })),
+        open_renewal_items: z.array(z.object({
+            kind: z.enum(['ticket', 'subscription', 'contract_end', 'included_hours_burn']),
+            id: z.number().nullable(),
+            label: untrustedField(z.string(), fields).describe('The ticket title / subscriptionName / contractName (untrusted by construction).'),
+            date: z.string().nullable(),
+            detail: z.string(),
+        })),
+        data_quality_warnings: z.array(z.object({
+            code: z.enum([
+                'miscoded_time_out',
+                'cross_contract_ticket_time',
+                'duplicate_entries',
+                'zero_negative_hours',
+                'time_outside_ticket_period',
+                'missing_cost_rate',
+                'recurring_cost_drift',
+                'expected_unbilled_revenue',
+                'cross_contract_tickets',
+                'open_stale_tickets',
+                'estimate_vs_actual',
+            ]),
+            count: z.number(),
+            sample_ids: z.array(z.union([z.number(), z.string()])),
+            note: z.string().optional(),
+        })),
+        costRateResolution: z.object({
+            method: z.enum(['billing_item_our_cost', 'contract_role_cost', 'resource_internal_cost', 'provided']),
+            sources: z.record(z.string(), RATE_BUCKET),
+            unresolvedHours: z.number(),
+            notes: z.array(z.string()),
+        }),
+        contractServices: part,
+        contractServiceUnits: part,
+        contractCharges: part,
+        contractRoleCosts: part,
+        contractRates: part,
+        contractBlocks: part,
+        billingItems: part,
+        invoices: part,
+        timeEntries: part,
+        ticketsActivity: part,
+        ticketsOpen: part,
+        resources: part,
+        expenses: part,
+        miscodingProbe: part,
+        configurationItems: part,
+        subscriptions: part,
+        parts: z
+            .object({
+            contract: z.literal('ok'),
+            customer: partStatus('ok', 'skipped', 'absent'),
+            contractServices: partStatus('ok', 'blind', 'absent'),
+            contractServiceUnits: partStatus('ok', 'blind', 'absent'),
+            contractCharges: partStatus('ok', 'blind', 'skipped', 'absent'),
+            contractRoleCosts: partStatus('ok', 'blind', 'absent'),
+            contractRates: partStatus('ok', 'blind', 'absent'),
+            contractBlocks: partStatus('ok', 'blind', 'skipped', 'absent'),
+            billingItems: partStatus('ok', 'blind', 'absent'),
+            invoices: partStatus('ok', 'skipped'),
+            timeEntries: partStatus('ok', 'blind', 'absent'),
+            ticketsActivity: partStatus('ok', 'blind', 'absent'),
+            ticketsOpen: partStatus('ok', 'blind', 'skipped', 'absent'),
+            resources: partStatus('ok', 'skipped'),
+            expenses: partStatus('ok', 'blind', 'skipped', 'absent'),
+            miscodingProbe: partStatus('ok', 'blind', 'skipped', 'absent'),
+            configurationItems: partStatus('ok', 'blind', 'skipped', 'absent'),
+            subscriptions: partStatus('ok', 'blind', 'skipped', 'absent'),
+        })
+            .describe('Per-part status (the closed SDK vocabulary).'),
+        wires: z
+            .object({ issued: z.number(), requests: z.number(), budget: z.number(), note: z.string().optional() })
+            .describe('issued = logical part reads; requests = raw HTTP requests.'),
+    });
+}
+/** The contract profitability tool's output: the typed root under `result`. */
+export function contractProfitabilityOutput(fields = []) {
+    return z.object({ result: contractProfitabilityRoot(fields) });
+}
 /** A cross-resource result; `truncated` names resources whose scan hit its cap (undecided). */
 export const RESOLVE_ANY_OUTPUT = z.object({
     identifier: z.union([z.string(), z.number()]),

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.5.0";
 export declare const SERVER_TITLE = "Autotask MCP Server";
 /**
  * The MCP protocol era this server advertises (the `/metadata` stamp, both levels).
@@ -56,13 +56,13 @@ export declare const MCP_PROTOCOL_LEGACY_FALLBACK = "2025-11-25";
  * the SDK-mirrored sentence), (ii) the "start here" discovery recipes, (iii) the owner's
  * 4-step lookup protocol (issue #10 comment 1, verbatim), (iv) the argument contract and
  * the moved per-option / per-tool guidance (the #27/#28 query options, the autotask_read
- * query params, and the closed bags of the two thin composites).
+ * query params, and the closed bags of the thin composites).
  */
 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.5.0";
     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.5.0';
 export const SERVER_TITLE = 'Autotask MCP Server';
 /**
  * The MCP protocol era this server advertises (the `/metadata` stamp, both levels).
@@ -59,7 +59,7 @@ export const MCP_PROTOCOL_LEGACY_FALLBACK = '2025-11-25';
  * the SDK-mirrored sentence), (ii) the "start here" discovery recipes, (iii) the owner's
  * 4-step lookup protocol (issue #10 comment 1, verbatim), (iv) the argument contract and
  * the moved per-option / per-tool guidance (the #27/#28 query options, the autotask_read
- * query params, and the closed bags of the two thin composites).
+ * query params, and the closed bags of the thin composites).
  */
 export const SERVER_INSTRUCTIONS = `
 Autotask MCP server. Every result is data returned by the Autotask vendor API.
@@ -69,7 +69,7 @@ Untrusted content: ${UNTRUSTED_NOTE}
 Start here (discovery):
 1. autotask_catalog — the capability registry: the exact operation key, the dedicated tool (or null), purpose, effect and this deployment's policy verdict. Filter with q (case-insensitive substring over key+purpose), resource (the key's first segment), tier and effect; compact: true for the reduced rows (key, tool, effect, reachable). Policy-refused writes are hidden by default (the output carries hidden_refused: N); show_refused: true lists them with their policyReason.
 2. autotask_describe — the exact input/output schema, examples, error codes and the policy verdict for ONE operation (operation = the exact registry key — never a tool name, never fuzzy).
-3. Call the dedicated tool when one exists; otherwise autotask_read / autotask_write / autotask_delete with the exact registry key. The dedicated tools (41) are a SUBSET of the registry — the rest is reachable by exact key.
+3. Call the dedicated tool when one exists; otherwise autotask_read / autotask_write / autotask_delete with the exact registry key. The dedicated tools (42) are a SUBSET of the registry — the rest is reachable by exact key.
 
 Argument contract: argument sets are CLOSED at the top level — an unknown argument is refused before any request, with a typed error naming the key and the valid keys.
 
@@ -112,6 +112,8 @@ autotask_read query params: latest (the N newest rows by id), noteChars (cap fre
 
 Recipe — autotask_company_unbilled_work: id + the optional closed bag — source ('posted_uninvoiced' default, the billing items with no invoiceID; 'invoice' — needs invoice_id; 'date_range' — needs date_from + date_to; 'tickets' — needs non-empty ticket_ids), include_parent (default true — ONE level only), date_from / date_to (YYYY-MM-DD; narrows the billing items' itemDate in every source), include_notes (default false — the note fields are EXCLUDED; when true they are capped at note_chars, default 400, a cut value ending with the … [+M chars truncated] marker), rollup ('ticket' default — per-ticket rows; 'entry' — the capped per-entry list), limit (the per-part record cap, default 25, clamped 1..500). Wire: 6(+1) bounded reads; the unposted anti-join + totals + warnings are client-side folds (zero wire). Per-ticket rollup rows carry the numeric ticketId ONLY — resolve the distinct ids in ONE bounded call (autotask_read tickets.query with filter [{ field: 'id', op: 'in', value: [...] }], include_fields ['id','ticketNumber'], or autotask_fetch_many) when the answer must name the tickets; report the ticketNumber, never the bare id (rule 5).
 
+Recipe — autotask_contract_profitability: id + an optional window — date_from / date_to (YYYY-MM-DD, UTC days; default: the 12 calendar months ending today — the 1st of the month 11 months back through today; one side omitted defaults the same way; date_to < date_from is refused pre-request; at most 36 months) + the optional closed bag: include_rows (default false — each part carries its status stamps + rows_fetched, NOT its rows; true returns the raw rows and a much larger result), labour_cost_method / labour_rate_per_hour ('provided' needs the rate), include_recurring_costs, include_unbilled_revenue, external_monthly_costs (caller tooling costs per month from date_from — counted in total_cost), stale_after_days, limit (per-part cap, default 50). Reading it: money is in the INTERNAL currency (currency.note), per billing period — annual/periodic service units count in their START month, so that month spikes while the rest of the term shows none. Check every month's coverage_gaps and the parts status map before quoting a figure: a faulted part is status 'absent' + its code (the call still answers) and the affected months name it. unposted_time.value is priced on Time & Materials contracts only (otherwise null + absent). included_hours is Block Hours only (otherwise null + the typed reason). tooling_cost.vendor (CI subscriptions) is reported separately and EXCLUDED from total_cost/profit/margin; labour_cost.unresolvedHours > 0 means total_cost is a lower bound (missing_cost_rate warning). Report the contract by contractName and tickets by ticketNumber (rule 5).
+
 Recipe — autotask_aggregate: operation (the EXACT registry query op — a plan resource's .query ONLY; a special op, a .count row or an unknown resource is refused pre-request, naming autotask_catalog), filter (the query-bag condition grammar — 13 operators; an empty array = the unfiltered call: a 0 on a plan-pinned blind surface is marked blind: true, never a silent absence; a filtered 0 on an unfiltered-blind surface is a true zero) + the optional closed bag: group_by (vendor field names — the group key is the field tuple), sum (numeric vendor fields), top (default 25, clamped 1..100 — the group-row cap), limit (default 2500 — the total-record cap for the walk modes; the house hard max). NEITHER group_by NOR sum = COUNT mode (exactly one POST /query/count — no walk, no GETs; the count endpoint is not cached); a group_by or sum = WALK mode (/query pages of min(500, limit), <= ceil(limit/500) pages + the 1000-page guard; the queries are not cached). The fold is client-side: groups carry count + the requested sums; totalGroups + groupsTruncated say when top cut the groups; hasMore + totalScanned say when the walk truncated — groups/sums cover the returned rows ONLY (no silent partial sums); a mid-walk RATE_LIMITED propagates (the partial fold is discarded). Group/sum rows carry the vendor fields you grouped by — when a grouped field is a numeric FK (e.g. ticketID, companyID), resolve the distinct ids in ONE bounded call (the owning resource's query with filter [{ field: 'id', op: 'in', value: [...] }], or autotask_fetch_many) before reporting them (rule 5).
 
 Recipe — autotask_timeEntry_create: data is required (the TimeEntry payload — vendor model fields); vendor field chain (a bare payload burns vendor 500s, one per real wire dial): link the entry to one of ticketID / taskID / internalAllocationCodeID; entries on Tickets also require roleID; entries on Service tickets require startDateTime + endDateTime; the hours field is hoursWorked (NOT hours) — at least one of hoursWorked or (startDateTime + endDateTime) is required; the linked ticket must be open (a completed ticket is refused); the allocation code must be an active GENERAL billing code (billingCodeType 0 + isActive true — discover one via billing_codes.query) or pass an explicit active general billingCodeID. On apply (dry_run: false) the tool reads back the created record (live: the write clears the SDK read cache) and returns it as record next to result.id; a dry run returns no record; a read-back failure leaves record null, adds a note naming the typed error code and never fails the write (the created id rides result). Report the entry by the LINKED TICKET's human ticketNumber — autotask_ticket_resolve on the linked ticketID (NOT autotask_ticket_find_by_ticket_number, which takes the ticketNumber string, not the id) — never by the created entry's bare id.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "MCP server for the Autotask (Datto) PSA domain, built on the node-autotask SDK",
   "license": "MIT",
   "author": "Max Soukhomlinov",
@@ -47,18 +47,18 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.2.0",
-    "node-autotask": "0.10.0",
-    "zod": "^4.4.3"
+    "node-autotask": "0.13.0",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@eslint/js": "^9.17.0",
-    "@types/node": "^24.0.0",
-    "eslint": "^9.17.0",
-    "globals": "^15.14.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.19.1",
+    "eslint": "^10.12.0",
+    "globals": "^17.13.0",
     "rimraf": "^6.0.1",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0",
-    "typescript-eslint": "^8.18.0",
-    "vitest": "^4.1.11"
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.2",
+    "vitest": "^5.0.4"
   }
 }

package/server.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "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.13.0"
   },
   "vendorExtensions": false
 }