MCP: Consider unified command layer architecture

[joshrotenberg]

Parent Issue

Part of #475 (MCP Server)

Context

Discussion about avoiding duplication between CLI and MCP implementations.

Current State

• CLI has 3 layers: raw API, human commands, workflows
• MCP server wraps redis-enterprise / redis-cloud crates directly
• ~381 handler methods across both crates
• Currently implementing first-class MCP tools manually

Future Architecture Options

Option 1: Command Registry Pattern

pub struct Command {
    name: &'static str,           // "enterprise.database.create"
    description: &'static str,
    params: Vec<ParamDef>,        // typed parameter definitions
    handler: AsyncHandler,        // async fn(params) -> Result<Value>
}

// Both CLI and MCP consume this registry
let registry = CommandRegistry::new();

Option 2: Derive Macro

#[derive(Command)]  // generates CLI args + MCP tool schema
#[command(name = "enterprise.database.create")]
pub struct CreateDatabase {
    #[arg(required)]
    name: String,
    #[arg(default = 100)]
    memory_size_mb: u64,
}

Option 3: Thin MCP wrapper over CLI

async fn redisctl_exec(args: Vec<String>) -> Result<Value> {
    // Shell out to redisctl -o json
}

Decision

For now: Continue with direct handler wrapping for ~75% raw API coverage.
Revisit architecture after seeing real-world usage patterns.

Questions to Answer Later

• Is raw API coverage enough, or do users need workflow-level MCP tools?
• What's the right abstraction for "one implementation, multiple interfaces"?
• Should we generate MCP tools from handler signatures?

References

• Current MCP implementation: feat: add MCP server for AI integration #524, feat: add MCP server for AI integration #531
• Handler counts: 334 Enterprise + 47 Cloud = 381 total

[joshrotenberg]

Architecture Decision Point (Jan 2025)

Current State

• redisctl: 15MB CLI binary
• redisctl-mcp: 7MB MCP server binary
• Separate crates, separate binaries, shared dependencies

Options

Option A: Keep Separate (current)

• Two binaries: redisctl + redisctl-mcp
• Pros: Smaller individual binaries, deploy only what's needed, clear separation
• Cons: Two things to distribute

Option B: Combine into Single Binary

• Single binary with redisctl mcp serve subcommand
• Estimated size: ~16-17MB (shared deps dedupe)
• Pros: One thing to distribute, simpler user experience
• Cons: Larger binary, users get MCP even if they only want CLI

Option C: Feature Flags

• cargo install redisctl --features mcp
• Build with or without MCP
• Pros: Maximum flexibility
• Cons: Complex build matrix for releases

Option D: Hybrid Distribution

• Docker: Separate images for CLI and MCP (minimal size)
• Brew/cargo: Combined binary (convenience)
• Release artifacts: Both options available

Recommendation

Option D (Hybrid) seems best:

• Docker users care about image size -> separate
• Brew/cargo users care about convenience -> combined
• Power users can choose

Code Impact

Combining would require:

• Move redisctl-mcp src into redisctl as a module
• Add mcp serve subcommand
• Feature-gate MCP dependencies
• Update CI/CD for matrix builds

[joshrotenberg]

Decision: Approach B (Operation-Centric)

After exploring three patterns in the spike/core-engine-pattern branch, we're going with Approach B: Operation-Centric builders.

Why Approach B

• Approachable - builders are a familiar Rust pattern, easy for others to use
• Flexible - callbacks are optional, not baked into complex type signatures
• Self-documenting - each operation's params are explicit in the builder
• Testable - can test operations in isolation
• Right level of abstraction - not overengineered like trait-based hooks

Pattern

// CLI - with progress callback
CloudOperations::create_database(&client)
    .subscription_id(123)
    .name("my-db")
    .wait(true)
    .on_progress(|msg| spinner.set_message(msg))
    .execute()
    .await?

// MCP - same operation, no callback needed
CloudOperations::create_database(&client)
    .subscription_id(123)
    .name("my-db")
    .wait(true)
    .execute()
    .await?

Proposed Structure

redisctl-core/
├── src/
│   ├── lib.rs
│   ├── error.rs           # unified error types
│   ├── tracing.rs         # shared tracing/metrics setup
│   ├── config/
│   │   ├── mod.rs         # absorb redisctl-config
│   │   └── profiles.rs    # profile management
│   ├── cloud/
│   │   ├── mod.rs
│   │   ├── operations.rs  # CloudOperations entry point
│   │   ├── types.rs       # DatabaseInfo, SubscriptionInfo, etc.
│   │   └── ops/           # individual operation builders
│   │       ├── list_databases.rs
│   │       ├── create_database.rs
│   │       └── ...
│   └── enterprise/
│       ├── mod.rs
│       ├── operations.rs
│       ├── types.rs
│       └── ops/

What Lives Where

Layer	Responsibilities
redisctl-core	Operations, validation, async polling, workflows, config, profiles, error types, tracing
redisctl (CLI)	Arg parsing (clap), output formatting, progress bars (indicatif), interactive prompts
redisctl-mcp	Tool schemas, JSON-RPC, read-only filtering, MCP protocol handling

Migration Path

1. Create redisctl-core with operation builders
2. Migrate one operation end-to-end (e.g., cloud database list)
3. Update CLI to use core operation
4. Update MCP to use core operation
5. Iterate on remaining operations
6. Eventually absorb redisctl-config into core

Reference

• Spike branch: spike/core-engine-pattern
• Approach docs: crates/redisctl-core/src/approach_*.rs

[joshrotenberg]

Implemented in #630.

The Layer 2 architecture in redisctl-core provides the unified command layer:

• Layer 2 workflows (create_database_and_wait, backup_database_and_wait, etc.) are consumed by both CLI and MCP
• Progress callbacks allow each consumer to handle progress differently (CLI shows spinners, MCP can ignore or log)
• Unified errors (CoreError) wrap both Cloud and Enterprise errors

Architecture:

Layer 0: Raw HTTP
Layer 1: Typed handlers (redis-cloud, redis-enterprise crates)
Layer 2: Workflows + composition (redisctl-core) <-- unified layer
Layer 3: CLI, MCP (thin consumers)