@robinmordasiewicz/f5xc-api-mcp 2.0.20-2601080407 → 2.0.21-2601081701

package/dist/tools/discovery/schema.js

@@ -0,0 +1,380 @@
+/**
+ * Schema Retrieval Module
+ *
+ * Provides full JSON schemas for F5XC API request bodies to eliminate
+ * guessing by AI assistants when constructing API payloads.
+ *
+ * Enhanced with $ref resolution, minimum configuration extraction,
+ * and smart example generation.
+ */
+import { getToolByName } from "../registry.js";
+import { getResolvedRequestBodySchema as resolveSchema, getMinimumConfigurationFromSchema, extractRequiredFields, extractMutuallyExclusiveGroups, } from "./schema-loader.js";
+/**
+ * Get the raw JSON schema for a tool's request body (may contain $refs)
+ *
+ * @param toolName - The exact tool name
+ * @returns Raw JSON schema or null if not found
+ *
+ * @example
+ * ```typescript
+ * const schema = getRequestBodySchema("f5xc-api-virtual-http-loadbalancer-create");
+ * if (schema) {
+ *   console.log(JSON.stringify(schema, null, 2));
+ * }
+ * ```
+ */
+export function getRequestBodySchema(toolName) {
+    const tool = getToolByName(toolName);
+    if (!tool || !tool.requestBodySchema) {
+        return null;
+    }
+    return tool.requestBodySchema;
+}
+/**
+ * Get fully resolved request body schema (all $refs expanded)
+ *
+ * This is the recommended function for AI assistants as it provides
+ * the complete schema structure without any unresolved references.
+ *
+ * @param toolName - The exact tool name
+ * @returns Fully resolved schema or null if not found
+ *
+ * @example
+ * ```typescript
+ * const schema = getResolvedRequestBodySchema("f5xc-api-virtual-http-loadbalancer-create");
+ * if (schema) {
+ *   // schema.properties contains all nested structures
+ *   console.log(schema.properties);
+ * }
+ * ```
+ */
+export function getResolvedRequestBodySchema(toolName) {
+    return resolveSchema(toolName);
+}
+/**
+ * Get the full JSON schema for a tool's response
+ *
+ * @param toolName - The exact tool name
+ * @returns Complete JSON schema or null if not found
+ */
+export function getResponseSchema(toolName) {
+    const tool = getToolByName(toolName);
+    if (!tool || !tool.responseSchema) {
+        return null;
+    }
+    return tool.responseSchema;
+}
+/**
+ * Get both request and response schemas for a tool
+ *
+ * @param toolName - The exact tool name
+ * @returns Object with request and response schemas
+ */
+export function getToolSchemas(toolName) {
+    const tool = getToolByName(toolName);
+    if (!tool) {
+        return {};
+    }
+    return {
+        requestBody: tool.requestBodySchema ?? undefined,
+        response: tool.responseSchema ?? undefined,
+    };
+}
+/**
+ * Get x-f5xc-minimum-configuration from a tool's request body schema
+ *
+ * This contains rich examples (JSON, YAML, cURL), required fields,
+ * and mutually exclusive field groups from the OpenAPI spec.
+ *
+ * @param toolName - The exact tool name
+ * @returns Minimum configuration or null if not found
+ */
+export function getMinimumConfiguration(toolName) {
+    return getMinimumConfigurationFromSchema(toolName);
+}
+/**
+ * Get all required fields for a tool's request body
+ *
+ * Combines required fields from:
+ * 1. Schema 'required' arrays (recursively)
+ * 2. x-f5xc-minimum-configuration.required_fields
+ *
+ * @param toolName - The exact tool name
+ * @returns Array of required field paths (e.g., ["metadata.name", "spec.domains"])
+ */
+export function getRequiredFields(toolName) {
+    const requiredSet = new Set();
+    // Get from resolved schema
+    const schema = resolveSchema(toolName);
+    if (schema) {
+        for (const field of extractRequiredFields(schema)) {
+            requiredSet.add(field);
+        }
+    }
+    // Get from minimum configuration
+    const minConfig = getMinimumConfigurationFromSchema(toolName);
+    if (minConfig?.required_fields) {
+        for (const field of minConfig.required_fields) {
+            requiredSet.add(field);
+        }
+    }
+    return Array.from(requiredSet).sort();
+}
+/**
+ * Get mutually exclusive field groups for a tool
+ *
+ * These indicate fields where only one option should be specified.
+ *
+ * @param toolName - The exact tool name
+ * @returns Array of mutually exclusive groups
+ */
+export function getMutuallyExclusiveFields(toolName) {
+    const groups = [];
+    // Get from resolved schema (x-ves-oneof-field-* and oneOf/anyOf)
+    const schema = resolveSchema(toolName);
+    if (schema) {
+        groups.push(...extractMutuallyExclusiveGroups(schema));
+    }
+    // Get from minimum configuration
+    const minConfig = getMinimumConfigurationFromSchema(toolName);
+    if (minConfig?.mutually_exclusive_groups) {
+        for (const group of minConfig.mutually_exclusive_groups) {
+            groups.push({
+                fieldPath: group.fields.join(" | "),
+                options: group.fields.map((f) => ({ fieldName: f })),
+                reason: group.reason,
+            });
+        }
+    }
+    return groups;
+}
+/**
+ * Smart defaults for common field patterns
+ */
+const SMART_DEFAULTS = {
+    name: (toolName) => `my-${extractResourceFromTool(toolName)}`,
+    "metadata.name": (toolName) => `my-${extractResourceFromTool(toolName)}`,
+    namespace: () => "default",
+    "metadata.namespace": () => "default",
+    port: () => 80,
+    listen_port: () => 80,
+    domains: () => ["example.com"],
+    hostnames: () => ["example.com"],
+    timeout: () => 30,
+    connect_timeout: () => 30,
+    idle_timeout: () => 60,
+    retries: () => 3,
+    enabled: () => true,
+    active: () => true,
+    path: () => "/",
+    url_path: () => "/",
+    method: () => "GET",
+    protocol: () => "HTTP",
+};
+/**
+ * Extract resource type from tool name
+ */
+function extractResourceFromTool(toolName) {
+    // f5xc-api-virtual-http-loadbalancer-create -> http-loadbalancer
+    const parts = toolName.replace("f5xc-api-", "").split("-");
+    // Remove domain (first part) and operation (last part)
+    if (parts.length > 2) {
+        parts.shift(); // Remove domain
+        parts.pop(); // Remove operation
+        return parts.join("-");
+    }
+    return parts.join("-");
+}
+/**
+ * Generate smart default value for a field
+ */
+function getSmartDefault(fieldPath, schema, toolName) {
+    // Check for explicit example in schema
+    if (schema.example !== undefined) {
+        return schema.example;
+    }
+    if (schema["x-ves-example"] !== undefined) {
+        return schema["x-ves-example"];
+    }
+    // Check smart defaults by field name
+    const fieldName = fieldPath.split(".").pop() || fieldPath;
+    if (SMART_DEFAULTS[fieldPath]) {
+        return SMART_DEFAULTS[fieldPath](toolName, schema);
+    }
+    if (SMART_DEFAULTS[fieldName]) {
+        return SMART_DEFAULTS[fieldName](toolName, schema);
+    }
+    // Handle enums
+    if (schema.enum && Array.isArray(schema.enum) && schema.enum.length > 0) {
+        return schema.enum[0];
+    }
+    // Handle default values
+    if (schema.default !== undefined) {
+        return schema.default;
+    }
+    // Type-based defaults
+    switch (schema.type) {
+        case "string":
+            return "example-value";
+        case "integer":
+        case "number":
+            return 1;
+        case "boolean":
+            return false;
+        case "array":
+            return [];
+        case "object":
+            return {};
+        default:
+            return null;
+    }
+}
+/**
+ * Generate example payload from resolved schema with smart defaults
+ */
+function generateFromResolvedSchema(schema, toolName, path = "") {
+    // For objects, build example from properties
+    if (schema.type === "object" && schema.properties) {
+        const example = {};
+        for (const [key, propSchema] of Object.entries(schema.properties)) {
+            const propPath = path ? `${path}.${key}` : key;
+            const value = generateFromResolvedSchema(propSchema, toolName, propPath);
+            if (value !== null && value !== undefined) {
+                example[key] = value;
+            }
+        }
+        return Object.keys(example).length > 0 ? example : null;
+    }
+    // For arrays, generate one item example
+    if (schema.type === "array" && schema.items) {
+        const itemExample = generateFromResolvedSchema(schema.items, toolName, `${path}[]`);
+        return itemExample !== null ? [itemExample] : [];
+    }
+    // For primitives, use smart defaults
+    return getSmartDefault(path, schema, toolName);
+}
+/**
+ * Extract example values from OpenAPI schema (legacy function)
+ *
+ * Recursively traverses the schema to find example values for complex objects
+ */
+function extractExamplesFromSchema(schema) {
+    // If schema has an example, return it
+    if ("example" in schema && schema.example !== undefined) {
+        return schema.example;
+    }
+    // If schema has examples array, return first example
+    if ("examples" in schema && Array.isArray(schema.examples) && schema.examples.length > 0) {
+        return schema.examples[0];
+    }
+    // Handle $ref - now we can resolve references!
+    if ("$ref" in schema) {
+        // The caller should use generateSmartExamplePayload instead
+        return null;
+    }
+    // For object schemas, recursively build example from properties
+    if (schema.type === "object" && "properties" in schema) {
+        const properties = schema.properties;
+        const example = {};
+        for (const [key, propSchema] of Object.entries(properties)) {
+            const propExample = extractExamplesFromSchema(propSchema);
+            if (propExample !== null) {
+                example[key] = propExample;
+            }
+        }
+        return Object.keys(example).length > 0 ? example : null;
+    }
+    // For array schemas, create example array with one item
+    if (schema.type === "array" && "items" in schema) {
+        const itemSchema = schema.items;
+        const itemExample = extractExamplesFromSchema(itemSchema);
+        if (itemExample !== null) {
+            return [itemExample];
+        }
+    }
+    // For primitive types, provide reasonable defaults
+    switch (schema.type) {
+        case "string":
+            return schema.enum && Array.isArray(schema.enum) ? schema.enum[0] : "example-value";
+        case "number":
+        case "integer":
+            return schema.default ?? 1;
+        case "boolean":
+            return schema.default ?? false;
+        default:
+            return null;
+    }
+}
+/**
+ * Generate example payload from request body schema (legacy function)
+ *
+ * This helps AI assistants understand the structure of complex nested objects
+ * without having to guess the format.
+ *
+ * @param toolName - The exact tool name
+ * @returns Example payload or null if no schema found
+ *
+ * @deprecated Use generateSmartExamplePayload for better results with $ref resolution
+ */
+export function generateExamplePayload(toolName) {
+    const schema = getRequestBodySchema(toolName);
+    if (!schema) {
+        return null;
+    }
+    return extractExamplesFromSchema(schema);
+}
+/**
+ * Generate smart example payload with $ref resolution and intelligent defaults
+ *
+ * This is the recommended function for generating example payloads as it:
+ * 1. Resolves all $ref pointers
+ * 2. Uses smart defaults based on field names
+ * 3. Falls back to x-f5xc-minimum-configuration examples when available
+ *
+ * @param toolName - The exact tool name
+ * @returns Complete example payload or null if no schema found
+ */
+export function generateSmartExamplePayload(toolName) {
+    // First, try to get example from minimum configuration (most reliable)
+    const minConfig = getMinimumConfigurationFromSchema(toolName);
+    if (minConfig?.example_json) {
+        try {
+            return JSON.parse(minConfig.example_json);
+        }
+        catch {
+            // Invalid JSON, continue to schema-based generation
+        }
+    }
+    // Generate from resolved schema with smart defaults
+    const schema = resolveSchema(toolName);
+    if (!schema) {
+        return null;
+    }
+    const example = generateFromResolvedSchema(schema, toolName);
+    return example;
+}
+/**
+ * Get comprehensive schema information for a tool
+ *
+ * This combines all schema-related data into a single response,
+ * ideal for AI assistants that need full context.
+ *
+ * @param toolName - The exact tool name
+ * @returns Comprehensive schema info or null if not found
+ */
+export function getComprehensiveSchemaInfo(toolName) {
+    const schema = resolveSchema(toolName);
+    if (!schema) {
+        return null;
+    }
+    const minConfig = getMinimumConfigurationFromSchema(toolName);
+    return {
+        resolvedSchema: schema,
+        requiredFields: getRequiredFields(toolName),
+        mutuallyExclusiveGroups: getMutuallyExclusiveFields(toolName),
+        examplePayload: generateSmartExamplePayload(toolName),
+        minimumConfiguration: minConfig,
+        curlExample: minConfig?.example_curl || null,
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/tools/discovery/schema.js.map

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

package/dist/tools/discovery/suggest-params.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Parameter Suggestion Module
+ *
+ * Provides pre-built example payloads for common F5XC API operations
+ * to help AI assistants construct correct request bodies without guessing.
+ *
+ * Enhanced with schema-based generation and smart defaults fallback.
+ */
+import { type MutuallyExclusiveGroup } from "./schema.js";
+/**
+ * Extended suggestion result with rich metadata
+ */
+export interface SuggestionResult {
+    /** The example payload to use */
+    examplePayload: Record<string, unknown>;
+    /** Human-readable description */
+    description: string;
+    /** Source of the example */
+    source: "curated" | "spec" | "generated";
+    /** Required fields that must be provided */
+    requiredFields?: string[];
+    /** Mutually exclusive field groups */
+    mutuallyExclusiveGroups?: MutuallyExclusiveGroup[];
+    /** Usage notes and tips */
+    notes?: string[];
+    /** cURL example if available */
+    curlExample?: string;
+    /** YAML example if available */
+    yamlExample?: string;
+}
+/**
+ * Get suggested parameters for a tool with fallback chain
+ *
+ * Priority order:
+ * 1. x-f5xc-minimum-configuration.example_json (from spec)
+ * 2. COMMON_EXAMPLES (curated)
+ * 3. Schema-generated with smart defaults
+ *
+ * @param toolName - The exact tool name
+ * @returns Suggested parameters with metadata or null if unavailable
+ */
+export declare function suggestParameters(toolName: string): SuggestionResult | null;
+/**
+ * Get suggested parameters (legacy interface for backward compatibility)
+ *
+ * @deprecated Use suggestParameters() for richer metadata
+ */
+export declare function suggestParametersLegacy(toolName: string): {
+    examplePayload: Record<string, unknown>;
+    description: string;
+    notes?: string[];
+} | null;
+/**
+ * Get all available example tools (curated only)
+ *
+ * @returns List of tool names that have curated pre-built examples
+ */
+export declare function getAvailableExamples(): string[];
+/**
+ * Check if a tool has suggested parameters (from any source)
+ *
+ * @param toolName - The exact tool name
+ * @returns True if examples are available from any source
+ */
+export declare function hasSuggestedParameters(toolName: string): boolean;
+/**
+ * Check if a tool has curated examples (not generated)
+ *
+ * @param toolName - The exact tool name
+ * @returns True if curated examples exist
+ */
+export declare function hasCuratedExample(toolName: string): boolean;
+/**
+ * Get suggestion source for a tool
+ *
+ * @param toolName - The exact tool name
+ * @returns Source type or null if no suggestions available
+ */
+export declare function getSuggestionSource(toolName: string): "curated" | "spec" | "generated" | null;
+/**
+ * Get statistics about available suggestions
+ */
+export declare function getSuggestionStats(): {
+    curatedCount: number;
+    curatedTools: string[];
+};
+//# sourceMappingURL=suggest-params.d.ts.map

package/dist/tools/discovery/suggest-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest-params.d.ts","sourceRoot":"","sources":["../../../src/tools/discovery/suggest-params.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAML,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,CAAC;IACzC,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,sCAAsC;IACtC,uBAAuB,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACnD,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA2PD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAsE3E;AA6BD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACzD,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,IAAI,CAWP;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAahE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,IAAI,CAmB7F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAMA"}