MCP CLI Command System

MCP CLI features a unified command system that works consistently across all operational modes: Chat mode, Interactive mode, CLI mode, and Command mode. This document describes the command architecture, patterns, and usage.

Command Architecture

Unified Command System

The command system is built on a unified architecture defined in src/mcp_cli/commands/base.py:

┌─────────────────────────────────────────────────────┐
│           UnifiedCommand (Base Class)               │
│  - Single implementation works in all modes         │
│  - Consistent behavior and validation               │
│  - Mode-specific formatting support                 │
└─────────────────────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
┌───────▼──────┐ ┌─────▼──────┐ ┌─────▼──────┐
│  Chat Mode   │ │ Interactive│ │  CLI Mode  │
│  /command    │ │   command  │ │ mcp-cli cmd│
└──────────────┘ └────────────┘ └────────────┘

Command Components

Every command is built from these components:

Command Definition (src/mcp_cli/commands/definitions/) - Defines command metadata
Command Action (src/mcp_cli/commands/actions/) - Implements command logic
Command Models (src/mcp_cli/commands/models/) - Pydantic models for parameters and responses
Command Registry (src/mcp_cli/commands/registry.py) - Central command registration

Command Modes

Commands can support one or more operational modes:

class CommandMode(Flag):
    CHAT = auto()         # Chat mode (/command)
    CLI = auto()          # CLI mode (mcp-cli command)
    INTERACTIVE = auto()  # Interactive mode (command)
    ALL = CHAT | CLI | INTERACTIVE

Command Patterns

Singular vs Plural Pattern

MCP CLI follows a consistent singular/plural pattern for related commands:

Command Type	Purpose	Example	Result
Singular	Show current status	`/model`	Shows current model with tips
Plural	List all available	`/models`	Lists all models in a table
Singular + Name	Direct action	`/model gpt-4o`	Switches to gpt-4o
Singular + Subcommand	Specific action	`/model refresh`	Refreshes model discovery

Examples:

# Models
/model                    # Show current model status
/models                   # List all available models
/model gpt-4o             # Switch to gpt-4o directly
/model refresh            # Refresh model discovery

# Providers
/provider                 # Show current provider status
/providers                # List all available providers
/provider ollama          # Switch to Ollama provider
/provider set openai api_key KEY  # Configure provider

# Themes
/theme                    # Show current theme with preview
/themes                   # List all available themes
/theme dark               # Switch to dark theme

# Servers
/server echo              # Show details about echo server
/servers                  # List all connected MCP servers
/servers ping             # Ping all servers

Command Groups

Some commands have subcommands organized into groups:

# Tools command group
/tools                    # List available tools (default: list)
/tools list               # List tools explicitly
/tools call               # Interactive tool execution
/tools --all              # Detailed tool information

# Server command group
/server                   # List servers (default)
/server list              # List servers explicitly
/server add <name>        # Add a new server
/server remove <name>     # Remove a server
/server ping <name>       # Ping specific server

# Token command group
/token                    # List tokens (default)
/token list               # List tokens explicitly
/token set <name>         # Store a token
/token get <name>         # Get token details
/token delete <name>      # Delete a token

Core Commands

Provider & Model Management

Provider Commands

Show Current Provider:

/provider                           # Show current configuration (default: ollama)

List All Providers:

/providers                          # List all providers

Switch Provider:

/provider ollama                    # Switch to Ollama
/provider openai                    # Switch to OpenAI (requires API key)
/provider anthropic                 # Switch to Anthropic (requires API key)
/provider openai gpt-4o             # Switch to OpenAI with specific model

Provider Configuration:

/provider set openai api_key sk-...   # Configure API key
/provider set ollama api_base http://localhost:11434  # Configure endpoint
/provider config                      # Show detailed configuration
/provider diagnostic                  # Test provider connectivity

Custom Provider Management:

/provider custom                      # List custom providers
/provider add localai http://localhost:8080/v1 gpt-4  # Add custom provider
/provider remove localai              # Remove custom provider

Model Commands

Show Current Model:

/model                              # Show current model (default: gpt-oss)

List Available Models:

