@tenonhq/dovetail-servicenow 0.0.15 → 0.0.16

package/dist/mcp/registry.d.ts

@@ -7,6 +7,7 @@
  * a client is injected via RegistryDeps (used by tests).
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import type { ServiceNowClient } from "../client";
 export declare var TOOL_NAMES: readonly ["create_view", "set_list_layout", "set_form_layout", "set_related_lists", "add_choices_to_field", "flow_view", "action_view", "flow_publish", "flow_copy", "flow_create", "flow_test", "flow_edit"];
@@ -19,6 +20,7 @@ export interface ToolDescriptor {
     name: ToolName;
     description: string;
     shape: z.ZodRawShape;
+    annotations: ToolAnnotations;
     handler: (args: any) => Promise<any>;
 }
 export declare function buildDescriptors(deps?: RegistryDeps): Array<ToolDescriptor>;

package/dist/mcp/registry.js

@@ -39,6 +39,20 @@ exports.TOOL_NAMES = [
     "flow_test",
     "flow_edit"
 ];
+// MCP tool annotations (spec 2025-11-25) — untrusted behavioural hints that let a
+// host parallelize reads and gate writes; never a security boundary. Five presets
+// cover every tool's safety profile:
+//   READ_ONLY                 — no writes; safe to auto-approve and run concurrently.
+//   WRITE_ADDITIVE_IDEMPOTENT — additive write, safe to repeat (idempotent upsert/create).
+//   WRITE_CREATE              — additive write, NOT idempotent (each call mints a new record).
+//   WRITE_OVERWRITE           — destructive but idempotent (prune/overwrite: same end state).
+//   WRITE_EXECUTE             — destructive AND non-idempotent (runs a flow; repeating repeats the effect).
+// openWorldHint is left at its spec default (true) — every tool reaches a ServiceNow instance.
+var READ_ONLY = { readOnlyHint: true };
+var WRITE_ADDITIVE_IDEMPOTENT = { readOnlyHint: false, destructiveHint: false, idempotentHint: true };
+var WRITE_CREATE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false };
+var WRITE_OVERWRITE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true };
+var WRITE_EXECUTE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false };
 function buildDescriptors(deps = {}) {
     function client() {
         return deps.client || (0, client_1.createClient)({});
@@ -46,6 +60,7 @@ function buildDescriptors(deps = {}) {
     return [
         {
             name: "create_view",
+            annotations: WRITE_ADDITIVE_IDEMPOTENT,
             description: "Create a ServiceNow custom view (sys_ui_view). Idempotent — an existing view of the "
                 + "same name is returned unchanged. Every write is captured in the supplied update set.",
             shape: schemas_1.createViewSchema.shape,
@@ -55,6 +70,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "set_list_layout",
+            annotations: WRITE_OVERWRITE,
             description: "Declaratively set a ServiceNow list layout — which columns appear in a list, and their "
                 + "order — for a table + view. Idempotent; prune (default true) removes columns not in "
                 + "the spec; dryRun previews without writing. Writes are captured in the update set.",
@@ -65,6 +81,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "set_form_layout",
+            annotations: WRITE_OVERWRITE,
             description: "Declaratively set a ServiceNow form layout — sections and the fields within them — for "
                 + "a table + view. The first section is the primary section (omit its caption). "
                 + "Idempotent; prune (default true) removes sections/fields not in the spec; dryRun "
@@ -76,6 +93,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "set_related_lists",
+            annotations: WRITE_OVERWRITE,
             description: "Declaratively set which related lists appear on a ServiceNow form for a table + view. "
                 + "Related-list ids are \"<table>.<field>\" or \"REL:<sys_relationship>\". Idempotent; "
                 + "prune (default true); dryRun previews. Writes are captured in the update set.",
@@ -86,6 +104,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "add_choices_to_field",
+            annotations: WRITE_ADDITIVE_IDEMPOTENT,
             description: "Upsert sys_choice values for a ServiceNow table.column and (optionally) flip "
                 + "sys_dictionary.choice so the field renders as a dropdown. Idempotent. Writes are "
                 + "captured in the supplied update set.",
@@ -96,6 +115,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_view",
+            annotations: READ_ONLY,
             description: "Read a ServiceNow Flow Designer flow or subflow's compiled step graph, headless. "
                 + "Returns the ordered, nesting-aware list of action + flow-logic steps plus the flow "
                 + "variables, via GET /api/now/processflow/flow/{sysId}. Read-only. Pass raw:true to "
@@ -108,6 +128,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "action_view",
+            annotations: READ_ONLY,
             description: "Read a ServiceNow Custom Action Type's compiled model (identity, inputs, outputs), "
                 + "headless, via GET /api/now/processflow/action/action_types/{sysId}. Read-only. "
                 + "sysId is the sys_hub_action_type_definition sys_id; scopeSysId is the application "
@@ -120,6 +141,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_publish",
+            annotations: WRITE_OVERWRITE,
             description: "Publish (compile the snapshot of) a ServiceNow Flow Designer flow or subflow via "
                 + "POST /api/now/processflow/flow/{sysId}/snapshot. This is a WRITE that recompiles the "
                 + "flow's current design — use after editing in the Designer. sysId is the sys_hub_flow "
@@ -132,6 +154,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_copy",
+            annotations: WRITE_CREATE,
             description: "Copy a ServiceNow flow/subflow via the Designer's Copy endpoint — a complete, faithful "
                 + "clone created as an INACTIVE DRAFT in the target scope. sourceSysId is the sys_hub_flow "
                 + "to copy; newName is the copy's name; scopeSysId defaults to the source's scope. Publish "
@@ -145,6 +168,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_create",
+            annotations: WRITE_CREATE,
             description: "Create a NEW ServiceNow Flow Designer flow (sys_hub_flow, type=flow) from scratch and "
                 + "PUBLISH it, headless. Mints a fresh flow via POST /processflow/flow, grafts the trigger + "
                 + "action graph from an existing published template flow (templateSysId), then compiles the "
@@ -174,6 +198,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_test",
+            annotations: WRITE_EXECUTE,
             description: "Test or run a ServiceNow flow/subflow. mode='validate' (default) is a safe, read-only "
                 + "pre-flight — checks the flow is published and that supplied inputs match its declared "
                 + "variables; it never runs the flow. mode='execute' actually runs it via the server-side "
@@ -194,6 +219,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_edit",
+            annotations: WRITE_OVERWRITE,
             description: "Edit a ServiceNow flow/subflow in place. Supports rename (name/internalName), description, "
                 + "and patchStepInputs (set named input values on steps by uiId or label). apply=false "
                 + "(default) is a dry-run that returns the diff; apply=true persists the edit (a write). "
@@ -221,7 +247,7 @@ function registerAllTools(server, deps = {}) {
     }
 }
 function registerOne(server, desc) {
-    server.registerTool(desc.name, { description: desc.description, inputSchema: desc.shape }, async function (args) {
+    server.registerTool(desc.name, { description: desc.description, inputSchema: desc.shape, annotations: desc.annotations }, async function (args) {
         try {
             var result = await desc.handler(args);
             return { content: [{ type: "text", text: JSON.stringify(result) }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-servicenow",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "engines": {
     "node": ">=22"
   },