iit-mcp-autotask 0.0.0-stage → 0.2.0

package/.env.example

@@ -0,0 +1,80 @@
+# The credentials load recipe (issue #6) — read this before your first live session.
+#
+# A .env value may be SINGLE-QUOTED on purpose: a secret containing `$` must be, or the shell would
+# expand it. Those quotes are part of the shell syntax, NOT part of the credential:
+#
+#     set -a; . ./.env; set +a        # shell sourcing — the ONLY load recipe this server documents
+#     autotask-mcp doctor             # confirm the shape before any live session (zero vendor calls)
+#
+# Do NOT load this file with a quote-preserving dotenv parser (most `dotenv` variants, a hand-rolled
+# split('=')): it hands the value over with its quotes intact, and the vendor answers 401 "Bad
+# credentials" — which reads like a rotated credential, on an account where repeated auth failures
+# risk a lock. The server refuses such a value before dialing (CREDENTIAL_MALFORMED) and `doctor`
+# reports it as `shapeOk: false`, but the fix is the load recipe.
+#
+# A green `doctor` makes any later 401 vendor-side (rotated, revoked or role-restricted credential).
+# See README §Credentials & env files.
+
+# iit-mcp-autotask — non-secret configuration only.
+# Real credentials never live in a committed file: under stdio the process environment IS the
+# trust boundary (set them in the launching environment); under http they travel per request
+# in the X-Autotask-* headers injected by the gateway.
+
+# stdio (local: Claude Code / Claude Desktop / VS Code) or http (remote MCP clients / gateway).
+MCP_TRANSPORT=stdio
+
+# --- Credentials (stdio: required from the environment; http: optional discouraged defaults) ---
+# stdio: all three are REQUIRED for a live server; without them the server still boots and serves
+# the full surface in credential-less mode (initialize/tools/list work; tool calls refuse).
+# http: when set, every request WITHOUT its own X-Autotask-* headers runs as this identity and the
+# identity is only ever presented to the AUTOTASK_BASE_URL default origin. Left commented so a
+# copied example does not set empty values.
+# AUTOTASK_API_INTEGRATION_CODE=
+# AUTOTASK_USERNAME=
+# AUTOTASK_SECRET=
+# AUTOTASK_IMPERSONATION_RESOURCE_ID=
+
+# The Autotask origin the server talks to. stdio: REQUIRED (the zone lives in the host, e.g.
+# https://webservices6.autotask.net; base path /atservicesrest is fixed). http: optional DEFAULT
+# origin for requests that send no X-Autotask-Base-Url header.
+# AUTOTASK_BASE_URL=https://webservices6.autotask.net
+
+# http only. Hosts a caller may name in X-Autotask-Base-Url: comma-separated exact hostnames or
+# *.suffix subdomain suffixes (no scheme/port/path). Unset alongside a set default origin -> only
+# that origin is accepted. Unset with no default origin -> the server REFUSES to boot unless
+# AUTOTASK_ALLOW_ANY_BASE_HOST=true. Literal private-IP origins are always refused.
+# Recommended production value: the line below.
+# AUTOTASK_ALLOWED_BASE_HOSTS=*.autotask.net
+# AUTOTASK_ALLOW_ANY_BASE_HOST=false
+
+# --- Mutation surface (opt-in; reads are never affected) ---
+# Omit all mutation tools entirely. Set false before enabling a write policy.
+AUTOTASK_READ_ONLY=true
+# deny (default — forgetting this yields a read-only server, never an open one) | allow_list | all
+# (must be typed out deliberately).
+AUTOTASK_WRITE_POLICY=deny
+# Only under allow_list: comma-separated registry operation keys (e.g. time_entries.create).
+# Must be non-empty and every key must exist in the SDK registry and be a write, or boot fails
+# with the variable named. Ignored under deny/all.
+# AUTOTASK_WRITE_ALLOW=time_entries.create
+
+# --- Secret reads (independent of the write policy) ---
+# deny (default) refuses authenticate.get, which returns a plaintext vendor token that the SDK's
+# redaction deliberately exempts. allow permits it; the token is still never logged.
+AUTOTASK_SECRET_READS=deny
+
+# --- Per-tenant read cache (in-process; never cross-tenant; never on disk) ---
+# on (default): each pooled tenant client applies the SDK reference TTL table (structural ~1 h /
+# mutable ~5 min / base ~1 min) plus the field-metadata cache; repeated reads of the same record
+# are served from the tenant's cache until TTL expiry. off: every read re-dials the vendor.
+AUTOTASK_CACHE_PRESET=on
+
+# --- Vendor budget (the server boots the SDK in the conservative `agent` profile; overrides here) ---
+# AUTOTASK_RATE_LIMIT_PER_HOUR=8000
+# AUTOTASK_MAX_CONCURRENT=3
+# AUTOTASK_TIMEOUT_MS=20000
+# AUTOTASK_MAX_RETRIES=1
+
+# --- Operational ---
+PORT=8080
+LOG_LEVEL=info

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Soukhomlinov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,496 @@
-# Temporary Holding Version
+# iit-mcp-autotask
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 (38 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 +
+TTL read cache).
+
+> **Package status (2026-10-10):** the runtime dependency `node-autotask` is published to public npm
+> at `0.8.3` (stricter identifier validation and pagination handling); 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.8.3`) — never a `file:`, `git:`, `link:` or workspace reference
+> to a local checkout.
+
+## Tool surface
+
+38 tools: **12 platform/discovery** (Layer A) + **5 workflow-resource resolves** (Layer B) +
+**21 dedicated workflow tools** (Layer C). Every other operation in the SDK's 1,212-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
+(e.g. `ticket_limit`, `task_limit`, `time_off_limit`, `service_limit`, `billing_rule_limit`,
+`item_limit`, `contact_limit`, `note_limit`, `project_limit`), defaulting to 500 per part — a part
+miss never fails the call (typed `absent`); only a missing root record fails the composite.
+
+| Layer | Tools | Role |
+|-------|-------|------|
+| A — platform & discovery (12) | `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_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 (21) | `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` (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).
+
+### 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 40 / max 500, tier + effect filters).
+- `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
+  **refused before any request** (the message names the correct tool).
+- `autotask_write` — route any `effect=write` operation, **dry-run-first**: the first call always
+  travels `dry_run: true` (pinned `DryRunResult` envelope; the mutating request is never issued);
+  `dry_run: false` applies. The 3 approval-gated writes additionally require `confirm === <op key>`
+  in both modes.
+- `autotask_delete` — route any `effect=destructive` operation; dry-run-first and `confirm === <op key>`
+  **required for all 54 deletes** in both modes.
+
+Dispatch accepts only registered exact operation keys — never tool names, never URLs, never HTTP
+paths. Argument sets are closed at the top level: an unknown key is refused pre-request with a
+typed error naming the key and the valid keys. So the ~1,145 non-exposed operations are always
+discoverable (`catalog`/`describe`) and reachable (`read`/`write`/`delete`) — nothing is a silent gap.
+`autotask_catalog` and `autotask_describe` also surface this deployment's policy verdict
+(`reachable` / `policyReason`) per row, so a policy refusal is visible in the catalog rather than
+discovered by failing; the full served descriptions (the single source of truth,
+`src/tools/catalog-data.ts`) are mirrored in [`capabilities.json`](capabilities.json).
+
+### Writes
+
+One dedicated write tool exists — `autotask_timeEntry_create` (the confirmed W3 write workflow).
+Everything else that mutates rides `autotask_write` / `autotask_delete` under the SDK's governor
+(dry-run-first, `confirm`, cross-mode refusal) **and** the deployment write policy:
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `AUTOTASK_READ_ONLY` | `true` | All mutation tools omitted entirely. Set `false` before enabling a write policy. |
+| `AUTOTASK_WRITE_POLICY` | `deny` | `deny` (forgetting it yields a read-only server, never an open one) / `allow_list` / `all` (typed out deliberately). |
+| `AUTOTASK_WRITE_ALLOW` | — | Under `allow_list`: comma-separated registry operation keys (e.g. `time_entries.create`). Boot fails unless non-empty and every key is a write **or destructive** registry operation key (a read key in the list grants nothing). |
+
+`AUTOTASK_SECRET_READS=deny` (default) independently refuses `authenticate.get` (a plaintext vendor
+token the SDK's redaction deliberately exempts); the tool stays registered and is refused by policy
+(decision D-3 — stable surface, typed refusal). The policy answers *whether* an operation is
+reachable in this deployment — never *how*: validation, forced dry-run and `confirm` governance
+stay in the SDK.
+
+## Transports
+
+| Transport | For | Caller auth | Autotask credential |
+|-----------|-----|-------------|---------------------|
+| `http` (Streamable HTTP, `/mcp`) | shared MCP gateway / federation, remote MCP clients | gateway-owned (client auth, rate limiting, tool filtering) | per request: `X-Autotask-*` headers injected by the gateway |
+| `stdio` (`--transport stdio`) | Claude Code, Claude Desktop, VS Code | none — the process boundary is the trust boundary | environment: `AUTOTASK_*` variables |
+
+## Deployment
+
+### Gateway (http, container)
+
+Run behind the shared MCP gateway on a private, unpublished network (the gateway terminates TLS;
+the listener must not be exposed publicly). The gateway owns client authentication, rate limiting,
+per-tenant tool filtering and **credential injection** into the `X-Autotask-*` headers. The server
+is tenant-agnostic: one deployment serves every Autotask tenant; the zone host and identity travel
+per request.
+
+```
+docker build -t iit-mcp-autotask .
+docker run -d --name iit-mcp-autotask \
+  -p 8080:8080 \
+  -e AUTOTASK_ALLOWED_BASE_HOSTS=*.autotask.net \
+  -e AUTOTASK_BASE_URL=https://webservices6.autotask.net \
+  iit-mcp-autotask
+```
+
+Env-only configuration: no credentials are baked into the image (no `ENV` secrets, no `.env` copy).
+Operational defaults (`MCP_TRANSPORT=http`, `PORT=8080`) are image-level and overridable. `SIGTERM`
+reaches the node process directly (no shell wrapper) and triggers graceful shutdown: stop accepting,
+drain in-flight with a bounded timeout, exit 0. The `HEALTHCHECK` probes `/health` (liveness only —
+it never calls Autotask, so a zone outage cannot cycle the container).
+
+### Local (stdio)
+
+Needs Node 24+ and your Autotask zone origin. `stdio` is the default transport.
+
+**From npm** (once published):
+
+```
+claude mcp add autotask \
+  --env AUTOTASK_API_INTEGRATION_CODE=... \
+  --env AUTOTASK_USERNAME=... \
+  --env AUTOTASK_SECRET=... \
+  --env AUTOTASK_BASE_URL=https://webservices6.autotask.net \
+  -- npx -y iit-mcp-autotask
+```
+
+or in `.mcp.json` / Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "autotask": {
+      "command": "npx",
+      "args": ["-y", "iit-mcp-autotask"],
+      "env": {
+        "AUTOTASK_API_INTEGRATION_CODE": "...",
+        "AUTOTASK_USERNAME": "...",
+        "AUTOTASK_SECRET": "...",
+        "AUTOTASK_BASE_URL": "https://webservices6.autotask.net"
+      }
+    }
+  }
+}
+```
+
+`npx` fetches the package on first run and caches it; pin with `iit-mcp-autotask@<version>`.
+**From a clone**: `pnpm i && pnpm build`, then point the client at `node /abs/path/iit-mcp-autotask/dist/main.js`.
+
+## Endpoints
+
+| Endpoint | Purpose | Auth |
+|----------|---------|------|
+| `POST /mcp` | the canonical MCP endpoint (Streamable HTTP transport) | per-request `X-Autotask-*` headers for tool calls |
+| `GET /health` | process alive — pre-auth, **no vendor call** (container healthcheck) | none |
+| `GET /ready` | config valid, SDK plan-hash pin checked, server initialised, client factory ready — **no live vendor call** (credentials are request-scoped) | none |
+| `GET /doctor` | zero-wire credential/config preflight: per credential field `present`/`len`/`prefix2`/`shapeOk` (`AUTOTASK_SECRET`'s prefix is masked to `[REDACTED]` — no character of a secret is ever emitted; identifiers keep their format prefix), the base-url + allow-list resolution (`default_only` / `allow_list` / `default_and_list` / `any`), the SDK plan-hash gate status and the host-policy mode — **no vendor call, by construction** | none |
+| `GET /metadata` | server identity + the MCP protocol **era pair** (baseline `2026-07-28` + legacy fallback `2025-11-25`) + capability-manifest pointer — the served payload is the repo's `server.json` + build stamp | none |
+
+## Configuration
+
+Copy [.env.example](.env.example). Every variable is Zod-validated at boot; the process exits
+non-zero on an invalid config (fail-fast) instead of failing at the first tool call.
+
+| Variable | Required | Default | Meaning |
+|----------|----------|---------|---------|
+| `MCP_TRANSPORT` | no | `stdio` | `stdio` or `http`; the CLI `--transport` flag overrides |
+| `AUTOTASK_API_INTEGRATION_CODE` | stdio: yes · http: no (discouraged default) | — | the `ApiIntegrationCode` credential (stdio env; http: optional discouraged server default, presented only to the default origin) |
+| `AUTOTASK_USERNAME` | stdio: yes · http: no (discouraged default) | — | the `UserName` credential (same semantics) |
+| `AUTOTASK_SECRET` | stdio: yes · http: no (discouraged default) | — | the `Secret` credential (same semantics) |
+| `AUTOTASK_IMPERSONATION_RESOURCE_ID` | no | — | act as another resource in the tenant (`ImpersonationResourceId` header) |
+| `AUTOTASK_BASE_URL` | stdio: yes · http: no (default origin) | — | the zone origin, e.g. `https://webservices6.autotask.net` (zone lives in the host; base path `/atservicesrest` is fixed — never configurable) |
+| `AUTOTASK_ALLOWED_BASE_HOSTS` | http: unless `AUTOTASK_ALLOW_ANY_BASE_HOST=true` | — | comma-separated exact hostnames or `*.suffix` subdomain suffixes a caller may name in `X-Autotask-Base-Url` (no scheme/port/path). Unset + default origin set → only that origin accepted. Unset + no default → boot refused unless the lab-only flag. **Recommended production value: `*.autotask.net`**. Literal private-IP origins are always refused. |
+| `AUTOTASK_ALLOW_ANY_BASE_HOST` | no | `false` | lab-only opt-in to boot with neither allow-list nor default origin; `warn`-logged at boot (decision D-4). Not set in production. |
+| `AUTOTASK_READ_ONLY` | no | `true` | omit all mutation tools when true |
+| `AUTOTASK_WRITE_POLICY` | no | `deny` | `deny` / `allow_list` / `all` |
+| `AUTOTASK_WRITE_ALLOW` | only under `allow_list` | — | comma-separated registry operation keys; boot fails on empty/unknown keys |
+| `AUTOTASK_SECRET_READS` | no | `deny` | `deny` refuses `authenticate.get` (plaintext vendor token) — the gate is scoped to the **whole `authenticate` resource**, so any future `authenticate.*` operation arrives denied, not reachable; `allow` permits it — the token is still never logged |
+| `AUTOTASK_CACHE_PRESET` | no | `on` | per-tenant in-process TTL read cache (see [Per-tenant pool & cache](#per-tenant-pool--cache)); `off` disables it (every read re-dials the vendor) |
+| `AUTOTASK_RATE_LIMIT_PER_HOUR` | no | 8000 (agent profile) | override the SDK's local hourly budget (never above the vendor cap; `null`/off is rejected at boot — it would void the budget guard) |
+| `AUTOTASK_MAX_CONCURRENT` | no | 3 (agent profile) | override the SDK's local concurrency bound |
+| `AUTOTASK_TIMEOUT_MS` | no | 20000 (agent profile) | whole-call budget |
+| `AUTOTASK_MAX_RETRIES` | no | 1 (agent profile) | bounded retries with backoff (idempotent methods, 429/5xx only) |
+| `HOST` | no | `0.0.0.0` | http bind address (`--host` overrides it) |
+| `PORT` | no | `8080` | http listener port (`--port` overrides it) |
+| `LOG_LEVEL` | no | `info` | log level (sensitive-data-safe structured JSON) |
+
+**No credentials as CLI flags, ever.** The CLI carries only `--transport` / `--host` / `--port` /
+`--version` / `--help`.
+
+## Credentials & env files
+
+The 2026-10-07 incident class, in one paragraph: a `.env` value written `AUTOTASK_SECRET='a$b'` was
+fed to the wire **with its quotes intact** by a quote-preserving loader, the vendor answered
+`401 Bad credentials` three times, and the operator read it as a rotated credential — on an account
+where repeated auth failures risk a lock. Nothing in this package inspected the shape of a
+credential before dialing it. Now something does, on every path.
+
+### The load recipe (the only supported one)
+
+```sh
+set -a; . ./.env; set +a        # shell sourcing: strips the quoting the shell itself added
+autotask-mcp doctor             # confirm the shape, zero vendor calls, exit 0 = go
+autotask-mcp                    # the live session
+```
+
+- **Single-quote a value that contains `$`.** A secret with `$` in it written bare (`SECRET=a$b`)
+  is expanded by the shell to something else entirely. Single quotes stop that — and are then
+  removed by the shell on load, which is why the value that reaches the process is the credential.
+- **Do not use a quote-preserving dotenv parser.** Most `dotenv` variants and any hand-rolled
+  `Key=Value` split hand the value over *with its quotes*, and a surrounding quote pair is
+  presented to the vendor as part of the secret.
+- A trailing CR from a Windows-edited file is the same class of accident: the CR and everything
+  after it would travel as part of the secret.
+
+### What happens when a value is malformed
+
+| Path | Behaviour |
+|------|-----------|
+| `stdio` boot (env) | **boot refusal**, exit 1, naming the variable, the anomaly, the length and the load recipe — never a character of the value. The value is loaded through the SDK's own canonical loader (`loadAutotaskCredentialsFromEnv`), so this process has exactly one parser: the shell-equivalent one that strips a surrounding quote pair, drops a CRLF's CR and trims edge whitespace. |
+| `http` per request | **before any client is constructed**, the three `X-Autotask-*` identity headers (and the impersonation header when present) are shape-checked. A malformed one answers the typed `CREDENTIAL_MALFORMED` envelope: `category: "validation"`, `retryable: false`, the anomaly names, and a `suggestedAction` naming the env-load pitfall. **Zero vendor wire** — nothing was dialed, so a `401` shape would be a lie, and `retryable: false` is what stops a retry loop against a lock-sensitive account. |
+| vendor `401` | the envelope gains `credentialShape: "anomalous"` + the SDK's value-free `shapeDiagnostic` + the load-recipe `suggestedAction` when the credential this request presented shows a shape anomaly; `code`, `category`, `httpStatus`, `retryable` and `message` are unchanged. With **clean** values the envelope is byte-identical to the pinned `UNAUTHORIZED` one. |
+
+Anomaly names reported: `surrounding_single_quotes`, `surrounding_double_quotes`, `carriage_return`,
+`newline`, `edge_whitespace`. **Values are never printed** — lengths, two-character prefixes and
+anomaly names only. `AUTOTASK_SECRET_READS=deny` and every other gate are unchanged, and the shape
+check runs before them, at the boundary.
+
+### `doctor` — the zero-wire preflight
+
+`autotask-mcp doctor` (stdio CLI, exit `0`/`1`) and `GET /doctor` (http, same trust model as
+`/health` and `/ready`: pre-auth, before the MCP handler) report the same facts about the
+**server-held** environment: per field `present` / `len` / `prefix2` / `shapeOk` (+ the anomaly
+names), the `AUTOTASK_BASE_URL` resolution (origin only), the host-policy mode and the SDK
+plan-hash gate status. Nothing here emits a character of a secret: `AUTOTASK_SECRET`'s prefix is
+masked to `[REDACTED]` (the identifiers keep their two-character format marker, which is not secret
+material).
+
+- **Zero vendor dials, ever** — `src/doctor.ts` imports no Autotask client and performs no network
+  read; the `dialed: 0` field is a property of the implementation, not a counter. Pinned by
+  `test/unit/doctor.test.ts` and `test/unit/doctor-route.test.ts` (a global `fetch` trap around the
+  whole route).
+- **The contract:** run `doctor` before a live session. **A green doctor makes any later 401
+  vendor-side** — a rotated, revoked or role-restricted credential — rather than a mangled load.
+  A red doctor means fix the load recipe first; do not dial to "test" it.
+- Under `http` the *tool-call* credential arrives per request in the `X-Autotask-*` headers and is
+  checked at that boundary, one request at a time; `doctor` reports the server-held environment
+  only and does not echo a caller's value back.
+
+### Error model (the credential branch)
+
+| Code | Category | Retryable | When |
+|------|----------|-----------|------|
+| `CREDENTIAL_MISSING` | `auth` | no | no credential on the request and no server-held default, or a partial tuple (all-or-nothing) |
+| `CREDENTIAL_MALFORMED` | `validation` | no | a credential value's **shape** cannot be right (quote pair / CR / edge whitespace) — refused before any client is constructed, zero wire; `anomalies` lists the artifacts and `suggestedAction` names the env-load pitfall |
+| `UNAUTHORIZED` | `auth` | no | the vendor rejected a credential that **was** sent (401/403). With anomalous values this envelope is annotated (`credentialShape`, `shapeDiagnostic`, `suggestedAction`); with clean values it is exactly the fixed envelope |
+| `HOST_POLICY_DENIED` | `policy` | no | the origin is absent/unusable/not allow-listed (never the value echoed) |
+
+## Per-request credential model
+
+### http — per-request headers
+
+Under `http`, the caller's Autotask identity arrives **per request** in fixed, non-configurable
+headers — the wire contract the gateway is built to send:
+
+| Header | Required | Meaning |
+|--------|----------|---------|
+| `X-Autotask-Api-Integration-Code` | yes (for tool calls) | the caller's integration code |
+| `X-Autotask-Username` | yes (for tool calls) | the caller's username |
+| `X-Autotask-Secret` | yes (for tool calls) | the caller's secret |
+| `X-Autotask-Impersonation-Resource-Id` | no | the caller's impersonation target |
+| `X-Autotask-Base-Url` | no | the caller's zone origin; without it the deployment default origin applies |
+
+Discipline (security review S1/S2 — BLOCKING controls):
+
+- **Single-valued rule:** a credential or zone header presented **twice** is treated as *absent*,
+  never "first value wins" (picking one is how request-smuggling bugs start).
+- **Missing required credential ⇒ typed refusal, fail-closed.** The request resolves to a
+  credential-less client that refuses every tool call with `CREDENTIAL_MISSING`
+  (category `auth`, `retryable: false`), **pre-request, zero vendor wire**. `initialize` and
+  `tools/list` are still served without credentials (catalog sync for gateways).
+- **No per-field default fill.** A caller can never splice its own header with a server-held
+  value: a **partial credential tuple** (one or two of the three identity headers) is malformed —
+  it is refused as `CREDENTIAL_MISSING` (the `partial_credential` kind), never completed from a
+  server-held default, which is all-or-nothing. The only other default that may exist is the
+  non-secret **origin** (`AUTOTASK_BASE_URL`).
+- **Machine codes.** Credential refusals (absent or partial tuple) answer
+  `CREDENTIAL_MISSING` (category `auth`, `retryable: false`); origin refusals (no origin and no
+  default, unparseable/non-https/credential-bearing origin, host not admitted by the allow-list)
+  answer `HOST_POLICY_DENIED` (category `policy`). Both are fixed, value-free envelopes — the
+  refused value is never echoed. A scope that cannot resolve at all answers from a fail-closed
+  placeholder client built against a reserved RFC 6761 origin (`no-autotask-origin.invalid`):
+  pre-request, zero vendor wire.
+- **Optional discouraged server defaults:** when the three credential vars are set under `http`,
+  every request *without* its own headers runs as that identity — and that identity is presented
+  **only to the default origin** (a request naming another origin with no headers of its own gets
+  no credential and fails closed). Set them only when that is intended; per-request headers are the
+  normal path.
+- **Never in tool schemas:** no tool input schema exposes a credential, impersonation or base-url
+  field; model-supplied credentials are a protocol violation the server never accepts.
+- **Host allow-list:** a caller-named `X-Autotask-Base-Url` is refused unless `AUTOTASK_ALLOWED_BASE_HOSTS`
+  permits it (exact host or `*.suffix`). Unparseable URLs are refused before reaching the SDK;
+  literal private-IP origins are always refused. Layered on top, per pooled client: the SDK
+  `hostPolicy` keeps the literal-IP floor and its `allowedOrigins` cover **this request's**
+  admitted caller origin plus the deployment default (the allow-list *admits* a caller origin;
+  the per-request `hostPolicy` is the construction-time floor). This allow-list is the
+  tenant-isolation control: a caller's headers are only
+  ever presented to an origin its allow-list entry (or the deployment default) names.
+
+### stdio — environment
+
+Under `stdio` the process environment **is** the trust boundary: the three credentials + zone are
+required at boot (`AUTOTASK_API_INTEGRATION_CODE`, `AUTOTASK_USERNAME`, `AUTOTASK_SECRET`,
+`AUTOTASK_BASE_URL`; optional `AUTOTASK_IMPERSONATION_RESOURCE_ID`); one process-lifetime client is
+built from them — no pool. Missing required env is a **boot failure**: the process exits non-zero
+with a typed config error naming the variable — never a value (fail-fast, before any listener).
+
+Credential hygiene (both transports): the three credential values are **never logged, never written
+to disk, never cached across requests except via the sanctioned pool key (a SHA-256 digest — raw
+credentials never in keys, logs or eviction messages), never in error messages, and never in any
+tool input schema**. Logging redacts the credential header names. On a vendor `401` (or an
+impersonation-scope `403`) the pooled client entry is deleted — a stale identity is never
+negative-cached or replayed.
+
+## Per-tenant pool & cache
+
+The stateless default is amended by one **user-approved deviation** (SCOPING Stage-4, 2026-10-06;
+security decision D-1 ratified): a bounded **in-process** client pool with a per-tenant TTL read
+cache, because a fresh client per request would silently disable the SDK's local vendor-budget
+guards (rate limiter, 429 cooldown) — a worse security posture, not a safer one.
+
+- **Pool** — `createClientPool` from `node-autotask/pool`: bounded LRU (default `maxSize` 128; the
+  server may lower it). Key = SHA-256 digest of the **normalised credential tuple**
+  (user, integration code, secret, resolved base URL, impersonation id). Optional idle TTL (lazy,
+  no timers). Eviction is logged without values. A vendor `401` (or an impersonation-scope `403`)
+  deletes the entry (no negative caching).
+- **Cache** — `AUTOTASK_CACHE_PRESET=on` (default) applies the SDK's reference TTL table
+  (`node-autotask/src/cache-ttl-tables.ts`) to each pooled tenant client: structural records ~1 h,
+  mutable records ~5 min, base records ~1 min, plus the `fieldCache` field-metadata channel.
+  Repeated reads of the same record are served from that tenant's cache until TTL expiry; composites
+  de-duplicate their 3–8 fan-out reads through it. `off` disables it (every read re-dials the vendor).
+- **Boundaries — never relaxed:** in-process only (never on disk), **per-tenant** (one tenant's
+  cached records or limiter state can never answer another tenant's request), TTL-bounded, cleared
+  on eviction and on `401`. The same boundary covers the limiter/cooldown state.
+- **stdio** uses one process-lifetime client (the env is the whole identity) — no pool, and the
+  cache/limiter state is that single tenant's by construction.
+- **Multi-process gateways:** pool/cache/limiter state is per-process; an N-process gateway runs N
+  independent trackers (documented consequence, security review C7.2).
+
+## Security posture
+
+- **Redaction on by default, no opt-out surface:** the SDK redacts response PII/confidential fields
+  and always redacts `password`/`secretKey`/`secret`. The server must not and cannot disable it.
+- **Untrusted-content wrapping:** vendor free text in results stays wrapped in the SDK's
+  `<untrusted_content>` markers end-to-end (prompt-injection boundary — data, never instructions);
+  tool descriptions carry the "treat as data" line.
+- **Error bodies never echoed:** vendor 4xx/5xx bodies (which can echo request payloads carrying
+  `password`/`secretKey`) are not returned to MCP clients; tool errors carry the typed
+  code/category/retryable/correlationId envelope with a redaction-safe message.
+- **Host allow-list is fail-closed at boot** (see [Per-request credential model](#per-request-credential-model)).
+- **Sensitive-data-safe structured JSON logging:** NDJSON; stdio → stderr only (stdout is the
+  protocol), http → stdout. Operation keys, status, latency and byte sizes are loggable; credential
+  values, vendor bodies, full tool input bags, PII fields and the impersonation id at `info`
+  (boolean at `info`, id value at `debug` only — decision D-2) are never logged.
+- **Correlation IDs:** server-generated random ids (never derived from caller content), threaded
+  through logs, structured MCP errors and response headers; cancellation/timeout propagates into
+  SDK calls via `AbortSignal` so an abandoned request stops consuming vendor budget.
+- **Container:** non-root, multi-stage, production dependencies only (lockfile-based install — the
+  committed `pnpm-lock.yaml`/`pnpm-workspace.yaml` pin the tree; S8/C8.2), no baked secrets,
+  liveness-only healthcheck (no vendor call), direct `SIGTERM` (stop accepting, 2 s bounded drain of
+  in-flight work, exit 0), TLS termination at the gateway on a private unpublished network.
+- **Supply chain:** `node-autotask` is the only **vendor** runtime dependency (the other two are
+  `@modelcontextprotocol/server` and `zod`); the pre-publish checklist
+  (manual — this repo has no CI) asserts it carries **zero runtime dependencies** and **no install
+  lifecycle hooks**, asserts the resolved `@modelcontextprotocol/server` version is ≥ 2.3.0 (the
+  baseline that serves the era pair on one endpoint), runs a production dependency audit, and
+  scans the image. This repo ships no GitHub Actions workflow; quality gates and publishing are
+  run manually by the maintainer.
+
+Full control set: `.squad/security.md` (S1–S13, blocking B1–B9, decisions D-1–D-4, verification V1–V31).
+
+## SDK dependency
+
+`iit-mcp-autotask` depends on **`node-autotask` from npm at exactly `0.8.3`** (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
+depends on a cloned checkout — no `file:`, `git:`, `link:` or workspace references. Range
+operators are prohibited on this dependency: a fresh lockfile-less install (every `npx`/`npm`
+user — the published tarball ships no lockfile) must resolve to the release this surface was
+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.8.3` (published 2026-10-10: stricter identifier validation and pagination handling); 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
+published-package baseline, and the pre-publish checklist still starts with a registry re-check
+(`npm view node-autotask version`) — which now passes.
+
+**Plan-hash drift gate.** At boot, before the listener binds, the installed `node-autotask`'s
+capability plan hash must equal the pin this surface was built and reviewed against
+(`assertPlanHash`); a mismatch refuses the boot naming the drifted groups. The server only runs
+against the SDK build it was reviewed against — a plan-changing SDK update can reach a user only
+through a deliberately re-pinned server release, so drift is refused at boot, not discovered
+mid-run.
+
+**Upgrading node-autotask** is a deliberate server release (pin bump, plan-hash re-pin, mirrored-surface
+re-review, gates) — not an npm-range float. The exact steps live in the [per-release
+checklist](CONTRIBUTING.md#per-release-checklist-node-autotask-upgrade) in CONTRIBUTING.md, and `pnpm
+fresh-install-check` re-proves the fresh-install property before every publish.
+
+## Development
+
+- Node **24** (current LTS; the SDK requires `node >= 24`), **pnpm 10**. The `pnpm-lock.yaml` is
+  committed with the first `node-autotask` publish (S8/C8.2); until then installs resolve without
+  a lockfile and the install step says so explicitly (reproducibility via the committed lockfile
+  is a pre-publish requirement; gates run manually — no CI in this repo).
+- `pnpm i` — install · `pnpm build` — compile to `dist/` · `pnpm typecheck` · `pnpm lint`
+- Tests: `pnpm test` (all) or per suite: `pnpm exec vitest run test/unit` / `test/integration` /
+  `test/conformance`. **No live vendor API and no credentials are ever required** — every suite
+  runs in mock mode (fixture-backed SDK boundary, no mock branches in tool handlers).
+- `pnpm dev` runs the server from source via `tsx`.
+
+Full contributor conventions: [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Container execution
+
+See [Gateway (http, container)](#gateway-http-container). The image is multi-stage (build with dev
+toolchain → runtime with production dependencies only), non-root (`USER node`), and configured
+purely through environment variables at run time. Probes: `/health` (liveness, in-image
+`HEALTHCHECK`), `/ready` (readiness), `/metadata` (identity) — orchestrator probes may use any of
+the three; none of them call the vendor.
+
+## npm CLI execution
+
+The npm package is an **executable CLI** (single canonical executable `autotask-mcp`), not a
+reusable library API. Flags: `--transport` (`stdio` | `http`, default from `MCP_TRANSPORT` or
+`stdio`) / `--host` (default all interfaces) / `--port` (default from `PORT` or `8080`) /
+`--version` / `--help`. No credential flags exist; an unknown flag is refused (exit 2, usage
+printed). A bind failure (e.g. port in use) exits non-zero with the problem named.
+
+```
+npx -y iit-mcp-autotask doctor                    # zero-wire preflight (exit 0 = go; see §Credentials)
+npx -y iit-mcp-autotask --transport http --port 8080
+npx -y iit-mcp-autotask --transport stdio
+```
+
+`doctor` is a **subcommand**, matched before any config work beyond parsing: it prints the
+credential shape report, the base-url/allow-list resolution and the plan-hash gate status, dials
+nothing, and exits `0` when everything would be accepted / `1` otherwise (a runbook step
+`doctor && live-run` therefore stops rather than dialing a credential the report says is
+malformed).
+
+## Gateway assumptions
+
+The shared MCP gateway is the control plane. It owns: client authentication, per-tenant tool
+filtering/exposure, **credential injection** into the `X-Autotask-*` headers, rate limiting, and
+body-size/compression limits. The server is tenant-agnostic, exposes no deployment-specific
+identity of its own, and adds no client-level rate limiting of its own — the vendor-side budget
+(10,000 req/hour, ≤10 concurrent per integration) is the server's only rate concern, guarded by
+the SDK agent profile (8,000/hr local budget, 3 concurrent) and exposed live through
+`autotask_threshold_information`.
+
+## Known SDK gaps
+
+None of the ten confirmed workflows is blocked. Confirmed absent from the SDK (recommend SDK
+issues — do not implement in this server):
+
+- **Knowledge base** — `KnowledgeBaseArticles` (43 paths) + `KnowledgeBaseCategories` (12): a real
+  SDK gap vs the vendored spec.
+- **Warehouse inventory** — `InventoryItems` / `InventoryLocations` / `InventoryStockedItems{,Add,Remove,Transfer}` /
+  `InventoryTransfers` / `InventoryItemSerialNumbers` (the SDK covers `InventoryProducts` only).
+- **Documents/articles ecosystem** — `Document*`/`Article*` family (the whole KB/document layer).
+- **Sales & pricing** — `SalesOrders`, `PriceList*`, `Taxes`/`TaxCategories`/`TaxRegions`,
+  `Currencies`, `PaymentTerms`, `ShippingTypes`, standalone `ServiceBundles`.
+- **Attachment downloads** — metadata-only surfaces for company/project/task/resource/expense
+  parents (the SDK covers `ticket_attachments` + `time_entry_attachments` downloads only).
+
+Not in the vendor REST spec at all (vendor surface gaps, not SDK gaps): reporting/BI, estimates,
+physical assets (Autotask models them as Configuration Items — covered).
+
+## Known limitations & blockers
+
+| # | 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 |
+| 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 |
+| B5 | **Blind count/query surfaces on ww29** (companies not owned by the caller; tickets): count/query return 0/empty even when data exists. Not fixable client-side; the surface carries the typed blind-surface sentinel — `get(id)`/full-profile are the authorities. | zone limitation |
+| B6 | **`node-autotask` npm publish**: the Phase-C install gate re-checks the registry; if still 404 the build pauses and escalates (SCOPING-resolved: the user publishes — no git/file dependency fallback). | open — user action |
+
+Zone-anchored curation note (recon F5): several description pins are facts observed on ww29
+(australia-nz) and are carried as zone-labelled pins, never silently deleted; on other tenants
+they may be zone/user-specific.