/models                             # List models for current provider
/models openai                      # List models for specific provider

Switch Model:

/model llama3.3                     # Switch to different Ollama model
/model gpt-4o                       # Switch to GPT-4 (if using OpenAI)
/model claude-3-5-sonnet-20241022   # Switch to Claude 3.5 (if using Anthropic)

Model Discovery:

/model refresh                      # Refresh available models

Tool Management

List Tools:

/tools                              # List available tools
/tools --all                        # Show detailed tool information
/tools --raw                        # Show raw JSON definitions

Execute Tools:

/tools call                         # Interactive tool execution

Tool History:

/toolhistory                        # Show tool execution history
/th -n 5                           # Last 5 tool calls
/th 3                              # Details for call #3
/th --json                         # Full history as JSON

Server Management

List Servers:

/server                             # List all configured servers
/servers                            # List servers (alias)
/servers list                       # List servers explicitly
/servers list all                   # Include disabled servers

Add Servers:

Runtime server additions persist in ~/.mcp-cli/preferences.json:

# STDIO servers
/server add sqlite stdio uvx mcp-server-sqlite --db-path test.db
/server add playwright stdio npx @playwright/mcp@latest
/server add time stdio uvx mcp-server-time
/server add fs stdio npx @modelcontextprotocol/server-filesystem /path/to/dir

# HTTP/SSE servers with authentication
/server add github --transport http --header "Authorization: Bearer ghp_token" -- https://api.github.com/mcp
/server add myapi --transport http --env API_KEY=secret -- https://api.example.com/mcp
/server add events --transport sse -- https://events.example.com/sse

Manage Servers:

/server enable <name>               # Enable a disabled server
/server disable <name>              # Disable without removing
/server remove <name>               # Remove user-added server
/server ping <name>                 # Test server connectivity
/server <name>                      # Show server configuration details

Server Details:

/server echo                        # Show details about echo server
/servers ping                       # Ping all servers

Token Management

List Tokens:

/token                              # List all tokens (default)
/token list                         # List all tokens explicitly
/token list --oauth                 # Only OAuth tokens
/token list --api-keys              # Only API keys
/token list --bearer                # Only bearer tokens

Store Tokens:

/token set my-server --type bearer  # Interactive prompt (secure)
/token set openai --type api-key --provider openai  # API key
/token set my-api --type bearer --value "token123"  # With value (less secure)

Get Token Info:

/token get my-server                # Get metadata
/token get openai --namespace api-key  # Get from specific namespace
/token get notion --oauth           # Get OAuth token

Delete Tokens:

/token delete my-server             # Delete bearer token
/token delete openai --namespace api-key  # Delete from namespace
/token delete notion --oauth        # Delete OAuth token
/token clear                        # Clear all tokens (with confirmation)
/token clear --force                # Clear without confirmation

Storage Backends:

/token backends                     # List available backends

See TOKEN_MANAGEMENT.md for comprehensive token documentation.

Conversation Management

View History:

/conversation                       # Show conversation history
/ch -n 10                          # Last 10 messages
/ch 5                              # Details for message #5
/ch --json                         # Full history as JSON

Save & Clear:

/save                              # Save session (auto-generates filename)
/compact                           # Summarize conversation
/clear                             # Clear conversation history
/cls                               # Clear screen only

Virtual Memory (Experimental)

Inspect the AI virtual memory subsystem during conversations (requires --vm flag):

/memory                            # Summary dashboard: mode, turn, pages, utilization, metrics
/vm                                # Alias for /memory
/mem                               # Alias for /memory
/memory pages                      # Table of all memory pages (ID, type, tier, tokens, pinned)
/memory page <id>                  # Detailed view of a specific page with content preview
/memory stats                      # Full debug dump of all VM subsystem stats (JSON)

The dashboard shows:

Working set utilization: L0/L1 page counts, tokens used/available, visual utilization bar
Page table: Total pages, dirty pages, distribution by storage tier (L0-L4)
Metrics: Page faults, evictions, TLB hit rate
Configuration: VM mode, current turn, token budget

Without --vm, the command shows: "VM not enabled. Start with --vm flag."

VM CLI Flags:

