Initial public release

Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
This commit is contained in:
Evan Whittaker
2026-10-17 12:08:30 -05:00
commit 09a7de2520
1730 changed files with 412952 additions and 0 deletions

View File

@@ -0,0 +1,487 @@
//! MCP (Model Context Protocol) client types.
//!
//! Provides types for connecting to MCP servers via stdio or HTTP/SSE,
//! listing tools, and calling them.
use serde::{Deserialize, Serialize};
use std::path::PathBuf;
/// When an MCP server's process/connection is started and stopped.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum McpLifecycle {
/// Don't connect at startup; connect on the first tool call, disconnect after idle. Cached
/// metadata keeps discovery working without a live connection.
#[default]
Lazy,
/// Connect at startup; no auto-reconnect and no idle disconnect unless `idle_timeout_mins` is set.
Eager,
/// Connect at startup and keep alive (health-checked, auto-reconnect); never idle-disconnect.
KeepAlive,
}
/// Transport type for MCP connections.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum McpTransport {
/// Stdio transport — communicates with a local server process via stdin/stdout.
Stdio {
/// Command to run.
command: String,
/// Arguments to pass to the command.
args: Vec<String>,
/// Working directory for the process.
cwd: Option<PathBuf>,
/// Extra environment variables for the child process. Values support `${VAR}` and
/// `$env:VAR` interpolation against Luxe's own environment.
#[serde(default)]
env: std::collections::HashMap<String, String>,
},
/// HTTP/SSE transport — communicates with a remote server via HTTP.
HttpSse {
/// Server URL.
url: String,
},
}
impl Default for McpTransport {
fn default() -> Self {
Self::Stdio {
command: String::new(),
args: Vec::new(),
cwd: None,
env: std::collections::HashMap::new(),
}
}
}
/// Configuration for an MCP server.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct McpServerConfig {
/// Unique identifier for this server.
pub id: String,
/// Human-readable name.
pub name: String,
/// Transport configuration.
pub transport: McpTransport,
/// Whether this server is enabled.
pub enabled: bool,
/// When to start/stop the connection (default: lazy).
#[serde(default)]
pub lifecycle: McpLifecycle,
/// Minutes of inactivity before a lazy server disconnects (`None` = the manager default).
#[serde(default)]
pub idle_timeout_mins: Option<u64>,
/// Seconds one tool call may take before it is abandoned (`None` = the network default, 60).
///
/// Abandoning a stdio call stops the server's whole process tree and reconnects on next use,
/// so the work really stops — a server that delegates to a subagent would otherwise go on
/// writing after the model was told the call had ended. A server whose calls are slow by
/// nature, like that delegate, declares how slow here.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub timeout_secs: Option<u64>,
/// Tool names to hide from this server, as the server spells them (`get_project_internal`,
/// not `asana/get_project_internal`)
#[serde(default)]
pub exclude_tools: Vec<String>,
/// Extra HTTP headers (HTTP transport only); values support `${VAR}` interpolation.
#[serde(default)]
pub headers: std::collections::HashMap<String, String>,
/// Authentication for HTTP transports (bearer or, later, OAuth).
#[serde(default)]
pub auth: Option<McpAuth>,
/// Declared in the reader's own config rather than a project's, which is what lets a
/// `!command` secret run. Set by the store from where the server was found; never read from,
/// or written to, a file — a config cannot vouch for itself.
#[serde(skip)]
pub declared_by_user: bool,
}
/// Authentication for an HTTP MCP server. Stdio servers ignore it.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum McpAuth {
/// Static bearer token — the literal `token` (supports `${VAR}`) or the value of `token_env`.
Bearer {
/// Literal token value (supports `${VAR}` interpolation).
#[serde(default)]
token: Option<String>,
/// Environment variable to read the token from.
#[serde(default)]
token_env: Option<String>,
},
/// OAuth 2.1. Endpoints and client id are optional — missing pieces are filled by
/// `.well-known` discovery and dynamic client registration (RFC 7591).
///
/// Spelled `oauth`, as every example in the docs writes it. `snake_case` alone made it
/// `o_auth`, so a hand-written `"kind": "oauth"` failed to parse and took the whole file with it;
/// `o_auth` is still read, since that is what Luxe itself would have written.
#[serde(rename = "oauth", alias = "o_auth")]
OAuth(OAuthConfig),
}
/// OAuth grant type.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum OAuthGrant {
/// Interactive browser flow with PKCE (default).
#[default]
AuthorizationCode,
/// Non-interactive machine-to-machine flow.
ClientCredentials,
}
/// OAuth client configuration for an MCP server. All endpoint/client fields are optional so a bare
/// `{ "kind": "oauth" }` works when the server supports discovery + dynamic registration.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OAuthConfig {
/// Grant type (default: authorization_code).
#[serde(default)]
pub grant_type: OAuthGrant,
/// Pre-registered client id; dynamic registration is used when omitted.
#[serde(default)]
pub client_id: Option<String>,
/// Client secret for confidential clients, as written: `${VAR}` and `$env:VAR` are expanded when
/// it is sent, so the file can name an environment variable rather than hold the secret.
#[serde(default)]
pub client_secret: Option<ConfigSecret>,
/// Requested scopes (space-joined on the wire).
#[serde(default)]
pub scope: Option<String>,
/// Authorization endpoint; discovered from `.well-known` when omitted.
#[serde(default)]
pub authorization_endpoint: Option<String>,
/// Token endpoint; discovered from `.well-known` when omitted.
#[serde(default)]
pub token_endpoint: Option<String>,
/// Dynamic client registration endpoint; discovered when omitted.
#[serde(default)]
pub registration_endpoint: Option<String>,
/// Exact loopback redirect URI to advertise (for providers that pre-register it). A lazy
/// OS-assigned localhost port is used when omitted.
#[serde(default)]
pub redirect_uri: Option<String>,
}
/// A secret as written in an MCP config file: hidden from `Debug`, written back exactly as read.
///
/// Redacting it on `Serialize` instead would be a data-loss bug, not a hardening: `luxe mcp add`
/// parses the whole file and writes it back, so a redacting serializer would replace every other
/// server's secret with the placeholder.
#[derive(Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(transparent)]
pub struct ConfigSecret(String);
impl ConfigSecret {
/// The secret exactly as the file spells it, `${VAR}` references unexpanded.
pub fn as_written(&self) -> &str {
&self.0
}
}
impl From<&str> for ConfigSecret {
fn from(written: &str) -> Self {
Self(written.to_owned())
}
}
impl From<String> for ConfigSecret {
fn from(written: String) -> Self {
Self(written)
}
}
impl std::fmt::Debug for ConfigSecret {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("ConfigSecret([redacted])")
}
}
/// Why a call to an MCP server did not come back with an answer.
///
/// What a [`McpConnection`] reports, whichever transport it speaks. The variant says what kind of
/// failure it was; each carries the text for the reader, which a caller shows as it is.
#[derive(Debug, thiserror::Error)]
pub enum McpError {
/// The server could not be started or reached, or the exchange with it broke
#[error("{0}")]
Transport(String),
/// The server answered with a JSON-RPC error
#[error("{0}")]
Rpc(String),
/// The server's answer was not MCP
#[error("{0}")]
Protocol(String),
/// The connection is gone: the server exited, or the call was abandoned
#[error("{0}")]
Closed(String),
}
/// A transport-agnostic live connection to an MCP server, so the orchestration layer can drive
/// stdio and HTTP servers uniformly. Implemented by each transport (stdio lives in core; HTTP in
/// `luxe-mcp`, which carries the HTTP dependency core forbids).
#[async_trait::async_trait]
pub trait McpConnection: Send + Sync {
/// The server id this connection speaks to.
fn server_id(&self) -> &str;
/// List the server's tools (raw, un-namespaced names).
async fn list_tools(&self) -> Result<Vec<McpTool>, McpError>;
/// Call a tool by its raw (server-side) name.
async fn call_tool(
&self,
raw_name: &str,
arguments: serde_json::Value,
) -> Result<McpToolResult, McpError>;
/// Stop whatever the server is doing for a call nobody is waiting on any more.
///
/// Stdio kills the server's process tree, since a call cannot be withdrawn from one pipe
/// without the others; HTTP has nothing local to stop. Called from `Drop`, so it must not
/// block on the runtime.
fn abandon(&self) {}
/// Whether [`McpConnection::abandon`] (or anything else) has left this connection unusable.
fn is_closed(&self) -> bool {
false
}
}
/// A tool provided by an MCP server.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct McpTool {
/// Server ID that provides this tool.
pub server_id: String,
/// Tool name, as the server spells it; `mcp` presents it as `server_id/name`
pub name: String,
/// Human-readable description.
pub description: String,
/// JSON Schema for the tool's input parameters.
pub input_schema: serde_json::Value,
}
/// A call to an MCP tool.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct McpToolCall {
/// The tool being called.
pub tool: McpTool,
/// Input arguments for the tool call.
pub arguments: serde_json::Value,
}
/// Result of an MCP tool call.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct McpToolResult {
/// Whether the call was successful.
pub success: bool,
/// Output text (if successful).
pub output: Option<String>,
/// Error message (if failed).
pub error: Option<String>,
}
/// The MCP protocol version Luxe speaks, on both transports and the OAuth probe.
pub const MCP_PROTOCOL_VERSION: &str = "2025-06-18";
/// Expands `${VAR}` and `$env:VAR` from the environment, left to right, whichever marker comes
/// first; what a variable held is never read again. An unset variable becomes empty, with a
/// warning naming it, so a half-configured header degrades rather than sending the literal.
pub fn expand_env(input: &str) -> String {
expand(input, false)
}
/// [`expand_env`], and a bare `$NAME` as well — left as written when unset, since a key may hold
/// a `$` of its own. What `models.json` values take.
pub fn expand_env_with_bare(input: &str) -> String {
expand(input, true)
}
fn expand(input: &str, bare: bool) -> String {
let name_end = |text: &str| {
text.find(|c: char| !c.is_ascii_alphanumeric() && c != '_').unwrap_or(text.len())
};
let mut out = String::with_capacity(input.len());
let mut rest = input;
while let Some(at) = rest.find('$') {
out.push_str(&rest[..at]);
let marker = &rest[at..];
let (name, skip, keep_unset) = if let Some(body) = marker.strip_prefix("${") {
match body.find('}') {
Some(end) => (&body[..end], end + 3, false),
None => ("", 0, true),
}
} else if let Some(body) = marker.strip_prefix("$env:") {
let end = name_end(body);
(&body[..end], end + 5, false)
} else if bare && marker[1..].starts_with(|c: char| c.is_alphabetic() || c == '_') {
let end = name_end(&marker[1..]);
(&marker[1..=end], end + 1, true)
} else {
("", 0, true)
};
if skip == 0 {
out.push('$');
rest = &marker[1..];
continue;
}
match std::env::var(name) {
Ok(value) => out.push_str(&value),
Err(_) if keep_unset => out.push_str(&marker[..skip]),
Err(_) => tracing::warn!(
variable = name,
"a configured variable is not set; it expands to nothing"
),
}
rest = &marker[skip..];
}
out.push_str(rest);
out
}
/// Whether `name` — a server id, or a tool's name — is safe to put in front of the model and the
/// reader as it is: `[A-Za-z0-9._-]`, 1 to 64 characters.
///
/// A project chooses its own server ids and a server chooses its tools' names, and both end up in
/// a picker row and in the text a reference sends. A name that could hold a space could hold a
/// sentence, and a sentence in that position reads as an instruction; one that could hold a control
/// character could redraw the terminal. Anything else is not listed, and not repeated.
pub fn is_plain_name(name: &str) -> bool {
(1..=64).contains(&name.len())
&& name.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'-'))
}
/// Reads a `tools/list` result into [`McpTool`]s attributed to `server_id`.
///
/// The MCP shape is `{ "tools": [ { "name": …, "description": …, "inputSchema": … } ] }`. Entries
/// without a name are skipped rather than failing the batch — one malformed tool should not cost a
/// server all of its others. The names stay raw; namespacing is the caller's job.
///
/// Shared by both transports: the wire shape belongs to the protocol, not to stdio or HTTP.
pub fn parse_tool_list(result: &serde_json::Value, server_id: &str) -> Option<Vec<McpTool>> {
let tools = result.get("tools")?.as_array()?;
Some(
tools
.iter()
.filter_map(|tool| {
Some(McpTool {
server_id: server_id.to_string(),
name: tool.get("name")?.as_str()?.to_string(),
description: tool
.get("description")
.and_then(serde_json::Value::as_str)
.unwrap_or_default()
.to_string(),
input_schema: tool
.get("inputSchema")
.cloned()
.unwrap_or(serde_json::Value::Null),
})
})
.collect(),
)
}
/// Reads a `tools/call` result into an [`McpToolResult`], shaped for the model.
///
/// The MCP shape is `{ "content": [ { "type": "text", "text": … } ], "isError": bool }`; a missing
/// `isError` means success, per the specification's default. What the model is sent is shaped once,
/// here, where both transports meet:
///
/// - each text block that is a JSON document loses its insignificant whitespace
/// ([`crate::output_limit::compact_json`]) — the indentation servers send is a third or more of
/// it, and nothing else changes;
/// - a block this surface cannot show is named at the end rather than dropped without a word, so
/// the model knows an image or a resource was there;
/// - the whole is capped at [`crate::output_limit::RESULT_MAX_CHARS`], the ceiling every tool
/// promises, with a note saying how to see more. An unbounded MCP result would stay in the
/// conversation for the rest of the session.
pub fn parse_tool_call_result(result: &serde_json::Value) -> McpToolResult {
let blocks = result.get("content").and_then(serde_json::Value::as_array);
let mut texts = Vec::new();
let mut unseen: Vec<(&str, usize)> = Vec::new();
for block in blocks.into_iter().flatten() {
match block.get("text").and_then(serde_json::Value::as_str) {
Some(text) => texts
.push(crate::output_limit::compact_json(text).unwrap_or_else(|| text.to_owned())),
None => {
let kind = block.get("type").and_then(serde_json::Value::as_str).unwrap_or("");
match unseen.iter_mut().find(|(seen, _)| *seen == kind) {
Some((_, count)) => *count += 1,
None => unseen.push((kind, 1)),
}
}
}
}
let mut text = texts.join("\n");
if !unseen.is_empty() {
let note = format!("({} not shown)", named_blocks(&unseen));
text = if text.is_empty() { note } else { format!("{text}\n{note}") };
}
let text = crate::output_limit::cap_chars(
&text,
crate::output_limit::RESULT_MAX_CHARS,
"Narrow the call — a filter, fewer fields, a smaller page, or one item — to see the rest.",
);
if result.get("isError").and_then(serde_json::Value::as_bool).unwrap_or(false) {
McpToolResult { success: false, output: None, error: Some(text) }
} else {
McpToolResult { success: true, output: Some(text), error: None }
}
}
/// `1 image and 2 embedded resources`: what a result held that it could not show, in the words a
/// reader would use.
fn named_blocks(unseen: &[(&str, usize)]) -> String {
let named: Vec<String> = unseen
.iter()
.map(|(kind, count)| {
let noun = match *kind {
"image" => "image",
"audio" => "audio clip",
"resource" => "embedded resource",
"resource_link" => "resource link",
_ => "block of another kind",
};
let noun = match (*count, noun) {
(1, noun) => noun.to_string(),
(_, "block of another kind") => "blocks of another kind".to_string(),
(_, noun) => format!("{noun}s"),
};
format!("{count} {noun}")
})
.collect();
match named.as_slice() {
[only] => only.clone(),
[rest @ .., last] => format!("{} and {last}", rest.join(", ")),
[] => String::new(),
}
}
/// State of an MCP server connection.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum McpServerState {
/// Not connected.
Disconnected,
/// Connecting...
Connecting,
/// Connected and ready.
Connected {
/// Server name.
name: String,
/// Version reported by the server.
version: Option<String>,
},
/// Connection error.
Error(String),
}
/// Summary of an MCP server.
#[derive(Debug, Clone)]
pub struct McpServerSummary {
/// Server configuration.
pub config: McpServerConfig,
/// Current connection state.
pub state: McpServerState,
/// Tools available from this server.
pub tools: Vec<McpTool>,
}
#[cfg(test)]
mod tests;