GetPackageTree

Instructions

Implementation Reference

• src/handlers/system/high/handleGetPackageTree.ts:63-132 (handler)

  Main handler function for GetPackageTree tool. Validates package_name, creates ADT client, verifies package existence via client.getPackage().read(), fetches hierarchical tree via utils.getPackageHierarchy(), and returns formatted response with package tree data.

  export async function handleGetPackageTree(
    context: HandlerContext,
    args: GetPackageTreeArgs,
  ) {
    const { connection, logger } = context;
    try {
      // Validate required parameters
      if (!args?.package_name) {
        return return_error(new Error('package_name is required'));
      }
  
      const packageName = args.package_name.toUpperCase();
      const includeSubpackages = args.include_subpackages !== false;
      const maxDepth = args.max_depth || 5;
      const includeDescriptions = args.include_descriptions !== false;
  
      logger?.info(
        `Fetching package tree for ${packageName} (include_subpackages: ${includeSubpackages}, max_depth: ${maxDepth}) using adt-clients`,
      );
  
      const client = createAdtClient(connection, logger);
      const utils = client.getUtils();
  
      // Verify package exists before building tree (fixes #38)
      try {
        const readResult = await client.getPackage().read({ packageName });
        if (!readResult || !readResult.readResult) {
          return return_error(new Error(`Package ${packageName} not found`));
        }
      } catch (readError: any) {
        if (readError.response?.status === 404) {
          return return_error(new Error(`Package ${packageName} not found`));
        }
        throw readError;
      }
  
      // Use the optimized and fixed hierarchy builder from adt-clients
      const packageTree = await utils.getPackageHierarchy(packageName, {
        includeSubpackages,
        maxDepth,
        includeDescriptions,
      });
  
      if (!packageTree) {
        return return_error(
          new Error(`Failed to fetch package tree for ${packageName}`),
        );
      }
  
      logger?.debug(`Package tree fetched successfully for ${packageName}`);
  
      // Format response
      const response = {
        package_name: packageName,
        tree: packageTree,
        metadata: {
          include_subpackages: includeSubpackages,
          max_depth: maxDepth,
          include_descriptions: includeDescriptions,
        },
      };
  
      return return_response({
        data: JSON.stringify(response, null, 2),
      } as any);
    } catch (error: any) {
      logger?.error('Failed to fetch package tree', error);
      return return_error(error);
    }
  }

• src/handlers/system/high/handleGetPackageTree.ts:12-50 (schema)

  Tool definition and input schema for GetPackageTree. Defines name 'GetPackageTree', availability in onprem/cloud, and input properties: package_name (required string), include_subpackages (boolean, default true), max_depth (integer, default 5), include_descriptions (boolean, default true), debug (boolean, default false).

  export const TOOL_DEFINITION = {
    name: 'GetPackageTree',
    available_in: ['onprem', 'cloud'] as const,
    description:
      '[high-level] Retrieve complete package tree structure including subpackages and objects. Returns hierarchical tree with object names, types, and descriptions.',
    inputSchema: {
      type: 'object',
      properties: {
        package_name: {
          type: 'string',
          description: 'Package name (e.g., "ZMY_PACKAGE")',
        },
        include_subpackages: {
          type: 'boolean',
          description:
            'Include subpackages recursively in the tree. If false, subpackages are shown as first-level objects but not recursively expanded. Default: true',
          default: true,
        },
        max_depth: {
          type: 'integer',
          description:
            'Maximum depth for recursive package traversal. Default: 5',
          default: 5,
        },
        include_descriptions: {
          type: 'boolean',
          description: 'Include object descriptions in response. Default: true',
          default: true,
        },
        debug: {
          type: 'boolean',
          description:
            'Include diagnostic metadata in response (counts, types, hierarchy info). Default: false',
          default: false,
        },
      },
      required: ['package_name'],
    },
  } as const;

• src/handlers/system/high/handleGetPackageTree.ts:52-58 (helper)

  TypeScript interface GetPackageTreeArgs defining the typed input arguments for the handler.

  interface GetPackageTreeArgs {
    package_name: string;
    include_subpackages?: boolean;
    max_depth?: number;
    include_descriptions?: boolean;
    debug?: boolean;
  }

• src/lib/handlers/groups/SystemHandlersGroup.ts:297-311 (registration)

  Registration of GetPackageTree in SystemHandlersGroup. Maps the TOOL_DEFINITION (aliased as GetPackageTree_Tool) to the handleGetPackageTree handler within the getHandlers() method, which is later registered on the MCP server via BaseHandlerGroup.registerHandlers().

  // High-level handler for package tree
  {
    toolDefinition: GetPackageTree_Tool,
    handler: (args: any) => {
      return handleGetPackageTree(
        this.context,
        args as {
          package_name: string;
          include_subpackages?: boolean;
          max_depth?: number;
          include_descriptions?: boolean;
        },
      );
    },
  },