noyalib-mcp

noyalib-mcp

Model Context Protocol server for lossless YAML inspection, editing, and validation.

---

Contents

Getting started

• Install — Cargo, npm wrapper, and container
• Requirements — toolchain floor, platforms
• Quick Start — start a server over stdio or HTTP

The noyalib-mcp ecosystem

• The noyalib-mcp ecosystem — protocol and library relationships

Library reference

• Capabilities at a glance — the current surface by theme
• Ecosystem comparison — short matrix; full table at docs/COMPARISON.md
• Benchmarks — harness coverage; full method at docs/BENCHMARKS.md
• Features — MCP tools and resources
• Configuration — transports and endpoints
• Examples — runnable clients

Operational

• When not to use noyalib-mcp — limitations
• Development — make targets, fuzzing, CI
• Security — guarantees and compliance
• Documentation — all reference docs
• Stability guarantees — protocol, SemVer, and toolchain discipline
• License

---

Install

As a Rust library

[dependencies]
noyalib-mcp = "0.0.58"

Install or run the server through the channel that fits the host:

cargo install noyalib-mcp --locked
docker run --rm -i ghcr.io/sebastienrousseau/noyalib-mcp:latest

The npm wrapper (npx @sebastienrousseau/noyalib-mcp) runs a binary only when its package carries a SHA-256 for your platform. Releases do not yet publish per-platform archives, so today it refuses to run and points to the two commands above.

Requirements

• Rust 1.89.0 or newer when building from source.
• Linux, macOS, and Windows are tested by CI.
• The crate pins noyalib at exactly =0.0.58 under the lockstep contract.
• An MCP client is required to drive the server.

Surface	Minimum toolchain	Enforcement
Server and library	Rust 1.89.0	manifest and MSRV CI
Complete test surface	Rust 1.89.0	all-target CI

Quick Start

Use stdio for a child-process integration:

noyalib-mcp

A stdio client begins with an MCP initialization request before sending the initialized notification or listing tools:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "example",
      "version": "0.0.1"
    }
  }
}

Serve streamable HTTP at /mcp, or the legacy HTTP+SSE bridge at /sse and /messages/:

noyalib-mcp --transport streamable-http --host 127.0.0.1 --port 8000
noyalib-mcp --transport sse --host 127.0.0.1 --port 8001

The server negotiates supported MCP revisions during initialize; clients should not send raw tool calls before completing that handshake.

The noyalib-mcp ecosystem

Component	Role
noyalib-mcp	MCP server, transports, tools, prompts, and resources
noyalib	YAML parser, CST editor, and schema validator
noya-cli	Human-facing formatting and validation commands
rmcp	Official Rust MCP SDK used for protocol handling

Capabilities at a glance

Area	Capability	Status
Transport	stdio, streamable HTTP, and HTTP+SSE	Supported
Protocol	Revisions from 2024-11-05 through 2026-07-28	Negotiated
Results	Text plus typed structuredContent	Supported
YAML	Parse, get, set, multidocument set, edit, and validate	Supported
Metadata	Tool schemas, annotations, examples, prompts, and resources	Published

Ecosystem comparison

Delivery surface	Lossless YAML edits	Remote transport	Typed tool results
noyalib-mcp	Yes	HTTP and SSE	Yes
noya-cli	Yes	No	Not applicable
noyalib	Yes	No	Native Rust types

See docs/COMPARISON.md for scope and evidence.

Benchmarks

The checked-in mcp_tools Criterion harness measures tool dispatch and YAML operations without treating noisy timing values as correctness gates.

cargo bench --bench mcp_tools

See docs/BENCHMARKS.md for methodology.

Features

• Six typed tools for YAML reads, edits, parsing, and validation.
• Declared outputSchema, structuredContent, annotations, and examples.
• stdio, streamable HTTP, and legacy HTTP+SSE transports.
• Prompts and resources for agent integration.
• Protocol revision negotiation and session-aware routing.

Configuration

Option	Effect
--transport stdio	Use process stdin and stdout; this is the default
--transport streamable-http	Serve MCP at /mcp
--transport sse	Serve /sse and /messages/
--host ADDRESS	Bind an HTTP transport to an address
--port PORT	Select the HTTP listening port
--root DIR	Confine the file tools to DIR (default: the working directory, which may not be / or the home directory)
--profile strict|standard	Rules every tool parses under, the file tools and noyalib_edit included: noyalib's strict YAML 1.2 profile (the default: duplicate keys and odd indentation are errors, tighter limits) or the library defaults
--max-sessions N	Sessions an HTTP transport holds at once (default 64)

Bind remote transports deliberately. The default loopback host avoids exposing the server beyond the local machine. The file tools (noyalib_get, noyalib_set, noyalib_set_multidoc) refuse any path that resolves outside the root, symlinks included; start the server with --root on the directory a client may touch. The HTTP transports refuse a foreign Host or Origin and do not authenticate. SECURITY.md has the full trust model.

Examples

• mcp_session.rs: SDK-backed in-memory session.
• handshake.sh: initialize and list tools.
• set-then-get.sh: lossless mutation and readback.

Client configuration recipes are in docs/agent-integration.md.

When not to use noyalib-mcp

• Use noyalib directly inside a Rust application that does not need MCP.
• Use noya-cli for shell pipelines and repository-wide validation.
• Do not expose an HTTP transport to an untrusted network without an authentication and authorization layer in front of it.
• The server does not fetch remote schemas; callers must supply trusted schema content.

The detailed README reference retains client setup, tool detail, verification steps, and conformance discussion.

Development

make
make test
make clippy
make fmt
cargo fuzz run fuzz_tool_call

CI checks Rust formatting, linting, tests, documentation, dependency policy, fuzz regressions, protocol behaviour, and the shared YAML test suite. See DEVELOPMENT.md.

Security

Report vulnerabilities through SECURITY.md. The crate forbids unsafe code, audits dependencies, uses bounded noyalib operations, and emits release attestations and SBOMs. Treat file content, YAML, schemas, and MCP metadata as untrusted input.

Documentation

• User Manual
• API reference
• Developer documentation
• Agent integration
• Tool reference
• Architecture
• Engineering policies
• Compliance grade
• Detailed README reference

Stability guarantees

• During 0.0.x, the patch component is the breaking-change axis.
• Tool names, argument schemas, output schemas, and transport routes form the public compatibility surface.
• Protocol revisions are negotiated rather than inferred.
• The MSRV may rise only on the breaking axis with a changelog explanation.

License

Dual-licensed under either the Apache License, Version 2.0 or the MIT License, at your option.