aem-mcp-server 1.0.0

package/src/aem/aem.errors.ts

@@ -0,0 +1,152 @@
+export interface AEMErrorDetails {
+  [key: string]: any;
+}
+
+export class AEMOperationError extends Error {
+  code: string;
+  details?: AEMErrorDetails;
+  recoverable?: boolean;
+  retryAfter?: number;
+
+  constructor(error: {
+    code: string;
+    message: string;
+    details?: AEMErrorDetails;
+    recoverable?: boolean;
+    retryAfter?: number;
+  }) {
+    super(error.message);
+    this.name = 'AEMOperationError';
+    this.code = error.code;
+    this.details = error.details;
+    this.recoverable = error.recoverable;
+    this.retryAfter = error.retryAfter;
+  }
+}
+
+export const AEM_ERROR_CODES = {
+  CONNECTION_FAILED: 'CONNECTION_FAILED',
+  TIMEOUT: 'TIMEOUT',
+  AUTHENTICATION_FAILED: 'AUTHENTICATION_FAILED',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  INVALID_PATH: 'INVALID_PATH',
+  INVALID_COMPONENT_TYPE: 'INVALID_COMPONENT_TYPE',
+  INVALID_LOCALE: 'INVALID_LOCALE',
+  INVALID_PARAMETERS: 'INVALID_PARAMETERS',
+  RESOURCE_NOT_FOUND: 'RESOURCE_NOT_FOUND',
+  COMPONENT_NOT_FOUND: 'COMPONENT_NOT_FOUND',
+  PAGE_NOT_FOUND: 'PAGE_NOT_FOUND',
+  UPDATE_FAILED: 'UPDATE_FAILED',
+  VALIDATION_FAILED: 'VALIDATION_FAILED',
+  REPLICATION_FAILED: 'REPLICATION_FAILED',
+  QUERY_FAILED: 'QUERY_FAILED',
+  INSUFFICIENT_PERMISSIONS: 'INSUFFICIENT_PERMISSIONS',
+  SYSTEM_ERROR: 'SYSTEM_ERROR',
+  RATE_LIMITED: 'RATE_LIMITED',
+} as const;
+
+export function createAEMError(
+  code: string,
+  message: string,
+  details?: AEMErrorDetails,
+  recoverable = false,
+  retryAfter?: number
+): AEMOperationError {
+  return new AEMOperationError({ code, message, details, recoverable, retryAfter });
+}
+
+export function handleAEMHttpError(error: any, operation: string): AEMOperationError {
+  if (error.response) {
+    const status = error.response.status;
+    const data = error.response.data;
+    switch (status) {
+      case 401:
+        return createAEMError(AEM_ERROR_CODES.AUTHENTICATION_FAILED, 'Authentication failed. Check AEM credentials.', { status, data });
+      case 403:
+        return createAEMError(AEM_ERROR_CODES.INSUFFICIENT_PERMISSIONS, 'Insufficient permissions for this operation.', { status, data, operation });
+      case 404:
+        return createAEMError(AEM_ERROR_CODES.RESOURCE_NOT_FOUND, 'Resource not found in AEM.', { status, data, operation });
+      case 429:
+        const retryAfter = error.response.headers['retry-after'];
+        return createAEMError(AEM_ERROR_CODES.RATE_LIMITED, 'Rate limit exceeded. Please try again later.', { status, data }, true, retryAfter ? parseInt(retryAfter) * 1000 : 60000);
+      case 500:
+      case 502:
+      case 503:
+        return createAEMError(AEM_ERROR_CODES.SYSTEM_ERROR, 'AEM system error. Please try again later.', { status, data }, true, 30000);
+      default:
+        return createAEMError(AEM_ERROR_CODES.SYSTEM_ERROR, `HTTP ${status}: ${data?.message || 'Unknown error'}`, { status, data, operation });
+    }
+  } else if (error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND') {
+    return createAEMError(AEM_ERROR_CODES.CONNECTION_FAILED, 'Cannot connect to AEM instance. Check host and network.', { originalError: error.message }, true, 5000);
+  } else if (error.code === 'ETIMEDOUT') {
+    return createAEMError(AEM_ERROR_CODES.TIMEOUT, 'Request to AEM timed out.', { originalError: error.message }, true, 10000);
+  } else {
+    return createAEMError(AEM_ERROR_CODES.SYSTEM_ERROR, `Unexpected error during ${operation}: ${error.message}`, { originalError: error.message });
+  }
+}
+
+export async function safeExecute<T>(operation: () => Promise<T>, operationName: string, maxRetries = 3): Promise<T> {
+  let lastError: any;
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error: any) {
+      lastError = error instanceof AEMOperationError
+        ? error
+        : handleAEMHttpError(error, operationName);
+      if (!lastError.recoverable || attempt === maxRetries) {
+        break;
+      }
+      const delay = lastError.retryAfter || Math.pow(2, attempt) * 1000;
+      // eslint-disable-next-line no-console
+      console.warn(`[${operationName}] Attempt ${attempt} failed, retrying in ${delay}ms:`, lastError.message);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  throw lastError;
+}
+
+export function validateComponentOperation(locale: string, pagePath: string, component: string, props: any): void {
+  const errors: string[] = [];
+  if (!locale || typeof locale !== 'string') {
+    errors.push('Locale is required and must be a string');
+  }
+  if (!pagePath || typeof pagePath !== 'string') {
+    errors.push('Page path is required and must be a string');
+  } else if (!pagePath.startsWith('/content')) {
+    errors.push('Page path must start with /content');
+  }
+  if (!component || typeof component !== 'string') {
+    errors.push('Component type is required and must be a string');
+  }
+  if (!props || typeof props !== 'object') {
+    errors.push('Component properties are required and must be an object');
+  }
+  if (errors.length > 0) {
+    throw createAEMError(AEM_ERROR_CODES.INVALID_PARAMETERS, 'Invalid component operation parameters', { errors });
+  }
+}
+
+export function createSuccessResponse<T>(data: T, operation: string) {
+  return {
+    success: true,
+    operation,
+    timestamp: new Date().toISOString(),
+    data
+  };
+}
+
+export function createErrorResponse(error: AEMOperationError, operation: string) {
+  return {
+    success: false,
+    operation,
+    timestamp: new Date().toISOString(),
+    error: {
+      code: error.code,
+      message: error.message,
+      details: error.details,
+      recoverable: error.recoverable,
+      retryAfter: error.retryAfter
+    }
+  };
+} 

