Skip to main content

Crate noyalib_mcp

Crate noyalib_mcp 

Source
Expand description

Library surface for noyalib-mcp.

Hosts the JSON-RPC 2.0 dispatch logic and the tool implementations. The noyalib-mcp binary in main.rs is a thin stdio loop that drives handle_message; tests reach the same handlers directly so coverage no longer depends on standing up a real stdio process.

§Cargo features

This crate exposes no optional features; the MCP tool set (noyalib_get, noyalib_set) is fixed. Optional noyalib features pulled in by a downstream packager (schema, parallel, …) do not change the MCP wire surface — they only affect what noyalib::Error messages can appear inside tool-call error envelopes. The canonical noyalib feature matrix lives in crates/noyalib/src/lib.rs.

§MSRV

Rust 1.75.0 stable — same as the core noyalib library. The MCP wire surface is text-only JSON-RPC and pulls no nightly-only deps. CI verifies the floor via the Per-crate MSRV workflow job. See the workspace POLICIES.md for the bump policy.

§Panics

Public functions in this crate do not panic on well-formed input. The MCP binary unwraps once on stdin acquisition during boot — that’s deliberate, every caller invokes the binary via a host process that controls the pipe.

§Errors

Tool calls return JSON-RPC error envelopes per the MCP specification. The error code taxonomy lives in crates/noyalib-mcp/doc/tools-reference.md: -32000 (file I/O), -32001 (parse), -32002 (path not found), -32003 (set), -32602 (missing arg), -32601 (unknown method).

§Concurrency

Each MCP request is processed sequentially on the binary’s stdio loop. The host (Claude Desktop, Cursor, Zed, …) is responsible for not pipelining requests; if it does, the tool execution is serialised by the loop’s BufRead reader.

§Platform support

Tier-1 (CI-verified each PR): aarch64-apple-darwin, x86_64-unknown-linux-gnu, x86_64-pc-windows-msvc.

noyalib_set writes via an atomic file replacement helper: write to a sibling temp file → sync_all → rename. This is naturally atomic on POSIX; on Windows it uses MoveFileExW(MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH) semantics so concurrent readers always see either the old or the new contents — never a half-write or a stale-page-cache observation. This was the fix for the historical Windows-only tool_call_set_preserves_comments flake.

§Performance

Each tools/call round-trip goes through one noyalib::cst::parse_document (O(n) over input bytes) and, for noyalib_set, one Document::to_string emit (O(n) over output bytes). JSON-RPC line framing is amortised constant-time per message. Tool calls do not cache the parsed CST between requests — every call is a fresh parse so concurrent edits from outside the MCP server are always observed. Typical tool-call latency on a 100 KB YAML file: 1–3 ms parse + emit on commodity hardware.

§Security

#![forbid(unsafe_code)]. No FFI. No network I/O — noyalib-mcp is stdio-only by design; remote hosting goes through a separate broker (see examples/hosted-mcp-run.md). The server has no auth layer; restrict the working directory of the spawned process via container mounts / systemd ReadWritePaths= for production deployments. Resource-limit gates are inherited from noyalib’s ParserConfig defaults. Full posture: SECURITY.md.

§API stability and SemVer

Pre-1.0 (0.0.x): the MCP wire contract (tool names, input-schema shapes, error code ranges, protocolVersion string) is stable within a 0.0.x line — bug fixes only. Adding a new tool is allowed within a 0.0.x bump; removing or renaming a tool, or repurposing an error code, is held to a 0.x bump (e.g. 0.0.x → 0.1.0). The Rust library surface (handle_message, dispatch, error_str, Request, Response, ErrorResponse, HandleOutcome) is covered by the workspace SemVer policy in POLICIES.md. cargo-semver-checks runs in CI on every PR.

§Documentation

Modules§

tools
Tool registry for the MCP server.

Structs§

ErrorObject
JSON-RPC 2.0 error object.
ErrorResponse
JSON-RPC 2.0 error envelope.
Request
JSON-RPC 2.0 request envelope. Method-specific parameters live in JsonValue to keep parsing flexible across the few methods the MCP spec asks of a server.
Response
JSON-RPC 2.0 success response envelope.

Enums§

HandleOutcome
What the stdio loop should do with a parsed message — write a reply on stdout, or stay silent (notifications never receive a response).

Functions§

dispatch
MCP method dispatcher. Returns the result payload on success or a (code, message) pair for the error envelope.
error_str
Render a JSON-RPC error envelope to a single line string.
handle_message
Process one newline-delimited JSON-RPC message. The stdio loop in main calls this per line; tests call it with crafted strings.