@sonisoft/now-sdk-ext-mcp 4.3.0 → 4.5.0

package/README.md

@@ -207,7 +207,8 @@ test/
 
 ### Adding a New Tool
 
-1. Create a new file in `src/tools/` (e.g., `src/tools/query-table.ts`).
+1. Create a new file in `src/resources/       # servicenow:// read-only resources
+src/tools/` (e.g., `src/tools/query-table.ts`).
 2. Export a registration function:
 
    ```typescript

package/dist/common/annotations.d.ts

@@ -27,8 +27,14 @@
  * - `idempotentHint` — repeating the call with identical arguments leaves the
  *   same end state. True for "set this field to X"; false for "append a comment"
  *   or "create a record", which accumulate.
- * - `openWorldHint` — reserved here for arbitrary code execution, where the
- *   effect is genuinely unbounded and cannot be inferred from the arguments.
+ * - `openWorldHint` — TRUE FOR EVERY TOOL HERE, and set explicitly rather than
+ *   left to the spec's default. All of them talk to a live ServiceNow instance,
+ *   which is exactly what the spec means by an open world. It was tempting to use
+ *   it to single out arbitrary code execution, but that would have been wrong in
+ *   both directions: the spec default is already `true`, so the marking would
+ *   have been a no-op, and leaving it off the other 80-odd would have implied
+ *   they were closed-world when they are not. MCP has no hint for "runs
+ *   caller-supplied logic" — the tool description carries that.
  */
 export interface ToolAnnotations {
     readOnlyHint?: boolean;

package/dist/common/annotations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/common/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,eAAe;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B;AAyBD,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAmJ5D,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAShE"}
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/common/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,WAAW,eAAe;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B;AA2BD,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAwJ5D,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAchE"}

package/dist/common/annotations.js

@@ -27,27 +27,39 @@
  * - `idempotentHint` — repeating the call with identical arguments leaves the
  *   same end state. True for "set this field to X"; false for "append a comment"
  *   or "create a record", which accumulate.
- * - `openWorldHint` — reserved here for arbitrary code execution, where the
- *   effect is genuinely unbounded and cannot be inferred from the arguments.
+ * - `openWorldHint` — TRUE FOR EVERY TOOL HERE, and set explicitly rather than
+ *   left to the spec's default. All of them talk to a live ServiceNow instance,
+ *   which is exactly what the spec means by an open world. It was tempting to use
+ *   it to single out arbitrary code execution, but that would have been wrong in
+ *   both directions: the spec default is already `true`, so the marking would
+ *   have been a no-op, and leaving it off the other 80-odd would have implied
+ *   they were closed-world when they are not. MCP has no hint for "runs
+ *   caller-supplied logic" — the tool description carries that.
  */
 /** Cannot modify anything. */
-const READ = { readOnlyHint: true };
+const READ = { readOnlyHint: true, openWorldHint: true };
 /** Adds something new; nothing pre-existing is lost. Repeating accumulates. */
-const CREATE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false };
+const CREATE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
 /** Sets state to a given value. Nothing is destroyed; repeating is a no-op. */
-const SET = { readOnlyHint: false, destructiveHint: false, idempotentHint: true };
+const SET = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 /** Overwrites or removes data that already existed. Repeating settles. */
-const OVERWRITE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true };
+const OVERWRITE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true };
 /** Overwrites or removes, and repeating does NOT settle. */
-const OVERWRITE_ONCE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false };
-/** Runs caller-supplied logic. Effect is unbounded and not inferable from args. */
-const ARBITRARY = {
-    readOnlyHint: false,
-    destructiveHint: true,
-    idempotentHint: false,
-    openWorldHint: true,
-};
+const OVERWRITE_ONCE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
+/**
+ * Runs caller-supplied logic — a script or a flow someone else authored.
+ *
+ * Structurally identical to OVERWRITE_ONCE, because MCP has no hint that means
+ * "unbounded effect". Kept as a separate name purely so this table records which
+ * tools are in that category; the warning that actually reaches the model is in
+ * the tool description.
+ */
+const ARBITRARY = OVERWRITE_ONCE;
 export const TOOL_ANNOTATIONS = {
+    // ---- meta: reports this server's own configuration, touches no instance.
+    // Registered outside TOOL_REGISTRY because it is always available regardless
+    // of the active package.
+    list_tool_packages: READ,
     // ---- aggregate: server-side counts, no writes
     count_records: READ,
     aggregate_query: READ,
@@ -183,7 +195,12 @@ export const TOOL_ANNOTATIONS = {
  * Failing at registration makes that impossible.
  */
 export function annotationsFor(toolName) {
-    const annotations = TOOL_ANNOTATIONS[toolName];
+    // hasOwnProperty, not bracket access: TOOL_ANNOTATIONS["constructor"] would
+    // otherwise return the Object constructor — truthy — and this would hand back
+    // a function instead of throwing.
+    const annotations = Object.prototype.hasOwnProperty.call(TOOL_ANNOTATIONS, toolName)
+        ? TOOL_ANNOTATIONS[toolName]
+        : undefined;
     if (!annotations) {
         throw new Error(`No annotations defined for tool "${toolName}". Add it to TOOL_ANNOTATIONS ` +
             `in src/common/annotations.ts — every tool must declare whether it is read-only.`);

package/dist/common/annotations.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/common/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AASH,8BAA8B;AAC9B,MAAM,IAAI,GAAoB,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;AAErD,+EAA+E;AAC/E,MAAM,MAAM,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;AAEvG,+EAA+E;AAC/E,MAAM,GAAG,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;AAEnG,0EAA0E;AAC1E,MAAM,SAAS,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;AAExG,4DAA4D;AAC5D,MAAM,cAAc,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;AAE9G,mFAAmF;AACnF,MAAM,SAAS,GAAoB;IAC/B,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,IAAI;IACrB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,IAAI;CACtB,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAoC;IAC7D,gDAAgD;IAChD,aAAa,EAAE,IAAI;IACnB,eAAe,EAAE,IAAI;IACrB,iBAAiB,EAAE,IAAI;IAEvB,qBAAqB;IACrB,eAAe,EAAE,IAAI;IACrB,iBAAiB,EAAE,IAAI;IACvB,iBAAiB,EAAE,IAAI;IACvB,oEAAoE;IACpE,oBAAoB,EAAE,IAAI;IAC1B,6EAA6E;IAC7E,6EAA6E;IAC7E,iBAAiB,EAAE,cAAc;IACjC,gBAAgB,EAAE,cAAc;IAChC,qBAAqB,EAAE,cAAc;IACrC,mBAAmB,EAAE,cAAc;IAEnC,wEAAwE;IACxE,gDAAgD;IAChD,cAAc,EAAE,IAAI;IACpB,YAAY,EAAE,cAAc;IAC5B,kBAAkB,EAAE,cAAc;IAElC,mBAAmB;IACnB,gBAAgB,EAAE,IAAI;IACtB,mBAAmB,EAAE,IAAI;IACzB,iBAAiB,EAAE,MAAM;IAEzB,aAAa;IACb,oBAAoB,EAAE,MAAM;IAC5B,oBAAoB,EAAE,SAAS;IAE/B,eAAe;IACf,kBAAkB,EAAE,IAAI;IACxB,gBAAgB,EAAE,IAAI;IACtB,uBAAuB,EAAE,IAAI;IAC7B,oBAAoB,EAAE,IAAI;IAC1B,2BAA2B,EAAE,IAAI;IACjC,sBAAsB,EAAE,MAAM;IAE9B,YAAY;IACZ,sBAAsB,EAAE,IAAI;IAC5B,mBAAmB,EAAE,IAAI;IAEzB,mBAAmB;IACnB,WAAW,EAAE,IAAI;IACjB,uBAAuB,EAAE,IAAI;IAC7B,uBAAuB,EAAE,IAAI;IAC7B,kEAAkE;IAClE,qBAAqB,EAAE,GAAG;IAE1B,iBAAiB;IACjB,oBAAoB,EAAE,IAAI;IAC1B,YAAY,EAAE,IAAI;IAElB,6EAA6E;IAC7E,cAAc,EAAE,SAAS;IAEzB,mEAAmE;IACnE,YAAY,EAAE,SAAS;IACvB,eAAe,EAAE,SAAS;IAC1B,cAAc,EAAE,SAAS;IACzB,SAAS,EAAE,SAAS;IACpB,uBAAuB,EAAE,IAAI;IAC7B,gBAAgB,EAAE,IAAI;IACtB,cAAc,EAAE,IAAI;IACpB,0BAA0B,EAAE,IAAI;IAChC,aAAa,EAAE,IAAI;IACnB,wEAAwE;IACxE,WAAW,EAAE,SAAS;IACtB,SAAS,EAAE,MAAM;IAEjB,cAAc;IACd,qBAAqB,EAAE,IAAI;IAE3B,iBAAiB;IACjB,oBAAoB,EAAE,IAAI;IAC1B,kBAAkB,EAAE,IAAI;IACxB,kBAAkB,EAAE,IAAI;IACxB,kBAAkB,EAAE,MAAM;IAC1B,gBAAgB,EAAE,IAAI;IACtB,cAAc,EAAE,IAAI;IACpB,iBAAiB,EAAE,MAAM;IACzB,iBAAiB,EAAE,SAAS;IAC5B,kEAAkE;IAClE,kBAAkB,EAAE,GAAG;IAEvB,eAAe;IACf,UAAU,EAAE,IAAI;IAChB,cAAc,EAAE,IAAI;IACpB,YAAY,EAAE,IAAI;IAElB,0EAA0E;IAC1E,8DAA8D;IAC9D,oBAAoB,EAAE,SAAS;IAC/B,oBAAoB,EAAE,SAAS;IAE/B,qBAAqB;IACrB,YAAY,EAAE,IAAI;IAClB,WAAW,EAAE,IAAI;IAEjB,cAAc;IACd,qBAAqB,EAAE,IAAI;IAC3B,aAAa,EAAE,IAAI;IACnB,gBAAgB,EAAE,IAAI;IAEtB,aAAa;IACb,iBAAiB,EAAE,IAAI;IACvB,gBAAgB,EAAE,IAAI;IACtB,iBAAiB,EAAE,GAAG;IAEtB,mBAAmB;IACnB,gFAAgF;IAChF,6EAA6E;IAC7E,YAAY;IACZ,WAAW,EAAE,SAAS;IACtB,gDAAgD;IAChD,WAAW,EAAE,SAAS;IAEtB,wCAAwC;IACxC,SAAS,EAAE,IAAI;IACf,8CAA8C;IAC9C,gBAAgB,EAAE,MAAM;IACxB,WAAW,EAAE,GAAG;IAChB,gBAAgB,EAAE,GAAG;IACrB,cAAc,EAAE,GAAG;IACnB,cAAc,EAAE,GAAG;IAEnB,mBAAmB;IACnB,sBAAsB,EAAE,IAAI;IAC5B,gBAAgB,EAAE,IAAI;IACtB,kBAAkB,EAAE,IAAI;IACxB,iBAAiB,EAAE,MAAM;IACzB,sBAAsB,EAAE,GAAG;IAC3B,gBAAgB,EAAE,MAAM;IACxB,+DAA+D;IAC/D,uBAAuB,EAAE,SAAS;IAElC,gBAAgB;IAChB,eAAe,EAAE,MAAM;IAEvB,WAAW;IACX,iBAAiB,EAAE,IAAI;IACvB,0DAA0D;IAC1D,kBAAkB,EAAE,cAAc;CACrC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC3C,MAAM,WAAW,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC/C,IAAI,CAAC,WAAW,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACX,oCAAoC,QAAQ,gCAAgC;YACxE,iFAAiF,CACxF,CAAC;IACN,CAAC;IACD,OAAO,WAAW,CAAC;AACvB,CAAC"}
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/common/annotations.ts"],"names":[],"mappings":"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"}

package/dist/common/connection.d.ts

@@ -17,6 +17,16 @@ export declare function getServiceNowInstance(authAlias?: string): Promise<Servi
  * creates a fresh connection.
  */
 export declare function clearInstance(authAlias?: string): void;
+/** Patterns that indicate a connection/session problem worth retrying. */
+/** Set by sn-credstore's shim once it has taken over credential storage. */
+export declare const CRED_STORE_PATCHED_ENV = "NOW_SDK_KEYCHAIN_PATCHED";
+/**
+ * True when credentials come from sn-credstore rather than the OS keyring.
+ *
+ * Exported so callers do not re-spell the variable name and the "=== 1"
+ * convention; both were already duplicated once.
+ */
+export declare function isCredStoreActive(): boolean;
 /**
  * Returns true if an HTTP response indicates a stale or dead session.
  */

package/dist/common/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/common/connection.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAEnB,MAAM,4BAA4B,CAAC;AA4BpC;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,kBAAkB,CAAC,CAkD7B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAKtD;AAgBD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GACpE,OAAO,CAIT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,GACtD,OAAO,CAAC,CAAC,CAAC,CAeZ"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/common/connection.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAEnB,MAAM,4BAA4B,CAAC;AA4BpC;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,kBAAkB,CAAC,CAkD7B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAKtD;AAED,0EAA0E;AAC1E,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,6BAA6B,CAAC;AAEjE;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAeD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GACpE,OAAO,CAIT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,GACtD,OAAO,CAAC,CAAC,CAAC,CAeZ"}

package/dist/common/connection.js

@@ -81,6 +81,17 @@ export function clearInstance(authAlias) {
     }
 }
 /** Patterns that indicate a connection/session problem worth retrying. */
+/** Set by sn-credstore's shim once it has taken over credential storage. */
+export const CRED_STORE_PATCHED_ENV = "NOW_SDK_KEYCHAIN_PATCHED";
+/**
+ * True when credentials come from sn-credstore rather than the OS keyring.
+ *
+ * Exported so callers do not re-spell the variable name and the "=== 1"
+ * convention; both were already duplicated once.
+ */
+export function isCredStoreActive() {
+    return process.env[CRED_STORE_PATCHED_ENV] === "1";
+}
 const RETRYABLE_PATTERNS = /ECONNREFUSED|ECONNRESET|ETIMEDOUT|EPIPE|socket hang up|fetch failed|No response|Body not XML/i;
 /**
  * Returns true if the error looks like a transient connection or stale-session

package/dist/common/connection.js.map

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

package/dist/common/tool-packages.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolves MCP_TOOL_PACKAGE into the set of tools to register.
+ *
+ * Every failure mode here degrades toward MORE tools, never fewer. A typo in the
+ * env var that silently exposed a smaller surface would look like the server was
+ * broken — tools simply missing, with no error to search for. Falling back to
+ * `full` and saying so on stderr is the recoverable direction.
+ */
+export interface ResolvedPackage {
+    /** Package names that were actually applied. */
+    names: string[];
+    /** Tool names to register, already filtered to ones that exist. */
+    tools: string[];
+    /** Requested names that matched no package. */
+    unknownPackages: string[];
+    /** Tools named by a package that this server does not have. */
+    unknownTools: string[];
+    /** True when the requested selection could not be used and `full` was substituted. */
+    fellBack: boolean;
+}
+/**
+ * Resolves a selection into a concrete tool set.
+ *
+ * `selection` is the raw env value: one package name, or several comma-separated,
+ * in which case the result is their UNION. Union rather than intersection because
+ * combining packages is how someone expresses "I do service desk work AND change
+ * approvals" — an intersection of two role packages is almost always empty.
+ */
+export declare function resolveToolPackage(selection: string | undefined): ResolvedPackage;
+/**
+ * Reports the resolution on stderr.
+ *
+ * stderr, never stdout — stdout is the JSON-RPC transport, and a stray byte
+ * there breaks the client's parser.
+ */
+export declare function reportResolution(resolved: ResolvedPackage): void;
+//# sourceMappingURL=tool-packages.d.ts.map

package/dist/common/tool-packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-packages.d.ts","sourceRoot":"","sources":["../../src/common/tool-packages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,MAAM,WAAW,eAAe;IAC5B,gDAAgD;IAChD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mEAAmE;IACnE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+CAA+C;IAC/C,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,+DAA+D;IAC/D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,sFAAsF;IACtF,QAAQ,EAAE,OAAO,CAAC;CACrB;AAgBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAuEjF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAuBhE"}

package/dist/common/tool-packages.js

@@ -0,0 +1,128 @@
+/**
+ * Resolves MCP_TOOL_PACKAGE into the set of tools to register.
+ *
+ * Every failure mode here degrades toward MORE tools, never fewer. A typo in the
+ * env var that silently exposed a smaller surface would look like the server was
+ * broken — tools simply missing, with no error to search for. Falling back to
+ * `full` and saying so on stderr is the recoverable direction.
+ */
+import { TOOL_PACKAGES, DEFAULT_PACKAGE } from "../config/tool-packages.js";
+import { TOOL_ANNOTATIONS } from "./annotations.js";
+import { allToolNames } from "../tools/registry.js";
+/** Sentinel in a package's `tools` meaning "everything". */
+const ALL = "*";
+/** Sentinel meaning "every tool annotated readOnlyHint: true". */
+const READONLY = "@readonly";
+/**
+ * Tools annotated as read-only. Derived, so it cannot drift from the annotations.
+ *
+ * Filtered to the registry deliberately. TOOL_ANNOTATIONS covers one tool the
+ * registry does not — `list_tool_packages`, which is registered unconditionally —
+ * and returning it here would put a name in the resolved set that has no
+ * registrar, crashing startup on `TOOL_REGISTRY[name](server)`.
+ */
+function readonlyTools(known) {
+    return Object.entries(TOOL_ANNOTATIONS)
+        .filter(([name, a]) => a.readOnlyHint === true && known.has(name))
+        .map(([name]) => name);
+}
+/**
+ * Resolves a selection into a concrete tool set.
+ *
+ * `selection` is the raw env value: one package name, or several comma-separated,
+ * in which case the result is their UNION. Union rather than intersection because
+ * combining packages is how someone expresses "I do service desk work AND change
+ * approvals" — an intersection of two role packages is almost always empty.
+ */
+export function resolveToolPackage(selection) {
+    const known = new Set(allToolNames());
+    const requested = (selection ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (requested.length === 0) {
+        return {
+            names: [DEFAULT_PACKAGE],
+            tools: allToolNames(),
+            unknownPackages: [],
+            unknownTools: [],
+            fellBack: false,
+        };
+    }
+    const names = [];
+    const unknownPackages = [];
+    const selected = new Set();
+    const namedButMissing = new Set();
+    for (const name of requested) {
+        // hasOwnProperty, not bracket access. TOOL_PACKAGES is an object literal,
+        // so TOOL_PACKAGES["constructor"] returns the Object constructor — truthy,
+        // with no `.tools` — and `for (const t of pkg.tools)` then throws at module
+        // load, before the uncaughtException handler exists. MCP_TOOL_PACKAGE=
+        // constructor would crash the server rather than falling back, which is the
+        // exact opposite of this file's stated invariant.
+        const pkg = Object.prototype.hasOwnProperty.call(TOOL_PACKAGES, name)
+            ? TOOL_PACKAGES[name]
+            : undefined;
+        if (!pkg) {
+            unknownPackages.push(name);
+            continue;
+        }
+        names.push(name);
+        for (const tool of pkg.tools) {
+            if (tool === ALL) {
+                allToolNames().forEach((t) => selected.add(t));
+            }
+            else if (tool === READONLY) {
+                readonlyTools(known).forEach((t) => selected.add(t));
+            }
+            else if (known.has(tool)) {
+                selected.add(tool);
+            }
+            else {
+                // Expected for packages naming tools from open tickets; still
+                // reported, because the same path catches a genuine typo.
+                namedButMissing.add(tool);
+            }
+        }
+    }
+    // Nothing usable was requested. Fall back rather than register an empty
+    // server: a server with no tools is indistinguishable from a broken one.
+    if (names.length === 0) {
+        return {
+            names: [DEFAULT_PACKAGE],
+            tools: allToolNames(),
+            unknownPackages,
+            unknownTools: [],
+            fellBack: true,
+        };
+    }
+    return {
+        names,
+        tools: [...selected].sort(),
+        unknownPackages,
+        unknownTools: [...namedButMissing].sort(),
+        fellBack: false,
+    };
+}
+/**
+ * Reports the resolution on stderr.
+ *
+ * stderr, never stdout — stdout is the JSON-RPC transport, and a stray byte
+ * there breaks the client's parser.
+ */
+export function reportResolution(resolved) {
+    const { names, tools, unknownPackages, unknownTools, fellBack } = resolved;
+    if (unknownPackages.length > 0) {
+        const available = Object.keys(TOOL_PACKAGES).sort().join(", ");
+        console.error(`[tool-packages] unknown package(s): ${unknownPackages.join(", ")}. ` +
+            `Available: ${available}.` +
+            (fellBack ? ` Falling back to "${DEFAULT_PACKAGE}".` : ""));
+    }
+    if (unknownTools.length > 0) {
+        console.error(`[tool-packages] ${unknownTools.length} tool(s) named by a package do not exist ` +
+            `on this server and were skipped: ${unknownTools.join(", ")}. ` +
+            `This is expected for tools from work that has not landed yet.`);
+    }
+    console.error(`[tool-packages] active: ${names.join(", ")} — ${tools.length} of ${allToolNames().length} tools registered`);
+}
+//# sourceMappingURL=tool-packages.js.map

package/dist/common/tool-packages.js.map

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

package/dist/config/tool-packages.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tool packages — named subsets of the tool surface.
+ *
+ * All 86 tools are registered by default, and their descriptions are long by
+ * design (`execute_script`'s runs to about thirteen lines, because it has to
+ * teach scoped-vs-global name qualification). That is a fixed cost paid on every
+ * session, and model tool-selection accuracy degrades as the option count grows.
+ * A user doing service-desk work does not need Flow Designer, ATF, or app
+ * publishing in front of them.
+ *
+ * Selected with MCP_TOOL_PACKAGE. Unset means "full", so the default behaviour
+ * is unchanged.
+ *
+ * ---
+ *
+ * ON NAMING TOOLS THAT DO NOT EXIST YET
+ *
+ * Packages may reference tools this server does not have. That is deliberate,
+ * not sloppiness: NEX-38 (user and group tools), NEX-39 (incident and change
+ * tools) and NEX-46 (workflow execution) are all open, and their tools belong in
+ * these packages the day they land. Naming them now means the package is already
+ * right rather than something someone has to remember to revisit.
+ *
+ * Unknown names are reported once at startup and skipped. They are a warning
+ * rather than an error precisely because forward references are expected — but
+ * they are still surfaced, because the same warning catches a genuine typo.
+ */
+export interface ToolPackage {
+    /** Shown by list_tool_packages, so write it for whoever picks a package. */
+    description: string;
+    /** Tool names, or ["*"] for everything. May name tools that do not exist yet. */
+    tools: string[];
+}
+export declare const TOOL_PACKAGES: Record<string, ToolPackage>;
+/** The package used when MCP_TOOL_PACKAGE is unset or unusable. */
+export declare const DEFAULT_PACKAGE = "full";
+//# sourceMappingURL=tool-packages.d.ts.map

package/dist/config/tool-packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-packages.d.ts","sourceRoot":"","sources":["../../src/config/tool-packages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,WAAW;IACxB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,KAAK,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAkLrD,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,eAAe,SAAS,CAAC"}

package/dist/config/tool-packages.js

@@ -0,0 +1,197 @@
+/**
+ * Tool packages — named subsets of the tool surface.
+ *
+ * All 86 tools are registered by default, and their descriptions are long by
+ * design (`execute_script`'s runs to about thirteen lines, because it has to
+ * teach scoped-vs-global name qualification). That is a fixed cost paid on every
+ * session, and model tool-selection accuracy degrades as the option count grows.
+ * A user doing service-desk work does not need Flow Designer, ATF, or app
+ * publishing in front of them.
+ *
+ * Selected with MCP_TOOL_PACKAGE. Unset means "full", so the default behaviour
+ * is unchanged.
+ *
+ * ---
+ *
+ * ON NAMING TOOLS THAT DO NOT EXIST YET
+ *
+ * Packages may reference tools this server does not have. That is deliberate,
+ * not sloppiness: NEX-38 (user and group tools), NEX-39 (incident and change
+ * tools) and NEX-46 (workflow execution) are all open, and their tools belong in
+ * these packages the day they land. Naming them now means the package is already
+ * right rather than something someone has to remember to revisit.
+ *
+ * Unknown names are reported once at startup and skipped. They are a warning
+ * rather than an error precisely because forward references are expected — but
+ * they are still surfaced, because the same warning catches a genuine typo.
+ */
+export const TOOL_PACKAGES = {
+    full: {
+        description: "Every tool. The default when MCP_TOOL_PACKAGE is unset.",
+        tools: ["*"],
+    },
+    readonly: {
+        description: "Only tools that cannot modify anything — safe to expose when the session " +
+            "should be able to investigate but never change the instance. Derived from " +
+            "the readOnlyHint annotations rather than hand-listed, so it cannot drift.",
+        // Resolved dynamically; see resolveReadonlyPackage in common/tool-packages.ts.
+        tools: ["@readonly"],
+    },
+    developer: {
+        description: "Building and debugging on an instance: scripts, schema, source sync, " +
+            "update sets, scope, logs and code search.",
+        tools: [
+            "execute_script",
+            "query_table",
+            "query_syslog",
+            "count_records",
+            "aggregate_query",
+            "aggregate_grouped",
+            "discover_table_schema",
+            "explain_field",
+            "lookup_table",
+            "lookup_columns",
+            "lookup_app",
+            "list_instance_tables",
+            "pull_script",
+            "push_script",
+            "code_search",
+            "list_code_search_groups",
+            "list_code_search_tables",
+            "add_code_search_table",
+            "get_current_update_set",
+            "list_update_sets",
+            "create_update_set",
+            "set_current_update_set",
+            "inspect_update_set",
+            "clone_update_set",
+            "move_update_set_records",
+            "get_current_scope",
+            "set_current_scope",
+            "list_scoped_apps",
+            "check_instance_health",
+            "find_task",
+            "export_record_xml",
+            "import_records_xml",
+        ],
+    },
+    service_desk: {
+        description: "Working tickets: find and update tasks, read knowledge, raise catalog " +
+            "requests. No scripting, no schema, no app lifecycle.",
+        tools: [
+            "find_task",
+            "query_table",
+            "add_task_comment",
+            "assign_task",
+            "resolve_incident",
+            "close_incident",
+            "approve_change",
+            "list_knowledge_bases",
+            "list_kb_articles",
+            "get_kb_article",
+            "list_catalog_items",
+            "get_catalog_item",
+            "list_catalog_item_variables",
+            "submit_catalog_request",
+            "list_attachments",
+            "get_attachment_info",
+            // Pending NEX-39.
+            "create_incident",
+            "update_incident",
+            "add_work_note",
+        ],
+    },
+    admin: {
+        description: "Instance administration: users and groups, plugins, health, logs, and " +
+            "scripting. Deliberately includes execute_script — an admin package " +
+            "without it is not an admin package.",
+        tools: [
+            "query_table",
+            "query_syslog",
+            "count_records",
+            "find_task",
+            "execute_script",
+            "list_plugins",
+            "list_instance_tables",
+            "check_instance_health",
+            "list_scoped_apps",
+            "get_app_details",
+            "list_company_apps",
+            "search_store_apps",
+            "validate_app_install",
+            "install_store_app",
+            "update_store_app",
+            // Pending NEX-38.
+            "find_user",
+            "list_users",
+            "create_user",
+            "update_user",
+            "list_groups",
+            "get_group_members",
+            "add_group_members",
+            "remove_group_members",
+            "assign_user_role",
+            "remove_user_role",
+        ],
+    },
+    change_manager: {
+        description: "Change and release work: change approvals, update sets, flows and " +
+            "workflows, and the app repo.",
+        tools: [
+            "find_task",
+            "query_table",
+            "approve_change",
+            "add_task_comment",
+            "get_current_update_set",
+            "list_update_sets",
+            "create_update_set",
+            "set_current_update_set",
+            "inspect_update_set",
+            "clone_update_set",
+            "move_update_set_records",
+            "execute_flow",
+            "get_flow_context_status",
+            "get_flow_outputs",
+            "get_flow_error",
+            "get_flow_logs",
+            "cancel_flow",
+            "create_workflow",
+            "install_from_app_repo",
+            "publish_to_app_repo",
+            // Pending NEX-39 and NEX-46.
+            "create_change_request",
+            "update_change_request",
+            "get_change_details",
+            "add_change_task",
+            "get_workflow_versions",
+            "execute_workflow",
+        ],
+    },
+    flow_developer: {
+        description: "Flow Designer work end to end: run, test, copy, inspect and diagnose " +
+            "flows, plus the schema and logs needed to debug them.",
+        tools: [
+            "execute_flow",
+            "execute_subflow",
+            "execute_action",
+            "test_flow",
+            "copy_flow",
+            "cancel_flow",
+            "get_flow_context_status",
+            "get_flow_outputs",
+            "get_flow_error",
+            "get_flow_execution_details",
+            "get_flow_logs",
+            "query_table",
+            "query_syslog",
+            "discover_table_schema",
+            "lookup_table",
+            "get_current_scope",
+            "set_current_scope",
+            "list_scoped_apps",
+        ],
+    },
+};
+/** The package used when MCP_TOOL_PACKAGE is unset or unusable. */
+export const DEFAULT_PACKAGE = "full";
+//# sourceMappingURL=tool-packages.js.map

package/dist/config/tool-packages.js.map

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