package/src/config.ts

@@ -0,0 +1,12 @@
+const SERVER_PORT = parseInt(process.env.SERVER_PORT || '3000', 10);
+const MCP_PORT = parseInt(process.env.MCP_PORT || '8080', 10);
+const MCP_USERNAME = process.env.MCP_USERNAME || 'admin';
+const MCP_PASSWORD = process.env.MCP_PASSWORD || 'admin';
+const APP_VERSION = process.env.npm_package_version || '1.0.0';
+
+export const config = {
+  SERVER_PORT,
+  MCP_USERNAME,
+  MCP_PASSWORD,
+  APP_VERSION
+}

package/src/explorer/api.explorer.ts

@@ -0,0 +1,30 @@
+import swaggerUi from 'swagger-ui-express';
+import swaggerJSDoc from 'swagger-jsdoc';
+import { Express, Request, Response } from 'express';
+import { config } from '../config.js';
+import { apiPaths } from './api.spec.js';
+
+const swaggerDefinition = {
+  openapi: '3.0.0',
+  info: {
+    title: 'AEM MCP Gateway API',
+    version: '1.0.0',
+    description: 'API documentation for the AEM MCP Gateway Server',
+  },
+  servers: [
+    { url: `http://localhost:${config.SERVER_PORT}` },
+  ],
+};
+
+const options = {
+  swaggerDefinition,
+  apis: [],
+};
+
+const openapiSpec: any = swaggerJSDoc(options);
+openapiSpec.paths = apiPaths;
+
+export const useExplorer = (app: Express) => {
+  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(openapiSpec));
+  app.get('/openapi.json', (req: Request, res: Response) => { res.json(openapiSpec); });
+}

package/src/explorer/api.spec.ts

