1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
//! Typed MCP Apps registration and resources for rmcp servers.
//!
//! Start with [`StaticUiResource`] for embedded HTML. With the `server` feature,
//! `AppRouter` groups rmcp tools and resources and checks their associations;
//! `AppServer` provides the common server handling. With `macros`, the optional
//! derive declares fixed views and `app_router` associates each UI tool with its
//! view in one place. Manual declarations and routing remain directly usable.
//! Consumers choose their runtime and transport and own business logic/access checks.
//!
//! # Simple application (`server` and `macros`)
//!
//! The consumer enables rmcp's `server` and `macros` features. The HTML below is
//! this project's bundled example; use a path relative to your own declaring file.
//! rmcp generates both schemas from the Rust models; no input schema JSON is needed.
//!
//! ```
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! # #[cfg(all(feature = "server", feature = "macros"))] {
//! use mcp_apps_server::{AppServer, StaticUiResource, app_router};
//! use rmcp::{tool, schemars::JsonSchema, ServerHandler,
//! handler::server::wrapper::{Json, Parameters}};
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(StaticUiResource)]
//! #[ui_resource(id = "inventory/dashboard", name = "dashboard",
//! html_file = "../examples/dashboard.html")]
//! struct Dashboard;
//!
//! #[derive(Deserialize, JsonSchema)]
//! #[schemars(crate = "rmcp::schemars")]
//! #[serde(deny_unknown_fields)]
//! struct Input { sku: String }
//! #[derive(Serialize, JsonSchema)]
//! #[schemars(crate = "rmcp::schemars")]
//! struct Snapshot { sku: String, available: u32 }
//! struct Inventory;
//! #[app_router]
//! impl Inventory {
//! #[tool(description = "Read inventory")]
//! #[ui(resource = Dashboard)]
//! fn snapshot(&self, Parameters(input): Parameters<Input>) -> Json<Snapshot> {
//! Json(Snapshot { sku: input.sku, available: 12 })
//! }
//! }
//! let server = AppServer::new(Inventory, Inventory::app_router()?)?;
//! assert!(server.get_info().capabilities.resources.is_some());
//! assert!(server.get_tool("snapshot").is_some());
//! # }
//! # Ok(())
//! # }
//! ```
//!
//! Construction performs no request or transport activity. Call rmcp's
//! `ServiceExt::serve` with the transport you choose when ready to serve. The
//! repository's `examples/server.rs` supplies the complete stdio lifecycle.
//!
//! # Custom integration
//!
//! Keep your own `ServerHandler` when you need authorization middleware, prompts,
//! unrelated resources or custom lifecycle behavior. Prepare the same router,
//! call its validation before serving, then delegate with the original request
//! and context. Its lists are unpaginated; your handler owns filtering, pagination
//! and selecting other resource owners. Callback errors are not fallback signals.
//! See `AppRouter` for executable tool and dynamic-resource examples and
//! `AppServer` for the supported ready-server methods. The repository's
//! `examples/custom_server.rs` implements the complete manual equivalent.
//!
//! <details>
//! <summary>Implement your own handler over the same prepared router</summary>
//!
//! This handler replaces the ready adapter. With macros, obtain the same router
//! from `Inventory::app_router()`; with manual declarations, register resources
//! and associate rmcp tools explicitly. Validate the router and
//! store it with your application state. These methods let you insert access
//! checks and retain other MCP methods. A fully manual resource declaration is
//! demonstrated on [`StaticUiResource`].
//!
//! ```
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! # #[cfg(feature = "server")] {
//! use mcp_apps_server::{AppRouter, UiResource, UiResourceRoute, UiResourceUri};
//! use rmcp::{ErrorData, RoleServer, ServerHandler, model::*, service::RequestContext};
//!
//! struct ExistingServer<S> { state: S, apps: AppRouter<S> }
//! impl<S: Send + Sync + 'static> ServerHandler for ExistingServer<S> {
//! fn get_info(&self) -> ServerConfig {
//! let mut info = ServerConfig::default();
//! self.apps.declare_capabilities(&mut info.capabilities);
//! info
//! }
//! fn get_tool(&self, name: &str) -> Option<Tool> { self.apps.get_tool(name) }
//! async fn list_tools(&self, request: Option<PaginatedRequestParams>, _: RequestContext<RoleServer>)
//! -> Result<ListToolsResult, ErrorData> { self.apps.list_tools(request) }
//! async fn list_resources(&self, request: Option<PaginatedRequestParams>, _: RequestContext<RoleServer>)
//! -> Result<ListResourcesResult, ErrorData> { self.apps.list_resources(request) }
//! async fn call_tool(&self, request: CallToolRequestParams, context: RequestContext<RoleServer>)
//! -> Result<CallToolResponse, ErrorData> {
//! // Authorize the original request before delegating.
//! self.apps.call_tool(&self.state, request, context).await
//! }
//! async fn read_resource(&self, request: ReadResourceRequestParams, context: RequestContext<RoleServer>)
//! -> Result<ReadResourceResponse, ErrorData> {
//! // Select other resource owners by URI here when needed.
//! self.apps.read_resource(&self.state, request, context).await
//! }
//! }
//! # let mut apps = AppRouter::<()>::new();
//! # apps.register_resource(UiResourceRoute::static_html(
//! # UiResource::new(UiResourceUri::new("ui://inventory/dashboard.html")?, "dashboard"),
//! # "<!doctype html><html><body>Inventory</body></html>"))?;
//! # apps.validate()?;
//! # let server = ExistingServer { state: (), apps };
//! # assert!(server.get_info().capabilities.resources.is_some());
//! # }
//! # Ok(())
//! # }
//! ```
//!
//! </details>
//!
//! # Low-level declarations
//!
//! [`UiResource`] prepares a descriptor and matching HTML contents. [`ToolUi`]
//! and [`ResourceUi`] prepare typed declarations and compose them into open rmcp
//! metadata, preserving unknown keys. Omitted fields leave existing values intact;
//! unequal supplied scalar/array values return [`MetadataError::Conflict`] without
//! a partial update. These primitives remain usable without either optional feature.
//!
//! ```
//! use mcp_apps_server::{ResourceUi, UiResource, UiResourceUri};
//! let resource = UiResource::new(UiResourceUri::new("ui://inventory/dashboard")?, "dashboard");
//! let mut ui = ResourceUi::default();
//! ui.prefers_border = Some(true);
//! let contents = resource.html_contents("<!doctype html><html><body>Inventory</body></html>")
//! .with_meta(ui.to_meta()?);
//! # let _ = contents;
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! # Capabilities, security and limits
//!
//! [`ui_capability`] inspects caller-supplied client capabilities and distinguishes
//! absent, malformed and valid non-HTML support. On current rmcp requests use
//! `RequestContext::client_capabilities()` rather than assume initialization is
//! always the source. The consuming application chooses its fallback behavior.
//!
//! HTML is supplied by the consumer, without parsing, sanitization or bundling.
//! CSP, permissions and visibility are declarations for the host, not access
//! control implemented by the server. The browser renders the interface and the
//! host mediates communication. Local protocol checks do not establish real-host
//! rendering or permission behavior. No runtime, transport or background work is
//! started by this crate.
pub use ;
/// Derive a static resource's declaration, embedded HTML and optional metadata.
///
/// Requires `macros` (or its compatibility alias `derive`). Supply `name`, either
/// `id` or `uri`, and either `html_file` or `html` as string literals in
/// `#[ui_resource(...)]`. `id` is a nonempty logical identifier without `ui://`;
/// that prefix is added and the resulting URI is validated. `uri` supplies a
/// complete URI. Neither form requires an `.html` suffix or derives identity from
/// the filesystem. `html` retains the original file-path meaning of `html_file`.
/// Supplying both alternatives of a pair is a compilation error.
/// Optional `description` is a string; `ui` is a function path returning
/// [`ResourceUi`], `meta` is a function path returning `Result<MetaObject,
/// MetadataError>`, and `crate` is the path of a renamed dependency. The complete
/// open map from `meta` is composed with `ui` at registration; omitted options
/// retain trait defaults. See [`StaticUiResource::meta`] for extension ownership,
/// preparation errors and the placement of returned annotations.
/// The compiler includes the UTF-8 HTML file relative to the declaring Rust file.
/// Nothing is read from the filesystem by the running server. Generic struct
/// parameters and bounds are retained without adding field-trait requirements.
/// For a fixed view, prefer a fieldless struct. Its type identifies the resource;
/// registration never constructs an instance or reads any struct fields.
///
/// Invalid literal URIs are compilation errors, using the runtime's parser:
///
/// ```compile_fail
/// use mcp_apps_server::StaticUiResource;
/// #[derive(StaticUiResource)]
/// #[ui_resource(uri = "https://example.com/view", name = "view", html = "../examples/dashboard.html")]
/// struct InvalidView;
/// ```
pub use StaticUiResource;
/// Declare an application's rmcp tools and their static UI resources together.
///
/// Requires `macros` and `server`; the consumer enables rmcp's `macros` feature.
/// Apply this to an inherent impl with directly annotated rmcp `#[tool]` methods.
/// Mark UI tools with `#[ui(resource = ResourceType)]`; the type must implement
/// [`StaticUiResource`]. Unmarked tools keep their original declarations.
/// Do not also apply rmcp's `tool_router` to this block.
///
/// The generated public `app_router()` method prepares an [`AppRouter`] and returns
/// registration errors before serving. It registers resources first, composes each
/// association into rmcp's original tool metadata, then registers checked routes.
/// Custom rmcp tool names, schemas, annotations and callbacks are retained. Several
/// tools can share a URI only with identical descriptors, HTML and content metadata.
/// Metadata conflicts and duplicate tool names fail rather than overwrite routes.
/// A failed preparation returns no router; tool handlers are never called by it.
/// Resource declaration methods and rmcp metadata factories must have no side effects.
///
/// Use `#[app_router(crate = apps_sdk)]` for a renamed runtime dependency. Generic
/// impl bounds are preserved; router preparation requires `Self: Sized + Send +
/// Sync + 'static`. Method `cfg` and gating `cfg_attr` attributes also
/// gate registration; put `tool` and `ui` directly on the method, outside `cfg_attr`.
/// Helper methods remain unchanged; the method name `app_router` is reserved.
/// The macro does not implement `ServerHandler`, start a transport or load assets.
/// Pass its router to [`AppServer::new`] or invoke it from your custom handler.
/// See the crate's getting-started example for a complete typed workflow.
pub use app_router;
pub use MetadataError;
pub use ;
/// An open MCP metadata map, reused from rmcp for extension annotations.
///
/// This is the same type as [`rmcp::model::MetaObject`]; its keys and values are
/// owned by the extension that defines them. See [`StaticUiResource::meta`] for
/// composition with generic MCP Apps resource settings.
pub use MetaObject;
pub use ;
pub use AppServer;
pub use ;
pub use ;
/// The MCP Apps HTML MIME type required on returned resource contents.
pub const UI_MIME_TYPE: &str = "text/html;profile=mcp-app";
/// The standard MCP Apps capability extension identifier.
pub const UI_EXTENSION_ID: &str = "io.modelcontextprotocol/ui";