mcpmesh_local_api/
lib.rs

1//! Talk to a running [mcpmesh](https://github.com/counterpunchtech/mcpmesh) daemon from Rust.
2//!
3//! This crate is the `mcpmesh-local/1` control seam: the typed wire vocabulary of the daemon's
4//! local control endpoint (requests, results, and the live-stream frames), the platform rule for
5//! finding that endpoint ([`paths`]), and — behind the `client` feature — an async client that
6//! speaks it. It links **no networking stack**: embedders (UIs, plugins, scripts) drive the
7//! daemon without pulling the mesh transport.
8//!
9//! The full protocol (framing, method-by-method semantics, the identity contract) is documented in
10//! [`docs/local-protocol.md`](https://github.com/counterpunchtech/mcpmesh/blob/main/docs/local-protocol.md).
11//! To RUN a node in-process instead of driving a daemon, see
12//! [`mcpmesh-node`](https://docs.rs/mcpmesh-node) — its `Node::control()` returns this same
13//! [`ControlClient`] over an in-memory pipe.
14//!
15//! # Quickstart (feature `client`)
16//!
17#![cfg_attr(feature = "client", doc = "```no_run")]
18#![cfg_attr(not(feature = "client"), doc = "```ignore")]
19//! # async fn quickstart() -> Result<(), mcpmesh_local_api::client::ClientError> {
20//! let mut daemon = mcpmesh_local_api::connect_control_default().await?;
21//! let status = daemon.status().await?;
22//! for peer in &status.peers {
23//!     println!("{} shares: {}", peer.name, peer.services.join(", "));
24//! }
25//! # Ok(())
26//! # }
27//! ```
28//!
29//! [`connect_control_default`] dials the platform default endpoint (a unix socket, or a named
30//! pipe on Windows — the one rule in [`paths::default_endpoint`]); [`ControlClient`] then offers
31//! a typed helper per control method (`status`, `invite`, `pair`, `subscribe`, …), with
32//! [`ControlClient::request`] as the raw escape hatch for forward compatibility.
33//!
34//! # Features
35//!
36//! | Feature   | Adds                                                                    | Dependencies |
37//! |-----------|-------------------------------------------------------------------------|--------------|
38//! | *(none)*  | The wire vocabulary ([`protocol`]) + endpoint resolution ([`paths`])    | serde only   |
39//! | `client`  | [`ControlClient`]: connect, typed request helpers, the typed [`client::StreamSubscription`] live stream | + tokio |
40//! | `service` | The plugin seam ([`service`]): local endpoint bind + same-user gate, `[services.*]` self-registration | + rustix, tracing |
41
42/// This crate's version — the mcpmesh release train the `mcpmesh` binary ships on.
43/// Embedders that bundle the daemon binary pin both to ONE version and use this const
44/// as the expected `stack_version` anchor for the daemon they spawned.
45pub const VERSION: &str = env!("CARGO_PKG_VERSION");
46
47/// The canonical transport-vocabulary blocklist (spec §1.5/§17), shipped in-crate so
48/// embedders' surface-leak suites assert against the ONE canonical copy instead of
49/// forking it. JSON object with `substring_banned`, `token_banned`, `carve_outs`.
50pub const TRANSPORT_VOCABULARY: &str = include_str!("../fixtures/transport-vocabulary.json");
51
52/// Platform paths + endpoint resolution — featureless/std-only, so any consumer
53/// resolves the daemon endpoint from the ONE rule.
54pub mod paths;
55pub mod principals;
56pub mod protocol;
57pub use principals::principal_set;
58pub use protocol::{
59    API_MINOR, API_NAME, API_VERSION, ActiveSession, AuditKind, AuditRecord, AuditSummaryResult,
60    BackendKind, BackendSpec, BlobFetchParams, BlobFetchResult, BlobGrantParams, BlobPublishParams,
61    BlobPublishResult, BlobScopeList, Hello, InviteParams, InviteResult, OpenSessionParams,
62    OrgJoinParams, OrgJoinResult, PairParams, PairResult, PeerAddParams, PeerInfo,
63    PeerReachability, PeerRemoveParams, PeerRenameParams, PresencePeer, RecentPairing,
64    RegisterServiceParams, Request, RosterInstallParams, RosterInstallResult, RosterStatus,
65    ScopeInfo, ServiceInfo, SetNicknameParams, SetRosterUrlParams, StatusResult, StreamFrame,
66    method_of,
67};
68
69#[cfg(feature = "client")]
70pub mod client;
71#[cfg(feature = "client")]
72pub mod codec;
73
74/// The platform local-endpoint seam: connect/bind/accept/authorize.
75#[cfg(feature = "client")]
76pub mod transport;
77#[cfg(feature = "client")]
78pub use client::{
79    ControlClient, ControlRead, ControlWrite, StreamSubscription, connect_control,
80    connect_control_default, connect_control_io,
81};
82
83/// The shared plugin-platform seam (kb, loc, …): local endpoint faces, THE audience-authz
84/// expansion, `[services.*]` self-registration, and the `*-local/1` JSON-RPC conventions.
85#[cfg(feature = "service")]
86pub mod service;
mcpmesh_local_api/lib.rs

mcpmesh_local_api/
lib.rs