# Enable VM with defaults (passive mode, 128K budget)
mcp-cli --server sqlite --vm

# Set a tight budget to force eviction pressure
mcp-cli --server sqlite --vm --vm-budget 500

# Use relaxed mode (VM-aware but conversational)
mcp-cli --server sqlite --vm --vm-mode relaxed

Model-Driven Planning

Enable the LLM to autonomously create and execute multi-step plans during conversation:

# Enable plan tools — the model decides WHEN to plan
mcp-cli --server sqlite --plan-tools

# Or with the chat subcommand
mcp-cli chat --server sqlite --plan-tools

When enabled, three internal tools are added to the LLM's tool list:

plan_create_and_execute — generate and execute a plan in one call (most common)
plan_create — generate a plan without executing it
plan_execute — execute a previously created plan by ID

The model calls these when it determines a task requires multi-step coordination (e.g., "read a file, find importers, run tests"). For simple tasks, it calls tools directly.

See PLANNING.md for full documentation.

Direct LLM Chat (No Tools)

Skip MCP server connections entirely and chat directly with the LLM:

# No tool calling — MCP servers are not connected
mcp-cli --no-tools
mcp-cli --no-tools --provider openai --model gpt-4o
mcp-cli chat --no-tools --provider anthropic --model claude-sonnet-4-6

When --no-tools is set:

No MCP servers are initialized (no network connections attempted)
The LLM receives no tool definitions
The model responds conversationally only

This is useful when you want a fast, lightweight chat session without the overhead of server connections, or when using a model that handles tools poorly.

Token Usage

Track API token consumption across your conversation:

/usage                             # Show token usage summary
/tokens                            # Alias for /usage
/cost                              # Alias for /usage

Displays per-turn and cumulative input/output token counts. When provider usage data is unavailable, tokens are estimated using a chars/4 heuristic (marked as "estimated").

Session Persistence

Save and restore conversation sessions:

/sessions list                     # List all saved sessions
/sessions save                     # Save current session
/sessions load <id>                # Load a saved session
/sessions delete <id>              # Delete a saved session

Sessions are stored as JSON in ~/.mcp-cli/sessions/. Auto-save triggers every 10 turns by default.

Multi-Modal Attachments

Stage files to include in your next message. Supports images, text/code files, and audio.

Stage Files:

/attach photo.png                  # Stage an image
/attach code.py                    # Stage a text/code file
/attach clip.mp3                   # Stage an audio file
/file data.csv                     # Alias for /attach
/image screenshot.heic             # Alias for /attach

Manage Staging:

/attach list                       # Show currently staged files
/attach clear                      # Clear all staged files

Inline References (in any message):

@file:screenshot.png describe what you see in this image
@file:report.txt @file:data.csv compare these two files

Image URLs in messages are automatically detected and sent as vision content.

Supported File Types:

Images: .png, .jpg, .jpeg, .gif, .webp, .heic
Audio: .mp3, .wav
Text/Code: .txt, .md, .csv, .json, .html, .xml, .yaml, .yml, .py, .js, .ts, .jsx, .tsx, .sh, .bash, .rs, .go, .java, .c, .cpp, .h, .hpp, .rb, .swift, .kt, .sql, .toml, .ini, .cfg, .env, .log

Size Limits:

Maximum file size: 20 MB per file
Maximum attachments per message: 10

CLI Flag:

# Attach files to the first message (repeatable)
mcp-cli --server sqlite --attach image.png --attach data.csv

See ATTACHMENTS.md for comprehensive attachments documentation.

Conversation Export

Export conversations in structured formats:

/export markdown                   # Export as formatted Markdown
/export markdown chat.md           # Export to specific file
/export json                       # Export as structured JSON
/export json chat.json             # Export to specific file

Markdown exports include tool calls as code blocks. JSON exports include metadata and token usage.

UI Customization

Theme Management:

/theme                             # Interactive theme selector with preview
/theme dark                        # Switch to dark theme
/theme monokai                     # Switch to monokai theme
/themes                            # List all available themes

Available Themes:

default
dark
light
minimal
terminal
monokai
dracula
solarized

Themes are persisted across sessions in user preferences.

