Skip to main content

Crate mcport

Crate mcport 

Source
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, and tools/list are answered from the catalog alone, so servers can defer expensive startup to the first tools/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_schemas turns those defects into a startup failure. See validate_tool_schema.

Modules§

protocol
JSON-RPC and MCP tool-result message shapes.

Macros§

json
Constructs a Value with JSON-like syntax.
tools
Collects #[tool] adapters for mcport::McpServer::tools.

Structs§

CancellationToken
Cloneable cooperative cancellation signal supplied to tool handlers.
ConcurrentMcpServer
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 ToolServer implementation.
PreparedTool
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.
RequestContext
Context supplied to every handler running under serve_controlled.
RuntimeConfig
Scheduling, execution, and transport policy for the controlled runtime.
SchemaDefect
One advertised schema node that does not describe what the tool accepts.
ServerIdentity
Identity block reported from initialize.
ToolAnnotations
MCP tool annotation hints. These describe intended behaviour; they are not a sandbox and do not prevent a handler from doing other work.
ToolDefinition
Descriptor accepted by the builder without requiring a handwritten trait.
ToolError
Public tool-level failure. The message is sent to the client; do not put secrets or raw third-party Display text here without reviewing it.
ToolPage
One cursor-addressed page returned from tools/list.
TransportConfig
Complete framing and flushing policy for the blocking stream adapter.
TransportLimits
Byte budgets enforced by mcport’s newline-delimited stream adapter.

Enums§

FlushPolicy
Controls when a stream adapter flushes complete response frames.
MethodReply
Outcome of a non-tool JSON-RPC method handled by a server extension.
SchemaDefectKind
Obligation an advertised schema node failed to meet.
ToolPayload
Which representations of one successful result reach the client.
ToolReply
Outcome of one tools/call dispatch.
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§

ConcurrentToolServer
Thread-safe tool surface for the controlled runtime.
IntoToolReply
Converts a Rust return value into a ToolReply for the convenience API.
ToolSchema
Lightweight JSON Schema fragment for a supported Rust type.
ToolServer
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 ToolServer over 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 ToolServer over arbitrary streams until EOF.
serve_streams_with_config
Serves a ToolServer over arbitrary streams with byte and flush policy.
serve_streams_with_limits
Serves a ToolServer over arbitrary streams with explicit byte budgets.
serve_with_config
Serves a ToolServer over process stdin/stdout with complete transport policy, including opt-in response batching.
serve_with_limits
Serves a ToolServer over 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§

ToolOutput
Implements mcport::IntoToolReply for a serializable struct.
ToolSchema
Implements mcport::ToolSchema for a simple struct.