rmcp_server_kit/
lib.rs

1#![forbid(unsafe_code)]
2#![cfg_attr(
3    test,
4    allow(
5        clippy::unwrap_used,
6        clippy::expect_used,
7        clippy::panic,
8        clippy::indexing_slicing,
9        clippy::unwrap_in_result,
10        clippy::print_stdout,
11        clippy::print_stderr
12    )
13)]
14
15//! `rmcp-server-kit` — production-grade reusable framework for building
16//! [Model Context Protocol](https://modelcontextprotocol.io/) servers in Rust.
17//!
18//! Application crates depend on `rmcp-server-kit` and supply their own
19//! [`rmcp::handler::server::ServerHandler`] implementation; the kit provides
20//! transport, security, and observability around it.
21//!
22//! # What you get
23//!
24//! - **Streamable HTTP transport** with TLS / mTLS termination, configurable
25//!   keep-alive and session idle timeouts, CORS, compression, body-size and
26//!   concurrency caps, and graceful shutdown on `SIGINT`/`SIGTERM`.
27//! - **Authentication**: API keys (Argon2-hashed, constant-time compared),
28//!   mTLS client certificates with optional CDP-driven CRL revocation, and —
29//!   under the `oauth` feature — OAuth 2.1 Bearer JWT validation against a
30//!   cached JWKS endpoint.
31//! - **RBAC** with per-tool argument allow-lists and per-IP per-tool rate
32//!   limiting; policies and API keys are hot-reloadable at runtime via
33//!   [`transport::ReloadHandle`] (lock-free [`arc_swap`] swaps).
34//! - **Observability**: `tracing` with JSON or pretty formats, optional audit
35//!   file sink, `/healthz` + `/readyz` probes, `/version`, `/admin/*`
36//!   diagnostics, and — under the `metrics` feature — a Prometheus
37//!   `/metrics` endpoint on a separate listener.
38//! - **OWASP-grade defaults**: HSTS, CSP, `X-Frame-Options`, MCP `Origin`
39//!   validation, and per-hop SSRF guards on outbound HTTP.
40//!
41//! # Quick start
42//!
43//! ```no_run
44//! use rmcp::{
45//!     handler::server::ServerHandler,
46//!     model::{ServerCapabilities, ServerInfo},
47//! };
48//! use rmcp_server_kit::transport::{McpServerConfig, serve};
49//!
50//! #[derive(Clone)]
51//! struct MyHandler;
52//!
53//! impl ServerHandler for MyHandler {
54//!     fn get_info(&self) -> ServerInfo {
55//!         ServerInfo::new(ServerCapabilities::builder().enable_tools().build())
56//!     }
57//! }
58//!
59//! #[tokio::main]
60//! async fn main() -> rmcp_server_kit::Result<()> {
61//!     let _ = rmcp_server_kit::observability::init_tracing("info");
62//!
63//!     let config = McpServerConfig::new(
64//!         "127.0.0.1:8080",
65//!         "my-mcp-server",
66//!         env!("CARGO_PKG_VERSION"),
67//!     );
68//!
69//!     serve(config.validate()?, || MyHandler).await
70//! }
71//! ```
72//!
73//! See [`examples/`](https://github.com/andrico21/rmcp-server-kit/tree/main/examples)
74//! for richer setups (API-key + RBAC, OAuth resource server) and
75//! [`docs/GUIDE.md`](https://github.com/andrico21/rmcp-server-kit/blob/main/docs/GUIDE.md)
76//! for the full TOML configuration reference.
77//!
78//! # Cargo features
79//!
80//! All features are **off by default**:
81//!
82//! - `oauth` — OAuth 2.1 Bearer JWT validation, JWKS cache, and optional
83//!   OAuth proxy endpoints. Pulls in [`jsonwebtoken`] and [`urlencoding`].
84//!   Required to use the [`oauth`] module.
85//! - `oauth-mtls-client` — RFC 8705 §2 mTLS client authentication for the
86//!   OAuth token-exchange endpoint. Implies `oauth`. Without this feature,
87//!   [`oauth::OAuthConfig::validate`] rejects any configuration that sets
88//!   [`oauth::TokenExchangeConfig::client_cert`].
89//! - `metrics` — Prometheus registry and `/metrics` listener. Pulls in
90//!   the [`prometheus`] crate. Required to use the [`metrics`] module.
91//! - `test-helpers` — exposes test-only helpers from [`bounded_limiter`] and
92//!   [`mtls_revocation`] for downstream integration tests. **Not part of the
93//!   stable API surface** — no semver guarantees across minor releases.
94//!
95//! # ⚠️ stdio transport is unauthenticated
96//!
97//! [`transport::serve_stdio`] runs MCP over the process's stdin/stdout for
98//! local subprocess scenarios (desktop clients, IDE integrations). It
99//! **bypasses authentication, RBAC, TLS, Origin validation, and rate
100//! limiting** — the surrounding OS process boundary is the only trust
101//! boundary. Never expose `serve_stdio` to untrusted callers; for any
102//! network-reachable deployment use [`transport::serve`] over HTTPS instead.
103
104/// Reusable server and observability configuration primitives.
105pub mod config;
106/// Generic error type and `Result` alias for server-side code.
107pub mod error;
108/// Tracing / JSON logs / audit file initialization.
109pub mod observability;
110/// Streamable HTTP transport and server entry points.
111pub mod transport;
112
113/// Authentication state (API keys, mTLS, OAuth JWT) and middleware.
114pub mod auth;
115/// Role-based access control policy engine and middleware.
116pub mod rbac;
117
118/// Memory-bounded keyed rate limiter (LRU + idle eviction).
119pub mod bounded_limiter;
120
121/// Admin diagnostic endpoints (status, auth keys metadata, counters, RBAC).
122pub mod admin;
123
124/// Re-exports for the [`secrecy`] crate's secret-wrapper types.
125pub mod secret;
126
127pub(crate) mod ssrf;
128pub(crate) mod ssrf_resolver;
129
130/// Opt-in tool-call hooks (before/after) and result-size cap.
131pub mod tool_hooks;
132
133#[cfg(feature = "oauth")]
134/// OAuth 2.1 JWKS cache, token validation, and token exchange helpers.
135pub mod oauth;
136
137#[cfg(feature = "metrics")]
138/// Prometheus metrics registry shared across server components.
139pub mod metrics;
140
141/// CDP-driven CRL revocation support for mTLS.
142pub mod mtls_revocation;
143
144// Re-export the canonical error types at the crate root for ergonomic
145// `rmcp_server_kit::Result<()>` / `rmcp_server_kit::McpxError` usage in downstream crates.
146pub use crate::error::{McpxError, Result};
rmcp_server_kit/lib.rs

rmcp_server_kit/
lib.rs
