node-autotask 0.21.0 → 0.23.0

package/examples/mcp/tools-read.ts

@@ -0,0 +1,264 @@
+/**
+ * tools-read.ts — the ten registry-backed core read tools (R2/R3/R4), their
+ * live dispatch (`coreReadCall`) and the untrusted-content projection
+ * (issue #1).
+ */
+import * as z from 'zod/v4';
+import { AutotaskConfigError } from 'node-autotask';
+import type { AutotaskClient } from 'node-autotask';
+import type { CapabilityRecord } from 'node-autotask/capabilities';
+import { resolveAny, searchAcrossResources } from 'node-autotask/operations';
+import { deepMarkUntrusted, markUntrusted } from 'node-autotask/untrusted';
+import { CATALOG, RECORD_BY_ID, annotationsFor, manifestDescription, untrustedFieldsOf } from './manifest.js';
+import type { CoreToolSpec } from './manifest.js';
+import { DRY_OUTPUT, EXPAND, IDENTIFIER, LIMIT, RESOURCES, closedInput, hitsOutput, modelOutput, oneOutput, resolveAnyOutput } from './schemas.js';
+import { closedArgsError, dryResult, errorContent, ok } from './errors.js';
+import type { ToolContext } from './types.js';
+
+export function registerReadTools({ server, client, dry, untrustedWrap }: ToolContext): void {
+  // ==========================================================================
+  // CORE READ TOOLS (R2 / R3 / R4) — the ten registry-backed core tools.
+  // Descriptions are the manifest's (manifestDescription); annotations derive
+  // from the registry record. Every handler: live call, or the DRY-mode
+  // validate-and-report answer. No tool is backed by queryAll/listPages.
+  // ==========================================================================
+
+  const registerCoreRead = (spec: CoreToolSpec, schema: z.ZodType, output: (rec: CapabilityRecord) => z.ZodType, text: (v: unknown) => string) => {
+    const opId = spec.backingOperation!;
+    const rec = RECORD_BY_ID.get(opId);
+    if (rec === undefined) throw new Error(`mcp-register: core tool "${spec.tool}" has no registry record for "${opId}"`);
+    // Issue #3: closed top level — the advertised schema carries
+    // additionalProperties: false and an unknown key is refused with the
+    // typed contract (never silently dropped), DRY and live alike.
+    const coreInput = closedInput(schema);
+    server.registerTool(
+      spec.tool,
+      {
+        title: titleFor(spec.tool, rec),
+        description: manifestDescription(spec.tool, opId),
+        inputSchema: coreInput.input,
+        outputSchema: z.union([output(rec), DRY_OUTPUT]),
+        annotations: annotationsFor(rec),
+        _meta: { backingOperation: opId, requirement: spec.requirement },
+      },
+      async (args, extra) => {
+        const closedErr = closedArgsError(args, coreInput.validKeys);
+        if (closedErr !== null) return closedErr;
+        if (dry || client === null) return dryResult(opId);
+        try {
+          const value = await client.withSignal(extra.mcpReq.signal, () => coreReadCall(client, opId, args as Record<string, unknown>));
+          // Issue #1: the projection layer wraps the externally-sourced free
+          // text AFTER the call (SDK primitives keep returning raw values) —
+          // compact AND expand: true alike (the expansion is a no-op for the
+          // five workflow resources, so one path covers both). The short
+          // summary text never echoes values, so it stays unwrapped.
+          const projected = projectUntrustedResult(opId, value, untrustedWrap ? untrustedFieldsOf(rec) : []);
+          return ok(text(projected), { ...(projected as Record<string, unknown>) });
+        } catch (err) {
+          return errorContent(err, untrustedWrap);
+        }
+      },
+    );
+  };
+
+  // R2 — identify itself to the tenant.
+  registerCoreRead(
+    coreSpec('autotask_resource_who_am_i')!,
+    z.object({}),
+    oneOutput,
+    (v) => (v === null ? 'No Resource matched the configured user.' : 'Authenticated integration identified.'),
+  );
+  registerCoreRead(
+    coreSpec('autotask_version')!,
+    z.object({}),
+    modelOutput,
+    () => 'API version in use returned.',
+  );
+  registerCoreRead(
+    coreSpec('autotask_threshold_information')!,
+    z.object({}),
+    modelOutput,
+    () => 'Request-threshold status returned.',
+  );
+
+  // R3 — find a record it cannot name.
+  registerCoreRead(
+    coreSpec('autotask_resolve_any')!,
+    z.object({ identifier: IDENTIFIER, resources: RESOURCES }),
+    resolveAnyOutput,
+    (v) => `${(v as { matches: string[] }).matches.length} resource(s) matched the identifier.`,
+  );
+  registerCoreRead(
+    coreSpec('autotask_search_across_resources')!,
+    z.object({ query: z.string().min(1).describe('The free text to search for.'), resources: RESOURCES, limit: LIMIT }),
+    hitsOutput,
+    (v) => `${(v as { results: Array<{ matches: unknown[] }> }).results.reduce((n, row) => n + row.matches.length, 0)} match(es) across ${(v as { results: unknown[] }).results.length} resource(s).`,
+  );
+
+  // R4 — one resolve per workflow resource.
+  for (const spec of CATALOG.coreProfile.tools.filter((t) => t.requirement === 'R4')) {
+    registerCoreRead(
+      spec,
+      z.object({ identifier: IDENTIFIER, expand: EXPAND }),
+      oneOutput,
+      (v) => (v === null ? 'No record matched the identifier.' : 'Record resolved (id + primary fields).'),
+    );
+  }
+}
+
+/** Look up a core spec by tool name (the generated core profile is the source). */
+function coreSpec(tool: string): CoreToolSpec | undefined {
+  return CATALOG.coreProfile.tools.find((t) => t.tool === tool);
+}
+
+/** A short human-readable display name for a registry-backed core tool. */
+function titleFor(_tool: string, rec: CapabilityRecord): string {
+  switch (rec.id) {
+    case 'resources.whoAmI': return 'Identify the Integration (whoAmI)';
+    case 'version.get': return 'API Version';
+    case 'threshold_information.get': return 'Request-Threshold Status';
+    case 'operations.resolveAny': return 'Resolve Any Workflow Record';
+    case 'operations.searchAcrossResources': return 'Search Across Workflow Resources';
+    default:
+      // The five R4 workflow resolves (operation verb `resolve`):
+      return `Resolve ${entityLabel(rec.resource)}`;
+  }
+}
+
+/** The entity label for the five workflow resources (the plan apiEntity names). */
+function entityLabel(resource: string): string {
+  const labels: Record<string, string> = {
+    companies: 'Company',
+    configuration_items: 'ConfigurationItem',
+    contacts: 'Contact',
+    projects: 'Project',
+    tickets: 'Ticket',
+  };
+  return labels[resource] ?? resource;
+}
+
+/**
+ * Issue #1 projection: wrap the externally-sourced free text of a helper
+ * tool result (the marker the LLM sees around ticket titles, notes, names,
+ * UDF values — never as instructions). Applied AFTER the SDK call returns
+ * (SDK primitives keep returning raw values — projection layer only) and to
+ * BOTH the compact and the `expand: true` result (for the five workflow
+ * resources the Summary is a structural alias of the full record, so one
+ * path covers both). `fields` empty (or wrapping disabled upstream) → the
+ * value passes through unchanged.
+ *
+ * Only the DATA payload is wrapped, never the server-generated envelope
+ * (the miss note, the match counts):
+ * - R4 resolve / whoAmI: the single `record`;
+ * - resolveAny: each `results[].value`;
+ * - searchAcrossResources: each `results[].matches[]` row.
+ * (The mode tools' `result` is envelope-shaped and is walked deeply instead
+ * — see the mode-tool handler.)
+ */
+export function projectUntrustedResult(opId: string, value: unknown, fields: readonly string[]): unknown {
+  if (!Array.isArray(fields) || fields.length === 0) return value;
+  const v = value as Record<string, unknown> | null;
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return value;
+  switch (opId) {
+    case 'operations.resolveAny':
+      return {
+        ...v,
+        results: (Array.isArray(v.results) ? v.results : []).map((row) =>
+          row !== null && typeof row === 'object' && !Array.isArray(row) && 'value' in row
+            ? { ...(row as Record<string, unknown>), value: deepMarkUntrusted((row as Record<string, unknown>).value, fields) }
+            : row,
+        ),
+      };
+    case 'operations.searchAcrossResources':
+      return {
+        ...v,
+        results: (Array.isArray(v.results) ? v.results : []).map((r) =>
+          r !== null && typeof r === 'object' && !Array.isArray(r)
+            ? {
+                ...(r as Record<string, unknown>),
+                matches: (Array.isArray((r as Record<string, unknown>).matches) ? ((r as Record<string, unknown>).matches as unknown[]) : []).map(
+                  (m) => (m !== null && typeof m === 'object' && !Array.isArray(m) ? markUntrusted(m as Record<string, unknown>, fields) : m),
+                ),
+              }
+            : r,
+        ),
+      };
+    default:
+      // R4 resolve / whoAmI: the single `record` (absent/null records pass
+      // through; non-record records are opaque).
+      if ('record' in v) {
+        return {
+          ...v,
+          record:
+            v.record !== null && typeof v.record === 'object' && !Array.isArray(v.record)
+              ? markUntrusted(v.record as Record<string, unknown>, fields)
+              : v.record,
+        };
+      }
+      return value;
+  }
+}
+
+/** The live-mode dispatch for the ten registry-backed core tools (helper tier only). Exported as the
+ * test seam (S12-E2E D1: the R4 miss-shape contract is pinned without a live tenant). */
+export async function coreReadCall(client: AutotaskClient, opId: string, args: Record<string, unknown>): Promise<unknown> {
+  switch (opId) {
+    case 'resources.whoAmI': {
+      const record = await client.resources.whoAmI();
+      return { found: record !== null, record };
+    }
+    case 'version.get':
+      return { model: await client.version.get() };
+    case 'threshold_information.get':
+      return { model: await client.thresholdInformation.get() };
+    case 'operations.resolveAny':
+      return resolveAny(client, args.identifier as number | string, { resources: args.resources as string[] | undefined });
+    case 'operations.searchAcrossResources':
+      return searchAcrossResources(client, args.query as string, {
+        resources: args.resources as string[] | undefined,
+        limit: args.limit as number | undefined,
+      });
+    default:
+      break;
+  }
+  // The five R4 workflow resolves share the same shape (helper tier, one call):
+  // route through the client accessor named by the resource key.
+  const resource = opId.split('.')[0]!;
+  const holder = (client as unknown as Record<string, {
+    resolveDetailed: (id: number | string) => Promise<{ value: unknown; triedFields?: string[] }>;
+  } | undefined>)[camelAccessor(resource)];
+  if (holder === undefined) {
+    // FULL100 F6 (second-pass MINOR): typed, not bare — the served-surface
+    // contract (F3) is that every isError the MCP layer serves carries a
+    // machine code; this branch is unreachable on the current registry
+    // (every read op's resource has a client accessor — sweep-verified) but
+    // must not regress the contract if the registry ever outgrows the client.
+    throw new AutotaskConfigError(
+      `mcp-register: the client exposes no accessor for resource "${resource}" (the SDK governor would refuse this dispatch too)`,
+      { operation: opId, suggestedAction: 'Rebuild the generated surface (npm run mcp:project) or the registry drifted from the client.' },
+    );
+  }
+  // resolveDetailed (not the plain resolve): a STRING miss returns value:null with the
+  // triedFields the exact match was run against — the tool carries that as the typed
+  // `miss` payload (a miss is never a bare zero). A numeric id miss still propagates
+  // the vendor's own typed NOT_FOUND (a miss that carries a fault is not a miss).
+  void args.expand; // the Summary is a structural alias of the full record (no-op, as before)
+  const res = await holder.resolveDetailed(args.identifier as number | string);
+  if (res.value === null) {
+    const tried = res.triedFields ?? [];
+    return {
+      found: false,
+      record: null,
+      miss: {
+        triedFields: tried,
+        note: `Exact match only against the primary text field(s): ${tried.join(', ') || 'id'}. No record matched — other identifier forms (e.g. an email address) are not tried by resolve; use the resource's dedicated lookup op where one exists (see autotask_catalog).`,
+      },
+    };
+  }
+  return { found: true, record: res.value };
+}
+
+/** snake_case resource key -> the client accessor name (the SDK's camelKey rule). */
+function camelAccessor(resource: string): string {
+  return resource.split('_').map((part, i) => (i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1))).join('');
+}

