isc-transforms-mcp 1.0.15 → 1.0.16

package/JSONS/sailpoint.isc.transforms.lookup.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "sailpoint.isc.transforms.lookup.schema.json",
   "title": "SailPoint ISC Transform Schema - lookup",
-  "description": "Strict schema derived from the SailPoint official Lookup operation documentation. Lookup returns a value from a key/value table using the incoming value as the key. Per docs, the table must include a 'default' key to avoid runtime errors when the lookup key is missing.",
+  "description": "Strict schema for the SailPoint ISC Lookup transform. Maps an incoming string value against a static key-value table and returns the corresponding output. If the input matches a table key, that key's value is returned. If no key matches, the 'default' key's value is returned. IMPORTANT: The 'default' key is mandatory — without it, any unmatched input causes a runtime error. Table comparisons are case-sensitive. Only static string values are supported in the table — nested transforms and conditional logic within table values are not supported.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -12,16 +12,18 @@
   ],
   "properties": {
     "type": {
-      "const": "lookup"
+      "const": "lookup",
+      "description": "Transform operation type. Must be exactly 'lookup'."
     },
     "name": {
       "type": "string",
-      "minLength": 1
+      "minLength": 1,
+      "description": "Display name for this transform, shown in UI dropdowns and identity profile mappings."
     },
     "requiresPeriodicRefresh": {
       "type": "boolean",
       "default": false,
-      "description": "Whether the transform should be reevaluated nightly as part of identity refresh. Default false."
+      "description": "If true, re-evaluates this transform during the nightly identity refresh cycle. Default is false."
     },
     "attributes": {
       "type": "object",
@@ -29,21 +31,32 @@
       "required": [
         "table"
       ],
+      "description": "Required container for lookup operation attributes.",
       "properties": {
         "table": {
           "type": "object",
-          "description": "Map of input keys to output values. Must include 'default'.",
-          "additionalProperties": {
-            "type": "string",
-            "description": "Lookup output value."
-          },
+          "description": "Required key-value mapping object. The key is the string the transform tries to match against the input value; the corresponding string value is returned on a match. MANDATORY: Must include a 'default' key — without it, any input that doesn't match a key causes a runtime error. Rules: (1) All values must be static strings — nested transforms are not supported. (2) Comparisons are case-sensitive: 'US' and 'us' are different keys. (3) Duplicate keys are not permitted. (4) Multiple keys may map to the same output value.",
           "required": [
             "default"
-          ]
+          ],
+          "properties": {
+            "default": {
+              "type": "string",
+              "description": "Mandatory fallback value returned when the input does not match any other key in the table. Prevents runtime errors on unmatched input."
+            }
+          },
+          "additionalProperties": {
+            "type": "string",
+            "description": "Output string value returned when the input matches this key. The key is compared case-sensitively against the input value."
+          }
         },
         "input": {
-          "description": "Optional explicit input to use as the lookup key (nested transform). If omitted, uses UI-configured input.",
-          "oneOf": [
+          "description": "Optional explicit input that provides the string value to look up in the table. If omitted, the transform uses the source and attribute combination configured in the identity profile UI. When provided, must be a nested transform object or a static string.",
+          "anyOf": [
+            {
+              "type": "string",
+              "description": "Static string value to use as the lookup key."
+            },
             {
               "$ref": "#/$defs/NestedTransform"
             }
@@ -55,7 +68,7 @@
   "$defs": {
     "NestedTransform": {
       "type": "object",
-      "description": "Nested transform object used for explicit input (name optional in docs).",
+      "description": "A nested transform object that provides the input value to look up. Its output string is matched against the table keys. Common use: accountAttribute or identityAttribute to supply a source value for the lookup. The 'name' field is optional in nested transforms per SailPoint docs.",
       "additionalProperties": false,
       "required": [
         "type",
@@ -63,18 +76,22 @@
       ],
       "properties": {
         "id": {
-          "type": "string"
+          "type": "string",
+          "description": "Optional ID when referencing an existing saved transform."
         },
         "name": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "description": "Optional display name for the nested transform."
         },
         "type": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "description": "The operation type of the nested transform (e.g., 'accountAttribute', 'identityAttribute', 'lower')."
         },
         "requiresPeriodicRefresh": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether this nested transform re-evaluates during nightly refresh."
         },
         "attributes": {
           "type": "object",
@@ -86,15 +103,72 @@
   },
   "examples": [
     {
+      "name": "Country Code to Country Name",
       "type": "lookup",
-      "name": "Lookup Transform",
       "attributes": {
         "table": {
           "US": "United States",
           "IN": "India",
+          "GB": "United Kingdom",
+          "AU": "Australia",
           "default": "Unknown"
         }
       }
+    },
+    {
+      "name": "Department Code to Building",
+      "type": "lookup",
+      "attributes": {
+        "table": {
+          "ENG": "Building A",
+          "HR": "Building B",
+          "FIN": "Building C",
+          "default": "Main Campus"
+        }
+      }
+    },
+    {
+      "name": "Employment Type with Nested Input",
+      "type": "lookup",
+      "attributes": {
+        "table": {
+          "FTE": "Full-Time Employee",
+          "PTE": "Part-Time Employee",
+          "CON": "Contractor",
+          "default": "Unknown"
+        },
+        "input": {
+          "type": "accountAttribute",
+          "attributes": {
+            "sourceName": "HR Source",
+            "attributeName": "employeeType"
+          }
+        }
+      }
+    },
+    {
+      "name": "Case-Normalized Status Lookup",
+      "type": "lookup",
+      "attributes": {
+        "table": {
+          "active": "Active",
+          "inactive": "Inactive",
+          "pending": "Pending Activation",
+          "default": "Unknown Status"
+        },
+        "input": {
+          "type": "lower",
+          "attributes": {
+            "input": {
+              "type": "accountAttribute",
+              "attributes": {
+                "sourceName": "HR Source",
+                "attributeName": "status"
+              }
+            }
+          }
+        }
+      }
     }
   ]
 }

package/dist/transforms/lint.js

@@ -927,22 +927,58 @@ function lintIso3166(attrs) {
     return msgs;
 }
 // ---------------------------------------------------------------------------
-// 18. lookup — table validation + default key warning
+// 18. lookup — table validation, default key, case-sensitivity, input
+// Docs: https://developer.sailpoint.com/docs/extensibility/transforms/operations/lookup
 // ---------------------------------------------------------------------------
 function lintLookup(attrs) {
     const msgs = [];
     if (attrs?.table !== undefined) {
         if (!isPlainObject(attrs.table)) {
-            push(msgs, "error", "table must be an object map of key → string value.", "attributes.table");
+            push(msgs, "error", "table must be an object map of string keys to string output values (e.g., {\"US\": \"United States\", \"default\": \"Unknown\"}). " +
+                "Nested transforms and conditional logic are not supported as table values.", "attributes.table");
         }
         else {
+            const tableKeys = Object.keys(attrs.table);
+            // 1. default key is mandatory per docs — unmatched input causes a runtime error without it
             if (!Object.prototype.hasOwnProperty.call(attrs.table, "default")) {
-                push(msgs, "warn", "lookup table is missing a 'default' key. Without it, the transform errors if input doesn't match any key.", "attributes.table");
+                push(msgs, "error", "lookup table must include a 'default' key. Without it, any input that doesn't match a table key " +
+                    "causes a runtime error. Add: \"default\": \"<fallback value>\".", "attributes.table");
             }
+            // 2. All values must be strings — nested transforms and dynamic values are not supported
             const badVals = Object.entries(attrs.table).filter(([, v]) => typeof v !== "string");
             if (badVals.length) {
-                push(msgs, "error", `All lookup table values must be strings. Non-string entries: ${badVals.map(([k]) => k).join(", ")}.`, "attributes.table");
+                push(msgs, "error", `All lookup table values must be static strings. Non-string entries: ${badVals.map(([k]) => `'${k}'`).join(", ")}. ` +
+                    "Nested transforms and conditional logic inside table values are not supported.", "attributes.table");
             }
+            // 3. Empty table (no keys at all — can't happen if default is required, but guard anyway)
+            if (tableKeys.length === 0) {
+                push(msgs, "error", "lookup table is empty. Add at least a 'default' key and one or more mapping entries.", "attributes.table");
+                // 4. Table has only a default key — no lookup entries, always returns default
+            }
+            else if (tableKeys.length === 1 && tableKeys[0] === "default") {
+                push(msgs, "warn", "lookup table contains only a 'default' key with no other mapping entries. " +
+                    "This will always return the default value regardless of input. " +
+                    "If you want a fixed output, use a static transform instead.", "attributes.table");
+            }
+            // 5. Empty-string key — unusual, only matches when input is an empty string
+            if (tableKeys.includes("")) {
+                push(msgs, "warn", "lookup table contains an empty-string key (\"\"). This matches only when the input value is an empty string. " +
+                    "If unintentional, remove it.", "attributes.table");
+            }
+            // 6. Case-sensitivity info — only when there are real mapping entries
+            if (tableKeys.filter(k => k !== "default").length > 0) {
+                push(msgs, "info", "Lookup table comparisons are case-sensitive — table keys must match the input value exactly. " +
+                    "'US' and 'us' are treated as different keys. " +
+                    "If case may vary in the input, normalize it first with a lower or upper transform.", "attributes.table");
+            }
+        }
+    }
+    // 7. input: validate type if provided
+    if (attrs?.input !== undefined) {
+        const inp = attrs.input;
+        if (!(typeof inp === "string" || (isPlainObject(inp) && typeof inp.type === "string"))) {
+            push(msgs, "warn", "input must be a nested transform object {type, attributes} that provides the value to look up, or a static string. " +
+                "If omitted, the transform uses the source+attribute combination configured in the identity profile UI.", "attributes.input");
         }
     }
     return msgs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isc-transforms-mcp",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "type": "module",
   "description": "MCP server for SailPoint Identity Security Cloud (ISC) Transform authoring — scaffold, strict lint, catalog, and safe upsert to live tenants.",
   "author": {