AEM MCP Server

Instructions

Implementation Reference

• src/operations/version-operations.ts:114-178 (handler)

  Core handler implementing the getVersionHistory tool logic: validates path, fetches from AEM .versionhistory.json, parses and structures version info (name, label, created, etc.), sorts newest first, identifies base version, logs, wraps in success response.

  async getVersionHistory(path: string): Promise<VersionHistoryResponse> {
    return safeExecute<VersionHistoryResponse>(async () => {
      if (!isValidContentPath(path)) {
        throw createAEMError(
          AEM_ERROR_CODES.INVALID_PARAMETERS,
          `Invalid content path: ${path}`,
          { path }
        );
      }
  
      try {
        // Get version history using AEM's versioning API
        const response = await this.httpClient.get(`${path}.versionhistory.json`, {
          params: { ':depth': '2' }
        });
  
        const versions: VersionInfo[] = [];
        let baseVersion: string | undefined;
  
        if (response.data && typeof response.data === 'object') {
          Object.entries(response.data).forEach(([key, value]: [string, any]) => {
            if (key === 'jcr:versionLabels') {
              // Handle version labels
              return;
            }
  
            if (value && typeof value === 'object' && value['jcr:frozenNode']) {
              const versionInfo: VersionInfo = {
                name: key,
                label: value['jcr:frozenNode']?.['jcr:versionLabel'],
                created: value['jcr:created'] || new Date().toISOString(),
                createdBy: value['jcr:createdBy'] || 'unknown',
                comment: value['jcr:versionComment'],
                isBaseVersion: value['jcr:isCheckedOut'] === false
              };
  
              if (versionInfo.isBaseVersion) {
                baseVersion = key;
              }
  
              versions.push(versionInfo);
            }
          });
        }
  
        // Sort versions by creation date (newest first)
        versions.sort((a, b) => new Date(b.created).getTime() - new Date(a.created).getTime());
  
        this.logger.info(`Retrieved version history for path: ${path}`, {
          versionCount: versions.length,
          baseVersion
        });
  
        return createSuccessResponse({
          path,
          versions,
          totalCount: versions.length,
          baseVersion
        }, 'getVersionHistory') as VersionHistoryResponse;
  
      } catch (error: any) {
        throw handleAEMHttpError(error, 'getVersionHistory');
      }
    }, 'getVersionHistory');
  }

• src/mcp-server.ts:516-524 (registration)

  MCP tool registration defining the getVersionHistory tool with name, description, and input schema requiring 'path' parameter.

  name: 'getVersionHistory',
  description: 'Get version history for a content path',
  inputSchema: {
    type: 'object',
    properties: {
      path: { type: 'string' }
    },
    required: ['path'],
  },

• src/mcp-server.ts:792-795 (handler)

  MCP server handler case that extracts 'path' from arguments and calls AEMConnector.getVersionHistory, formats result as MCP response.

  case 'getVersionHistory': {
    const path = (args as { path: string }).path;
    const result = await aemConnector.getVersionHistory(path);
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };

• src/operations/version-operations.ts:22-41 (schema)

  TypeScript interfaces defining input/output schema for getVersionHistory: VersionInfo for each version and VersionHistoryResponse for the full output structure.

  export interface VersionInfo {
    name: string;
    label?: string;
    created: string;
    createdBy: string;
    comment?: string;
    isBaseVersion?: boolean;
  }
  
  export interface VersionHistoryResponse {
    success: boolean;
    operation: string;
    timestamp: string;
    data: {
      path: string;
      versions: VersionInfo[];
      totalCount: number;
      baseVersion?: string;
    };
  }

• src/aem-connector-new.ts:273-274 (helper)

  Delegation helper in AEMConnector that forwards getVersionHistory call to the VersionOperations instance.

  async getVersionHistory(path: string) {
    return this.versionOps.getVersionHistory(path);