protocol_droid::adapters::secondary::stdio::spec

Struct ChildSpec

pub struct ChildSpec { /* private fields */ }

Expand description

A child MCP server’s program, arguments, and environment.

Built by new or parsed from an argv with from_argv, both of which refuse a spec the operating system would refuse. See the module docs for why.

§Examples

use protocol_droid::adapters::secondary::stdio::ChildSpec;

let spec = ChildSpec::new("npx")?
    .with_args(["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])?
    .with_env("RUST_LOG", "warn")?
    .with_current_dir("/srv");

assert_eq!(spec.program(), std::ffi::OsStr::new("npx"));
assert_eq!(spec.args().len(), 3);

Implementations§

Source §

impl ChildSpec

Source

pub fn new(program: impl Into<OsString>) -> Result<Self, ChildSpecError>

A program with no arguments and an inherited environment.

§Errors

ChildSpecError::EmptyProgram when the program is empty, and ChildSpecError::Unrepresentable when it contains a NUL.

Source

pub fn from_argv<I, S>(argv: I) -> Result<Self, ChildSpecError>
where I: IntoIterator<Item = S>, S: Into<OsString>,

A program read from an argv, where the first element is the program.

The convention every platform already uses — including std::env::args, which this is shaped for — so a caller holding a parsed command line hands it over whole rather than splitting it here and getting the split wrong.

§Errors

As ChildSpec::new, applied to the first element, and as with_args, applied to the rest. An empty argv has no program to refuse, so it is ChildSpecError::EmptyArgv.

§Examples

use protocol_droid::adapters::secondary::stdio::ChildSpec;

let spec = ChildSpec::from_argv(["my-server", "--stdio"])?;

assert_eq!(spec.program(), std::ffi::OsStr::new("my-server"));
assert_eq!(spec.args(), [std::ffi::OsString::from("--stdio")]);

Source

pub fn with_arg(self, arg: impl Into<OsString>) -> Result<Self, ChildSpecError>

Appends one argument.

The single-argument form of with_args, for the call site that has one.

§Errors

ChildSpecError::Unrepresentable when the argument contains a NUL.

Source

pub fn with_args<I, S>(self, args: I) -> Result<Self, ChildSpecError>
where I: IntoIterator<Item = S>, S: Into<OsString>,

Appends several arguments.

§Errors

ChildSpecError::Unrepresentable when any argument contains a NUL. Nothing is appended in that case, so a caller that ignores the error gets the spec it started with rather than one that is silently short at the spawn.

Source

pub fn with_env( self, key: impl Into<OsString>, value: impl Into<OsString>, ) -> Result<Self, ChildSpecError>

Adds an environment variable for the child.

An addition, not a replacement: see the module docs on inherited environments. A key already present is replaced, because that is what the second assignment to the same name means.

§Errors

ChildSpecError::EmptyEnvKey when the key is empty or contains the = that separates a key from its value, and ChildSpecError::Unrepresentable when either side contains a NUL.

No #[must_use]: the return type is a Result, which is already marked, and saying it twice is noise rather than emphasis.

Source

pub fn with_current_dir(self, directory: impl Into<PathBuf>) -> Self

Runs the child in directory.

Source

pub const fn without_inherited_env(self) -> Self

Starts the child with no inherited environment.

Everything outside env is then absent — including PATH on Unix, which usually means the program cannot be found. That is a real cost and the reason this is not the default; it is the right choice when a server is being started with a deliberately minimal environment, and the wrong one everywhere else.

Source

pub fn program(&self) -> &OsStr

The program, as the operating system will be asked to find it.

Source

pub fn args(&self) -> &[OsString]

The arguments, excluding the program.

Source

pub fn env(&self) -> &[(OsString, OsString)]

The environment entries added to whatever is inherited.

Source

pub fn current_dir(&self) -> Option<&Path>

The working directory, when one was set.

Source

pub const fn inherits_env(&self) -> bool

Whether the child starts from this process’s environment.

Source

pub fn to_command(&self) -> Command

The Command this spec describes.

Public because a caller embedding this transport may want to add something the spec has no field for — a process group, a uid — and there is no reason for it to have to rebuild the spec to do it. The pipes and the kill-on-drop flag are not set here; they belong to child::spawn, which is the only thing in the crate that may claim to have set them.