Noyalib MCP README

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.

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

Capabilities at a glance

Ecosystem comparison

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

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.