feat: align MCP server with alias-first architecture

[kapral18]

Summary

The indexer is moving to an alias-first architecture (see elastic/semantic-code-search-indexer#132). This requires corresponding changes in the MCP server to align with the new architecture.

Problem Statement

With the alias-first architecture:

• Aliases are primary: kibana (public-facing identifier)
• Indices are ephemeral: kibana-{timestamp} (internal implementation detail)
• list_indices should show aliases, not indices
• All operations should reference aliases

The MCP server needs to be updated to work with aliases as the primary concept.

Current State

• Discovers indices via *-repo aliases
• Extracts and shows index names to users
• Index names are the primary identifier
• Operations reference index names

Required Changes

1. list_indices Behavior

• Current: Shows index names (e.g., kibana)
• New: Should show alias names (e.g., kibana - which is now an alias)
• Discovery should find aliases, not indices
• Return alias names as the primary identifiers

2. Discovery Strategy

• Current: Discovers via *-repo aliases, extracts index names
• New: Discover aliases directly (no -repo suffix requirement)
• Users can create aliases with any name: kibana, my-alias, etc.
• Discovery should find all aliases that point to valid indices
• Filter out system indices: Exclude aliases pointing to system indices (those starting with .)

3. Operations Reference Aliases

• All tool operations (semantic_code_search, symbol_analysis, etc.) should accept alias names
• Internal operations resolve aliases to actual indices when needed
• Error messages should reference aliases, not indices

4. Settings Index Discovery

• Settings index pattern may change: {aliasName}_settings instead of {indexName}_settings
• Need to track alias → index mapping in settings
• Discovery should work with alias-based settings indices

Implementation Details

Example Flow

User runs: npm run index -- kibana

Indexer creates:
- Index: `kibana-1733856000000` (ephemeral)
- Alias: `kibana` → `kibana-1733856000000`

MCP Server:
- Discovers alias: `kibana`
- `list_indices` returns: [`kibana`] (alias name)
- User queries via alias: `kibana`
- Server resolves alias → `kibana-1733856000000` internally
- Operations work transparently

Discovery Strategy with System Index Filtering

Problem: getAlias({ name: '*' }) returns all aliases, including system indices like .internal-alerts*, .kibana*, etc. Elasticsearch doesn't support exclude patterns in getAlias API, so we need to filter results after fetching.

Solution: Filter out aliases that point to system indices (indices starting with .):

// Get all aliases
const aliasesResponse = await client.indices.getAlias({ name: '*' });

// Collect all alias names that point to non-system indices
const aliasNames = new Set<string>();

for (const [indexName, indexInfo] of Object.entries(aliasesResponse)) {
  // Skip system indices (almost all start with '.')
  if (indexName.startsWith('.')) {
    continue;
  }
  
  // Collect all aliases pointing to this index
  const aliases = Object.keys(indexInfo.aliases || {});
  aliases.forEach(alias => aliasNames.add(alias));
}

return Array.from(aliasNames); // Returns: ['kibana', 'my-alias', ...]

Why this works:

• ✅ Simple: Single filter check (startsWith('.'))
• ✅ Fast: No additional API calls needed
• ✅ Effective: Catches .internal-alerts*, .kibana*, .security*, etc.
• ✅ ES convention: System indices almost always start with .

Edge cases: If you encounter non-dot-prefixed system indices, add specific patterns:

const systemPatterns = [
  /^\./,  // All dot-prefixed indices
  // Add specific patterns if needed:
  // /^internal-/,  // If you have non-dot system indices
];

Complete Discovery Flow

1. Query all aliases: `getAlias({ name: '*' })`
2. Filter out aliases pointing to system indices (start with '.')
3. Extract alias names from remaining indices
4. Return alias names (not index names)
5. Fallback: Discover via settings indices if needed

Benefits

• ✅ Consistent with indexer's alias-first architecture
• ✅ Users see clean alias names (not cryptic timestamped indices)
• ✅ Supports zero-downtime reindexing (alias swapping is transparent)
• ✅ No -repo suffix requirement
• ✅ Flexible alias naming
• ✅ System indices automatically filtered out

Related

• Depends on: elastic/semantic-code-search-indexer#132
• Supersedes Improve list_indices to discover indices via _settings pattern fallback #33 and feat: improve list_indices with dual discovery and consistent index name display #34