Session Control

Display Settings:

/verbose                           # Toggle verbose/compact display (Default: Enabled)
/confirm                           # Toggle tool call confirmation (Default: Enabled)

System Commands:

/help                             # Show all commands
/help tools                       # Help for specific command
/interrupt                        # Stop running operations
/exit                             # Exit chat mode

Command Implementation

Creating a New Command

To create a new command, implement the UnifiedCommand interface:

# src/mcp_cli/commands/definitions/mycommand.py
from mcp_cli.commands.base import UnifiedCommand, CommandMode, CommandResult

class MyCommand(UnifiedCommand):
    @property
    def name(self) -> str:
        return "mycommand"

    @property
    def aliases(self) -> List[str]:
        return ["mc"]  # Optional aliases

    @property
    def description(self) -> str:
        return "My custom command"

    @property
    def modes(self) -> CommandMode:
        return CommandMode.ALL  # Support all modes

    async def execute(self, **kwargs) -> CommandResult:
        # Implementation
        return CommandResult(success=True, output="Done!")

Command Parameters

Define parameters for type-safe argument handling:

from mcp_cli.commands.base import CommandParameter

@property
def parameters(self) -> List[CommandParameter]:
    return [
        CommandParameter(
            name="server_name",
            type=str,
            required=True,
            help="Name of the server"
        ),
        CommandParameter(
            name="verbose",
            type=bool,
            default=False,
            is_flag=True,
            help="Enable verbose output"
        )
    ]

Command Models

Use Pydantic models for structured parameters:

# src/mcp_cli/commands/models/mycommand.py
from pydantic import BaseModel

class MyCommandParams(BaseModel):
    server_name: str
    verbose: bool = False

class MyCommandResponse(BaseModel):
    success: bool
    message: str

Command Actions

Implement the action logic separately for better organization:

# src/mcp_cli/commands/actions/mycommand.py
from mcp_cli.commands.models.mycommand import MyCommandParams, MyCommandResponse

async def my_command_action(params: MyCommandParams) -> MyCommandResponse:
    # Implementation logic
    return MyCommandResponse(success=True, message="Complete")

Registering Commands

# src/mcp_cli/commands/__init__.py
from mcp_cli.commands.registry import registry
from mcp_cli.commands.definitions.mycommand import MyCommand

def register_commands():
    registry.register(MyCommand())

Command Usage Across Modes

Chat Mode

Commands in chat mode use the / prefix:

# Start chat mode
mcp-cli --server sqlite

# Use commands
> /provider openai
> /model gpt-4o
> /tools list
> /server add myserver stdio node server.js

Interactive Mode

Commands in interactive mode don't require the / prefix:

# Start interactive mode
mcp-cli interactive --server sqlite

# Use commands
> provider openai
> model gpt-4o
> tools list
> servers

CLI Mode

Commands in CLI mode use the standard CLI syntax:

# Direct CLI commands
mcp-cli provider list
mcp-cli model set gpt-4o
mcp-cli tools --server sqlite
mcp-cli servers list

# With global options
mcp-cli --provider openai --server sqlite tools

Command Mode

Unix-friendly automation mode:

# Tool execution
mcp-cli cmd --server sqlite --tool list_tables --raw

# Text processing
echo "data" | mcp-cli cmd --server sqlite --input - --output result.txt

# Pipeline usage
mcp-cli cmd --tool read_query --tool-args '{"query": "SELECT * FROM users"}' | jq .

Design Principles

1. Predictability

Users can guess commands based on consistent patterns:

Singular shows current state
Plural lists all options
Direct actions without unnecessary subcommands

2. Discoverability

Tips and indicators guide users to related commands:

💡 Tip: Use: /model <name> to switch  |  /models to list all  |  /model refresh to discover

3. Efficiency

Quick actions available without deep menu navigation:

/theme dark              # Direct action
/provider openai         # Direct switch
/model gpt-4o            # Direct selection

4. Consistency

Same patterns across all command groups:

All listing commands use tables
All status commands use panels
All commands have help text

5. Theme-Aware

Uses theme colors, not hardcoded values:

from chuk_term.ui import output

