@bryan-thompson/inspector-assessment-client 1.15.0 → 1.16.0

package/lib/utils/jsonUtils.js

@@ -0,0 +1,141 @@
+/**
+ * Determines the specific data type of a JSON value
+ * @param value The JSON value to analyze
+ * @returns The specific data type including "array" and "null" as distinct types
+ */
+export function getDataType(value) {
+    if (Array.isArray(value))
+        return "array";
+    if (value === null)
+        return "null";
+    return typeof value;
+}
+/**
+ * Attempts to parse a string as JSON, only for objects and arrays
+ * @param str The string to parse
+ * @returns Object with success boolean and either parsed data or original string
+ */
+export function tryParseJson(str) {
+    const trimmed = str?.trim();
+    if (trimmed &&
+        !(trimmed.startsWith("{") && trimmed.endsWith("}")) &&
+        !(trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+        return { success: false, data: str };
+    }
+    try {
+        return { success: true, data: JSON.parse(str) };
+    }
+    catch {
+        return { success: false, data: str };
+    }
+}
+/**
+ * Updates a value at a specific path in a nested JSON structure
+ * @param obj The original JSON value
+ * @param path Array of keys/indices representing the path to the value
+ * @param value The new value to set
+ * @returns A new JSON value with the updated path
+ */
+export function updateValueAtPath(obj, path, value) {
+    if (path.length === 0)
+        return value;
+    if (obj === null || obj === undefined) {
+        obj = !isNaN(Number(path[0])) ? [] : {};
+    }
+    if (Array.isArray(obj)) {
+        return updateArray(obj, path, value);
+    }
+    else if (typeof obj === "object" && obj !== null) {
+        return updateObject(obj, path, value);
+    }
+    else {
+        console.error(`Cannot update path ${path.join(".")} in non-object/array value:`, obj);
+        return obj;
+    }
+}
+/**
+ * Updates an array at a specific path
+ */
+function updateArray(array, path, value) {
+    const [index, ...restPath] = path;
+    const arrayIndex = Number(index);
+    if (isNaN(arrayIndex)) {
+        console.error(`Invalid array index: ${index}`);
+        return array;
+    }
+    if (arrayIndex < 0) {
+        console.error(`Array index out of bounds: ${arrayIndex} < 0`);
+        return array;
+    }
+    let newArray = [];
+    for (let i = 0; i < array.length; i++) {
+        newArray[i] = i in array ? array[i] : null;
+    }
+    if (arrayIndex >= newArray.length) {
+        const extendedArray = new Array(arrayIndex).fill(null);
+        // Copy over the existing elements (now guaranteed to be dense)
+        for (let i = 0; i < newArray.length; i++) {
+            extendedArray[i] = newArray[i];
+        }
+        newArray = extendedArray;
+    }
+    if (restPath.length === 0) {
+        newArray[arrayIndex] = value;
+    }
+    else {
+        newArray[arrayIndex] = updateValueAtPath(newArray[arrayIndex], restPath, value);
+    }
+    return newArray;
+}
+/**
+ * Updates an object at a specific path
+ */
+function updateObject(obj, path, value) {
+    const [key, ...restPath] = path;
+    // Validate object key
+    if (typeof key !== "string") {
+        console.error(`Invalid object key: ${key}`);
+        return obj;
+    }
+    const newObj = { ...obj };
+    if (restPath.length === 0) {
+        newObj[key] = value;
+    }
+    else {
+        // Ensure key exists
+        if (!(key in newObj)) {
+            newObj[key] = {};
+        }
+        newObj[key] = updateValueAtPath(newObj[key], restPath, value);
+    }
+    return newObj;
+}
+/**
+ * Gets a value at a specific path in a nested JSON structure
+ * @param obj The JSON value to traverse
+ * @param path Array of keys/indices representing the path to the value
+ * @param defaultValue Value to return if path doesn't exist
+ * @returns The value at the path, or defaultValue if not found
+ */
+export function getValueAtPath(obj, path, defaultValue = null) {
+    if (path.length === 0)
+        return obj;
+    const [first, ...rest] = path;
+    if (obj === null || obj === undefined) {
+        return defaultValue;
+    }
+    if (Array.isArray(obj)) {
+        const index = Number(first);
+        if (isNaN(index) || index < 0 || index >= obj.length) {
+            return defaultValue;
+        }
+        return getValueAtPath(obj[index], rest, defaultValue);
+    }
+    if (typeof obj === "object" && obj !== null) {
+        if (!(first in obj)) {
+            return defaultValue;
+        }
+        return getValueAtPath(obj[first], rest, defaultValue);
+    }
+    return defaultValue;
+}

package/lib/utils/paramUtils.d.ts

@@ -0,0 +1,11 @@
+import type { JsonSchemaType } from "./jsonUtils.js";
+/**
+ * Cleans parameters by removing undefined, null, and empty string values for optional fields
+ * while preserving all values for required fields and fields with explicit default values.
+ *
+ * @param params - The parameters object to clean
+ * @param schema - The JSON schema defining which fields are required
+ * @returns Cleaned parameters object with optional empty fields omitted
+ */
+export declare function cleanParams(params: Record<string, unknown>, schema: JsonSchemaType): Record<string, unknown>;
+//# sourceMappingURL=paramUtils.d.ts.map

package/lib/utils/paramUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paramUtils.d.ts","sourceRoot":"","sources":["../../src/utils/paramUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,cAAc,GACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8BzB"}

package/lib/utils/paramUtils.js

@@ -0,0 +1,37 @@
+/**
+ * Cleans parameters by removing undefined, null, and empty string values for optional fields
+ * while preserving all values for required fields and fields with explicit default values.
+ *
+ * @param params - The parameters object to clean
+ * @param schema - The JSON schema defining which fields are required
+ * @returns Cleaned parameters object with optional empty fields omitted
+ */
+export function cleanParams(params, schema) {
+    const cleaned = {};
+    const required = schema.required || [];
+    const properties = schema.properties || {};
+    for (const [key, value] of Object.entries(params)) {
+        const isFieldRequired = required.includes(key);
+        const fieldSchema = properties[key];
+        // Check if the field has an explicit default value
+        const hasDefault = fieldSchema && "default" in fieldSchema;
+        const defaultValue = hasDefault ? fieldSchema.default : undefined;
+        if (isFieldRequired) {
+            // Required fields: always include, even if empty string or falsy
+            cleaned[key] = value;
+        }
+        else if (hasDefault && value === defaultValue) {
+            // Field has a default value and current value matches it - preserve it
+            // This is important for cases like default: null
+            cleaned[key] = value;
+        }
+        else {
+            // Optional fields: only include if they have meaningful values
+            if (value !== undefined && value !== "" && value !== null) {
+                cleaned[key] = value;
+            }
+            // Empty strings, undefined, null for optional fields → omit completely
+        }
+    }
+    return cleaned;
+}

package/lib/utils/schemaUtils.d.ts

@@ -0,0 +1,74 @@
+import type { JsonValue, JsonSchemaType } from "./jsonUtils.js";
+import type { ValidateFunction } from "ajv";
+import type { Tool, JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Compiles and caches output schema validators for a list of tools
+ * Following the same pattern as SDK's Client.cacheToolOutputSchemas
+ * @param tools Array of tools that may have output schemas
+ */
+export declare function cacheToolOutputSchemas(tools: Tool[]): void;
+/**
+ * Gets the cached output schema validator for a tool
+ * Following the same pattern as SDK's Client.getToolOutputValidator
+ * @param toolName Name of the tool
+ * @returns The compiled validator function, or undefined if not found
+ */
+export declare function getToolOutputValidator(toolName: string): ValidateFunction | undefined;
+/**
+ * Validates structured content against a tool's output schema
+ * Returns validation result with detailed error messages
+ * @param toolName Name of the tool
+ * @param structuredContent The structured content to validate
+ * @returns An object with isValid boolean and optional error message
+ */
+export declare function validateToolOutput(toolName: string, structuredContent: unknown): {
+    isValid: boolean;
+    error?: string;
+};
+/**
+ * Checks if a tool has an output schema
+ * @param toolName Name of the tool
+ * @returns true if the tool has an output schema
+ */
+export declare function hasOutputSchema(toolName: string): boolean;
+/**
+ * Generates a default value based on a JSON schema type
+ * @param schema The JSON schema definition
+ * @param propertyName Optional property name for checking if it's required in parent schema
+ * @param parentSchema Optional parent schema to check required array
+ * @returns A default value matching the schema type
+ */
+export declare function generateDefaultValue(schema: JsonSchemaType, propertyName?: string, parentSchema?: JsonSchemaType): JsonValue;
+/**
+ * Helper function to check if a property is required in a schema
+ * @param propertyName The name of the property to check
+ * @param schema The parent schema containing the required array
+ * @returns true if the property is required, false otherwise
+ */
+export declare function isPropertyRequired(propertyName: string, schema: JsonSchemaType): boolean;
+/**
+ * Resolves $ref references in JSON schema
+ * @param schema The schema that may contain $ref
+ * @param rootSchema The root schema to resolve references against
+ * @returns The resolved schema without $ref
+ */
+export declare function resolveRef(schema: JsonSchemaType, rootSchema: JsonSchemaType): JsonSchemaType;
+/**
+ * Normalizes union types (like string|null from FastMCP) to simple types for form rendering
+ * @param schema The JSON schema to normalize
+ * @returns A normalized schema or the original schema
+ */
+export declare function normalizeUnionType(schema: JsonSchemaType): JsonSchemaType;
+/**
+ * Formats a field key into a human-readable label
+ * @param key The field key to format
+ * @returns A formatted label string
+ */
+export declare function formatFieldLabel(key: string): string;
+/**
+ * Resolves `$ref` references in a JSON-RPC "elicitation/create" message's `requestedSchema` field
+ * @param message The JSON-RPC message that may contain $ref references
+ * @returns A new message with resolved $ref references, or the original message if no resolution is needed
+ */
+export declare function resolveRefsInMessage(message: JSONRPCMessage): JSONRPCMessage;
+//# sourceMappingURL=schemaUtils.d.ts.map

package/lib/utils/schemaUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaUtils.d.ts","sourceRoot":"","sources":["../../src/utils/schemaUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAC;AAC5C,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAQ/E;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,CAe1D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GACf,gBAAgB,GAAG,SAAS,CAE9B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,OAAO,GACzB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAetC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,cAAc,EACtB,YAAY,CAAC,EAAE,MAAM,EACrB,YAAY,CAAC,EAAE,cAAc,GAC5B,SAAS,CAkDX;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,cAAc,GACrB,OAAO,CAET;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,cAAc,GACzB,cAAc,CAiChB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CA4FzE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CA+B5E"}

package/lib/utils/schemaUtils.js

@@ -0,0 +1,268 @@
+import Ajv from "ajv";
+import { isJSONRPCRequest } from "@modelcontextprotocol/sdk/types.js";
+const ajv = new Ajv();
+// Cache for compiled validators
+const toolOutputValidators = new Map();
+/**
+ * Compiles and caches output schema validators for a list of tools
+ * Following the same pattern as SDK's Client.cacheToolOutputSchemas
+ * @param tools Array of tools that may have output schemas
+ */
+export function cacheToolOutputSchemas(tools) {
+    toolOutputValidators.clear();
+    for (const tool of tools) {
+        if (tool.outputSchema) {
+            try {
+                const validator = ajv.compile(tool.outputSchema);
+                toolOutputValidators.set(tool.name, validator);
+            }
+            catch (error) {
+                console.warn(`Failed to compile output schema for tool ${tool.name}:`, error);
+            }
+        }
+    }
+}
+/**
+ * Gets the cached output schema validator for a tool
+ * Following the same pattern as SDK's Client.getToolOutputValidator
+ * @param toolName Name of the tool
+ * @returns The compiled validator function, or undefined if not found
+ */
+export function getToolOutputValidator(toolName) {
+    return toolOutputValidators.get(toolName);
+}
+/**
+ * Validates structured content against a tool's output schema
+ * Returns validation result with detailed error messages
+ * @param toolName Name of the tool
+ * @param structuredContent The structured content to validate
+ * @returns An object with isValid boolean and optional error message
+ */
+export function validateToolOutput(toolName, structuredContent) {
+    const validator = getToolOutputValidator(toolName);
+    if (!validator) {
+        return { isValid: true }; // No validator means no schema to validate against
+    }
+    const isValid = validator(structuredContent);
+    if (!isValid) {
+        return {
+            isValid: false,
+            error: ajv.errorsText(validator.errors),
+        };
+    }
+    return { isValid: true };
+}
+/**
+ * Checks if a tool has an output schema
+ * @param toolName Name of the tool
+ * @returns true if the tool has an output schema
+ */
+export function hasOutputSchema(toolName) {
+    return toolOutputValidators.has(toolName);
+}
+/**
+ * Generates a default value based on a JSON schema type
+ * @param schema The JSON schema definition
+ * @param propertyName Optional property name for checking if it's required in parent schema
+ * @param parentSchema Optional parent schema to check required array
+ * @returns A default value matching the schema type
+ */
+export function generateDefaultValue(schema, propertyName, parentSchema) {
+    if ("default" in schema && schema.default !== undefined) {
+        return schema.default;
+    }
+    // Check if this property is required in the parent schema
+    const isRequired = propertyName && parentSchema
+        ? isPropertyRequired(propertyName, parentSchema)
+        : false;
+    const isRootSchema = propertyName === undefined && parentSchema === undefined;
+    switch (schema.type) {
+        case "string":
+            return isRequired ? "" : undefined;
+        case "number":
+        case "integer":
+            return isRequired ? 0 : undefined;
+        case "boolean":
+            return isRequired ? false : undefined;
+        case "array":
+            return isRequired ? [] : undefined;
+        case "object": {
+            if (!schema.properties) {
+                return isRequired || isRootSchema ? {} : undefined;
+            }
+            const obj = {};
+            // Include required properties OR optional properties that declare a default
+            Object.entries(schema.properties).forEach(([key, prop]) => {
+                const hasExplicitDefault = "default" in prop && prop.default !== undefined;
+                if (isPropertyRequired(key, schema) || hasExplicitDefault) {
+                    const value = generateDefaultValue(prop, key, schema);
+                    if (value !== undefined) {
+                        obj[key] = value;
+                    }
+                }
+            });
+            if (Object.keys(obj).length === 0) {
+                return isRequired || isRootSchema ? {} : undefined;
+            }
+            return obj;
+        }
+        case "null":
+            return null;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Helper function to check if a property is required in a schema
+ * @param propertyName The name of the property to check
+ * @param schema The parent schema containing the required array
+ * @returns true if the property is required, false otherwise
+ */
+export function isPropertyRequired(propertyName, schema) {
+    return schema.required?.includes(propertyName) ?? false;
+}
+/**
+ * Resolves $ref references in JSON schema
+ * @param schema The schema that may contain $ref
+ * @param rootSchema The root schema to resolve references against
+ * @returns The resolved schema without $ref
+ */
+export function resolveRef(schema, rootSchema) {
+    if (!("$ref" in schema) || !schema.$ref) {
+        return schema;
+    }
+    const ref = schema.$ref;
+    // Handle simple #/properties/name references
+    if (ref.startsWith("#/")) {
+        const path = ref.substring(2).split("/");
+        let current = rootSchema;
+        for (const segment of path) {
+            if (current &&
+                typeof current === "object" &&
+                current !== null &&
+                segment in current) {
+                current = current[segment];
+            }
+            else {
+                // If reference cannot be resolved, return the original schema
+                console.warn(`Could not resolve $ref: ${ref}`);
+                return schema;
+            }
+        }
+        return current;
+    }
+    // For other types of references, return the original schema
+    console.warn(`Unsupported $ref format: ${ref}`);
+    return schema;
+}
+/**
+ * Normalizes union types (like string|null from FastMCP) to simple types for form rendering
+ * @param schema The JSON schema to normalize
+ * @returns A normalized schema or the original schema
+ */
+export function normalizeUnionType(schema) {
+    // Handle anyOf with exactly string and null (FastMCP pattern)
+    if (schema.anyOf &&
+        schema.anyOf.length === 2 &&
+        schema.anyOf.some((t) => t.type === "string") &&
+        schema.anyOf.some((t) => t.type === "null")) {
+        return { ...schema, type: "string", anyOf: undefined, nullable: true };
+    }
+    // Handle anyOf with exactly boolean and null (FastMCP pattern)
+    if (schema.anyOf &&
+        schema.anyOf.length === 2 &&
+        schema.anyOf.some((t) => t.type === "boolean") &&
+        schema.anyOf.some((t) => t.type === "null")) {
+        return { ...schema, type: "boolean", anyOf: undefined, nullable: true };
+    }
+    // Handle anyOf with exactly number and null (FastMCP pattern)
+    if (schema.anyOf &&
+        schema.anyOf.length === 2 &&
+        schema.anyOf.some((t) => t.type === "number") &&
+        schema.anyOf.some((t) => t.type === "null")) {
+        return { ...schema, type: "number", anyOf: undefined, nullable: true };
+    }
+    // Handle anyOf with exactly integer and null (FastMCP pattern)
+    if (schema.anyOf &&
+        schema.anyOf.length === 2 &&
+        schema.anyOf.some((t) => t.type === "integer") &&
+        schema.anyOf.some((t) => t.type === "null")) {
+        return { ...schema, type: "integer", anyOf: undefined, nullable: true };
+    }
+    // Handle anyOf with exactly array and null (FastMCP pattern)
+    if (schema.anyOf &&
+        schema.anyOf.length === 2 &&
+        schema.anyOf.some((t) => t.type === "array") &&
+        schema.anyOf.some((t) => t.type === "null")) {
+        return { ...schema, type: "array", anyOf: undefined, nullable: true };
+    }
+    // Handle array type with exactly string and null
+    if (Array.isArray(schema.type) &&
+        schema.type.length === 2 &&
+        schema.type.includes("string") &&
+        schema.type.includes("null")) {
+        return { ...schema, type: "string", nullable: true };
+    }
+    // Handle array type with exactly boolean and null
+    if (Array.isArray(schema.type) &&
+        schema.type.length === 2 &&
+        schema.type.includes("boolean") &&
+        schema.type.includes("null")) {
+        return { ...schema, type: "boolean", nullable: true };
+    }
+    // Handle array type with exactly number and null
+    if (Array.isArray(schema.type) &&
+        schema.type.length === 2 &&
+        schema.type.includes("number") &&
+        schema.type.includes("null")) {
+        return { ...schema, type: "number", nullable: true };
+    }
+    // Handle array type with exactly integer and null
+    if (Array.isArray(schema.type) &&
+        schema.type.length === 2 &&
+        schema.type.includes("integer") &&
+        schema.type.includes("null")) {
+        return { ...schema, type: "integer", nullable: true };
+    }
+    return schema;
+}
+/**
+ * Formats a field key into a human-readable label
+ * @param key The field key to format
+ * @returns A formatted label string
+ */
+export function formatFieldLabel(key) {
+    return key
+        .replace(/([A-Z])/g, " $1") // Insert space before capital letters
+        .replace(/_/g, " ") // Replace underscores with spaces
+        .replace(/^\w/, (c) => c.toUpperCase()); // Capitalize first letter
+}
+/**
+ * Resolves `$ref` references in a JSON-RPC "elicitation/create" message's `requestedSchema` field
+ * @param message The JSON-RPC message that may contain $ref references
+ * @returns A new message with resolved $ref references, or the original message if no resolution is needed
+ */
+export function resolveRefsInMessage(message) {
+    if (!isJSONRPCRequest(message) || !message.params?.requestedSchema) {
+        return message;
+    }
+    const requestedSchema = message.params.requestedSchema;
+    if (!requestedSchema?.properties) {
+        return message;
+    }
+    const resolvedMessage = {
+        ...message,
+        params: {
+            ...message.params,
+            requestedSchema: {
+                ...requestedSchema,
+                properties: Object.fromEntries(Object.entries(requestedSchema.properties).map(([key, propSchema]) => {
+                    const resolved = resolveRef(propSchema, requestedSchema);
+                    const normalized = normalizeUnionType(resolved);
+                    return [key, normalized];
+                })),
+            },
+        },
+    };
+    return resolvedMessage;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bryan-thompson/inspector-assessment-client",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Client-side application for the Enhanced MCP Inspector with assessment capabilities",
   "license": "MIT",
   "author": "Bryan Thompson <bryan@triepod.ai>",