brontes 0.2.2

Transform any clap CLI into an MCP server.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

//! `mcp start` runtime: serve [`BrontesServer`] over rmcp's stdio transport.
//!
//! This module wires together:
//!
//! 1. The tracing subscriber (always to stderr — stdout is reserved for
//!    MCP protocol frames).
//! 2. The rmcp stdio transport ([`rmcp::transport::stdio`]).
//! 3. A signal listener (SIGINT/SIGTERM on Unix; Ctrl+C on Windows) that
//!    cancels the running service for graceful shutdown.
//!
//! Mirrors ophis `config.go::serveStdio` (`config.go:88-95`).

use clap::Command;
use rmcp::ServiceExt;
use rmcp::transport::stdio;
use tokio::io::{AsyncRead, AsyncWrite};
use tokio_util::sync::CancellationToken;
use tracing::Level;

use crate::Result;
use crate::config::Config;
use crate::server::BrontesServer;

/// Run the MCP server over stdio until the connected client disconnects,
/// the process receives a termination signal, or the cancellation token
/// fires.
///
/// `cli` is the user's full clap tree (cloned by the caller — clap's
/// `get_matches(self)` consumes the original). `cfg_opt` is the optional
/// user configuration; `None` and `Some(Config::default())` produce
/// identical behavior. `log_level_override` is the value of the
/// `--log-level` CLI flag — when set it wins over [`Config::log_level`].
///
/// stdout is reserved for MCP protocol frames; tracing output is always
/// directed to stderr.
///
/// # Errors
///
/// - [`crate::Error::McpInitialize`] if the rmcp transport fails to
///   negotiate the MCP handshake.
/// - [`crate::Error::Panic`] if the awaited rmcp service task panics
///   (the underlying tokio `JoinError`).
pub async fn serve_stdio(
    cli: Command,
    cfg_opt: Option<Config>,
    log_level_override: Option<Level>,
) -> Result<()> {
    let cfg = cfg_opt.unwrap_or_default();
    init_tracing(log_level_override.or(cfg.log_level));

    let cancel = CancellationToken::new();
    crate::subcommands::signal::spawn_signal_listener(cancel.clone());

    serve_stdio_with(cli, cfg, stdio(), cancel).await
}

/// Generic core of [`serve_stdio`]: serve [`BrontesServer`] over the
/// supplied `(reader, writer)` transport pair.
///
/// Production code reaches this via [`serve_stdio`] (which passes
/// [`rmcp::transport::stdio`]'s real-stdin / real-stdout pair); the
/// integration test crate passes an in-memory [`tokio::io::duplex`] pair
/// so the server can be driven by a real client peer over a synthetic
/// transport without touching the process stdio. Mirrors the
/// [`crate::server::http::serve_http`] →
/// [`crate::server::http::serve_http_with`] split.
///
/// `pub` (not `pub(crate)`) so the `__test_internal` re-export in
/// `lib.rs` can carry it out; effective visibility is crate-internal.
///
/// # Errors
///
/// Same as [`serve_stdio`].
pub async fn serve_stdio_with<R, W>(
    cli: Command,
    cfg: Config,
    transport: (R, W),
    cancel: CancellationToken,
) -> Result<()>
where
    R: AsyncRead + Send + Unpin + 'static,
    W: AsyncWrite + Send + Unpin + 'static,
{
    // `BrontesServer::new` walks the tree and caches the tool list at
    // construction; a bad config surfaces as a startup failure here rather
    // than as a silent server that fails the first `tools/list` request.
    let server = BrontesServer::new(cli, cfg)?;
    let running = server.serve_with_ct(transport, cancel).await?;

    // `waiting` returns the quit reason; a join error from the underlying
    // task represents a panic-in-task, not an I/O failure — surface it as
    // [`crate::Error::Panic`] so the category matches the cause.
    running
        .waiting()
        .await
        .map_err(|e| crate::Error::Panic(format!("MCP stdio service join: {e}")))?;
    Ok(())
}

/// Install a `tracing_subscriber` pointed at stderr.
///
/// Precedence: explicit override > `Config::log_level` > `RUST_LOG`
/// environment > `INFO`. The call is idempotent — `try_init` returns an
/// error if a subscriber is already installed (e.g., by a host binary's
/// test harness), which we silently ignore.
fn init_tracing(level: Option<Level>) {
    use tracing_subscriber::EnvFilter;

    let filter = level.map_or_else(
        || EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info")),
        |lvl| EnvFilter::new(lvl.to_string()),
    );

    let _ = tracing_subscriber::fmt()
        .with_writer(std::io::stderr)
        .with_env_filter(filter)
        .try_init();
}