@tenonhq/dovetail-servicenow 0.0.25 → 0.0.26

package/README.md

@@ -319,6 +319,39 @@ var r = await setField({
 console.log(r.status, r.verified); // "applied" true
 ```
 
+### Invoke an arbitrary REST operation
+
+Invoke any authenticated ServiceNow REST operation — an application's own
+Scripted REST endpoints (`sys_ws_operation` at `/api/<scope>/<service>/<resource>`)
+included — with GET, POST, PUT or DELETE. This is the transport primitive for
+operations the fixed verbs can't express, and the only surface with PUT/DELETE
+coverage (a verification harness that cleans up after itself needs the DELETE).
+
+```bash
+# Dry-run — the DEFAULT: echoes method + path + body, sends NOTHING
+npx dove-sn invoke-rest --method DELETE \
+  --path /api/x_cadso_core/testkit/resource/<sys_id>
+
+# Send for real
+npx dove-sn invoke-rest --method PUT \
+  --path /api/x_cadso_core/testkit/resource/<sys_id> \
+  --body '{"name":"updated"}' --confirm --json
+```
+
+`invoke-rest` is **dry-run by default** — nothing is sent without `--confirm`
+(`--dry-run` forces a dry-run even with it). On send the response passes through
+**verbatim** as `{ httpStatus, ok, body }`: non-2xx responses are returned, not
+thrown, so the operation's own error contract survives (the transport still
+retries 429/5xx first). The path must be instance-relative and start with
+`/api/`. **Bodies are never printed in human output** — request or response,
+dry-run or sent: method, path and status only. The structured `--json` result
+is the one channel that carries them (a dry-run's `requestBody` echo lives
+there). Exit codes: `0` dry-run or 2xx, `1` bad args, `2` sent but non-2xx.
+
+Programmatic: `invokeRest({ method, path, body, confirm })` is exported, and the
+client gained `now.put` / `now.delete` / `now.invoke` (the latter returns
+`{ status, body }` verbatim) alongside the existing `now.get` / `now.post`.
+
 `test-flow` defaults to **validate** — a safe pre-flight (published? inputs match
 declared variables?) that never runs the flow; `--execute --confirm` runs it via
 the server-side FlowAPI runner (deploy `resources/runFlow.md` first).
@@ -397,8 +430,10 @@ tools `flow_view` (read a flow/subflow's step graph), `action_view` (read an act
 type's model), `flow_publish` (compile a flow/subflow snapshot), `flow_copy`
 (copy a flow as an inactive draft), `flow_create` (create a NEW flow from scratch +
 publish, grafting a template), `flow_test` (validate or run a flow), and
-`flow_edit` (patch a flow). It reads ServiceNow credentials from the same env
-vars as the CLI.
+`flow_edit` (patch a flow), plus `invoke_rest` (invoke an arbitrary authenticated
+REST operation — Scripted REST included — with GET/POST/PUT/DELETE; dry-run by
+default, response passed through verbatim, bodies never logged). It reads
+ServiceNow credentials from the same env vars as the CLI.
 
 ```bash
 npx dove-sn mcp --smoke   # list the registered tools and exit

package/dist/cli.js

@@ -81,6 +81,7 @@ const testFlow_1 = require("./flowDesigner/testFlow");
 const table_1 = require("./table");
 const setField_1 = require("./setField");
 const createRecord_1 = require("./createRecord");
+const invokeRest_1 = require("./invokeRest");
 const hostAssets_1 = require("./hostAssets");
 const flowDesigner_formatter_2 = require("./flowDesigner-formatter");
 function parseArgs(argv) {
@@ -719,6 +720,10 @@ function printHelp() {
         "  create-record      Create ONE NEW record in a data table, into an update set, then verify\n" +
         "                     (--table <t> --fields \"k=v,k2=v2\" --scope <s> --update-set <sys_id>\n" +
         "                      [--if-absent <encoded-query>] [--dry-run] [--json])\n" +
+        "  invoke-rest        Invoke an arbitrary authenticated REST operation (Scripted REST incl.)\n" +
+        "                     DRY-RUN BY DEFAULT — nothing is sent without --confirm\n" +
+        "                     (--method <GET|POST|PUT|DELETE> --path /api/<scope>/<service>/<resource>\n" +
+        "                      [--body '<json>' | --body-json <path>] [--confirm] [--dry-run] [--json])\n" +
         "  host-assets        Deploy a built dist/ to ServiceNow (carrier sys_ui_script + attachment + m2m)\n" +
         "                     (--dir <dist> --app <sys_id> --scope <namespace>\n" +
         "                      [--update-set <sys_id>] [--max-bytes <n>] [--allow-oversize] [--dry-run] [--json])\n" +
@@ -988,6 +993,80 @@ async function runCreateRecord(flags) {
         return 2;
     return 0;
 }
+/**
+ * dove-sn invoke-rest:
+ *   --method <GET|POST|PUT|DELETE>  Required.
+ *   --path </api/...>       Required. Instance-relative; must start with /api/.
+ *   --body '<json>'         Optional inline JSON body (or --body-json <path>).
+ *   --confirm               Send for real. WITHOUT it the command is a DRY-RUN.
+ *   --dry-run               Force a dry-run even with --confirm.
+ *   --json                  Emit the structured InvokeRestResult.
+ *
+ * Invoke an arbitrary authenticated REST operation (Scripted REST included).
+ * Dry-run by default; --confirm sends and returns { httpStatus, ok, body } with
+ * the response passed through verbatim (non-2xx included — the transport still
+ * retries 429/5xx first). Bodies are NEVER printed in human output — request or
+ * response, dry-run or sent: method, path and status only. The structured
+ * --json result is the one channel that carries them (a dry-run's requestBody
+ * echo satisfies the #212 "echo the plan" gate there).
+ * Exit codes: 0 dry-run or 2xx, 1 bad args, 2 sent but non-2xx.
+ */
+async function runInvokeRest(flags) {
+    if (!flags.method || !flags.path) {
+        process.stderr.write("invoke-rest: --method <GET|POST|PUT|DELETE> and --path </api/...> are required\n");
+        return 1;
+    }
+    var body;
+    if (flags["body-json"]) {
+        try {
+            body = JSON.parse(fs.readFileSync(flags["body-json"], "utf8"));
+        }
+        catch (err) {
+            process.stderr.write("invoke-rest: --body-json must point to a readable JSON file: "
+                + (err && err.message ? err.message : String(err)) + "\n");
+            return 1;
+        }
+    }
+    else if (flags.body !== undefined) {
+        try {
+            body = JSON.parse(flags.body);
+        }
+        catch (err) {
+            process.stderr.write("invoke-rest: --body must be valid JSON: " + err.message + "\n");
+            return 1;
+        }
+    }
+    var params = {
+        method: flags.method,
+        path: flags.path,
+        confirm: flags.confirm === "true",
+        dryRun: flags["dry-run"] === "true"
+    };
+    if (body !== undefined) {
+        params.body = body;
+    }
+    var result = await (0, invokeRest_1.invokeRest)(params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else if (result.status === "dry-run") {
+        process.stdout.write("[dry-run] " + result.method + " " + result.path + "\n"
+            + (result.requestBody !== undefined
+                ? "Request body withheld from human output — use --json to view.\n"
+                : "")
+            + result.note + "\n");
+    }
+    else {
+        // Bodies are never logged: human output is method + path + status only.
+        process.stdout.write("[sent] " + result.method + " " + result.path + " -> HTTP " + result.httpStatus
+            + (result.ok ? "" : " (non-2xx)") + "\n"
+            + "Response body withheld from human output — use --json for { httpStatus, ok, body }.\n");
+    }
+    if (result.status === "sent" && result.ok !== true) {
+        return 2;
+    }
+    return 0;
+}
 /**
  * dove-sn host-assets:
  *   --dir <dist>            Required. Path to the pre-built dist/ directory.
@@ -1070,6 +1149,9 @@ async function main() {
     if (parsed.command === "create-record") {
         return await runCreateRecord(parsed.flags);
     }
+    if (parsed.command === "invoke-rest") {
+        return await runInvokeRest(parsed.flags);
+    }
     if (parsed.command === "host-assets") {
         return await runHostAssets(parsed.flags);
     }

package/dist/client.d.ts

@@ -43,6 +43,20 @@ export interface AttachmentMeta {
     hash?: string;
     size_bytes?: string;
 }
+export type NowInvokeMethod = "GET" | "POST" | "PUT" | "DELETE";
+export interface NowInvokeParams {
+    method: NowInvokeMethod;
+    /** Instance-relative path, e.g. /api/x_cadso_core/<service>/<resource>. */
+    path: string;
+    /** JSON request body for POST/PUT/DELETE. Ignored for GET. */
+    body?: unknown;
+}
+export interface NowInvokeResponse {
+    /** HTTP status code of the final response (after any 429/5xx retries). */
+    status: number;
+    /** Response body, verbatim. */
+    body: unknown;
+}
 export interface ServiceNowClient {
     table: {
         /** GET /api/now/table/<t>?sysparm_query=...&sysparm_limit=N — returns result array. */
@@ -121,6 +135,21 @@ export interface ServiceNowClient {
         get: <T = any>(path: string) => Promise<T>;
         /** POST an arbitrary native ServiceNow REST path with a JSON body. See `get`. */
         post: <T = any>(path: string, body: any) => Promise<T>;
+        /** PUT an arbitrary native ServiceNow REST path with a JSON body. See `get`. */
+        put: <T = any>(path: string, body: any) => Promise<T>;
+        /** DELETE an arbitrary native ServiceNow REST path (optional JSON body). See `get`. */
+        delete: <T = any>(path: string, body?: any) => Promise<T>;
+        /**
+         * Invoke an arbitrary native ServiceNow REST path with an explicit method and
+         * get the HTTP response back verbatim as { status, body }. Unlike get/post/
+         * put/delete, non-2xx responses are RETURNED, not thrown, so callers (the
+         * dove-sn invoke-rest verb / invoke_rest MCP tool) can pass a Scripted REST
+         * operation's own error contract through faithfully. Same auth/retry/throttle
+         * transport: 429/5xx are retried per the client config and the LAST response
+         * is returned when retries are exhausted; only a network failure (no HTTP
+         * response at all) throws.
+         */
+        invoke: (params: NowInvokeParams) => Promise<NowInvokeResponse>;
     };
     attachment: {
         /**

package/dist/client.js

@@ -110,7 +110,15 @@ function createClient(config = {}) {
     // Latch the legacy flag after the first 404 to avoid paying the round-trip
     // cost on every subsequent call.
     var useDovetailLegacyPath = false;
-    async function request(cfg, ctx) {
+    /**
+     * Shared transport loop: throttle, send, retry 429/5xx, and surface auth/404
+     * failures as clear errors. With `passThrough`, any HTTP response that would
+     * normally throw (or that exhausted its retries) is RETURNED as
+     * { status, data } instead — only a network failure (no HTTP response at all)
+     * still throws. now.invoke uses passThrough to hand a Scripted REST
+     * operation's own error contract back verbatim.
+     */
+    async function requestRaw(cfg, ctx, passThrough) {
         var attempt429 = 0;
         var attempt5xx = 0;
         // eslint-disable-next-line no-constant-condition
@@ -132,14 +140,10 @@ function createClient(config = {}) {
                 await sleep(Math.pow(2, attempt5xx) * 1000);
                 continue;
             }
-            if (res.status === 401 || res.status === 403) {
-                throw new Error("SN auth error " + res.status + " on " + ctx + " — check SN_USER/SN_PASSWORD and ACLs.");
-            }
-            if (res.status === 404) {
-                throw new Error("SN 404 on " + ctx + " — endpoint or record not found.");
-            }
             if (res.status === 429) {
                 if (attempt429 >= max429) {
+                    if (passThrough)
+                        return { status: res.status, data: res.data };
                     throw new Error("SN 429 rate limit — retries exhausted on " + ctx);
                 }
                 attempt429 += 1;
@@ -148,19 +152,34 @@ function createClient(config = {}) {
             }
             if (res.status >= 500) {
                 if (attempt5xx >= max5xx) {
+                    if (passThrough)
+                        return { status: res.status, data: res.data };
                     throw new Error("SN " + res.status + " on " + ctx + " — retries exhausted.");
                 }
                 attempt5xx += 1;
                 await sleep(Math.pow(2, attempt5xx) * 1000);
                 continue;
             }
+            if (passThrough) {
+                return { status: res.status, data: res.data };
+            }
+            if (res.status === 401 || res.status === 403) {
+                throw new Error("SN auth error " + res.status + " on " + ctx + " — check SN_USER/SN_PASSWORD and ACLs.");
+            }
+            if (res.status === 404) {
+                throw new Error("SN 404 on " + ctx + " — endpoint or record not found.");
+            }
             if (res.status < 200 || res.status >= 300) {
                 var body = typeof res.data === "string" ? res.data : JSON.stringify(res.data);
                 throw new Error("SN " + res.status + " on " + ctx + ": " + body.substring(0, 400));
             }
-            return res.data;
+            return { status: res.status, data: res.data };
         }
     }
+    async function request(cfg, ctx) {
+        var raw = await requestRaw(cfg, ctx);
+        return raw.data;
+    }
     // Dovetail core Scripted REST API request: try /api/cadso/dovetail_core/<op>,
     // fall back to the legacy /api/cadso/dovetail/<op> on 404 (one-time warning).
     async function dovetailRequest(method, op, body, params, ctx) {
@@ -315,6 +334,21 @@ function createClient(config = {}) {
             },
             post: function (path, body) {
                 return request({ method: "POST", url: path, data: body }, "now.post(" + path + ")");
+            },
+            put: function (path, body) {
+                return request({ method: "PUT", url: path, data: body }, "now.put(" + path + ")");
+            },
+            delete: function (path, body) {
+                return request({ method: "DELETE", url: path, data: body }, "now.delete(" + path + ")");
+            },
+            invoke: async function (params) {
+                var cfg = { method: params.method, url: params.path };
+                // Per NowInvokeParams: body is ignored for GET — never attach a GET payload.
+                if (params.method !== "GET" && params.body !== undefined) {
+                    cfg.data = params.body;
+                }
+                var raw = await requestRaw(cfg, "now.invoke(" + params.method + " " + params.path + ")", true);
+                return { status: raw.status, body: raw.data };
             }
         },
         attachment: {

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  */
 export { createClient } from "./client";
 export { createClientFromEnvFile, resolveConfigFromEnvFile } from "./createClientFromEnvFile";
-export type { ServiceNowClient, TableQueryOptions, TableSchema, TableSchemaField, AttachmentMeta } from "./client";
+export type { ServiceNowClient, TableQueryOptions, TableSchema, TableSchemaField, AttachmentMeta, NowInvokeMethod, NowInvokeParams, NowInvokeResponse } from "./client";
 export { addChoicesToField } from "./choices";
 export { hostAssets, classifyChunks, formatHostAssetsResult } from "./hostAssets";
 export { formatAddChoicesResult } from "./formatter";
@@ -25,3 +25,5 @@ export { setField } from "./setField";
 export { createRecord } from "./createRecord";
 export type { RecordWriteResult, SetFieldParams, SetFieldResult } from "./setField";
 export type { CreateRecordParams, CreateRecordResult } from "./createRecord";
+export { invokeRest, INVOKE_REST_METHODS } from "./invokeRest";
+export type { InvokeRestParams, InvokeRestResult } from "./invokeRest";

package/dist/index.js

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRecord = exports.setField = exports.applyAddColumnOverlay = exports.deriveElement = exports.addColumn = exports.DEFAULT_SAVE_ACTION = exports.DEFAULT_SUPER_CLASS = exports.TYPE_MAP = exports.defaultAccessFlags = exports.applyTableSaveOverlay = exports.resolveType = exports.normalizeColumns = exports.buildColumnXml = exports.projectTableGraph = exports.createTable = exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.editActionType = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = exports.sincPlugin = exports.formatCreateViewResult = exports.formatLayoutResult = exports.setRelatedLists = exports.setFormLayout = exports.setListLayout = exports.createView = exports.formatAddChoicesResult = exports.formatHostAssetsResult = exports.classifyChunks = exports.hostAssets = exports.addChoicesToField = exports.resolveConfigFromEnvFile = exports.createClientFromEnvFile = exports.createClient = void 0;
+exports.INVOKE_REST_METHODS = exports.invokeRest = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
 var createClientFromEnvFile_1 = require("./createClientFromEnvFile");
@@ -72,3 +73,6 @@ var setField_1 = require("./setField");
 Object.defineProperty(exports, "setField", { enumerable: true, get: function () { return setField_1.setField; } });
 var createRecord_1 = require("./createRecord");
 Object.defineProperty(exports, "createRecord", { enumerable: true, get: function () { return createRecord_1.createRecord; } });
+var invokeRest_1 = require("./invokeRest");
+Object.defineProperty(exports, "invokeRest", { enumerable: true, get: function () { return invokeRest_1.invokeRest; } });
+Object.defineProperty(exports, "INVOKE_REST_METHODS", { enumerable: true, get: function () { return invokeRest_1.INVOKE_REST_METHODS; } });

package/dist/invokeRest.d.ts

@@ -0,0 +1,50 @@
+/**
+ * dove-sn invoke-rest — invoke an arbitrary authenticated ServiceNow REST
+ * operation (an application's own Scripted REST endpoints included) with
+ * GET / POST / PUT / DELETE. The transport primitive behind the invoke_rest
+ * MCP tool (TenonHQ/Dovetail#212).
+ *
+ * DRY-RUN BY DEFAULT: without confirm:true the resolved method + path + body
+ * are echoed back and nothing is sent (no client, no credentials needed).
+ * On confirm the response comes back verbatim as { httpStatus, ok, body } —
+ * non-2xx responses are returned, not thrown, so a Scripted REST operation's
+ * own error contract passes through faithfully (the transport still retries
+ * 429/5xx first).
+ *
+ * PRIVACY: these endpoints carry caller payloads. This module never logs a
+ * request or response body — no console output, no debug files; bodies exist
+ * only in the returned result. Any log line about an invocation elsewhere must
+ * carry method, path and status ONLY.
+ */
+import type { NowInvokeMethod, ServiceNowClient } from "./client";
+export declare var INVOKE_REST_METHODS: Array<NowInvokeMethod>;
+export interface InvokeRestParams {
+    /** Optional client injection (tests / reuse). Only resolved on the send path —
+     *  a dry-run needs no credentials. */
+    client?: ServiceNowClient;
+    /** HTTP method — GET, POST, PUT or DELETE (case-insensitive). */
+    method: string;
+    /** Instance-relative path; must start with /api/ (e.g. /api/x_cadso_core/<service>/<resource>). */
+    path: string;
+    /** JSON request body for POST/PUT/DELETE. Rejected for GET. */
+    body?: unknown;
+    /** The send gate: the request is only sent when confirm is exactly true. */
+    confirm?: boolean;
+    /** Force a dry-run even when confirm is set. */
+    dryRun?: boolean;
+}
+export interface InvokeRestResult {
+    status: "dry-run" | "sent";
+    method: NowInvokeMethod;
+    path: string;
+    /** Echo of the request body (present when one was supplied) so the plan is auditable. */
+    requestBody?: unknown;
+    /** HTTP status of the response (sent only). */
+    httpStatus?: number;
+    /** True when httpStatus is 2xx (sent only). */
+    ok?: boolean;
+    /** Response body, verbatim (sent only). */
+    body?: unknown;
+    note: string;
+}
+export declare function invokeRest(params: InvokeRestParams): Promise<InvokeRestResult>;

package/dist/invokeRest.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * dove-sn invoke-rest — invoke an arbitrary authenticated ServiceNow REST
+ * operation (an application's own Scripted REST endpoints included) with
+ * GET / POST / PUT / DELETE. The transport primitive behind the invoke_rest
+ * MCP tool (TenonHQ/Dovetail#212).
+ *
+ * DRY-RUN BY DEFAULT: without confirm:true the resolved method + path + body
+ * are echoed back and nothing is sent (no client, no credentials needed).
+ * On confirm the response comes back verbatim as { httpStatus, ok, body } —
+ * non-2xx responses are returned, not thrown, so a Scripted REST operation's
+ * own error contract passes through faithfully (the transport still retries
+ * 429/5xx first).
+ *
+ * PRIVACY: these endpoints carry caller payloads. This module never logs a
+ * request or response body — no console output, no debug files; bodies exist
+ * only in the returned result. Any log line about an invocation elsewhere must
+ * carry method, path and status ONLY.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INVOKE_REST_METHODS = void 0;
+exports.invokeRest = invokeRest;
+const client_1 = require("./client");
+exports.INVOKE_REST_METHODS = ["GET", "POST", "PUT", "DELETE"];
+function normalizeMethod(method) {
+    var raw = typeof method === "string" ? method.toUpperCase() : "";
+    if (exports.INVOKE_REST_METHODS.indexOf(raw) === -1) {
+        throw new Error("invoke-rest: method must be one of GET, POST, PUT, DELETE (got '"
+            + String(method) + "').");
+    }
+    return raw;
+}
+function validatePath(path) {
+    if (typeof path !== "string" || path.length === 0) {
+        throw new Error("invoke-rest: path is required.");
+    }
+    if (path.indexOf("/api/") !== 0) {
+        throw new Error("invoke-rest: path must be instance-relative and start with /api/ (got '"
+            + path + "'). Absolute URLs are not accepted — the client's base URL supplies the instance.");
+    }
+    if (/\s/.test(path)) {
+        throw new Error("invoke-rest: path must not contain whitespace — URL-encode query values.");
+    }
+    return path;
+}
+async function invokeRest(params) {
+    if (!params || typeof params !== "object") {
+        throw new Error("invoke-rest: params object is required.");
+    }
+    var method = normalizeMethod(params.method);
+    var path = validatePath(params.path);
+    if (method === "GET" && params.body !== undefined) {
+        throw new Error("invoke-rest: a request body is not allowed with GET.");
+    }
+    var send = params.confirm === true && params.dryRun !== true;
+    if (!send) {
+        var dry = {
+            status: "dry-run",
+            method: method,
+            path: path,
+            note: "dry-run (the default): nothing was sent. Would " + method + " " + path
+                + (params.body !== undefined ? " with the supplied JSON body" : " with no body")
+                + ". Re-run with confirm to send."
+        };
+        if (params.body !== undefined) {
+            dry.requestBody = params.body;
+        }
+        return dry;
+    }
+    // Client is resolved only here so a dry-run never needs credentials.
+    var client = params.client || (0, client_1.createClient)({});
+    var response = await client.now.invoke({ method: method, path: path, body: params.body });
+    var ok = response.status >= 200 && response.status < 300;
+    var result = {
+        status: "sent",
+        method: method,
+        path: path,
+        httpStatus: response.status,
+        ok: ok,
+        body: response.body,
+        note: ok
+            ? "Sent " + method + " " + path + " — HTTP " + response.status + "."
+            : "Sent " + method + " " + path + " — HTTP " + response.status
+                + " (non-2xx returned verbatim"
+                + (response.status === 401 || response.status === 403
+                    ? "; if unexpected, check SN_USER/SN_PASSWORD and ACLs" : "")
+                + ")."
+    };
+    if (params.body !== undefined) {
+        result.requestBody = params.body;
+    }
+    return result;
+}

package/dist/mcp/registry.d.ts

@@ -10,7 +10,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { ToolAnnotations } from "@tenonhq/dovetail-mcp-kit";
 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", "create_table", "add_column", "set_field", "create_record", "host_assets"];
+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", "create_table", "add_column", "set_field", "create_record", "host_assets", "invoke_rest"];
 export type ToolName = typeof TOOL_NAMES[number];
 export interface RegistryDeps {
     /** Optional client injection for tests; defaults to createClient({}). */

package/dist/mcp/registry.js

@@ -29,6 +29,7 @@ const table_1 = require("../table");
 const hostAssets_1 = require("../hostAssets");
 const setField_1 = require("../setField");
 const createRecord_1 = require("../createRecord");
+const invokeRest_1 = require("../invokeRest");
 const schemas_1 = require("./schemas");
 exports.TOOL_NAMES = [
     "create_view",
@@ -47,7 +48,8 @@ exports.TOOL_NAMES = [
     "add_column",
     "set_field",
     "create_record",
-    "host_assets"
+    "host_assets",
+    "invoke_rest"
 ];
 // Annotation presets (READ_ONLY / WRITE_ADDITIVE_IDEMPOTENT / WRITE_CREATE /
 // WRITE_OVERWRITE / WRITE_EXECUTE) come from @tenonhq/dovetail-mcp-kit.
@@ -367,6 +369,38 @@ function buildDescriptors(deps = {}) {
             handler: async function (args) {
                 return (0, hostAssets_1.hostAssets)(client(), schemas_1.hostAssetsSchema.parse(args));
             }
+        },
+        {
+            name: "invoke_rest",
+            annotations: dovetail_mcp_kit_1.WRITE_EXECUTE,
+            description: "Invoke an arbitrary authenticated ServiceNow REST operation — including an application's "
+                + "own Scripted REST endpoints (/api/<scope>/<service>/<resource>) — with GET, POST, PUT or "
+                + "DELETE. A transport primitive: it can drive update and DELETE operations, so it is "
+                + "destructive-capable and non-idempotent. DRY-RUN BY DEFAULT — without confirm:true nothing "
+                + "is sent and the resolved method + path + body are echoed back; dryRun:true forces a "
+                + "dry-run even with confirm. On send, returns { httpStatus, ok, body } with the response "
+                + "passed through verbatim — non-2xx responses are returned, not thrown, so the operation's "
+                + "own error contract is preserved (429/5xx are retried by the transport first). path must "
+                + "be instance-relative and start with /api/. Request/response bodies are never logged — "
+                + "they exist only in this result. For sys_* / x_* record CRUD use set_field / "
+                + "create_record instead; this tool is for operations those fixed verbs cannot express.",
+            shape: schemas_1.invokeRestSchema.shape,
+            handler: async function (args) {
+                var p = schemas_1.invokeRestSchema.parse(args);
+                var params = {
+                    method: p.method,
+                    path: p.path,
+                    body: p.body,
+                    confirm: p.confirm,
+                    dryRun: p.dryRun
+                };
+                // Client resolution is lazy: a dry-run needs no credentials, so only
+                // attach one when injected (tests) — invokeRest creates its own on send.
+                if (deps.client) {
+                    params.client = deps.client;
+                }
+                return (0, invokeRest_1.invokeRest)(params);
+            }
         }
     ];
 }

package/dist/mcp/schemas.d.ts

@@ -607,3 +607,22 @@ export declare var createRecordSchema: z.ZodObject<{
     dryRun?: boolean | undefined;
     ifAbsentQuery?: string | undefined;
 }>;
+export declare var invokeRestSchema: z.ZodObject<{
+    method: z.ZodEffects<z.ZodEnum<["GET", "POST", "PUT", "DELETE"]>, "GET" | "DELETE" | "POST" | "PUT", unknown>;
+    path: z.ZodString;
+    body: z.ZodOptional<z.ZodUnknown>;
+    confirm: z.ZodOptional<z.ZodBoolean>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    method: "GET" | "DELETE" | "POST" | "PUT";
+    body?: unknown;
+    confirm?: boolean | undefined;
+    dryRun?: boolean | undefined;
+}, {
+    path: string;
+    body?: unknown;
+    method?: unknown;
+    confirm?: boolean | undefined;
+    dryRun?: boolean | undefined;
+}>;

package/dist/mcp/schemas.js

@@ -4,7 +4,7 @@
  * own file so registry.ts stays focused on wiring.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createRecordSchema = exports.setFieldSchema = exports.addColumnSchema = exports.createTableSchema = exports.columnSpecSchema = exports.hostAssetsSchema = exports.editFlowSchema = exports.stepInputPatchSchema = exports.testFlowSchema = exports.createFlowSchema = exports.copyFlowSchema = exports.publishFlowSchema = exports.viewActionSchema = exports.viewFlowSchema = exports.addChoicesToFieldSchema = exports.choiceValueSchema = exports.setRelatedListsSchema = exports.setFormLayoutSchema = exports.formSectionSchema = exports.setListLayoutSchema = exports.createViewSchema = void 0;
+exports.invokeRestSchema = exports.createRecordSchema = exports.setFieldSchema = exports.addColumnSchema = exports.createTableSchema = exports.columnSpecSchema = exports.hostAssetsSchema = exports.editFlowSchema = exports.stepInputPatchSchema = exports.testFlowSchema = exports.createFlowSchema = exports.copyFlowSchema = exports.publishFlowSchema = exports.viewActionSchema = exports.viewFlowSchema = exports.addChoicesToFieldSchema = exports.choiceValueSchema = exports.setRelatedListsSchema = exports.setFormLayoutSchema = exports.formSectionSchema = exports.setListLayoutSchema = exports.createViewSchema = void 0;
 const zod_1 = require("zod");
 exports.createViewSchema = zod_1.z.object({
     name: zod_1.z.string().min(1),
@@ -176,3 +176,13 @@ exports.createRecordSchema = zod_1.z.object({
     ifAbsentQuery: zod_1.z.string().optional(),
     dryRun: zod_1.z.boolean().optional()
 });
+// invoke_rest: transport primitive for arbitrary authenticated REST operations
+// (Scripted REST included). The dry-run-unless-confirm gate lives in invokeRest
+// itself; the regex here rejects absolute URLs and non-/api/ paths early.
+exports.invokeRestSchema = zod_1.z.object({
+    method: zod_1.z.preprocess(function (v) { return typeof v === "string" ? v.toUpperCase() : v; }, zod_1.z.enum(["GET", "POST", "PUT", "DELETE"])),
+    path: zod_1.z.string().min(1).regex(/^\/api\//, "path must be instance-relative and start with /api/"),
+    body: zod_1.z.unknown().optional(),
+    confirm: zod_1.z.boolean().optional(),
+    dryRun: zod_1.z.boolean().optional()
+});

package/package.json

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