output.success("Operation complete")  # Uses theme's success color
output.error("Failed")                # Uses theme's error color
output.info("Information")            # Uses theme's info color

Visual Indicators

Command Help Menu

Typing just / shows a menu of all available commands:

Available Commands:
  clear ▸      - Clear conversation or screen
  conversation - Show conversation history
  exit         - Exit the application
  export ▸     - Export conversation (markdown/json)
  help         - Show help information
  memory ▸     - View AI virtual memory state (aliases: /vm, /mem)
  model ▸      - Show current model or switch models
  models       - List all available models
  provider ▸   - Show current provider or switch providers
  providers    - List all available providers
  server ▸     - Manage MCP servers
  servers      - List all connected servers
  sessions ▸   - Save/load/list sessions
  theme ▸      - Show or change UI theme
  themes       - List all available themes
  token ▸      - Manage authentication tokens
  tools ▸      - List and manage tools
  usage        - Show token usage stats

Indicators:

▸ - Command has subcommands available
No indicator - Direct command with no subcommands

Status Panels

Status commands use panels for clear presentation:

╭─────────────────────────────────────────╮
│ ℹ Current provider: openai              │
│ ℹ Current model   : gpt-4o-mini         │
│ ℹ Status          : ✅ Ready            │
│ ℹ Features        : 📡 🔧 👁️            │
╰─────────────────────────────────────────╯

Tables for Lists

List commands use formatted tables:

┌──────────┬───────────┬──────────────┐
│ Provider │ Status    │ Models       │
├──────────┼───────────┼──────────────┤
│ openai   │ ✅ Ready  │ 15 models    │
│ ollama   │ ✅ Ready  │ 51 models    │
└──────────┴───────────┴──────────────┘

Advanced Command Features

Parameter Validation

Commands automatically validate parameters before execution:

def validate_parameters(self, **kwargs) -> Optional[str]:
    for param in self.parameters:
        if param.required and param.name not in kwargs:
            return f"Missing required parameter: {param.name}"

        if param.name in kwargs and param.choices:
            if kwargs[param.name] not in param.choices:
                return f"Invalid choice for {param.name}"

    return None

Mode-Specific Formatting

Commands can format output differently for each mode:

def format_output(self, result: CommandResult, mode: CommandMode) -> str:
    if mode == CommandMode.CLI:
        # Machine-readable format
        return json.dumps(result.data)
    else:
        # Human-readable format
        return result.output

Context Requirements

Commands can specify if they need active context:

@property
def requires_context(self) -> bool:
    return True  # Needs tool_manager, llm_client, etc.

Hidden Commands

Commands can be hidden from help menus:

@property
def hidden(self) -> bool:
    return True  # Won't appear in /help

Error Handling

Commands use consistent error handling patterns:

async def execute(self, **kwargs) -> CommandResult:
    try:
        # Execute action
        result = await my_action(params)
        return CommandResult(success=True, data=result)
    except ValueError as e:
        return CommandResult(success=False, error=f"Invalid parameter: {e}")
    except Exception as e:
        return CommandResult(success=False, error=f"Command failed: {e}")

Common error patterns:

Missing parameters: Validated before execution
Invalid choices: Checked against allowed values
Context errors: Graceful handling of missing context
Action failures: Proper error messages with hints

Best Practices

Command Design

Keep it Simple: Commands should do one thing well
Use Defaults: Sensible defaults for optional parameters
Provide Help: Clear descriptions and examples
Be Consistent: Follow established patterns
Think User-First: Design for how users will actually use it

Implementation

Separate Concerns: Definition → Model → Action
Use Type Hints: Leverage Pydantic for validation
Handle Errors: Graceful error messages
Test All Modes: Ensure command works in all supported modes
Document: Update command help and this guide

User Experience

Fast Defaults: Most common action is the default
Clear Feedback: Users know what happened
Helpful Tips: Guide users to related commands
Visual Clarity: Use tables, panels, and colors appropriately
Keyboard Friendly: Tab completion and shortcuts

Future Enhancements

Planned command system improvements:

FilesExpand file tree

COMMANDS.md

Latest commit

History