noyalib-mcp 0.0.56

Model Context Protocol server exposing noyalib's lossless YAML editing to AI agents
Documentation

Contents

Getting started

The noyalib-mcp ecosystem

Library reference

Operational

Install

As a Rust library

[dependencies]
noyalib-mcp = "0.0.56"

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.88.0 or newer when building from source.
  • Linux, macOS, and Windows are tested by CI.
  • The crate pins noyalib at exactly =0.0.56 under the lockstep contract.
  • An MCP client is required to drive the server.
Surface Minimum toolchain Enforcement
Server and library Rust 1.88.0 manifest and MSRV CI
Complete test surface Rust 1.88.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

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

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.