package/examples/mcp/types.ts

@@ -0,0 +1,34 @@
+/**
+ * types.ts — the shared shapes of the MCP reference registration: the
+ * structured tool result, the caller-facing deps, and the context handed to
+ * each tool group.
+ */
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { AutotaskClient } from 'node-autotask';
+
+export type ToolReturn =
+  | { content: Array<{ type: 'text'; text: string }>; structuredContent: Record<string, unknown> }
+  | { content: Array<{ type: 'text'; text: string }>; isError: true };
+
+export interface CoreToolDeps {
+  /** null in DRY mode (no credentials — the client refuses to construct fail-closed). */
+  client: AutotaskClient | null;
+  /** True when no credentials are present: registry-backed tools validate + report, never issue. */
+  dry: boolean;
+  /**
+   * Issue #1: untrusted-content wrapping for helper-tool results. Default
+   * (absent): ON unless `AUTOTASK_UNTRUSTED_WRAP=off` — the explicit env
+   * switch (option beats env). Disabling logs a warning on stderr (the stdio
+   * protocol rides stdout; the tag name is fixed).
+   */
+  untrustedWrap?: boolean;
+}
+
+/** What each tool group (`registerXxxTools`) receives: the server plus the resolved deps. */
+export interface ToolContext {
+  server: McpServer;
+  client: AutotaskClient | null;
+  dry: boolean;
+  /** Resolved (option, then env) — never undefined here. */
+  untrustedWrap: boolean;
+}