Get Journey Preview URL

Instructions

Implementation Reference

• src/tools/am/getJourneyPreviewUrl.ts:1-40 (handler)

  The main implementation file for the 'getJourneyPreviewUrl' tool. It defines the tool object with name, title, description, inputSchema (realm + optional journeyName), and the toolFunction handler that builds a preview URL for testing authentication journeys.

  import { z } from 'zod';
  import { createToolResponse } from '../../utils/apiHelpers.js';
  import { REALMS, safePathSegmentSchema } from '../../utils/validationHelpers.js';
  
  const aicBaseUrl = process.env.AIC_BASE_URL;
  
  export const getJourneyPreviewUrlTool = {
    name: 'getJourneyPreviewUrl',
    title: 'Get Journey Preview URL',
    description:
      'Generate the preview URL for testing an authentication journey. Returns a URL that can be opened in a browser to test the journey flow.',
    scopes: [],
    annotations: {
      readOnlyHint: true
    },
    inputSchema: {
      realm: z.enum(REALMS).describe('The realm containing the journey'),
      journeyName: safePathSegmentSchema
        .optional()
        .describe('The name of the journey to preview. If omitted, returns the URL for the default journey.')
    },
    async toolFunction({ realm, journeyName }: { realm: string; journeyName?: string }) {
      // Build the base URL
      let previewUrl = `https://${aicBaseUrl}/am/XUI/?realm=/${realm}`;
  
      // Add journey-specific parameters if a journey name is provided
      if (journeyName) {
        const encodedJourneyName = encodeURIComponent(journeyName);
        previewUrl += `&authIndexType=service&authIndexValue=${encodedJourneyName}`;
      }
  
      const result = {
        realm,
        journeyName: journeyName || '(default)',
        previewUrl
      };
  
      return createToolResponse(JSON.stringify(result, null, 2));
    }
  };

• src/tools/am/getJourneyPreviewUrl.ts:16-21 (schema)

  Input schema using Zod: realm must be one of the REALMS enum ('alpha' or 'bravo'), and journeyName is optional and validated via safePathSegmentSchema to prevent path traversal.

  inputSchema: {
    realm: z.enum(REALMS).describe('The realm containing the journey'),
    journeyName: safePathSegmentSchema
      .optional()
      .describe('The name of the journey to preview. If omitted, returns the URL for the default journey.')
  },

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

  General tool registration loop: iterates over all tools (including getJourneyPreviewUrlTool) and registers each with the MCP server using server.registerTool(tool.name, toolConfig, tool.toolFunction).

  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/toolHelpers.ts:15-33 (registration)

  getAllTools collects all tools from all categories. AM tools (including getJourneyPreviewUrlTool) are included via the amTools module export when not in Docker mode.

  export function getAllTools(): Tool[] {
    const isDockerMode = process.env.DOCKER_CONTAINER === 'true';
  
    const tools: Tool[] = [
      ...(Object.values(managedObjectTools) as Tool[]),
      ...(Object.values(logTools) as Tool[]),
      ...(Object.values(themeTools) as Tool[]),
      ...(Object.values(esvTools) as Tool[]),
      ...(Object.values(featureManagementTools) as Tool[])
    ];
  
    // Only include AM tools in non-Docker mode (requires browser-based PKCE auth)
    if (!isDockerMode) {
      tools.push(...(Object.values(amTools) as Tool[]));
      tools.push(...(Object.values(applicationTools) as Tool[]));
    }
  
    return tools;
  }

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

  createToolResponse helper function that formats the tool's return value into the standard MCP response format with text content.

  export function createToolResponse(text: string) {
    return {
      content: [
        {
          type: 'text' as const,
          text
        }
      ]
    };
  }