@@ -0,0 +1,79 @@
+export const apiPaths = {
+  '/mcp': {
+    post: {
+      summary: 'JSON-RPC endpoint for MCP calls',
+      description: 'Call MCP methods using JSON-RPC 2.0. The method and params must be provided in the request body.',
+      requestBody: {
+        required: true,
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: {
+                jsonrpc: { type: 'string', example: '2.0' },
+                id: { type: 'integer', example: 1 },
+                method: { type: 'string', example: 'listMethods' },
+                params: { type: 'object' },
+              },
+              required: ['jsonrpc', 'id', 'method'],
+            },
+          },
+        },
+      },
+      responses: {
+        200: {
+          description: 'JSON-RPC response',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  jsonrpc: { type: 'string', example: '2.0' },
+                  id: { type: 'integer', example: 1 },
+                  result: { type: 'object' },
+                  error: { type: 'object' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+  '/mcp/methods': {
+    get: {
+      summary: 'List all available MCP methods',
+      description: 'Returns a list of all available MCP methods and their parameters.',
+      responses: {
+        200: {
+          description: 'A list of MCP methods',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  methods: {
+                    type: 'array',
+                    items: {
+                      type: 'object',
+                      properties: {
+                        name: { type: 'string' },
+                        description: { type: 'string' },
+                        parameters: {
+                          type: 'array',
+                          items: { type: 'string' },
+                        },
+                      },
+                    },
+                  },
+                  total: { type: 'integer' },
+                  timestamp: { type: 'string', format: 'date-time' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+};

package/src/index.ts

@@ -0,0 +1,4 @@
+import { config } from './config.js';
+import { startServer } from './server/app.server.js';
+
+startServer(config.SERVER_PORT);

package/src/mcp/mcp.aem-handler.ts

@@ -0,0 +1,158 @@
+import { AEMConnector } from '../aem/aem.connector.js';
+import { config } from '../config.js';
+
+export class MCPRequestHandler {
+  aemConnector: AEMConnector;
+
+  constructor(aemConnector: AEMConnector) {
+    this.aemConnector = aemConnector;
+  }
+
+  async handleRequest(method: string, params: any) {
+    try {
+      switch (method) {
+        case 'validateComponent':
+          return await this.aemConnector.validateComponent(params);
+        case 'updateComponent':
+          return await this.aemConnector.updateComponent(params);
+        case 'undoChanges':
+          return await this.aemConnector.undoChanges(params);
+        case 'scanPageComponents':
+          return await this.aemConnector.scanPageComponents(params.pagePath);
+        case 'fetchSites':
+          return await this.aemConnector.fetchSites();
+        case 'fetchLanguageMasters':
+          return await this.aemConnector.fetchLanguageMasters(params.site);
+        case 'fetchAvailableLocales':
+          return await this.aemConnector.fetchAvailableLocales(params.site, params.languageMasterPath);
+        case 'replicateAndPublish':
+          return await this.aemConnector.replicateAndPublish(params.selectedLocales, params.componentData, params.localizedOverrides);
+        case 'getAllTextContent':
+          return await this.aemConnector.getAllTextContent(params.pagePath);
+        case 'getPageTextContent':
+          return await this.aemConnector.getPageTextContent(params.pagePath);
+        case 'getPageImages':
+          return await this.aemConnector.getPageImages(params.pagePath);
+        case 'updateImagePath':
+          return await this.aemConnector.updateImagePath(params.componentPath, params.newImagePath);
+        case 'getPageContent':
+          return await this.aemConnector.getPageContent(params.pagePath);
+        case 'listPages':
+          return await this.aemConnector.listPages(params.siteRoot || params.path || '/content', params.depth || 1, params.limit || 20);
+        case 'getNodeContent':
+          return await this.aemConnector.getNodeContent(params.path, params.depth || 1);
+        case 'listChildren':
+          return await this.aemConnector.listChildren(params.path);
+        case 'getPageProperties':
+          return await this.aemConnector.getPageProperties(params.pagePath);
+        case 'searchContent':
+          return await this.aemConnector.searchContent(params);
+        case 'executeJCRQuery':
+          return await this.aemConnector.executeJCRQuery(params.query, params.limit);
+        case 'getAssetMetadata':
+          return await this.aemConnector.getAssetMetadata(params.assetPath);
+        case 'getStatus':
+          return this.getWorkflowStatus(params.workflowId);
+        case 'listMethods':
+          return { methods: this.getAvailableMethods() };
+        case 'enhancedPageSearch':
+          return await this.aemConnector.searchContent({
+            fulltext: params.searchTerm,
+            path: params.basePath,
+            type: 'cq:Page',
+            limit: 20
+          });
+        case 'createPage':
+          return await this.aemConnector.createPage(params);
+        case 'deletePage':
+          return await this.aemConnector.deletePage(params);
+        case 'createComponent':
+          return await this.aemConnector.createComponent(params);
+        case 'deleteComponent':
+          return await this.aemConnector.deleteComponent(params);
+        case 'unpublishContent':
+          return await this.aemConnector.unpublishContent(params);
+        case 'activatePage':
+          return await this.aemConnector.activatePage(params);
+        case 'deactivatePage':
+          return await this.aemConnector.deactivatePage(params);
+        case 'uploadAsset':
+          return await this.aemConnector.uploadAsset(params);
+        case 'updateAsset':
+          return await this.aemConnector.updateAsset(params);
+        case 'deleteAsset':
+          return await this.aemConnector.deleteAsset(params);
+        case 'getTemplates':
+          return await this.aemConnector.getTemplates(params.sitePath);
+        case 'getTemplateStructure':
+          return await this.aemConnector.getTemplateStructure(params.templatePath);
+        default:
+          throw new Error(`Unknown method: ${method}`);
+      }
+    } catch (error: any) {
+      return { error: error.message, method, params };
+    }
+  }
+
+  getWorkflowStatus(workflowId: string) {
+    return {
+      success: true,
+      workflowId: workflowId,
+      status: 'completed',
+      message: 'Mock workflow status - always returns completed',
+      timestamp: new Date().toISOString()
+    };
+  }
+
+  getAvailableMethods() {
+    return [
+      { name: 'validateComponent', description: 'Validate component changes before applying them', parameters: ['locale', 'page_path', 'component', 'props'] },
+      { name: 'updateComponent', description: 'Update component properties in AEM', parameters: ['componentPath', 'properties'] },
+      { name: 'undoChanges', description: 'Undo the last component changes', parameters: ['job_id'] },
+      { name: 'scanPageComponents', description: 'Scan a page to discover all components and their properties', parameters: ['pagePath'] },
+      { name: 'fetchSites', description: 'Get all available sites in AEM', parameters: [] },
+      { name: 'fetchLanguageMasters', description: 'Get language masters for a specific site', parameters: ['site'] },
+      { name: 'fetchAvailableLocales', description: 'Get available locales for a site and language master', parameters: ['site', 'languageMasterPath'] },
+      { name: 'replicateAndPublish', description: 'Replicate and publish content to selected locales', parameters: ['selectedLocales', 'componentData', 'localizedOverrides'] },
+      { name: 'getAllTextContent', description: 'Get all text content from a page including titles, text components, and descriptions', parameters: ['pagePath'] },
+      { name: 'getPageTextContent', description: 'Get text content from a specific page', parameters: ['pagePath'] },
+      { name: 'getPageImages', description: 'Get all images from a page, including those within Experience Fragments', parameters: ['pagePath'] },
+      { name: 'updateImagePath', description: 'Update the image path for an image component and verify the update', parameters: ['componentPath', 'newImagePath'] },
+      { name: 'getPageContent', description: 'Get all content from a page including Experience Fragments and Content Fragments', parameters: ['pagePath'] },
+      { name: 'listPages', description: 'List all pages under a site root', parameters: ['siteRoot', 'depth', 'limit'] },
+      { name: 'getNodeContent', description: 'Legacy: Get JCR node content', parameters: ['path', 'depth'] },
+      { name: 'listChildren', description: 'Legacy: List child nodes', parameters: ['path'] },
+      { name: 'getPageProperties', description: 'Get page properties', parameters: ['pagePath'] },
+      { name: 'searchContent', description: 'Search content using Query Builder', parameters: ['type', 'fulltext', 'path', 'limit'] },
+      { name: 'executeJCRQuery', description: 'Execute JCR query', parameters: ['query', 'limit'] },
+      { name: 'getAssetMetadata', description: 'Get asset metadata', parameters: ['assetPath'] },
+      { name: 'getStatus', description: 'Get workflow status by ID', parameters: ['workflowId'] },
+      { name: 'listMethods', description: 'Get list of available MCP methods', parameters: [] },
+      { name: 'enhancedPageSearch', description: 'Intelligent page search with comprehensive fallback strategies and cross-section search', parameters: ['searchTerm', 'basePath', 'includeAlternateLocales'] },
+      { name: 'createPage', description: 'Create a new page in AEM', parameters: ['parentPath', 'title', 'template', 'name', 'properties'] },
+      { name: 'deletePage', description: 'Delete a page from AEM', parameters: ['pagePath', 'force'] },
+      { name: 'createComponent', description: 'Create a new component on a page', parameters: ['pagePath', 'componentType', 'resourceType', 'properties', 'name'] },
+      { name: 'deleteComponent', description: 'Delete a component from AEM', parameters: ['componentPath', 'force'] },
+      { name: 'unpublishContent', description: 'Unpublish content from the publish environment', parameters: ['contentPaths', 'unpublishTree'] },
+      { name: 'activatePage', description: 'Activate (publish) a single page', parameters: ['pagePath', 'activateTree'] },
+      { name: 'deactivatePage', description: 'Deactivate (unpublish) a single page', parameters: ['pagePath', 'deactivateTree'] },
+      { name: 'uploadAsset', description: 'Upload a new asset to AEM DAM', parameters: ['parentPath', 'fileName', 'fileContent', 'mimeType', 'metadata'] },
+      { name: 'updateAsset', description: 'Update an existing asset in AEM DAM', parameters: ['assetPath', 'metadata', 'fileContent', 'mimeType'] },
+      { name: 'deleteAsset', description: 'Delete an asset from AEM DAM', parameters: ['assetPath', 'force'] },
+      { name: 'getTemplates', description: 'Get available page templates', parameters: ['sitePath'] },
+      { name: 'getTemplateStructure', description: 'Get detailed structure of a specific template', parameters: ['templatePath'] },
+    ];
+  }
+
+  async handleHealthCheck() {
+    const aemConnected = await this.aemConnector.testConnection();
+    return {
+      status: 'healthy',
+      aem: aemConnected ? 'connected' : 'disconnected',
+      mcp: 'ready',
+      timestamp: new Date().toISOString(),
+      version: config.APP_VERSION || '1.0.0',
+      port: config.SERVER_PORT,
+    };
+  }
+}

package/src/mcp/mcp.server-handler.ts

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+import { Request, Response } from 'express';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { transports } from './mcp.transports.js';
+import { createMCPServer } from './mcp.server.js';
+
+export const handleRequest = async (req: Request, res: Response) => {
+  console.log('Received MCP request:', req.body);
+  const { jsonrpc, id, method, params } = req.body;
+  if (jsonrpc !== '2.0' || !method) {
+    res.status(400).json({
+      jsonrpc: '2.0',
+      id: id || null,
+      error: { code: -32600, message: 'Invalid Request', data: 'Must be valid JSON-RPC 2.0' },
+    });
+    return;
+  }
+  try {
+    // Check for existing session ID
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+    let transport: StreamableHTTPServerTransport;
+
+    if (sessionId && transports[sessionId]) {
+      // Reuse existing transport
+      transport = transports[sessionId]
+    } else if (!sessionId && isInitializeRequest(req.body)) {
+      // New initialization request - use JSON response mode
+      transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        enableJsonResponse: true, // Enable JSON response mode
+        onsessioninitialized: (sessionId) => {
+          // Store the transport by session ID when session is initialized
+          // This avoids race conditions where requests might come in before the session is stored
+          console.log(`Session initialized with ID: ${sessionId}`);
+          transports[sessionId] = transport;
+        }
+      });
+
+      // Connect the transport to the MCP server BEFORE handling the request
+      const server = createMCPServer();
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+      return; // Already handled
+    } else {
+      // Invalid request - no session ID or not initialization request
+      res.status(400).json({
+        jsonrpc: '2.0',
+        error: {
+          code: -32000,
+          message: 'Bad Request: No valid session ID provided',
+        },
+        id: null,
+      });
+      return;
+    }
+
+    // Handle the request with existing transport - no need to reconnect
+    await transport.handleRequest(req, res, req.body);
+  } catch (error) {
+    console.error('Error handling MCP request:', error);
+    if (!res.headersSent) {
+      res.status(500).json({
+        jsonrpc: '2.0',
+        error: {
+          code: -32603,
+          message: 'Internal server error',
+        },
+        id: null,
+      });
+    }
+  }
+};

package/src/mcp/mcp.server.ts

@@ -0,0 +1,51 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CallToolResult, CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { tools } from './mcp.tools.js';
+import { AEMConnector } from '../aem/aem.connector.js';
+import { MCPRequestHandler } from './mcp.aem-handler.js';
+
+export const createMCPServer = () => {
+  const aemConnector = new AEMConnector();
+  const mcpHandler = new MCPRequestHandler(aemConnector);
+
+  const server = new Server({
+    name: 'aem-mcp-server',
+    version: '1.0.0',
+  }, {
+    capabilities: {
+      resources: {},
+      tools: {},
+      prompts: {},
+    },
+  });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    if (!args) {
+      return {
+        content: [
+          { type: 'text', text: 'Error: No arguments provided' },
+        ],
+        isError: true,
+      };
+    }
+    try {
+      const result = await mcpHandler.handleRequest(name, args);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (error: any) {
+      return {
+        content: [{ type: 'text', text: `Error: ${error.message}` }],
+        isError: true,
+      };
+    }
+  });
+
+  return server;
+}