Expand description
Blocking, dependency-light MCP stdio server runtime.
MCP over stdio is a single ordered byte stream: the client writes one
newline-delimited JSON-RPC message, the server answers on stdout. There is
no need for an async executor: the inline adapter is a blocking bounded
read loop, while the optional controlled adapter uses fixed standard-library
worker threads and one ordered writer. The protocol path uses
blazingly-json without Tokio, Hyper, or Axum.
Ordinary Rust functions become tools without a Tokio runtime:
use mcport::{tool, tools, McpServer};
/// Echoes the provided text.
#[tool]
fn echo(text: String) -> String {
text
}
fn main() -> std::io::Result<()> {
McpServer::new("echo", env!("CARGO_PKG_VERSION"))
.tools(tools![echo])
.serve()
}The original typed_tool and tool
methods remain for handwritten schemas and raw JSON handlers.
Implement ToolServer when dispatch needs a fully custom static surface:
use mcport::{json, ServerIdentity, ToolReply, ToolServer, Value};
struct Echo;
impl ToolServer for Echo {
fn identity(&self) -> ServerIdentity {
ServerIdentity::new("echo", "1.0.0", "Echoes tool arguments back.")
}
fn catalog(&mut self) -> Value {
json!([{
"name": "echo",
"description": "Echo the arguments.",
"inputSchema": {
"type": "object",
"description": "Any caller-defined object; every key is echoed.",
"additionalProperties": true
}
}])
}
fn call(&mut self, name: &str, arguments: Value) -> ToolReply {
match name {
"echo" => ToolReply::structured(arguments),
_ => ToolReply::error(format!("unknown tool: {name}")),
}
}
}
fn main() -> std::io::Result<()> {
mcport::serve(&mut Echo)
}Runtime guarantees:
initialize,ping, andtools/listare answered from the catalog alone, so servers can defer expensive startup to the firsttools/call;- a UTF-8 byte-order mark on any line is stripped before parsing, so Windows shell pipelines cannot break the first request;
- notifications (messages without an
id) are consumed without replies; - malformed JSON, missing methods, and unknown methods produce JSON-RPC errors without terminating the loop;
- stream adapters bound request and response bytes and never emit a partial JSON response when the output budget is exceeded;
- both builders check every advertised tool schema at registration and
expose the defects; opting into
McpServer::strict_schemasturns those defects into a startup failure. Seevalidate_tool_schema.
Modules§
- protocol
- JSON-RPC and MCP tool-result message shapes.
Macros§
- json
- Constructs a
Valuewith JSON-like syntax. - tools
- Collects
#[tool]adapters formcport::McpServer::tools.
Structs§
- Cancellation
Token - Cloneable cooperative cancellation signal supplied to tool handlers.
- Concurrent
McpServer - Builder for thread-safe tools served by the controlled runtime.
- Json
- Explicit JSON result wrapper for types that already implement
Serialize. - Map
- Ordered object storage used by
crate::Value. - McpServer
- Builder-style MCP server for applications that do not need a custom
ToolServerimplementation. - Prepared
Tool - Prepared adapter generated by
#[tool]or built by hand. - RawJson
- A validated JSON value borrowed directly from the input buffer.
- RawValue
- A reference to one complete, validated JSON value.
- Request
Context - Context supplied to every handler running under
serve_controlled. - Runtime
Config - Scheduling, execution, and transport policy for the controlled runtime.
- Schema
Defect - One advertised schema node that does not describe what the tool accepts.
- Server
Identity - Identity block reported from
initialize. - Tool
Annotations - MCP tool annotation hints. These describe intended behaviour; they are not a sandbox and do not prevent a handler from doing other work.
- Tool
Definition - Descriptor accepted by the builder without requiring a handwritten trait.
- Tool
Error - Public tool-level failure. The message is sent to the client; do not put
secrets or raw third-party
Displaytext here without reviewing it. - Tool
Page - One cursor-addressed page returned from
tools/list. - Transport
Config - Complete framing and flushing policy for the blocking stream adapter.
- Transport
Limits - Byte budgets enforced by mcport’s newline-delimited stream adapter.
Enums§
- Flush
Policy - Controls when a stream adapter flushes complete response frames.
- Method
Reply - Outcome of a non-tool JSON-RPC method handled by a server extension.
- Schema
Defect Kind - Obligation an advertised schema node failed to meet.
- Tool
Payload - Which representations of one successful result reach the client.
- Tool
Reply - Outcome of one
tools/calldispatch. - Value
- An owned JSON value.
Constants§
- DEFAULT_
PROTOCOL_ VERSION - Latest legacy handshake revision implemented by the runtime.
- MODERN_
PROTOCOL_ VERSION - Stateless per-request protocol revision implemented by the runtime.
- SUPPORTED_
PROTOCOL_ VERSIONS - Protocol revisions accepted by this runtime.
Traits§
- Concurrent
Tool Server - Thread-safe tool surface for the controlled runtime.
- Into
Tool Reply - Converts a Rust return value into a
ToolReplyfor the convenience API. - Tool
Schema - Lightweight JSON Schema fragment for a supported Rust type.
- Tool
Server - A read-only tool surface served over MCP stdio.
Functions§
- decorate_
schema - Adds description, default, and numeric bounds to a schema node.
- dispatch
- Dispatches one parsed JSON-RPC request.
- negotiate_
protocol_ version - Chooses a supported protocol revision for an initialize response.
- object_
schema - Builds an object schema with
additionalProperties: false. - serve
- Serves a
ToolServerover process stdin/stdout until EOF. - serve_
controlled - Runs a thread-safe tool server with bounded scheduling and execution.
- serve_
controlled_ streams - Controlled runtime with injectable input and an owned writer.
- serve_
message - Processes one newline-free JSON-RPC message.
- serve_
streams - Serves a
ToolServerover arbitrary streams until EOF. - serve_
streams_ with_ config - Serves a
ToolServerover arbitrary streams with byte and flush policy. - serve_
streams_ with_ limits - Serves a
ToolServerover arbitrary streams with explicit byte budgets. - serve_
with_ config - Serves a
ToolServerover process stdin/stdout with complete transport policy, including opt-in response batching. - serve_
with_ limits - Serves a
ToolServerover process stdin/stdout with explicit byte budgets. - validate_
tool_ schema - Checks that one advertised tool input schema describes what it accepts.
Attribute Macros§
- tool
- Marks an ordinary function as an MCP tool and generates its adapter.
Derive Macros§
- Tool
Output - Implements
mcport::IntoToolReplyfor a serializable struct. - Tool
Schema - Implements
mcport::ToolSchemafor a simple struct.