AEM MCP Server

Instructions

Implementation Reference

• src/operations/search-operations.ts:85-181 (handler)

  Core handler implementing enhancedPageSearch with fallback strategies: fulltext, title, description searches, and optional cross-locale search using AEM QueryBuilder.

  async enhancedPageSearch(params: EnhancedSearchParams): Promise<SearchResponse> {
    return safeExecute<SearchResponse>(async () => {
      const { searchTerm, basePath, includeAlternateLocales } = params;
      
      // Try multiple search strategies
      const searchStrategies = [
        // Strategy 1: Direct fulltext search
        () => this.searchContent({
          fulltext: searchTerm,
          path: basePath,
          type: 'cq:Page',
          limit: 20
        }),
        
        // Strategy 2: Search by title
        () => this.searchContent({
          'property': 'jcr:title',
          'property.value': searchTerm,
          'property.operation': 'like',
          path: basePath,
          type: 'cq:Page',
          limit: 20
        } as any),
        
        // Strategy 3: Search by description
        () => this.searchContent({
          'property': 'jcr:description',
          'property.value': searchTerm,
          'property.operation': 'like',
          path: basePath,
          type: 'cq:Page',
          limit: 20
        } as any)
      ];
  
      // If includeAlternateLocales is true, add locale-specific searches
      if (includeAlternateLocales) {
        searchStrategies.push(
          // Strategy 4: Search in all locales
          () => this.searchContent({
            fulltext: searchTerm,
            path: basePath.replace(/\/[a-z]{2}(-[A-Z]{2})?$/, ''),
            type: 'cq:Page',
            limit: 20
          })
        );
      }
  
      // Try each strategy until one succeeds
      let lastError: any;
      for (const strategy of searchStrategies) {
        try {
          const result = await strategy();
          if (result.data.results && result.data.results.length > 0) {
            return createSuccessResponse({
              params: {
                searchTerm,
                basePath,
                includeAlternateLocales,
                strategy: 'enhanced'
              },
              results: result.data.results,
              total: result.data.total,
              searchStrategies: searchStrategies.length
            }, 'enhancedPageSearch') as SearchResponse;
          }
        } catch (error) {
          lastError = error;
          this.logger.warn('Search strategy failed', {
            error: error instanceof Error ? error.message : String(error),
            searchTerm,
            basePath
          });
        }
      }
  
      // If all strategies failed, return empty results
      this.logger.warn('All search strategies failed', {
        searchTerm,
        basePath,
        lastError: lastError instanceof Error ? lastError.message : String(lastError)
      });
  
      return createSuccessResponse({
        params: {
          searchTerm,
          basePath,
          includeAlternateLocales,
          strategy: 'enhanced'
        },
        results: [],
        total: 0,
        searchStrategies: searchStrategies.length,
        allStrategiesFailed: true
      }, 'enhancedPageSearch') as SearchResponse;
    }, 'enhancedPageSearch');
  }

• src/mcp-server.ts:254-266 (schema)

  MCP tool schema definition specifying input parameters for enhancedPageSearch.

  {
    name: 'enhancedPageSearch',
    description: 'Intelligent page search with comprehensive fallback strategies and cross-section search',
    inputSchema: {
      type: 'object',
      properties: {
        searchTerm: { type: 'string' },
        basePath: { type: 'string' },
        includeAlternateLocales: { type: 'boolean' },
      },
      required: ['searchTerm', 'basePath'],
    },
  },

• src/mcp-server.ts:578-580 (registration)

  Registration of tool list handler that exposes enhancedPageSearch in the tools array.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return { tools };
  });

• src/mcp-server.ts:701-703 (handler)

  MCP server tool call handler dispatching to AEM connector's enhancedPageSearch.

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

• src/mcp-handler.ts:57-58 (handler)

  Internal MCP request handler switch case calling enhancedPageSearch.

  case 'enhancedPageSearch':
    return await this.aemConnector.enhancedPageSearch(params);