@sonisoft/now-sdk-ext-mcp 1.0.0

package/dist/tools/execute-script.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+import { BackgroundScriptExecutor } from "@sonisoft/now-sdk-ext-core";
+import { withConnectionRetry } from "../common/connection.js";
+/**
+ * Registers the execute_script tool on the MCP server.
+ *
+ * This tool executes JavaScript on a ServiceNow instance via Scripts - Background
+ * (the /sys.scripts.do endpoint). It mirrors the behavior of the CLI's `exec` command.
+ */
+export function registerExecuteScriptTool(server) {
+    server.registerTool("execute_script", {
+        title: "Execute Background Script",
+        description: "Execute JavaScript on a ServiceNow instance using Scripts - Background. " +
+            "The script runs server-side with full GlideSystem API access (gs, GlideRecord, " +
+            "GlideAggregate, etc.). Use gs.print() to produce output. " +
+            "Scripts execute with the permissions of the authenticated user.\n\n" +
+            "IMPORTANT: This executes code directly on the ServiceNow instance. " +
+            "Always review scripts before execution and prefer read-only operations " +
+            "unless modification is explicitly intended.",
+        inputSchema: {
+            instance: z
+                .string()
+                .optional()
+                .describe("The ServiceNow instance auth alias to execute the script on. " +
+                "This is the alias configured via `snc configure` (e.g., " +
+                '"dev224436", "prod", "test"). The user will typically refer to ' +
+                "this by name when saying things like \"on my dev224436 instance\". " +
+                "If not provided, falls back to the SN_AUTH_ALIAS environment variable."),
+            script: z
+                .string()
+                .describe("The JavaScript code to execute on the ServiceNow instance. " +
+                "Use gs.print() to output results. The script runs in the server-side " +
+                "GlideSystem context with access to GlideRecord, GlideAggregate, " +
+                "gs.getUser(), gs.now(), and all standard ServiceNow server-side APIs."),
+            scope: z
+                .string()
+                .default("global")
+                .describe('The application scope to execute the script in. Use "global" for ' +
+                "global scope, or specify an application scope (e.g., " +
+                '"x_myapp_custom") to run within that application\'s context.'),
+            params: z
+                .record(z.string())
+                .optional()
+                .describe("Optional key-value pairs for parameter substitution. " +
+                "Occurrences of {paramName} in the script will be replaced with " +
+                "the corresponding value. Example: { \"table\": \"incident\", " +
+                '"field": "priority" } replaces {table} and {field} in the script.'),
+        },
+    }, async ({ instance, script, scope, params }) => {
+        try {
+            // Apply parameter substitutions if provided
+            let processedScript = script;
+            if (params && Object.keys(params).length > 0) {
+                for (const [key, value] of Object.entries(params)) {
+                    const placeholder = `{${key}}`;
+                    processedScript = processedScript.split(placeholder).join(value);
+                }
+            }
+            const result = await withConnectionRetry(instance, async (snInstance) => {
+                const executor = new BackgroundScriptExecutor(snInstance, scope);
+                return await executor.executeScript(processedScript, scope, snInstance);
+            });
+            if (!result || !result.scriptResults) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Script executed but returned no output. If you expected output, make sure your script uses gs.print() or gs.info().",
+                        },
+                    ],
+                };
+            }
+            // Build structured output
+            const scriptLines = result.scriptResults
+                .filter((line) => line.line && line.line.trim().length > 0)
+                .map((line) => line.line);
+            const output = scriptLines.join("\n");
+            // Include affected records info if present
+            let fullOutput = output;
+            if (result.affectedRecords) {
+                fullOutput += `\n\n[Affected Records: ${result.affectedRecords}]`;
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: fullOutput || "(Script produced no output)",
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error executing script: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=execute-script.js.map

package/dist/tools/execute-script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-script.js","sourceRoot":"","sources":["../../src/tools/execute-script.ts"],"names":[],"mappings":"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"}

package/dist/tools/find-atf-tests.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the find_atf_tests tool on the MCP server.
+ *
+ * Searches the sys_atf_test table to find ATF tests by name, description,
+ * or category. Returns results that can be fed into run_atf_test.
+ */
+export declare function registerFindAtfTestsTool(server: McpServer): void;
+//# sourceMappingURL=find-atf-tests.d.ts.map

package/dist/tools/find-atf-tests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-atf-tests.d.ts","sourceRoot":"","sources":["../../src/tools/find-atf-tests.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAqBpE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAwKhE"}

package/dist/tools/find-atf-tests.js

@@ -0,0 +1,152 @@
+import { z } from "zod";
+import { TableAPIRequest } from "@sonisoft/now-sdk-ext-core";
+import { withConnectionRetry, isRetryableResponse, } from "../common/connection.js";
+/**
+ * Registers the find_atf_tests tool on the MCP server.
+ *
+ * Searches the sys_atf_test table to find ATF tests by name, description,
+ * or category. Returns results that can be fed into run_atf_test.
+ */
+export function registerFindAtfTestsTool(server) {
+    server.registerTool("find_atf_tests", {
+        title: "Find ATF Tests",
+        description: "Search for ATF (Automated Test Framework) tests on a ServiceNow instance. " +
+            "Find tests by name, description, or category. Returns a list of matching tests " +
+            "with their sys_ids, which can then be passed to the run_atf_test tool for execution.\n\n" +
+            "Use this when you need to discover which ATF tests exist before running them.",
+        inputSchema: {
+            instance: z
+                .string()
+                .optional()
+                .describe("The ServiceNow instance auth alias (e.g., " +
+                '"dev224436", "prod"). If not provided, falls back ' +
+                "to the SN_AUTH_ALIAS environment variable."),
+            search_term: z
+                .string()
+                .optional()
+                .describe("Text to search for in test name and description fields. " +
+                "Case-insensitive contains matching. " +
+                'Example: "incident" finds tests with "incident" in the name or description.'),
+            category: z
+                .string()
+                .optional()
+                .describe('Filter by test category (e.g., "Custom", "Module"). ' +
+                "Maps to the sys_atf_test.category field."),
+            active: z
+                .boolean()
+                .default(true)
+                .describe("Filter by active status. Defaults to true (only active tests). " +
+                "Set to false to find only inactive tests."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(25)
+                .describe("Maximum number of tests to return. Default is 25."),
+        },
+    }, async ({ instance, search_term, category, active, limit }) => {
+        try {
+            const response = await withConnectionRetry(instance, async (snInstance) => {
+                const tableApi = new TableAPIRequest(snInstance);
+                // Build encoded query using ^NQ for safe OR grouping when search_term
+                // is provided. This ensures active/category filters apply to both
+                // name and description branches.
+                let encodedQuery;
+                if (search_term) {
+                    encodedQuery = `active=${active}^nameLIKE${search_term}`;
+                    if (category)
+                        encodedQuery += `^category=${category}`;
+                    encodedQuery += `^NQactive=${active}^descriptionLIKE${search_term}`;
+                    if (category)
+                        encodedQuery += `^category=${category}`;
+                }
+                else {
+                    encodedQuery = `active=${active}`;
+                    if (category)
+                        encodedQuery += `^category=${category}`;
+                }
+                encodedQuery += "^ORDERBYname";
+                const queryParams = {
+                    sysparm_query: encodedQuery,
+                    sysparm_fields: "sys_id,name,description,active,category,sys_updated_on",
+                    sysparm_limit: limit,
+                    sysparm_display_value: "false",
+                };
+                const resp = await tableApi.get("sys_atf_test", queryParams);
+                if (isRetryableResponse(resp)) {
+                    const status = resp?.status ?? "unknown";
+                    throw new Error(`HTTP ${status} searching ATF tests`);
+                }
+                return resp;
+            });
+            if (response.status !== 200) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error searching ATF tests: HTTP ${response.status}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const tests = response.bodyObject?.result ?? [];
+            const lines = [];
+            lines.push("=== ATF Test Search Results ===");
+            const searchInfo = [];
+            if (search_term)
+                searchInfo.push(`Search: "${search_term}"`);
+            if (category)
+                searchInfo.push(`Category: "${category}"`);
+            searchInfo.push(`Active: ${active}`);
+            lines.push(searchInfo.join(" | "));
+            lines.push(`Found: ${tests.length} test(s)`);
+            if (tests.length === 0) {
+                lines.push("");
+                lines.push("No ATF tests found matching the criteria.");
+            }
+            else {
+                tests.forEach((test, index) => {
+                    lines.push("");
+                    lines.push(`${index + 1}. ${test.name}`);
+                    lines.push(`   sys_id: ${test.sys_id}`);
+                    lines.push(`   Active: ${test.active}`);
+                    if (test.description) {
+                        const truncated = test.description.length > 100
+                            ? test.description.substring(0, 100) + "..."
+                            : test.description;
+                        lines.push(`   Description: ${truncated}`);
+                    }
+                });
+            }
+            lines.push("");
+            lines.push(`=== ${tests.length} test(s) found ===`);
+            if (tests.length > 0) {
+                lines.push("");
+                lines.push("Tip: Use the sys_id with the run_atf_test tool to execute a test.");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: lines.join("\n"),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error finding ATF tests: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=find-atf-tests.js.map

package/dist/tools/find-atf-tests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-atf-tests.js","sourceRoot":"","sources":["../../src/tools/find-atf-tests.ts"],"names":[],"mappings":"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"}

package/dist/tools/health.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the check_instance_health tool on the MCP server.
+ *
+ * Runs a consolidated health check against a ServiceNow instance, returning
+ * version info, cluster status, stuck jobs, semaphore count, and operational counts.
+ */
+export declare function registerCheckInstanceHealthTool(server: McpServer): void;
+//# sourceMappingURL=health.d.ts.map

package/dist/tools/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/tools/health.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6JvE"}

package/dist/tools/health.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { InstanceHealth, AggregateQuery } from "@sonisoft/now-sdk-ext-core";
+import { withConnectionRetry } from "../common/connection.js";
+/**
+ * Registers the check_instance_health tool on the MCP server.
+ *
+ * Runs a consolidated health check against a ServiceNow instance, returning
+ * version info, cluster status, stuck jobs, semaphore count, and operational counts.
+ */
+export function registerCheckInstanceHealthTool(server) {
+    server.registerTool("check_instance_health", {
+        title: "Check Instance Health",
+        description: "Run a consolidated health check on a ServiceNow instance. Returns version info, " +
+            "cluster node status, stuck scheduled jobs, active semaphore count, and operational " +
+            "counts (open incidents, changes, problems).\n\n" +
+            "Each section can be individually enabled/disabled. Use this to quickly assess " +
+            "the overall health and status of an instance.",
+        inputSchema: {
+            instance: z
+                .string()
+                .optional()
+                .describe("The ServiceNow instance auth alias (e.g., " +
+                '"dev224436", "prod"). If not provided, falls back ' +
+                "to the SN_AUTH_ALIAS environment variable."),
+            include_version: z
+                .boolean()
+                .default(true)
+                .describe("Include ServiceNow version/build info."),
+            include_cluster: z
+                .boolean()
+                .default(true)
+                .describe("Include cluster node status."),
+            include_stuck_jobs: z
+                .boolean()
+                .default(true)
+                .describe("Include stuck scheduled jobs."),
+            include_semaphores: z
+                .boolean()
+                .default(true)
+                .describe("Include active semaphore count."),
+            include_operational_counts: z
+                .boolean()
+                .default(true)
+                .describe("Include operational counts (open incidents, changes, problems)."),
+            stuck_job_threshold_minutes: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("Threshold in minutes for considering a scheduled job stuck. " +
+                "Jobs running longer than this are flagged. Default is 30 minutes."),
+        },
+    }, async ({ instance, include_version, include_cluster, include_stuck_jobs, include_semaphores, include_operational_counts, stuck_job_threshold_minutes, }) => {
+        try {
+            const result = await withConnectionRetry(instance, async (snInstance) => {
+                const aggregateQuery = new AggregateQuery(snInstance);
+                const health = new InstanceHealth(snInstance, aggregateQuery);
+                return await health.checkHealth({
+                    includeVersion: include_version,
+                    includeCluster: include_cluster,
+                    includeStuckJobs: include_stuck_jobs,
+                    includeSemaphores: include_semaphores,
+                    includeOperationalCounts: include_operational_counts,
+                    stuckJobThresholdMinutes: stuck_job_threshold_minutes,
+                });
+            });
+            const lines = [];
+            lines.push("=== Instance Health Check ===");
+            lines.push(`Timestamp: ${result.timestamp}`);
+            if (result.version) {
+                lines.push("");
+                lines.push("--- Version Info ---");
+                if (result.version.version)
+                    lines.push(`  Version: ${result.version.version}`);
+                if (result.version.buildDate)
+                    lines.push(`  Build Date: ${result.version.buildDate}`);
+                if (result.version.buildTag)
+                    lines.push(`  Build Tag: ${result.version.buildTag}`);
+            }
+            if (result.clusterNodes) {
+                lines.push("");
+                lines.push(`--- Cluster Nodes (${result.clusterNodes.length}) ---`);
+                for (const node of result.clusterNodes) {
+                    lines.push(`  ${node.node_id || node.sys_id}: status=${node.status || "unknown"}`);
+                }
+            }
+            if (result.stuckJobs) {
+                lines.push("");
+                lines.push(`--- Stuck Jobs (${result.stuckJobs.length}) ---`);
+                if (result.stuckJobs.length === 0) {
+                    lines.push("  None detected");
+                }
+                else {
+                    for (const job of result.stuckJobs) {
+                        lines.push(`  ${job.name || job.sys_id}: state=${job.state || "unknown"}, next_action=${job.next_action || "N/A"}`);
+                    }
+                }
+            }
+            if (result.activeSemaphoreCount !== undefined) {
+                lines.push("");
+                lines.push("--- Semaphores ---");
+                lines.push(`  Active count: ${result.activeSemaphoreCount}`);
+            }
+            if (result.operationalCounts) {
+                lines.push("");
+                lines.push("--- Operational Counts ---");
+                const counts = result.operationalCounts;
+                if (counts.openIncidents !== undefined)
+                    lines.push(`  Open Incidents: ${counts.openIncidents}`);
+                if (counts.openChanges !== undefined)
+                    lines.push(`  Open Changes: ${counts.openChanges}`);
+                if (counts.openProblems !== undefined)
+                    lines.push(`  Open Problems: ${counts.openProblems}`);
+            }
+            if (result.summary) {
+                lines.push("");
+                lines.push(`Summary: ${result.summary}`);
+            }
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error checking instance health: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=health.js.map

package/dist/tools/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/tools/health.ts"],"names":[],"mappings":"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"}

package/dist/tools/lookup-app.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the lookup_app tool on the MCP server.
+ *
+ * Searches ServiceNow for applications (scoped apps) and platform plugins
+ * by name, scope namespace, or plugin ID. Queries sys_scope (which covers
+ * both sys_app and sys_store_app via table inheritance) and sys_plugins
+ * in parallel.
+ */
+export declare function registerLookupAppTool(server: McpServer): void;
+//# sourceMappingURL=lookup-app.d.ts.map

package/dist/tools/lookup-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup-app.d.ts","sourceRoot":"","sources":["../../src/tools/lookup-app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAkDpE;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6P7D"}