Problem

Currently there is no way to control the JSON Schema format returned by tools/list. The schema transformation pipeline (from #32) always flattens discriminated unions to flat schemas.

Different MCP clients have different JSON Schema validation capabilities:

• Some clients (Claude Code, Claude Desktop) work better with flat schemas
• Some clients (Inspector) can handle oneOf/discriminated unions
• Future clients may support richer schema formats

Additionally, the same MCP server may serve different clients simultaneously, so a global setting is not ideal.

Proposed Solution

Phase 1: Basic GITLAB_SCHEMA_MODE

Add environment variable to control schema output format:

# Options: flat | discriminated
GITLAB_SCHEMA_MODE=flat  # default, current behavior

flat mode (current default):

• Merges all action branches into single object schema
• Adds "Required for 'X' action(s)" hints to descriptions
• Best compatibility with current AI clients

discriminated mode (future):

• Preserves oneOf with discriminator on action field
• Each branch has only its action-specific fields
• Better for clients that support JSON Schema properly

Phase 2: Auto-detection per-session

Automatically detect and cache schema mode per-session based on initialize.clientInfo:

function detectSchemaMode(clientInfo: ClientInfo): "flat" | "discriminated" {
  const name = clientInfo?.name?.toLowerCase() ?? "";
  
  // Known clients that need flat schemas
  if (name.includes("claude-code") || name.includes("claude-desktop")) {
    return "flat";
  }
  
  // Safe default for unknown clients
  return "flat";
}

Add new mode:

GITLAB_SCHEMA_MODE=auto  # detect from clientInfo (future default)

Benefits

• Phase 1: Users can explicitly choose schema format
• Phase 2: 90% of "why doesn't it work" issues resolved automatically
• Per-session isolation for mixed client environments
• Future-proof: can enable discriminated unions for capable clients

Tasks

Phase 1: Basic Implementation

• Add GITLAB_SCHEMA_MODE to config.ts (flat|discriminated)
• Add getSchemaMode() helper function
• Conditionally apply/skip flattening in schema-utils.ts based on mode
• Update tools/list to respect schema mode
• Add documentation for new env var
• Add unit tests for both modes

Phase 2: Auto-detection

• Add schema mode detection in initialize handler
• Store schema mode in session metadata
• Add auto as third option (detect from clientInfo)
• Make auto the default
• Add logging for detected schema mode

Environment Variable

# Phase 1
GITLAB_SCHEMA_MODE=flat|discriminated

# Phase 2
GITLAB_SCHEMA_MODE=auto|flat|discriminated  # auto = detect from clientInfo

Related

• Builds on schema transformation pipeline from feat: Dynamic action filtering with multi-level description customization #32
• Enhances documentation from feat(cli): Add --export flag to list-tools for TOOLS.md generation #47