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

mcpmesh_local_api/
lib.rs
