Crate fastmcp_console

Expand description

§fastmcp-console

Rich console output for FastMCP servers.

fastmcp-console renders human-friendly output to stderr and keeps stdout reserved for JSON-RPC (NDJSON). This preserves protocol correctness for agents while giving humans polished output.

§Role in FastMCP

fastmcp-console is the human-facing output layer of FastMCP. The server and CLI use it to render banners, tables, and logs to stderr while keeping stdout strictly reserved for JSON-RPC. This separation is critical for MCP clients and agents that parse stdout as a protocol stream.

§Quick Start

use fastmcp_console::banner::StartupBanner;
use fastmcp_console::console::FastMcpConsole;
use fastmcp_console::logging::RichLoggerBuilder;
use log::Level;

fn main() {
    // Optional: initialize rich logger (stderr only)
    let _ = RichLoggerBuilder::new()
        .level(Level::Info)
        .with_targets(true)
        .init();

    let console = FastMcpConsole::new();
    console.rule(Some("FastMCP Console"));

    let banner = StartupBanner::new("demo-server", "0.1.0")
        .tools(3)
        .resources(2)
        .prompts(1)
        .transport("stdio");
    banner.render(&console);

    console.print("Ready.");
}

§Key Concepts

Dual-stream architecture: stdout is JSON-RPC only, stderr is human output.
DisplayContext: automatic detection of agent vs human context.

§Detection and Environment Variables

Rich output is enabled when we are in a human context and not explicitly suppressed. The most common toggles are:

FASTMCP_RICH=1 forces rich output.
FASTMCP_PLAIN=1 or NO_COLOR=1 forces plain output.
Agent detection: MCP_CLIENT, CLAUDE_CODE, CODEX_CLI, CURSOR_SESSION, CI, or AGENT_MODE set.

ConsoleConfig::from_env() also supports:

FASTMCP_FORCE_COLOR, FASTMCP_BANNER, FASTMCP_LOG, FASTMCP_LOG_TIMESTAMPS, FASTMCP_TRAFFIC, RUST_BACKTRACE

§API Overview

console::FastMcpConsole: printing, renderables, rules, tables, panels
banner::StartupBanner: startup banner
tables::ToolTableRenderer / ResourceTableRenderer / PromptTableRenderer
handlers::HandlerRegistryRenderer: combined capabilities view
logging::RichLogger / RichLoggerBuilder / RichLayer (tracing)
stats::ServerStats + StatsRenderer
config::ConsoleConfig for customization
detection::DisplayContext and helpers
testing::TestConsole + SnapshotTest

§Examples

See crates/fastmcp-console/examples:

basic.rs
tables.rs
custom_theme.rs
agent_detection.rs

§Troubleshooting

JSON-RPC output corrupted: ensure you never print to stdout. Use stderr only.
No colors: set FASTMCP_RICH=1 or FASTMCP_FORCE_COLOR=1; clear NO_COLOR.
Too much output: disable banner or traffic logging via ConsoleConfig or env vars.

§License

MIT. See LICENSE-MIT.

Re-exports§

pub use console::console;
pub use client::RequestResponseRenderer;
pub use config::ConsoleConfig;
pub use detection::DisplayContext;
pub use detection::is_agent_context;
pub use detection::should_enable_rich;
pub use error::ErrorBoundary;
pub use handlers::HandlerRegistryRenderer;
pub use handlers::ServerCapabilities;
pub use theme::theme;
pub use rich_rust;

Modules§

banner: Startup banner for FastMCP servers.
client: Client info rendering for connection status display.
config: Centralized configuration for FastMCP console output.
console: Console wrapper for rich stderr output.
detection: Agent/human context detection
diagnostics: Error/warning formatting
error: Error handling utilities with automatic rich display.
handlers: Unified handler registry renderer.
logging: Rich log formatting module.
stats
status: Status/progress output.
tables: Server info table renderers
testing: Testing utilities for FastMCP console output.
theme: FastMCP color theme

Macros§

assert_raw_snapshot: Convenience macro for raw snapshot tests (with ANSI codes).
assert_snapshot: Convenience macro for snapshot tests.
try_display: Convenience macro for trying an operation with error display.
try_display_result: Convenience macro for trying an operation with error display, returning Result.