Get Managed Object Schema

Instructions

Implementation Reference

• src/tools/managedObjects/getManagedObjectSchema.ts:1-72 (handler)

  The complete tool definition for getManagedObjectSchema, including the toolFunction that retrieves managed object schema definitions from PingOne AIC

  // src/tools/getManagedObjectSchema.ts
  import { z } from 'zod';
  import { makeAuthenticatedRequest, createToolResponse } from '../../utils/apiHelpers.js';
  import { formatSuccess } from '../../utils/responseHelpers.js';
  import { EXAMPLE_TYPES_STRING } from '../../utils/managedObjectHelpers.js';
  
  const aicBaseUrl = process.env.AIC_BASE_URL;
  
  const SCOPES = ['fr:idm:*'];
  
  export const getManagedObjectSchemaTool = {
    name: 'getManagedObjectSchema',
    title: 'Get Managed Object Schema',
    description: 'Retrieve schema definition for a managed object type in PingOne AIC',
    scopes: SCOPES,
    annotations: {
      readOnlyHint: true,
      openWorldHint: true
    },
    inputSchema: {
      objectType: z
        .string()
        .min(1)
        .describe(
          `Managed object type (e.g., ${EXAMPLE_TYPES_STRING}). Use listManagedObjects to discover all available types.`
        ),
      includeFullDefinition: z
        .boolean()
        .default(false)
        .describe(
          'When true, returns the complete managed object definition including script hooks, lifecycle metadata, notifications, and other configuration. Defaults to false for a concise schema-only response.'
        )
    },
    async toolFunction({
      objectType,
      includeFullDefinition = false
    }: {
      objectType: string;
      includeFullDefinition?: boolean;
    }) {
      const url = `https://${aicBaseUrl}/openidm/config/managed`;
  
      try {
        const { data, response } = await makeAuthenticatedRequest(url, SCOPES);
  
        const config = data as any;
  
        // Find the specific managed object by name
        const managedObject = config.objects?.find((obj: any) => obj.name === objectType);
  
        if (!managedObject) {
          return createToolResponse(
            `Managed object type '${objectType}' not found. Available types: ${config.objects?.map((obj: any) => obj.name).join(', ') || 'none'}`
          );
        }
  
        if (includeFullDefinition) {
          return createToolResponse(formatSuccess(managedObject, response));
        }
  
        const schemaInfo = {
          name: managedObject.name,
          required: managedObject.schema?.required || [],
          properties: managedObject.schema?.properties || {}
        };
  
        return createToolResponse(formatSuccess(schemaInfo, response));
      } catch (error: any) {
        return createToolResponse(`Failed to retrieve managed object schema: ${error.message}`);
      }
    }
  };

• src/tools/managedObjects/getManagedObjectSchema.ts:20-33 (schema)

  Zod input schema defining objectType (required string) and includeFullDefinition (optional boolean, defaults false)

  inputSchema: {
    objectType: z
      .string()
      .min(1)
      .describe(
        `Managed object type (e.g., ${EXAMPLE_TYPES_STRING}). Use listManagedObjects to discover all available types.`
      ),
    includeFullDefinition: z
      .boolean()
      .default(false)
      .describe(
        'When true, returns the complete managed object definition including script hooks, lifecycle metadata, notifications, and other configuration. Defaults to false for a concise schema-only response.'
      )
  },

• src/index.ts:27-43 (registration)

  Where all tools are registered via getAllTools() and server.registerTool(). The getManagedObjectSchemaTool is included via managedObjectTools export.

  allTools.forEach((tool) => {
    const toolConfig: ToolConfig = {
      title: tool.title,
      description: tool.description
    };
  
    // Only add inputSchema if it exists (some tools like getLogSources don't have one)
    if ('inputSchema' in tool && tool.inputSchema) {
      toolConfig.inputSchema = tool.inputSchema;
    }
  
    // Add annotations if present
    if ('annotations' in tool && tool.annotations) {
      toolConfig.annotations = tool.annotations;
    }
  
    server.registerTool(tool.name, toolConfig, tool.toolFunction as any);

• src/utils/managedObjectHelpers.ts:1-31 (helper)

  Provides EXAMPLE_TYPES_STRING used in the inputSchema description to list example managed object types

  /**
   * Managed object specific helpers.
   *
   * Includes:
   * - Example managed object types for documentation and tool descriptions
   *
   * IMPORTANT: The example types are NOT exhaustive. The MCP server supports ANY
   * managed object type defined in your PingOne AIC environment, including custom types.
   * Use the listManagedObjects tool to discover all available types in your tenant.
   */
  
  /**
   * Example managed object types for use in tool descriptions.
   * These are common types but not exhaustive - any managed object type works.
   */
  export const EXAMPLE_MANAGED_OBJECT_TYPES = [
    'alpha_user',
    'bravo_user',
    'alpha_role',
    'bravo_role',
    'alpha_group',
    'bravo_group',
    'alpha_organization',
    'bravo_organization'
  ];
  
  /**
   * Formatted string of example types for use in tool descriptions.
   */
  export const EXAMPLE_TYPES_STRING = EXAMPLE_MANAGED_OBJECT_TYPES.join(', ');

• src/utils/apiHelpers.ts:14-58 (helper)

  makeAuthenticatedRequest used by the handler to make the HTTP call, and createToolResponse used to format the response

  export async function makeAuthenticatedRequest(
    url: string,
    scopes: string[],
    options: RequestInit = {}
  ): Promise<{ data: unknown; response: Response }> {
    const token = await getAuthService().getToken(scopes);
  
    const response = await fetch(url, {
      ...options,
      headers: {
        Authorization: `Bearer ${token}`,
        'User-Agent': USER_AGENT,
        // Only add Content-Type header if the request has a body
        ...(options.body && { 'Content-Type': 'application/json' }),
        ...options.headers
      }
    });
  
    if (!response.ok) {
      const errorBody = await response.text();
      throw new Error(formatError(response, errorBody));
    }
  
    // Handle empty responses (e.g., 204 No Content or DELETE operations)
    const contentLength = response.headers.get('content-length');
    const data = response.status === 204 || contentLength === '0' ? null : await response.json();
  
    return { data, response };
  }
  
  /**
   * Creates a standardized MCP tool response
   * @param text - The text content to return to the MCP client
   * @returns MCP-formatted response object
   */
  export function createToolResponse(text: string) {
    return {
      content: [
        {
          type: 'text' as const,
          text
        }
      ]
    };
  }